diff options
Diffstat (limited to 'doc')
985 files changed, 16059 insertions, 11621 deletions
diff --git a/doc/.vale/gitlab/Acronyms.yml b/doc/.vale/gitlab/Acronyms.yml index 481da94c627..c6b9bb45040 100644 --- a/doc/.vale/gitlab/Acronyms.yml +++ b/doc/.vale/gitlab/Acronyms.yml @@ -27,6 +27,8 @@ exceptions: - CNA - CNAME - CORE + - CVS + - FREE - CPU - CRIME - CSRF @@ -47,6 +49,7 @@ exceptions: - FAQ - FOSS - FQDN + - FREE - GCP - GDK - GDPR @@ -116,11 +119,13 @@ exceptions: - RSS - RVM - SAML + - SAAS - SAST - SCIM - SCP - SCSS - SDK + - SELF - SEO - SHA - SLA @@ -143,6 +148,8 @@ exceptions: - TLS - TODO - TOML + - TTL + - UDP - UNIX - URI - URL @@ -157,3 +164,4 @@ exceptions: - XML - XSS - YAML + - ZIP diff --git a/doc/.vale/gitlab/Admin.yml b/doc/.vale/gitlab/Admin.yml index 96325ad2ef4..dbbdb34a8e7 100644 --- a/doc/.vale/gitlab/Admin.yml +++ b/doc/.vale/gitlab/Admin.yml @@ -7,7 +7,8 @@ extends: substitution message: 'Use "administration", "administrator", "administer", or "Admin Area" instead of "admin" or "admin area".' link: https://docs.gitlab.com/ee/development/documentation/styleguide.html +# Do not set `level: error`, as our docs refer to other docs which use "admin" and "Admin" level: warning ignorecase: true swap: - 'admin ?\w*': '(?:Admin Area|[Aa]dminist(ration|rator|er|rative))' + 'admin ?\w*': '(?:Admin Area|[Aa]dminist(ration|rator|rators|er|rative))' diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index 6ce0ced52b3..c3dc596acb7 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -1,8 +1,12 @@ +accessor +accessors Akismet Alertmanager Algolia Alibaba +Aliyun allowlist +allowlisted allowlisting allowlists anonymized @@ -10,11 +14,14 @@ Ansible Anthos approvers architected +architecting +Arel Artifactory Asana Asciidoctor Assembla Atlassian +auditability Auth0 Authentiq autocomplete @@ -31,6 +38,7 @@ autoscaler autoscales autoscaling awardable +awardables Axios Azure B-tree @@ -52,8 +60,13 @@ blockquoted blockquotes blockquoting boolean +booleans Bootsnap browsable +bugfix +bugfixed +bugfixes +bugfixing Bugzilla Buildkite buildpack @@ -62,9 +75,16 @@ bundler bundlers burndown burnup +burstable cacheable +Caddy +callstack +callstacks +Camo CentOS Certbot +changeset +changesets chai chatbot chatbots @@ -86,6 +106,7 @@ Conda Consul Contentful Corosync +Coursier cron crons crontab @@ -96,15 +117,22 @@ crosslinks Crossplane CrowdIn CSV +cybersecurity Dangerfile datetime Debian +Decompressor +decryptable deduplicate deduplicated deduplicates deduplicating deduplication deliverables +denormalize +denormalized +denormalizes +denormalizing denylist denylisting denylists @@ -118,11 +146,16 @@ dequarantine dequarantined dequarantining DevOps +disambiguates discoverability +dismissable Disqus Divio Dockerfile Dockerfiles +Dockerize +Dockerized +Dockerizing dogfood dogfooding dogfoods @@ -135,6 +168,7 @@ Ecto Elasticsearch enablement enqueued +enqueues enum enums ETag @@ -145,17 +179,22 @@ failover failovers failsafe Falco +falsy fastlane favicon +favorited Figma Filebeat Fio firewalled +firewalling Flawfinder Flowdock Fluentd Forgerock +formatters Fugit +fuzzer Gantt Gemnasium Gemojione @@ -167,9 +206,11 @@ GitHub GitLab gitlabsos Gitleaks +Gitpod Gitter globals Gmail +Godep Gollum Google goroutine @@ -177,17 +218,20 @@ goroutines Gosec Gradle Grafana +Grafonnet gravatar Gzip Haml hardcode hardcoded hardcodes +Haswell heatmap heatmaps Helm Heroku Herokuish +Hexo HipChat hostname hostnames @@ -199,17 +243,22 @@ http https idempotence idmapper +Iglu inclusivity Ingress initializer initializers +innersource +innersourcing interdependencies interdependency interruptible Irker +issuables Istio Jaeger jasmine-jquery +Javafuzz JavaScript Jenkins Jenkinsfile @@ -217,6 +266,7 @@ Jira jq jQuery jsdom +Jsonnet JupyterHub kanban kanbans @@ -224,8 +274,11 @@ kaniko Karma Kerberos keyset +keytab +keytabs Kibana Kinesis +Klar Knative Kramdown Kroki @@ -233,13 +286,18 @@ Kubecost kubectl Kubernetes Kubesec +Kustomize Laravel ldapsearch Lefthook Leiningen +libFuzzer Libravatar liveness +Lodash Lograge +logrotate +Logrus Logstash lookahead lookaheads @@ -250,6 +308,7 @@ loopback Lucene Maildir Mailgun +Mailroom Makefile Makefiles Markdown @@ -297,9 +356,12 @@ namespaces namespacing namespacings Nanoc +negatable Netlify Nokogiri npm +nullability +nullable Nurtch nyc OAuth @@ -312,6 +374,7 @@ onboarding OpenID OpenShift Opsgenie +Overcommit Packagist parallelization parallelizations @@ -319,10 +382,12 @@ passwordless Patroni performant PgBouncer +pgLoader Phabricator phaser phasers phpenv +pipenv Pipfile Pipfiles Piwik @@ -362,12 +427,22 @@ pseudocode pseudonymized pseudonymizer Puma +pytest Python Qualys +queryable +Quicktime Rackspace Raspbian Rdoc reachability +Realplayer +reauthenticate +reauthenticated +reauthenticates +reauthenticating +rebalancing +rebar rebase rebased rebases @@ -383,6 +458,8 @@ referer referers reflog reflogs +refspec +refspecs reindex reindexed reindexes @@ -414,10 +491,12 @@ rsync rsynced rsyncing rsyncs +Rubinius Rubix Rubocop Rubular ruleset +rulesets runbook runbooks runit @@ -430,19 +509,24 @@ sbt scatterplot scatterplots Schemastore +scrollable Sendmail Sentry serializer serializers serializing serverless +sharded sharding shfmt Shibboleth +Shopify Sidekiq +Silverlight Sisense Sitespeed Slack +Slackbot Slony smartcard smartcards @@ -455,6 +539,9 @@ spidering Splunk SpotBugs Stackdriver +Stackprof +starrer +starrers storable storages strace @@ -475,22 +562,44 @@ subnet subnets subnetting subpath +subproject +subprojects subqueried subqueries subquery subquerying substring substrings +subtask +subtasks +subtest +subtests subtree subtrees sudo +supercookie +supercookies +supertype +supertypes +swappiness swimlane swimlanes +syncable +Sysbench +syscall +syscalls syslog tanuki tcpdump +templated Thanos +Thoughtbot +throughputs Tiller +timebox +timeboxed +timeboxes +timeboxing timecop todos tokenizer @@ -498,22 +607,33 @@ Tokenizers tokenizing toolchain toolchains +toolkit +toolkits tooltip tooltips transpile +transpiled transpiles transpiling Trello +triaged +triages triaging +truthy +Truststore Twilio Twitter TypeScript Ubuntu unapplied +unapprove +unapproved +unapproving unarchive unarchived unarchives unarchiving +unary unassign unassigning unassigns @@ -524,6 +644,7 @@ unchecks uncomment uncommented uncommenting +uncordon unencode unencoded unencoder @@ -534,6 +655,8 @@ unindexed unlink unlinking unlinks +unmappable +unmapped unmergeable unmerged unmerges @@ -543,9 +666,11 @@ unoptimize unoptimized unoptimizes unoptimizing +unpatched unprioritized unprotect unprotected +unprotecting unprotects unprovision unprovisioned @@ -554,6 +679,7 @@ unpublish unpublished unpublishes unpublishing +unpushed unreferenced unregister unregistered @@ -564,6 +690,9 @@ unresolved unresolving unschedule unscoped +unshare +unshared +unshares unstage unstaged unstages @@ -574,6 +703,7 @@ unstarted unstash unstashed unstashing +unsynced untarred untracked untrusted @@ -583,8 +713,12 @@ unverify unverifying uploader uploaders +upstreams +upvote upvoted upvotes +URIs +Vagrantfile validator validators vendored @@ -601,6 +735,8 @@ WebdriverIO Webex webpack webserver +websocket +websockets whitepaper whitepapers wireframe @@ -611,9 +747,11 @@ Wireshark Wordpress worktree worktrees +Worldline Xcode Xeon YouTrack +Yubico Zeitwerk Zendesk zsh diff --git a/doc/README.md b/doc/README.md index 41a68df09d0..4202da762d1 100644 --- a/doc/README.md +++ b/doc/README.md @@ -23,32 +23,32 @@ Here you can access the complete documentation for GitLab, the single applicatio No matter how you use GitLab, we have documentation for you. -| Essential documentation | Essential documentation | -|:---------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------| +| Essential documentation | Essential documentation | +|:------------------------|:------------------------| | [**User documentation**](user/index.md)<br>Discover features and concepts for GitLab users. | [**Administrator documentation**](administration/index.md)<br/>Everything GitLab self-managed administrators need to know. | -| [**Contributing to GitLab**](#contributing-to-gitlab)<br/>At GitLab, everyone can contribute! | [**New to Git and GitLab?**](#new-to-git-and-gitlab)<br/>We have the resources to get you started. | -| [**Build an integration with GitLab**](#build-an-integration-with-gitlab)<br/>Consult our integration documentation. | [**Coming to GitLab from another platform?**](#coming-to-gitlab-from-another-platform)<br/>Consult our guides. | -| [**Install GitLab**](https://about.gitlab.com/install/)<br/>Installation options for different platforms. | [**Customers**](subscriptions/index.md)<br/>Information for new and existing customers. | -| [**Update GitLab**](update/README.md)<br/>Update your GitLab self-managed instance to the latest version. | [**Reference Architectures**](administration/reference_architectures/index.md)<br/>GitLab reference architectures | -| [**GitLab releases**](https://about.gitlab.com/releases/)<br/>What's new in GitLab. | | +| [**Contributing to GitLab**](#contributing-to-gitlab)<br/>At GitLab, everyone can contribute! | [**New to Git and GitLab?**](#new-to-git-and-gitlab)<br/>We have the resources to get you started. | +| [**Build an integration with GitLab**](#build-an-integration-with-gitlab)<br/>Consult our integration documentation. | [**Coming to GitLab from another platform?**](#coming-to-gitlab-from-another-platform)<br/>Consult our guides. | +| [**Install GitLab**](https://about.gitlab.com/install/)<br/>Installation options for different platforms. | [**Customers**](subscriptions/index.md)<br/>Information for new and existing customers. | +| [**Update GitLab**](update/README.md)<br/>Update your GitLab self-managed instance to the latest version. | [**Reference Architectures**](administration/reference_architectures/index.md)<br/>GitLab reference architectures. | +| [**GitLab releases**](https://about.gitlab.com/releases/)<br/>What's new in GitLab. | | ## Popular topics Have a look at some of our most popular topics: -| Popular topic | Description | -|:-----------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------| -| [Two-factor authentication](user/profile/account/two_factor_authentication.md) | Improve the security of your GitLab account. | -| [GitLab groups](user/group/index.md) | Manage projects together. | -| [GitLab CI/CD pipeline configuration reference](ci/yaml/README.md) | Available configuration options for `.gitlab-ci.yml` files. | -| [Activate GitLab EE with a license](user/admin_area/license.md) **(STARTER ONLY)** | Activate GitLab Enterprise Edition functionality with a license. | -| [Back up and restore GitLab](raketasks/backup_restore.md) **(CORE ONLY)** | Rake tasks for backing up and restoring GitLab self-managed instances. | -| [GitLab release and maintenance policy](policy/maintenance.md) | Policies for version naming and cadence, and also upgrade recommendations. | -| [Elasticsearch integration](integration/elasticsearch.md) **(STARTER ONLY)** | Integrate Elasticsearch with GitLab to enable advanced searching. | -| [Omnibus GitLab database settings](https://docs.gitlab.com/omnibus/settings/database.html) **(CORE ONLY)** | Database settings for Omnibus GitLab self-managed instances. | -| [Omnibus GitLab NGINX settings](https://docs.gitlab.com/omnibus/settings/nginx.html) **(CORE ONLY)** | NGINX settings for Omnibus GitLab self-managed instances. | -| [Omnibus GitLab SSL configuration](https://docs.gitlab.com/omnibus/settings/ssl.html) **(CORE ONLY)** | SSL settings for Omnibus GitLab self-managed instances. | -| [GitLab.com settings](user/gitlab_com/index.md) | Settings used for GitLab.com. | +| Popular topic | Description | +|:-------------------------------------------------------------------------------------------|:------------| +| [Two-factor authentication](user/profile/account/two_factor_authentication.md) | Improve the security of your GitLab account. | +| [GitLab groups](user/group/index.md) | Manage projects together. | +| [GitLab CI/CD pipeline configuration reference](ci/yaml/README.md) | Available configuration options for `.gitlab-ci.yml` files. | +| [Activate GitLab EE with a license](user/admin_area/license.md) | Activate GitLab Enterprise Edition functionality with a license. | +| [Back up and restore GitLab](raketasks/backup_restore.md) | Rake tasks for backing up and restoring GitLab self-managed instances. | +| [GitLab release and maintenance policy](policy/maintenance.md) | Policies for version naming and cadence, and also upgrade recommendations. | +| [Elasticsearch integration](integration/elasticsearch.md) | Integrate Elasticsearch with GitLab to enable advanced searching. | +| [Omnibus GitLab database settings](https://docs.gitlab.com/omnibus/settings/database.html) | Database settings for Omnibus GitLab self-managed instances. | +| [Omnibus GitLab NGINX settings](https://docs.gitlab.com/omnibus/settings/nginx.html) | NGINX settings for Omnibus GitLab self-managed instances. | +| [Omnibus GitLab SSL configuration](https://docs.gitlab.com/omnibus/settings/ssl.html) | SSL settings for Omnibus GitLab self-managed instances. | +| [GitLab.com settings](user/gitlab_com/index.md) | Settings used for GitLab.com. | ## The entire DevOps lifecycle @@ -64,53 +64,53 @@ Working with new systems can be daunting. We have the following documentation to rapidly uplift your GitLab knowledge: -| Topic | Description | -|:--------------------------------------------------------------------------------------------------|:---------------------------------------------------------------| -| [GitLab basics guides](gitlab-basics/README.md) | Start working on the command line and with GitLab. | -| [GitLab workflow overview](https://about.gitlab.com/blog/2016/10/25/gitlab-workflow-an-overview/) | Enhance your workflow with the best of GitLab Workflow. | -| [Get started with GitLab CI/CD](ci/quick_start/README.md) | Quickly implement GitLab CI/CD. | -| [Auto DevOps](topics/autodevops/index.md) | Learn more about Auto DevOps in GitLab. | -| [GitLab Markdown](user/markdown.md) | Advanced formatting system (GitLab Flavored Markdown) | +| Topic | Description | +|:--------------------------------------------------------------------------------------------------|:------------| +| [GitLab basics guides](gitlab-basics/README.md) | Start working on the command line and with GitLab. | +| [GitLab workflow overview](https://about.gitlab.com/blog/2016/10/25/gitlab-workflow-an-overview/) | Enhance your workflow with the best of GitLab Workflow. | +| [Get started with GitLab CI/CD](ci/quick_start/README.md) | Quickly implement GitLab CI/CD. | +| [Auto DevOps](topics/autodevops/index.md) | Learn more about Auto DevOps in GitLab. | +| [GitLab Markdown](user/markdown.md) | Advanced formatting system (GitLab Flavored Markdown). | ### User account Learn more about GitLab account management: -| Topic | Description | -|:-----------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------| -| [User account](user/profile/index.md) | Manage your account. | +| Topic | Description | +|:-----------------------------------------------------------|:------------| +| [User account](user/profile/index.md) | Manage your account. | | [Authentication](topics/authentication/index.md) | Account security with two-factor authentication, set up your SSH keys, and deploy keys for secure access to your projects. | -| [Profile settings](user/profile/index.md#profile-settings) | Manage your profile settings, two factor authentication, and more. | -| [User permissions](user/permissions.md) | Learn what each role in a project can do. | +| [Profile settings](user/profile/index.md#profile-settings) | Manage your profile settings, two factor authentication, and more. | +| [User permissions](user/permissions.md) | Learn what each role in a project can do. | ### Git and GitLab Learn more about using Git, and using Git with GitLab: -| Topic | Description | -|:-----------------------------------------------------------------------------|:---------------------------------------------------------------------------| +| Topic | Description | +|:-----------------------------------------------------------------------------|:------------| | [Git](topics/git/index.md) | Getting started with Git, branching strategies, Git LFS, and advanced use. | -| [Git cheat sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf) | Download a PDF describing the most used Git operations. | -| [GitLab Flow](topics/gitlab_flow.md) | Explore the best of Git with the GitLab Flow strategy. | +| [Git cheat sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf) | Download a PDF describing the most used Git operations. | +| [GitLab Flow](topics/gitlab_flow.md) | Explore the best of Git with the GitLab Flow strategy. | ## Coming to GitLab from another platform If you are coming to GitLab from another platform, the following information is useful: -| Topic | Description | -|:----------------------------------------------------|:---------------------------------------------------------------------------------------| +| Topic | Description | +|:----------------------------------------------------|:------------| | [Importing to GitLab](user/project/import/index.md) | Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz, and SVN into GitLab. | -| [Migrating from SVN](user/project/import/svn.md) | Convert a SVN repository to Git and GitLab. | +| [Migrating from SVN](user/project/import/svn.md) | Convert a SVN repository to Git and GitLab. | ## Build an integration with GitLab There are many ways to integrate with GitLab, including: -| Topic | Description | -|:-------------------------------------------|:---------------------------------------------| -| [GitLab REST API](api/README.md) | Integrate with GitLab using our REST API. | +| Topic | Description | +|:-------------------------------------------|:------------| +| [GitLab REST API](api/README.md) | Integrate with GitLab using our REST API. | | [GitLab GraphQL API](api/graphql/index.md) | Integrate with GitLab using our GraphQL API. | -| [Integrations](integration/README.md) | Integrations with third-party products. | +| [Integrations](integration/README.md) | Integrations with third-party products. | ## Contributing to GitLab @@ -119,8 +119,8 @@ and GitLab Enterprise Edition is [open-core](https://gitlab.com/gitlab-org/gitla Learn how to contribute to GitLab with the following resources: -| Topic | Description | -|:------------------------------------------------------------|:-----------------------------------------| +| Topic | Description | +|:------------------------------------------------------------|:------------| | [Development](development/README.md) | How to contribute to GitLab development. | -| [Legal](legal/README.md) | Contributor license agreements. | -| [Writing documentation](development/documentation/index.md) | How to contribute to GitLab Docs. | +| [Legal](legal/README.md) | Contributor license agreements. | +| [Writing documentation](development/documentation/index.md) | How to contribute to GitLab Docs. | diff --git a/doc/administration/application_settings_cache.md b/doc/administration/application_settings_cache.md new file mode 100644 index 00000000000..b6c09129c79 --- /dev/null +++ b/doc/administration/application_settings_cache.md @@ -0,0 +1,47 @@ +--- +stage: Enablement +group: Memory +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Changing application settings cache expiry interval **(FREE SELF)** + +Application settings are cached for 60 seconds by default which should work +for most installations. A higher value would mean a greater delay between +changing an application setting and noticing that change come into effect. +A value of `0` would result in the `application_settings` table being +loaded for every request causing extra load on Redis and/or PostgreSQL. +It is therefore recommended to keep the value above zero. + +## Change the application settings cache expiry + +To change the expiry value: + +**For Omnibus installations** + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['application_settings_cache_seconds'] = 60 + ``` + +1. Save the file, and reconfigure and restart GitLab for the changes to take effect: + + ```shell + gitlab-ctl reconfigure + gitlab-ctl restart + ``` + +--- + +**For installations from source** + +1. Edit `config/gitlab.yml`: + + ```yaml + gitlab: + application_settings_cache_seconds: 60 + ``` + +1. Save the file and [restart](restart_gitlab.md#installations-from-source) + GitLab for the changes to take effect. diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index 27f6bbcd028..6512879e8b8 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Audit Events **(STARTER)** +# Audit Events **(PREMIUM)** GitLab offers a way to view the changes made within the GitLab server for owners and administrators on a [paid plan](https://about.gitlab.com/pricing/). @@ -42,7 +42,7 @@ There are two kinds of events logged: Impersonation is where an administrator uses credentials to perform an action as a different user. -### Group events **(STARTER)** +### Group events **(PREMIUM)** A user with a Owner role (or above) can retrieve group audit events of all users. A user with a Developer or Maintainer role is limited to group audit events based on their individual actions. @@ -72,7 +72,7 @@ From there, you can see the following actions: Group events can also be accessed via the [Group Audit Events API](../api/audit_events.md#group-audit-events) -### Project events **(STARTER)** +### Project events **(PREMIUM)** A user with a Maintainer role (or above) can retrieve project audit events of all users. A user with a Developer role is limited to project audit events based on their individual actions. @@ -99,13 +99,15 @@ From there, you can see the following actions: - 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) -- User was approved via Admin Area ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276250) in GitLab 13.6) +- Project access token was successfully created or revoked ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230007) in GitLab 13.9) +- Failed attempt to create or revoke a project access token ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230007) in GitLab 13.9) +- When default branch changes for a project ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/52339) in GitLab 13.9) Project events can also be accessed via the [Project Audit Events API](../api/audit_events.md#project-audit-events). Project event queries are limited to a maximum of 30 days. -### Instance events **(PREMIUM ONLY)** +### Instance events **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2336) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.3. @@ -129,6 +131,9 @@ recorded: - Changed username ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7797) in GitLab 12.8) - User was deleted ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/251) in GitLab 12.8) - User was added ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/251) in GitLab 12.8) +- User requests access to an instance ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298783) in GitLab 13.9) +- User was approved via Admin Area ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276250) in GitLab 13.6) +- User was rejected via Admin Area ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298783) in GitLab 13.9) - User was blocked via Admin Area ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/251) in GitLab 12.8) - User was blocked via API ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25872) in GitLab 12.9) - Failed second-factor authentication attempt ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16826) in GitLab 13.5) @@ -189,7 +194,7 @@ The search filters you can see depends on which audit level you are at.  -## Export to CSV **(PREMIUM ONLY)** +## Export to CSV **(PREMIUM SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1449) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/285441) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. diff --git a/doc/administration/auditor_users.md b/doc/administration/auditor_users.md index 7db20efb03f..b04ceebf645 100644 --- a/doc/administration/auditor_users.md +++ b/doc/administration/auditor_users.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Auditor users **(PREMIUM ONLY)** +# Auditor users **(PREMIUM SELF)** Auditor users are given read-only access to all projects, groups, and other resources on the GitLab instance. @@ -68,6 +68,8 @@ To create a new Auditor user: To revoke Auditor permissions from a user, make them a regular user by following the previous steps. +Additionally users can be set as an Auditor using [SAML groups](../integration/saml.md#auditor-groups). + ## Permissions and restrictions of an Auditor user An Auditor user should be able to access all projects and groups of a GitLab diff --git a/doc/administration/auth/README.md b/doc/administration/auth/README.md index cc3421d3133..69220113940 100644 --- a/doc/administration/auth/README.md +++ b/doc/administration/auth/README.md @@ -22,7 +22,8 @@ providers: - [Facebook](../../integration/facebook.md) - [GitHub](../../integration/github.md) - [GitLab.com](../../integration/gitlab.md) -- [Google](../../integration/google.md) +- [Google OAuth](../../integration/google.md) +- [Google Workspace SSO](../../integration/google_workspace_saml.md) - [JWT](jwt.md) - [Kerberos](../../integration/kerberos.md) - [LDAP](ldap/index.md): Includes Active Directory, Apple Open Directory, Open LDAP, @@ -31,9 +32,9 @@ providers: - [Okta](okta.md) - [Salesforce](../../integration/salesforce.md) - [SAML](../../integration/saml.md) -- [SAML for GitLab.com groups](../../user/group/saml_sso/index.md) **(SILVER ONLY)** +- [SAML for GitLab.com groups](../../user/group/saml_sso/index.md) **(PREMIUM SAAS)** - [Shibboleth](../../integration/shibboleth.md) -- [Smartcard](smartcard.md) **(PREMIUM ONLY)** +- [Smartcard](smartcard.md) **(PREMIUM SELF)** - [Twitter](../../integration/twitter.md) NOTE: diff --git a/doc/administration/auth/google_secure_ldap.md b/doc/administration/auth/google_secure_ldap.md deleted file mode 100644 index 37366b00f73..00000000000 --- a/doc/administration/auth/google_secure_ldap.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'ldap/google_secure_ldap.md' ---- - -This document was moved to [another location](ldap/google_secure_ldap.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md deleted file mode 100644 index ffce06afb63..00000000000 --- a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../ldap/index.md' ---- - -This document was moved to [another location](../ldap/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md deleted file mode 100644 index ffce06afb63..00000000000 --- a/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../ldap/index.md' ---- - -This document was moved to [another location](../ldap/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/img/okta_admin_panel_v13_9.png b/doc/administration/auth/img/okta_admin_panel_v13_9.png Binary files differnew file mode 100644 index 00000000000..bba859c80af --- /dev/null +++ b/doc/administration/auth/img/okta_admin_panel_v13_9.png diff --git a/doc/administration/auth/ldap-ee.md b/doc/administration/auth/ldap-ee.md deleted file mode 100644 index 6d56654a44b..00000000000 --- a/doc/administration/auth/ldap-ee.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'ldap/index.md' ---- - -This document was moved to [another location](ldap/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/ldap-troubleshooting.md b/doc/administration/auth/ldap-troubleshooting.md deleted file mode 100644 index 1e02755e3e5..00000000000 --- a/doc/administration/auth/ldap-troubleshooting.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'ldap/ldap-troubleshooting.md' ---- - -This document was moved to [another location](ldap/ldap-troubleshooting.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md deleted file mode 100644 index 6d56654a44b..00000000000 --- a/doc/administration/auth/ldap.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'ldap/index.md' ---- - -This document was moved to [another location](ldap/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index 6fecf74d935..2b75d864352 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Google Secure LDAP **(CORE ONLY)** +# Google Secure LDAP **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46391) in GitLab 11.9. diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index de0f123acf1..74621f9c1ba 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -29,7 +29,7 @@ stands for **Lightweight Directory Access Protocol**, which is a standard application protocol for accessing and maintaining distributed directory information services over an Internet Protocol (IP) network. -## Security **(CORE ONLY)** +## Security **(FREE SELF)** GitLab assumes that LDAP users: @@ -44,7 +44,7 @@ We recommend against using LDAP integration if your LDAP users are allowed to change their 'mail', 'email' or 'userPrincipalName' attribute on the LDAP server or share email addresses. -### User deletion **(CORE ONLY)** +### User deletion **(FREE SELF)** If a user is deleted from the LDAP server, they are also blocked in GitLab. Users are immediately blocked from logging in. However, there is an @@ -53,16 +53,16 @@ are already logged in or are using Git over SSH are be able to access GitLab for up to one hour. Manually block the user in the GitLab Admin Area to immediately block all access. -GitLab Enterprise Edition Starter supports a -[configurable sync time](#adjusting-ldap-user-sync-schedule). **(STARTER)** +GitLab Enterprise Edition Premium supports a +[configurable sync time](#adjusting-ldap-user-sync-schedule). **(PREMIUM)** -## Git password authentication **(CORE ONLY)** +## Git password authentication **(FREE SELF)** LDAP-enabled users can always authenticate with Git using their GitLab username or email and LDAP password, even if password authentication for Git is disabled in the application settings. -## Enabling LDAP sign-in for existing GitLab users **(CORE ONLY)** +## Enabling LDAP sign-in for existing GitLab users **(FREE SELF)** When a user signs in to GitLab with LDAP for the first time, and their LDAP email address is the primary email address of an existing GitLab user, then @@ -73,7 +73,7 @@ In other words, if an existing GitLab user wants to enable LDAP sign-in for themselves, they should check that their GitLab email address matches their LDAP email address, and then sign into GitLab via their LDAP credentials. -## Google Secure LDAP **(CORE ONLY)** +## Google Secure LDAP **(FREE SELF)** > Introduced in GitLab 11.9. @@ -81,7 +81,7 @@ LDAP email address, and then sign into GitLab via their LDAP credentials. LDAP service that can be configured with GitLab for authentication and group sync. See [Google Secure LDAP](google_secure_ldap.md) for detailed configuration instructions. -## Configuration **(CORE ONLY)** +## Configuration **(FREE SELF)** To enable LDAP integration you need to add your LDAP server settings in `/etc/gitlab/gitlab.rb` or `/home/git/gitlab/config/gitlab.yml` for Omnibus @@ -100,7 +100,7 @@ would be on port 389. `plain` also operates on port 389. Removed values: `tls` w LDAP users must have a set email address, regardless of whether or not it's used to sign in. -### Example Configurations **(CORE ONLY)** +### Example Configurations **(FREE SELF)** **Omnibus Configuration** @@ -163,7 +163,7 @@ production: ... ``` -### Basic Configuration Settings **(CORE ONLY)** +### Basic Configuration Settings **(FREE SELF)** | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | @@ -183,7 +183,7 @@ production: | `user_filter` | Filter LDAP users. Format: [RFC 4515](https://tools.ietf.org/search/rfc4515) Note: GitLab does not support `omniauth-ldap`'s custom filter syntax. | no | `'(employeeType=developer)'` or `'(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'` | | `lowercase_usernames` | If lowercase_usernames is enabled, GitLab converts the name to lower case. | no | boolean | -### SSL Configuration Settings **(CORE ONLY)** +### SSL Configuration Settings **(FREE SELF)** | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | @@ -193,7 +193,7 @@ production: | `cert` | Client certificate | no | `'-----BEGIN CERTIFICATE----- <REDACTED> -----END CERTIFICATE -----'` | | `key` | Client private key | no | `'-----BEGIN PRIVATE KEY----- <REDACTED> -----END PRIVATE KEY -----'` | -### Attribute Configuration Settings **(CORE ONLY)** +### Attribute Configuration Settings **(FREE SELF)** LDAP attributes that GitLab uses to create an account for the LDAP user. The specified attribute can either be the attribute name as a string (for example, `'mail'`), or an array of attribute names to try in order (for example, `['mail', 'email']`). Note that the user's LDAP sign-in is the attribute specified as `uid` above. @@ -205,7 +205,7 @@ LDAP attributes that GitLab uses to create an account for the LDAP user. The spe | `first_name` | LDAP attribute for user first name. Used when the attribute configured for `name` does not exist. | no | `'givenName'` | | `last_name` | LDAP attribute for user last name. Used when the attribute configured for `name` does not exist. | no | `'sn'` | -### LDAP Sync Configuration Settings **(STARTER ONLY)** +### LDAP Sync Configuration Settings **(PREMIUM SELF)** | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | @@ -214,7 +214,7 @@ LDAP attributes that GitLab uses to create an account for the LDAP user. The spe | `external_groups` | An array of CNs of groups containing users that should be considered external. Note: Not `cn=interns` or the full DN. | no | `['interns', 'contractors']` | | `sync_ssh_keys` | The LDAP attribute containing a user's public SSH key. | no | `'sshPublicKey'` or false if not set | -### Set up LDAP user filter **(CORE ONLY)** +### Set up LDAP user filter **(FREE SELF)** If you want to limit all GitLab access to a subset of the LDAP users on your LDAP server, the first step should be to narrow the configured `base`. However, @@ -254,12 +254,12 @@ group, you can use the following syntax: For more information about this "LDAP_MATCHING_RULE_IN_CHAIN" filter, see the following [Microsoft Search Filter Syntax](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) document. Support for nested members in the user filter should not be confused with -[group sync nested groups support](#supported-ldap-group-typesattributes). **(STARTER ONLY)** +[group sync nested groups support](#supported-ldap-group-typesattributes). **(PREMIUM SELF)** Please note that GitLab does not support the custom filter syntax used by OmniAuth LDAP. -#### Escaping special characters **(CORE ONLY)** +#### Escaping special characters **(FREE SELF)** The `user_filter` DN can contain special characters. For example: @@ -290,7 +290,7 @@ The `user_filter` DN can contain special characters. For example: OU=Gitlab \28Inc\29,DC=gitlab,DC=com ``` -### Enabling LDAP username lowercase **(CORE ONLY)** +### Enabling LDAP username lowercase **(FREE SELF)** Some LDAP servers, depending on their configurations, can return uppercase usernames. This can lead to several confusing issues such as creating links or namespaces with uppercase names. @@ -328,7 +328,7 @@ the configuration option `lowercase_usernames`. By default, this configuration o 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -### Disable LDAP web sign in **(CORE ONLY)** +### Disable LDAP web sign in **(FREE SELF)** It can be useful to prevent using LDAP credentials through the web UI when an alternative such as SAML is preferred. This allows LDAP to be used for group @@ -360,7 +360,7 @@ This does not disable [using LDAP credentials for Git access](#git-password-auth 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -### Using encrypted credentials **(CORE ONLY)** +### Using encrypted credentials **(FREE SELF)** Instead of having the LDAP integration credentials stored in plaintext in the configuration files, you can optionally use an encrypted file for the LDAP credentials. To use this feature, you first need to enable @@ -447,7 +447,7 @@ If initially your LDAP configuration looked like: 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -## Encryption **(CORE ONLY)** +## Encryption **(FREE SELF)** ### TLS Server Authentication @@ -467,7 +467,7 @@ You should disable anonymous LDAP authentication and enable simple or SASL authentication. The TLS client authentication setting in your LDAP server cannot be mandatory and clients cannot be authenticated with the TLS protocol. -## Multiple LDAP servers **(STARTER ONLY)** +## Multiple LDAP servers **(PREMIUM SELF)** With GitLab Enterprise Edition Starter, you can configure multiple LDAP servers that your GitLab instance connects to. @@ -515,7 +515,7 @@ gitlab_rails['ldap_servers'] = { If you configure multiple LDAP servers, use a unique naming convention for the `label` section of each entry. That label is used as the display name of the tab shown on the sign-in page. -## User sync **(STARTER ONLY)** +## User sync **(PREMIUM SELF)** Once per day, GitLab runs a worker to check and update GitLab users against LDAP. @@ -530,7 +530,12 @@ The process executes the following access checks: In Active Directory, a user is marked as disabled/blocked if the user account control attribute (`userAccountControl:1.2.840.113556.1.4.803`) has bit 2 set. -For more information, see <https://ctovswild.com/2009/09/03/bitmask-searches-in-ldap/> + +<!-- vale gitlab.Spelling = NO --> + +For more information, see [Bitmask Searches in LDAP](https://ctovswild.com/2009/09/03/bitmask-searches-in-ldap/). + +<!-- vale gitlab.Spelling = YES --> The user is set to an `ldap_blocked` state in GitLab if the previous conditions fail. This means the user is not able to sign in or push/pull code. @@ -546,7 +551,7 @@ The LDAP sync process: - Updates existing users. - Creates new users on first sign in. -### Adjusting LDAP user sync schedule **(STARTER ONLY)** +### Adjusting LDAP user sync schedule **(PREMIUM SELF)** By default, GitLab runs a worker once per day at 01:30 a.m. server time to check and update GitLab users against LDAP. @@ -579,7 +584,7 @@ sync to run once every 12 hours at the top of the hour. 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -## Group Sync **(STARTER ONLY)** +## Group Sync **(PREMIUM SELF)** If your LDAP supports the `memberof` property, when the user signs in for the first time GitLab triggers a sync for groups the user should be a member of. @@ -629,11 +634,11 @@ following. To take advantage of group sync, group owners or maintainers need to [create one or more LDAP group links](#adding-group-links). -### Adding group links **(STARTER ONLY)** +### Adding group links **(PREMIUM SELF)** 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)** +### Administrator sync **(PREMIUM SELF)** As an extension of group sync, you can automatically manage your global GitLab administrators. Specify a group CN for `admin_group` and all members of the @@ -677,7 +682,7 @@ group, as opposed to the full DN. 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -### Global group memberships lock **(STARTER ONLY)** +### Global group memberships lock **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1793) in GitLab 12.0. @@ -696,7 +701,7 @@ To enable it you need to: 1. Navigate to **(admin)** **Admin Area > Settings -> Visibility and access controls**. 1. Make sure the "Lock memberships to LDAP synchronization" checkbox is enabled. -### Adjusting LDAP group sync schedule **(STARTER ONLY)** +### Adjusting LDAP group sync schedule **(PREMIUM SELF)** By default, GitLab runs a group sync process every hour, on the hour. The values shown are in cron format. If needed, you can use a @@ -735,7 +740,7 @@ sync to run once every 2 hours at the top of the hour. 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -### External groups **(STARTER ONLY)** +### External groups **(PREMIUM SELF)** Using the `external_groups` setting will allow you to mark all users belonging to these groups as [external users](../../../user/permissions.md#external-users). diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 1976bab03c6..5640e938651 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -52,7 +52,7 @@ main: # 'main' is the GitLab 'provider ID' of this LDAP server admin_group: 'my_admin_group' ``` -#### Query LDAP **(STARTER ONLY)** +#### Query LDAP **(PREMIUM SELF)** 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 @@ -210,7 +210,7 @@ ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt -b "$ba port. - We are assuming the password for the `bind_dn` user is in `bind_dn_password.txt`. -#### Sync all users **(STARTER ONLY)** +#### Sync all users **(PREMIUM SELF)** 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) @@ -225,7 +225,7 @@ LdapSyncWorker.new.perform Next, [learn how to read the output](#example-console-output-after-a-user-sync). -##### Example console output after a user sync **(STARTER ONLY)** +##### Example console output after a user sync **(PREMIUM SELF)** 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: @@ -316,9 +316,9 @@ adapter = Gitlab::Auth::Ldap::Adapter.new('ldapmain') # If `main` is the LDAP pr Gitlab::Auth::Ldap::Person.find_by_uid('<uid>', adapter) ``` -### Group memberships **(STARTER ONLY)** +### Group memberships **(PREMIUM SELF)** -#### Membership(s) not granted **(STARTER ONLY)** +#### Membership(s) not granted **(PREMIUM SELF)** Sometimes you may think a particular user should be added to a GitLab group via LDAP group sync, but for some reason it's not happening. There are several @@ -376,7 +376,7 @@ 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)** +#### Sync all groups **(PREMIUM SELF)** NOTE: To sync all groups manually when debugging is unnecessary, [use the Rake @@ -394,7 +394,7 @@ LdapAllGroupsSyncWorker.new.perform Next, [learn how to read the output](#example-console-output-after-a-group-sync). -##### Example console output after a group sync **(STARTER ONLY)** +##### Example console output after a group sync **(PREMIUM SELF)** Like the output from the user sync, the output from the [manual group sync](#sync-all-groups) will also be very verbose. However, it contains lots @@ -484,7 +484,7 @@ stating as such: No `admin_group` configured for 'ldapmain' provider. Skipping ``` -#### Sync one group **(STARTER ONLY)** +#### Sync one group **(PREMIUM SELF)** [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 @@ -506,7 +506,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). -#### Query a group in LDAP **(STARTER ONLY)** +#### Query a group in LDAP **(PREMIUM SELF)** When you'd like to confirm that GitLab can read a LDAP group and see all its members, you can run the following: @@ -562,7 +562,7 @@ emails.each do |username, email| end ``` -You can then [run a UserSync](#sync-all-users) **(STARTER ONLY)** to sync the latest DN +You can then [run a UserSync](#sync-all-users) **(PREMIUM SELF)** to sync the latest DN for each of these users. ## Debugging Tools diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index 158182edfb5..1ddf75e7c1b 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -175,6 +175,6 @@ If you're having trouble, here are some tips: OAuth2 access token if `client_auth_method` is not defined or if set to `basic`. If you are seeing 401 errors upon retrieving the `userinfo` endpoint, you may want to check your OpenID Web server configuration. For example, for - [oauth2-server-php](https://github.com/bshaffer/oauth2-server-php), you + [`oauth2-server-php`](https://github.com/bshaffer/oauth2-server-php), you may need to [add a configuration parameter to Apache](https://github.com/bshaffer/oauth2-server-php/issues/926#issuecomment-387502778). diff --git a/doc/administration/auth/okta.md b/doc/administration/auth/okta.md index 50dc3b58680..a014fe7404f 100644 --- a/doc/administration/auth/okta.md +++ b/doc/administration/auth/okta.md @@ -19,13 +19,13 @@ The following guidance is based on this Okta article, on adding a [SAML Applicat 1. On Okta admin section, make sure to select Classic UI view in the top left corner. From there, choose to **Add an App**. 1. When the app screen comes up you see another button to **Create an App** and choose SAML 2.0 on the next screen. -1. Now, very important, add a logo +1. Optionally you can add a logo (you can choose it from <https://about.gitlab.com/press/>). You'll have to crop and resize it. -1. Next, you'll need the to fill in the SAML general configuration. Here's an example +1. Next, you'll need the to fill in the SAML general configuration. Here's an example (showing the required URLs and attribute mapping): image. -  +  1. The last part of the configuration is the feedback section where you can just say you're a customer and creating an app for internal use. diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md index 9790802e413..dfeee5e7ac4 100644 --- a/doc/administration/auth/smartcard.md +++ b/doc/administration/auth/smartcard.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Smartcard authentication **(PREMIUM ONLY)** +# Smartcard authentication **(PREMIUM SELF)** GitLab supports authentication using smartcards. diff --git a/doc/administration/availability/index.md b/doc/administration/availability/index.md deleted file mode 100644 index 4f934646ed6..00000000000 --- a/doc/administration/availability/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: ../reference_architectures/index.md ---- - -This document was moved to [another location](../reference_architectures/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/build_artifacts.md b/doc/administration/build_artifacts.md deleted file mode 100644 index e42f50b2e54..00000000000 --- a/doc/administration/build_artifacts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'job_artifacts.md' ---- - -This document was moved to [job_artifacts](job_artifacts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index 6079e838ac6..b2c8d8982bd 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -15,9 +15,9 @@ relevant compliance standards. |Feature |GitLab tier |GitLab.com | Product level | | ---------| :--------: | :-------: | :-----------: | -|**[Restrict SSH Keys](../security/ssh_keys_restrictions.md)**<br>Control the technology and key length of SSH keys used to access GitLab|Core+||Instance| -|**[Granular user roles and flexible permissions](../user/permissions.md)**<br>Manage access and permissions with five different user roles and settings for external users. Set permissions according to people's role, rather than either read or write access to a repository. Don't share the source code with people that only need access to the issue tracker.|Core+|✓|Instance, Group, Project| -|**[Enforce TOS acceptance](../user/admin_area/settings/terms.md)**<br>Enforce your users accepting new terms of service by blocking GitLab traffic.|Core+||Instance| +|**[Restrict SSH Keys](../security/ssh_keys_restrictions.md)**<br>Control the technology and key length of SSH keys used to access GitLab|Free+||Instance| +|**[Granular user roles and flexible permissions](../user/permissions.md)**<br>Manage access and permissions with five different user roles and settings for external users. Set permissions according to people's role, rather than either read or write access to a repository. Don't share the source code with people that only need access to the issue tracker.|Free+|✓|Instance, Group, Project| +|**[Enforce TOS acceptance](../user/admin_area/settings/terms.md)**<br>Enforce your users accepting new terms of service by blocking GitLab traffic.|Free+||Instance| |**[Email all users of a project, group, or entire server](../tools/email.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+|||Instance |**[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+||Instance| |**[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+|✓|Group| @@ -26,4 +26,4 @@ relevant compliance standards. |**[Audit events](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 events system, so you can control, analyze, and track every change.|Premium+|✓|Instance, Group, Project| |**[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+||Instance| |**[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||Instance| -|**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 the GitLab cross-project YAML configurations 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+|✓|Project| +|**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-cicd-configuration-path)**<br> GitLab Premium users can leverage the GitLab cross-project YAML configurations 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+|✓|Project| diff --git a/doc/administration/consul.md b/doc/administration/consul.md index 5b577443c7c..dfc859e30c2 100644 --- a/doc/administration/consul.md +++ b/doc/administration/consul.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# How to set up Consul **(PREMIUM ONLY)** +# How to set up Consul **(PREMIUM SELF)** A Consul cluster consists of both [server and client agents](https://www.consul.io/docs/agent). diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md deleted file mode 100644 index 52941556237..00000000000 --- a/doc/administration/container_registry.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'packages/container_registry.md' ---- - -This document was moved to [another location](packages/container_registry.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/custom_hooks.md b/doc/administration/custom_hooks.md deleted file mode 100644 index 0580540eef9..00000000000 --- a/doc/administration/custom_hooks.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'server_hooks.md' ---- - -This document was moved to [another location](server_hooks.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/database_load_balancing.md b/doc/administration/database_load_balancing.md index 45243afd8ac..fe30d98b92d 100644 --- a/doc/administration/database_load_balancing.md +++ b/doc/administration/database_load_balancing.md @@ -4,7 +4,7 @@ group: Database info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Database Load Balancing **(PREMIUM ONLY)** +# Database Load Balancing **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1283) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. diff --git a/doc/administration/dependency_proxy.md b/doc/administration/dependency_proxy.md deleted file mode 100644 index c0e0643b5de..00000000000 --- a/doc/administration/dependency_proxy.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'packages/dependency_proxy.md' ---- - -This document was moved to [another location](packages/dependency_proxy.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md index 01a1cf66bdc..508f4314694 100644 --- a/doc/administration/encrypted_configuration.md +++ b/doc/administration/encrypted_configuration.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Encrypted Configuration **(CORE ONLY)** +# Encrypted Configuration **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45712) in GitLab 13.7. @@ -34,4 +34,4 @@ The new secret can be generated by running: bundle exec rake gitlab:env:info RAILS_ENV=production GITLAB_GENERATE_ENCRYPTED_SETTINGS_KEY_BASE=true ``` -This will print general info on the GitLab instance, but will also cause the key to be generated in `<path-to-gitlab-rails>/config/secrets.yml` +This will print general information on the GitLab instance, but will also cause the key to be generated in `<path-to-gitlab-rails>/config/secrets.yml` diff --git a/doc/administration/external_database.md b/doc/administration/external_database.md deleted file mode 100644 index 7424b4e1e83..00000000000 --- a/doc/administration/external_database.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -redirect_to: 'postgresql/external.md' ---- - -# Configure GitLab using an external PostgreSQL service - -This content has been moved to a [new location](postgresql/external.md). diff --git a/doc/administration/feature_flags.md b/doc/administration/feature_flags.md index 272009c1f3a..55727822654 100644 --- a/doc/administration/feature_flags.md +++ b/doc/administration/feature_flags.md @@ -6,7 +6,7 @@ type: reference description: "GitLab administrator: enable and disable GitLab features deployed behind feature flags" --- -# Enable and disable GitLab features deployed behind feature flags **(CORE ONLY)** +# Enable and disable GitLab features deployed behind feature flags **(FREE SELF)** GitLab adopted [feature flags strategies](../development/feature_flags/index.md) to deploy features in an early stage of development so that they can be diff --git a/doc/administration/file_hooks.md b/doc/administration/file_hooks.md index 5de2e4aec3f..cfaeda546cc 100644 --- a/doc/administration/file_hooks.md +++ b/doc/administration/file_hooks.md @@ -19,19 +19,20 @@ directly to the GitLab source code and contribute back upstream. This way we can ensure functionality is preserved across versions and covered by tests. NOTE: -File hooks must be configured on the filesystem of the GitLab server. Only GitLab -server administrators will be able to complete these tasks. Explore -[system hooks](../system_hooks/system_hooks.md) or [webhooks](../user/project/integrations/webhooks.md) as an option if you do not have filesystem access. - -A file hook will run on each event so it's up to you to filter events or projects -within a file hook code. You can have as many file hooks as you want. Each file hook will -be triggered by GitLab asynchronously in case of an event. For a list of events +File hooks must be configured on the file system of the GitLab server. Only GitLab +server administrators can complete these tasks. Explore +[system hooks](../system_hooks/system_hooks.md) or [webhooks](../user/project/integrations/webhooks.md) +as an option if you do not have file system access. + +A file hook runs on each event. You can filter events or projects +in a file hook's code, and create many file hooks as you need. Each file hook is +triggered by GitLab asynchronously in case of an event. For a list of events see the [system hooks](../system_hooks/system_hooks.md) documentation. ## Setup The file hooks must be placed directly into the `file_hooks` directory, subdirectories -will be ignored. There is an +are ignored. There is an [`example` directory inside `file_hooks`](https://gitlab.com/gitlab-org/gitlab/tree/master/file_hooks/examples) where you can find some basic examples. @@ -52,23 +53,23 @@ Follow the steps below to set up a custom hook: in any language, and ensure the 'shebang' at the top properly reflects the language type. For example, if the script is in Ruby the shebang will probably be `#!/usr/bin/env ruby`. -1. The data to the file hook will be provided as JSON on STDIN. It will be exactly +1. The data to the file hook is provided as JSON on STDIN. It is exactly the same as for [system hooks](../system_hooks/system_hooks.md). -That's it! Assuming the file hook code is properly implemented, the hook will fire +That's it! Assuming the file hook code is properly implemented, the hook fires as appropriate. The file hooks file list is updated for each event, there is no need to restart GitLab to apply a new file hook. If a file hook executes with non-zero exit code or GitLab fails to execute it, a -message will be logged to: +message is logged to: - `gitlab-rails/plugin.log` in an Omnibus installation. - `log/plugin.log` in a source installation. ## Creating file hooks -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. +This example responds only on the event `project_create`, and +the GitLab instance informs the administrators that a new project has been created. ```ruby #!/opt/gitlab/embedded/bin/ruby @@ -97,7 +98,7 @@ end Writing your own file hook can be tricky and it's easier if you can check it without altering the system. A Rake task is provided so that you can use it in a staging environment to test your file hook before using it in production. -The Rake task will use a sample data and execute each of file hook. The output +The Rake task uses a sample data and execute each of file hook. The output should be enough to determine if the system sees your file hook and if it was executed without errors. diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md index f2854d0538b..ae81db8a8d0 100644 --- a/doc/administration/geo/disaster_recovery/background_verification.md +++ b/doc/administration/geo/disaster_recovery/background_verification.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Automatic background verification **(PREMIUM ONLY)** +# Automatic background verification **(PREMIUM SELF)** NOTE: Automatic background verification of repositories and wikis was added in diff --git a/doc/administration/geo/disaster_recovery/bring_primary_back.md b/doc/administration/geo/disaster_recovery/bring_primary_back.md index 3f86e03bd7f..d06f11bbe09 100644 --- a/doc/administration/geo/disaster_recovery/bring_primary_back.md +++ b/doc/administration/geo/disaster_recovery/bring_primary_back.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Bring a demoted primary node back online **(PREMIUM ONLY)** +# Bring a demoted primary node back online **(PREMIUM SELF)** After a failover, it is possible to fail back to the demoted **primary** node to restore your original configuration. This process consists of two steps: diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index 2b0a3e2f114..d62d7322ac0 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Disaster Recovery (Geo) **(PREMIUM ONLY)** +# Disaster Recovery (Geo) **(PREMIUM SELF)** 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 @@ -145,6 +145,13 @@ Note the following when promoting a secondary: a point-in-time recovery to the last known state. Data that was created on the primary while the secondary was paused will be lost. + NOTE: + In GitLab 13.7 and earlier, if you have a data type with zero items to sync, + this command reports `ERROR - Replication is not up-to-date` even if + replication is actually up-to-date. If replication and verification output + shows that it is complete, you can add `--skip-preflight-checks` to make the + command complete promotion. This bug was fixed in GitLab 13.8 and later. + To promote the secondary node to primary along with preflight checks: ```shell diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md index 1468c5cd39d..1418ff77262 100644 --- a/doc/administration/geo/disaster_recovery/planned_failover.md +++ b/doc/administration/geo/disaster_recovery/planned_failover.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Disaster recovery for planned failover **(PREMIUM ONLY)** +# Disaster recovery for planned failover **(PREMIUM SELF)** The primary use-case of Disaster Recovery is to ensure business continuity in the event of unplanned outage, but it can be used in conjunction with a planned @@ -45,6 +45,12 @@ be found in `/var/opt/gitlab/gitlab-rails/shared/pages` if using Omnibus). ## Preflight checks +NOTE: +In GitLab 13.7 and earlier, if you have a data type with zero items to sync, +this command reports `ERROR - Replication is not up-to-date` even if +replication is actually up-to-date. This bug was fixed in GitLab 13.8 and +later. + Run this 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 diff --git a/doc/administration/geo/disaster_recovery/promotion_runbook.md b/doc/administration/geo/disaster_recovery/promotion_runbook.md deleted file mode 100644 index eef1e7ae9dd..00000000000 --- a/doc/administration/geo/disaster_recovery/promotion_runbook.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: runbooks/planned_failover_single_node.md ---- - -This document was moved to [another location](runbooks/planned_failover_single_node.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md index f17990ce5f8..3227fafca0f 100644 --- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md @@ -9,7 +9,7 @@ WARNING: This runbook is in **alpha**. For complete, production-ready documentation, see the [disaster recovery documentation](../index.md). -# Disaster Recovery (Geo) promotion runbooks **(PREMIUM ONLY)** +# Disaster Recovery (Geo) promotion runbooks **(PREMIUM SELF)** ## Geo planned failover for a multi-node configuration diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md index a2a9350e411..7f311d172ef 100644 --- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md @@ -9,7 +9,7 @@ WARNING: This runbook is in **alpha**. For complete, production-ready documentation, see the [disaster recovery documentation](../index.md). -# Disaster Recovery (Geo) promotion runbooks **(PREMIUM ONLY)** +# Disaster Recovery (Geo) promotion runbooks **(PREMIUM SELF)** ## Geo planned failover for a single-node configuration @@ -233,12 +233,25 @@ To promote the secondary node: check if replication and verification are complete before scheduling a planned failover to ensure the process will go smoothly: + NOTE: + In GitLab 13.7 and earlier, if you have a data type with zero items to sync, + this command reports `ERROR - Replication is not up-to-date` even if + replication is actually up-to-date. This bug was fixed in GitLab 13.8 and + later. + ```shell gitlab-ctl promotion-preflight-checks ``` 1. Promote the **secondary**: + NOTE: + In GitLab 13.7 and earlier, if you have a data type with zero items to sync, + this command reports `ERROR - Replication is not up-to-date` even if + replication is actually up-to-date. If replication and verification output + shows that it is complete, you can add `--skip-preflight-checks` to make the + command complete promotion. This bug was fixed in GitLab 13.8 and later. + ```shell gitlab-ctl promote-to-primary-node ``` diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index 1985ea2e04c..296500e35e2 100644 --- a/doc/administration/geo/index.md +++ b/doc/administration/geo/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Geo **(PREMIUM ONLY)** +# Geo **(PREMIUM SELF)** > - Introduced in GitLab Enterprise Edition 8.9. > - Using Geo in combination with diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index 5adf256f6fa..63c5b5d6c62 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Geo configuration **(PREMIUM ONLY)** +# Geo configuration **(PREMIUM SELF)** ## Configuring a new **secondary** node diff --git a/doc/administration/geo/replication/database.md b/doc/administration/geo/replication/database.md deleted file mode 100644 index 099a73e93d8..00000000000 --- a/doc/administration/geo/replication/database.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../setup/database.md' ---- - -This document was moved to [another location](../setup/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index 0d2922c3347..667dd83c3f1 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Geo data types support **(PREMIUM ONLY)** +# Geo data types support **(PREMIUM SELF)** A Geo data type is a specific class of data that is required by one or more GitLab features to store relevant information. @@ -35,21 +35,21 @@ verification methods: | Git | Object pools for forked project deduplication | Geo with Gitaly | _Not implemented_ | | Git | Project Snippets | Geo with Gitaly | _Not implemented_ | | Git | Personal Snippets | Geo with Gitaly | _Not implemented_ | -| Blobs | User uploads _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | User uploads _(file system)_ | Geo with API | _Not implemented_ | | Blobs | User uploads _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | -| Blobs | LFS objects _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | LFS objects _(file system)_ | Geo with API | _Not implemented_ | | Blobs | LFS objects _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | -| Blobs | CI job artifacts _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | CI job artifacts _(file system)_ | Geo with API | _Not implemented_ | | Blobs | CI job artifacts _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | -| Blobs | Archived CI build traces _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | Archived CI build traces _(file system)_ | Geo with API | _Not implemented_ | | 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 _(file system)_ | 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 _(file system)_ | Geo with API | _Not implemented_ | | Blobs | Package registry _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | -| Blobs | Versioned Terraform State _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | Versioned Terraform State _(file system)_ | Geo with API | _Not implemented_ | | Blobs | Versioned Terraform State _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | -| Blobs | External Merge Request Diffs _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | External Merge Request Diffs _(file system)_ | Geo with API | _Not implemented_ | | Blobs | External Merge Request Diffs _(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. @@ -63,8 +63,8 @@ is responsible for allowing access and operations on the locally stored Git repo on a machine with a single disk, multiple disks mounted as a single mount-point (like with a RAID array), or using LVM. -It requires no special filesystem and can work with NFS or a mounted Storage Appliance (there may be -performance limitations when using a remote filesystem). +It requires no special file system and can work with NFS or a mounted Storage Appliance (there may be +performance limitations when using a remote file system). Communication is done via Gitaly's own gRPC API. There are three possible ways of synchronization: @@ -88,13 +88,13 @@ Both types will be synced to a secondary node. GitLab stores files and blobs such as Issue attachments or LFS objects into either: -- The filesystem in a specific location. +- The file system in a specific location. - An [Object Storage](../../object_storage.md) solution. Object Storage solutions can be: - Cloud based like Amazon S3 Google Cloud Storage. - Hosted by you (like MinIO). - A Storage Appliance that exposes an Object Storage-compatible API. -When using the filesystem store instead of Object Storage, you need to use network mounted filesystems +When using the file system store instead of Object Storage, you need to use network mounted file systems to run GitLab when using more than one server. With respect to replication and verification: @@ -144,9 +144,9 @@ 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)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable them](#enable-or-disable-replication-for-some-data-types). **(FREE SELF)** -#### Enable or disable replication (for some data types) **(CORE ONLY)** +#### Enable or disable replication (for some data types) Replication for some data types are released behind feature flags that are **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../feature_flags.md) can opt to disable it for your instance. You can find feature flag names of each of those data types in the notes column of the table below. @@ -173,7 +173,7 @@ successfully, you must replicate their data using some other means. | Feature | Replicated (added in GitLab version) | Verified (added in GitLab version) | Object Storage replication (see [Geo with Object Storage](object_storage.md)) | Notes | |:---------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------|:----------------------------------------------------------|:-------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Application data in PostgreSQL](../../postgresql/index.md) | **Yes** (10.2) | **Yes** (10.2) | No | | -| [Project repository](../../..//user/project/repository/) | **Yes** (10.2) | **Yes** (10.7) | No | | +| [Project repository](../../../user/project/repository/) | **Yes** (10.2) | **Yes** (10.7) | No | | | [Project wiki repository](../../../user/project/wiki/) | **Yes** (10.2) | **Yes** (10.7) | No | | [Group wiki repository](../../../user/group/index.md#group-wikis) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/208147) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/208147) | No | | | [Uploads](../../uploads.md) | **Yes** (10.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | No | Verified only on transfer or manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them. | @@ -201,4 +201,4 @@ successfully, you must replicate their data using some other means. | [GitLab Pages](../../pages/index.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/589) | No | No | | | [CI Pipeline Artifacts](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/ci/pipeline_artifact.rb) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/238464) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Persists additional artifacts after a pipeline completes | | [Dependency proxy images](../../../user/packages/dependency_proxy/index.md) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/259694) | No | No | Blocked on [Geo: Secondary Mimicry](https://gitlab.com/groups/gitlab-org/-/epics/1528). Note that replication of this cache is not needed for Disaster Recovery purposes because it can be recreated from external sources. | -| [Vulnerability Export](../../../user/application_security/security_dashboard/#export-vulnerabilities) | [Not planned](https://gitlab.com/groups/gitlab-org/-/epics/3111) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Not planned because they are ephemeral and sensitive. They can be regenerated on demand. | +| [Vulnerability Export](../../../user/application_security/vulnerability_report/#export-vulnerabilities) | [Not planned](https://gitlab.com/groups/gitlab-org/-/epics/3111) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Not planned because they are ephemeral and sensitive. They can be regenerated on demand. | diff --git a/doc/administration/geo/replication/disable_geo.md b/doc/administration/geo/replication/disable_geo.md index e8767a56266..a26adcefef5 100644 --- a/doc/administration/geo/replication/disable_geo.md +++ b/doc/administration/geo/replication/disable_geo.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Disabling Geo **(PREMIUM ONLY)** +# Disabling Geo **(PREMIUM SELF)** If you want to revert to a regular Omnibus setup after a test, or you have encountered a Disaster Recovery situation and you want to disable Geo momentarily, you can use these instructions to disable your diff --git a/doc/administration/geo/replication/docker_registry.md b/doc/administration/geo/replication/docker_registry.md index f92a878662e..1669abbc52a 100644 --- a/doc/administration/geo/replication/docker_registry.md +++ b/doc/administration/geo/replication/docker_registry.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Docker Registry for a secondary node **(PREMIUM ONLY)** +# Docker Registry for a secondary node **(PREMIUM SELF)** You can set up a [Docker Registry](https://docs.docker.com/registry/) on your **secondary** Geo node that mirrors the one on the **primary** Geo node. diff --git a/doc/administration/geo/replication/external_database.md b/doc/administration/geo/replication/external_database.md deleted file mode 100644 index dfaf6819fa0..00000000000 --- a/doc/administration/geo/replication/external_database.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../setup/external_database.md' ---- - -This document was moved to [another location](../setup/external_database.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md index ab8199c3717..73a36f5e674 100644 --- a/doc/administration/geo/replication/faq.md +++ b/doc/administration/geo/replication/faq.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Geo Frequently Asked Questions **(PREMIUM ONLY)** +# Geo Frequently Asked Questions **(PREMIUM SELF)** ## What are the minimum requirements to run Geo? diff --git a/doc/administration/geo/replication/geo_validation_tests.md b/doc/administration/geo/replication/geo_validation_tests.md index 2d701458e66..f050d3e708c 100644 --- a/doc/administration/geo/replication/geo_validation_tests.md +++ b/doc/administration/geo/replication/geo_validation_tests.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Geo validation tests **(PREMIUM ONLY)** +# Geo validation tests **(PREMIUM SELF)** The Geo team performs manual testing and validation on common deployment configurations to ensure that Geo works when upgrading between minor GitLab versions and major PostgreSQL database versions. @@ -53,7 +53,7 @@ The following are GitLab upgrade validation tests we performed. - Outcome: Partial success because we did not run the looping pipeline during the demo to validate zero-downtime. - Follow up issues: - - [Clarify hup Puma/Unicorn should include deploy node](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5460) + - [Clarify how Puma/Unicorn should include deploy node](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5460) - [Investigate MR creation failure after upgrade to 12.9.10](https://gitlab.com/gitlab-org/gitlab/-/issues/223282) Closed as false positive. ### February 2020 @@ -128,7 +128,7 @@ The following are PostgreSQL upgrade validation tests we performed. PostgreSQL 12 with a database cluster on the primary is not recommended until the issues are resolved. - Known issues for PostgreSQL clusters: - [Ensure Patroni detects PostgreSQL update](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5423) - - [Allow configuring permanent replication slots in patroni](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5628) + - [Allow configuring permanent replication slots in Patroni](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5628) ### August 2020 diff --git a/doc/administration/geo/replication/high_availability.md b/doc/administration/geo/replication/high_availability.md deleted file mode 100644 index 1da4246db1f..00000000000 --- a/doc/administration/geo/replication/high_availability.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'multiple_servers.md' ---- - -This document was moved to [another location](multiple_servers.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/replication/location_aware_git_url.md b/doc/administration/geo/replication/location_aware_git_url.md index f2cf8c9bda0..0eea792d374 100644 --- a/doc/administration/geo/replication/location_aware_git_url.md +++ b/doc/administration/geo/replication/location_aware_git_url.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Location-aware Git remote URL with AWS Route53 **(PREMIUM ONLY)** +# Location-aware Git remote URL with AWS Route53 **(PREMIUM SELF)** You can provide GitLab users with a single remote URL that automatically uses the Geo node closest to them. This means users don't need to update their Git diff --git a/doc/administration/geo/replication/multiple_servers.md b/doc/administration/geo/replication/multiple_servers.md index 0ab972c9077..f83e0e14e54 100644 --- a/doc/administration/geo/replication/multiple_servers.md +++ b/doc/administration/geo/replication/multiple_servers.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Geo for multiple nodes **(PREMIUM ONLY)** +# Geo for multiple nodes **(PREMIUM SELF)** This document describes a minimal reference architecture for running Geo in a multi-node configuration. If your multi-node setup differs from the one diff --git a/doc/administration/geo/replication/object_storage.md b/doc/administration/geo/replication/object_storage.md index ce791d66b34..ad419f999b3 100644 --- a/doc/administration/geo/replication/object_storage.md +++ b/doc/administration/geo/replication/object_storage.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Geo with Object storage **(PREMIUM ONLY)** +# Geo with Object storage **(PREMIUM SELF)** Geo can be used in combination with Object Storage (AWS S3, or other compatible object storage). @@ -29,7 +29,7 @@ WARNING: 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. +whether they are stored on the local file system or in object storage. To enable GitLab replication, you must: diff --git a/doc/administration/geo/replication/remove_geo_node.md b/doc/administration/geo/replication/remove_geo_node.md index 519b93b447b..fd74c224a7f 100644 --- a/doc/administration/geo/replication/remove_geo_node.md +++ b/doc/administration/geo/replication/remove_geo_node.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Removing secondary Geo nodes **(PREMIUM ONLY)** +# Removing secondary Geo nodes **(PREMIUM SELF)** **Secondary** nodes can be removed from the Geo cluster using the Geo admin page of the **primary** node. To remove a **secondary** node: diff --git a/doc/administration/geo/replication/security_review.md b/doc/administration/geo/replication/security_review.md index 7c15662340c..70b58582435 100644 --- a/doc/administration/geo/replication/security_review.md +++ b/doc/administration/geo/replication/security_review.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Geo security review (Q&A) **(PREMIUM ONLY)** +# Geo security review (Q&A) **(PREMIUM SELF)** The following security review of the Geo feature set focuses on security aspects of the feature as they apply to customers running their own GitLab instances. The review @@ -194,7 +194,7 @@ from [owasp.org](https://owasp.org/). administrator via SSH, and then back out to the **secondary** node in the same manner. In particular, this includes the PostgreSQL replication credentials and a secret key (`db_key_base`) which is used to decrypt certain columns in the database. - The `db_key_base` secret is stored unencrypted on the filesystem, in + The `db_key_base` secret is stored unencrypted on the file system, in `/etc/gitlab/gitlab-secrets.json`, along with a number of other secrets. There is no at-rest protection for them. @@ -217,7 +217,7 @@ from [owasp.org](https://owasp.org/). - **Secondary** nodes and **primary** nodes interact via HTTP/HTTPS (secured with JSON web tokens) and via PostgreSQL streaming replication. -- Within a **primary** node or **secondary** node, the SSOT is the filesystem and the database +- Within a **primary** node or **secondary** node, the SSOT is the file system and the database (including Geo tracking database on **secondary** node). The various internal components are orchestrated to make alterations to these stores. @@ -231,7 +231,7 @@ from [owasp.org](https://owasp.org/). ### What data is or may need to be encrypted and what key management requirements have been defined? -- Neither **primary** nodes or **secondary** nodes encrypt Git repository or filesystem data at +- Neither **primary** nodes or **secondary** nodes encrypt Git repository or file system data at rest. A subset of database columns are encrypted at rest using the `db_otp_key`. - A static secret shared across all hosts in a GitLab deployment. - In transit, data should be encrypted, although the application does permit @@ -287,5 +287,5 @@ from [owasp.org](https://owasp.org/). ### What application auditing requirements have been defined? How are audit and debug logs accessed, stored, and secured? -- Structured JSON log is written to the filesystem, and can also be ingested +- Structured JSON log is written to the file system, and can also be ingested into a Kibana installation for further analysis. diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index 2c0160ed02a..3e9fb9d29e7 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Troubleshooting Geo **(PREMIUM ONLY)** +# Troubleshooting Geo **(PREMIUM SELF)** Setting up Geo requires careful attention to details and sometimes it's easy to miss a step. @@ -678,19 +678,19 @@ 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 +### Message: `ERROR - Replication is not up-to-date` during `gitlab-ctl promotion-preflight-checks` -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. +In GitLab 13.7 and earlier, if you have a data type with zero items to sync, +this command reports `ERROR - Replication is not up-to-date` even if +replication is actually up-to-date. This bug was fixed in GitLab 13.8 and +later. -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). +### Message: `ERROR - Replication is not up-to-date` during `gitlab-ctl promote-to-primary-node` + +In GitLab 13.7 and earlier, if you have a data type with zero items to sync, +this command reports `ERROR - Replication is not up-to-date` even if +replication is actually up-to-date. If replication and verification output +shows that it is complete, you can add `--skip-preflight-checks` to make the command complete promotion. This bug was fixed in GitLab 13.8 and later. ## Expired artifacts diff --git a/doc/administration/geo/replication/tuning.md b/doc/administration/geo/replication/tuning.md index 183180e5ade..535d1053744 100644 --- a/doc/administration/geo/replication/tuning.md +++ b/doc/administration/geo/replication/tuning.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Tuning Geo **(PREMIUM ONLY)** +# Tuning Geo **(PREMIUM SELF)** ## Changing the sync/verification capacity values diff --git a/doc/administration/geo/replication/updating_the_geo_nodes.md b/doc/administration/geo/replication/updating_the_geo_nodes.md index ff3a1e8689b..0c68adf162d 100644 --- a/doc/administration/geo/replication/updating_the_geo_nodes.md +++ b/doc/administration/geo/replication/updating_the_geo_nodes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Updating the Geo nodes **(PREMIUM ONLY)** +# Updating the Geo nodes **(PREMIUM SELF)** WARNING: Read these sections carefully before updating your Geo nodes. Not following diff --git a/doc/administration/geo/replication/using_a_geo_server.md b/doc/administration/geo/replication/using_a_geo_server.md index 743b1b384db..7578b6bf61a 100644 --- a/doc/administration/geo/replication/using_a_geo_server.md +++ b/doc/administration/geo/replication/using_a_geo_server.md @@ -7,7 +7,7 @@ type: howto <!-- Please update EE::GitLab::GeoGitAccess::GEO_SERVER_DOCS_URL if this file is moved) --> -# Using a Geo Server **(PREMIUM ONLY)** +# Using a Geo Server **(PREMIUM SELF)** 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. diff --git a/doc/administration/geo/replication/version_specific_updates.md b/doc/administration/geo/replication/version_specific_updates.md index 0d8eba555ab..be2ce0ac2c0 100644 --- a/doc/administration/geo/replication/version_specific_updates.md +++ b/doc/administration/geo/replication/version_specific_updates.md @@ -5,23 +5,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Version specific update instructions +# Version-specific update instructions -Check this document if it includes instructions for the version you are updating. -These steps go together with the [general steps](updating_the_geo_nodes.md#general-update-steps) +Review this page for update instructions for your version. These steps +accompany the [general steps](updating_the_geo_nodes.md#general-update-steps) for updating Geo nodes. +## Updating to GitLab 13.7 + +We've detected an issue with the `FetchRemove` call used by Geo secondaries. +This causes performance issues as we execute reference transaction hooks for +each updated reference. Delay any upgrade attempts until this is in the +[13.7.5 patch release.](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3002). +More details are available [in this issue](https://gitlab.com/gitlab-org/git/-/issues/79). + ## Updating to GitLab 13.5 -In GitLab 13.5, there is a [regression that prevents viewing a list of container repositories and registries](https://gitlab.com/gitlab-org/gitlab/-/issues/285475) on Geo secondaries. This issue is fixed in GitLab 13.6.1 and later. +GitLab 13.5 has a [regression that prevents viewing a list of container repositories and registries](https://gitlab.com/gitlab-org/gitlab/-/issues/285475) +on Geo secondaries. This issue is fixed in GitLab 13.6.1 and later. ## Updating to GitLab 13.3 -In GitLab 13.3, Geo removed the PostgreSQL [Foreign Data Wrapper](https://www.postgresql.org/docs/11/postgres-fdw.html) dependency for the tracking database. +In GitLab 13.3, Geo removed the PostgreSQL [Foreign Data Wrapper](https://www.postgresql.org/docs/11/postgres-fdw.html) +dependency for the tracking database. -The FDW server, user, and the extension will be removed during the upgrade process on each **secondary** node. The GitLab settings related to the FDW in the `/etc/gitlab/gitlab.rb` have been deprecated and can be safely removed. +The FDW server, user, and the extension will be removed during the upgrade +process on each secondary node. The GitLab settings related to the FDW in the +`/etc/gitlab/gitlab.rb` have been deprecated and can be safely removed. -There are some scenarios like using an external PostgreSQL instance for the tracking database where the FDW settings must be removed manually. Enter the PostgreSQL console of that instance and remove them: +There are some scenarios like using an external PostgreSQL instance for the +tracking database where the FDW settings must be removed manually. Enter the +PostgreSQL console of that instance and remove them: ```shell DROP SERVER gitlab_secondary CASCADE; @@ -36,7 +50,10 @@ upgrade to GitLab 13.4 or later. ## Updating to GitLab 13.2 -In GitLab 13.2, promoting a secondary node to a primary while the secondary is paused fails. **Do not pause replication before promoting a secondary.** If the node is paused, please resume before promoting. To avoid this issue, upgrade to GitLab 13.4 or later. +In GitLab 13.2, promoting a secondary node to a primary while the secondary is +paused fails. Do not pause replication before promoting a secondary. If the +node is paused, be sure to resume before promoting. To avoid this issue, +upgrade to GitLab 13.4 or later. ## Updating to GitLab 13.0 @@ -59,12 +76,13 @@ GitLab 12.9.0 through GitLab 12.9.3 are affected by [a bug that stops repository verification](https://gitlab.com/gitlab-org/gitlab/-/issues/213523). The issue is fixed in GitLab 12.9.4. Upgrade to GitLab 12.9.4 or later. -By default, GitLab 12.9 will attempt to automatically update the embedded -PostgreSQL server to 10.12 from 9.6, which requires downtime on secondaries -while reinitializing streaming replication. For the recommended procedure, see the +By default, GitLab 12.9 attempts to update the embedded PostgreSQL server +version from 9.6 to 10.12, which requires downtime on secondaries while +reinitializing streaming replication. For the recommended procedure, see the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). -This can be temporarily disabled by running the following before updating: +You can temporarily disable this behavior by running the following before +updating: ```shell sudo touch /etc/gitlab/disable-postgresql-upgrade @@ -72,12 +90,13 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade ## Updating to GitLab 12.8 -By default, GitLab 12.8 will attempt to automatically update the embedded -PostgreSQL server to 10.12 from 9.6, which requires downtime on secondaries -while reinitializing streaming replication. For the recommended procedure, see -the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). +By default, GitLab 12.8 attempts to update the embedded PostgreSQL server +version from 9.6 to 10.12, which requires downtime on secondaries while +reinitializing streaming replication. For the recommended procedure, see the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). -This can be temporarily disabled by running the following before updating: +You can temporarily disable this behavior by running the following before +updating: ```shell sudo touch /etc/gitlab/disable-postgresql-upgrade @@ -87,18 +106,17 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade WARNING: Only upgrade to GitLab 12.7.5 or later. Do not upgrade to versions 12.7.0 -through 12.7.4 because there is [an initialization order -bug](https://gitlab.com/gitlab-org/gitlab/-/issues/199672) that causes Geo -**secondaries** to set the incorrect database connection pool size. [The -fix](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24021) was +through 12.7.4 because there is [an initialization order bug](https://gitlab.com/gitlab-org/gitlab/-/issues/199672) that causes Geo secondaries to set the incorrect database connection pool size. +[The fix](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24021) was shipped in 12.7.5. -By default, GitLab 12.7 will attempt to automatically update the embedded -PostgreSQL server to 10.9 from 9.6, which requires downtime on secondaries -while reinitializing streaming replication. For the recommended procedure, see -the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). +By default, GitLab 12.7 attempts to update the embedded PostgreSQL server +version from 9.6 to 10.9, which requires downtime on secondaries while +reinitializing streaming replication. For the recommended procedure, see the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). -This can be temporarily disabled by running the following before updating: +You can temporarily disable this behavior by running the following before +updating: ```shell sudo touch /etc/gitlab/disable-postgresql-upgrade @@ -106,12 +124,13 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade ## Updating to GitLab 12.6 -By default, GitLab 12.6 will attempt to automatically update the embedded -PostgreSQL server to 10.9 from 9.6, which requires downtime on secondaries -while reinitializing streaming replication. For the recommended procedure, see -the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). +By default, GitLab 12.6 attempts to update the embedded PostgreSQL server +version from 9.6 to 10.9, which requires downtime on secondaries while +reinitializing streaming replication. For the recommended procedure, see the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). -This can be temporarily disabled by running the following before updating: +You can temporarily disable this behavior by running the following before +updating: ```shell sudo touch /etc/gitlab/disable-postgresql-upgrade @@ -119,12 +138,13 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade ## Updating to GitLab 12.5 -By default, GitLab 12.5 will attempt to automatically update the embedded -PostgreSQL server to 10.9 from 9.6, which requires downtime on secondaries -while reinitializing streaming replication. For the recommended procedure, see -the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). +By default, GitLab 12.5 attempts to update the embedded PostgreSQL server +version from 9.6 to 10.9, which requires downtime on secondaries while +reinitializing streaming replication. For the recommended procedure, see the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). -This can be temporarily disabled by running the following before updating: +You can temporarily disable this behavior by running the following before +updating: ```shell sudo touch /etc/gitlab/disable-postgresql-upgrade @@ -132,12 +152,13 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade ## Updating to GitLab 12.4 -By default, GitLab 12.4 will attempt to automatically update the embedded -PostgreSQL server to 10.9 from 9.6, which requires downtime on secondaries -while reinitializing streaming replication. For the recommended procedure, see -the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). +By default, GitLab 12.4 attempts to update the embedded PostgreSQL server +version from 9.6 to 10.9, which requires downtime on secondaries while +reinitializing streaming replication. For the recommended procedure, see the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). -This can be temporarily disabled by running the following before updating: +You can temporarily disable this behavior by running the following before +updating: ```shell sudo touch /etc/gitlab/disable-postgresql-upgrade @@ -146,9 +167,9 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade ## Updating to GitLab 12.3 WARNING: -If the existing PostgreSQL server version is 9.6.x, it is recommended to -upgrade to GitLab 12.4 or later. By default, GitLab 12.3 attempts to update the -embedded PostgreSQL server from 9.6 to 10.9. In certain circumstances, it will +If the existing PostgreSQL server version is 9.6.x, we recommend upgrading to +GitLab 12.4 or later. By default, GitLab 12.3 attempts to update the embedded +PostgreSQL server version from 9.6 to 10.9. In certain circumstances, it can fail. For more information, see the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). @@ -160,23 +181,23 @@ For the recommended procedure, see the ## Updating to GitLab 12.2 WARNING: -If the existing PostgreSQL server version is 9.6.x, it is recommended to -upgrade to GitLab 12.4 or later. By default, GitLab 12.2 attempts to update the -embedded PostgreSQL server from 9.6 to 10.9. In certain circumstances, it will +If the existing PostgreSQL server version is 9.6.x, we recommend upgrading to +GitLab 12.4 or later. By default, GitLab 12.2 attempts to update the embedded +PostgreSQL server version from 9.6 to 10.9. In certain circumstances, it can fail. For more information, see the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). -Additionally, if the PostgreSQL upgrade does not fail, a successful upgrade +Additionally, if the PostgreSQL upgrade doesn't fail, a successful upgrade requires downtime for secondaries while reinitializing streaming replication. For the recommended procedure, see the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). GitLab 12.2 includes the following minor PostgreSQL updates: -- To version `9.6.14` if you run PostgreSQL 9.6. -- To version `10.9` if you run PostgreSQL 10. +- To version `9.6.14`, if you run PostgreSQL 9.6. +- To version `10.9`, if you run PostgreSQL 10. -This update will occur even if major PostgreSQL updates are disabled. +This update occurs even if major PostgreSQL updates are disabled. Before [refreshing Foreign Data Wrapper during a Geo upgrade](https://docs.gitlab.com/omnibus/update/README.html#run-post-deployment-migrations-and-checks), restart the Geo tracking database: @@ -185,14 +206,15 @@ restart the Geo tracking database: sudo gitlab-ctl restart geo-postgresql ``` -The restart avoids a version mismatch when PostgreSQL tries to load the FDW extension. +The restart avoids a version mismatch when PostgreSQL tries to load the FDW +extension. ## Updating to GitLab 12.1 WARNING: -If the existing PostgreSQL server version is 9.6.x, it is recommended to -upgrade to GitLab 12.4 or later. By default, GitLab 12.1 attempts to update the -embedded PostgreSQL server from 9.6 to 10.9. In certain circumstances, it will +If the existing PostgreSQL server version is 9.6.x, we recommend upgrading to +GitLab 12.4 or later. By default, GitLab 12.1 attempts to update the embedded +PostgreSQL server version from 9.6 to 10.9. In certain circumstances, it can fail. For more information, see the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). @@ -206,419 +228,11 @@ For the recommended procedure, see the WARNING: This version is affected by a [bug that results in new LFS objects not being replicated to Geo secondary nodes](https://gitlab.com/gitlab-org/gitlab/-/issues/32696). -The issue is fixed in GitLab 12.1; be sure to upgrade to GitLab 12.1 or later. +The issue is fixed in GitLab 12.1. Be sure to upgrade to GitLab 12.1 or later. ## Updating to GitLab 11.11 WARNING: This version is affected by a [bug that results in new LFS objects not being replicated to Geo secondary nodes](https://gitlab.com/gitlab-org/gitlab/-/issues/32696). -The issue is fixed in GitLab 12.1; be sure to upgrade to GitLab 12.1 or later. - -## Updating to GitLab 10.8 - -Before 10.8, broadcast messages would not propagate without flushing -the cache on the **secondary** nodes. This has been fixed in 10.8, but -requires one last cache flush on each **secondary** node: - -```shell -sudo gitlab-rake cache:clear -``` - -## Updating to GitLab 10.6 - -In 10.4, we started to recommend that you define a password for database user (`gitlab`). - -We now require this change as we use this password to enable the Foreign Data Wrapper, as a way to optimize -the Geo Tracking Database. We are also improving security by disabling the use of **trust** -authentication method. - -1. **(primary)** Login to your **primary** node and run: - - ```shell - gitlab-ctl pg-password-md5 gitlab - # Enter password: <your_password_here> - # Confirm password: <your_password_here> - # fca0b89a972d69f00eb3ec98a5838484 - ``` - - Copy the generated hash and 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 Unicorn or Sidekiq needs to have the database - # password specified as below. - # This must be present in all application nodes. - gitlab_rails['db_password'] = '<your_password_here>' - ``` - - Still in the configuration file, locate and remove the `trust_auth_cidr_address`: - - ```ruby - postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/32','1.2.3.4/32'] # <- Remove this - ``` - -1. **(primary)** Reconfigure and restart: - - ```shell - sudo gitlab-ctl reconfigure - sudo gitlab-ctl restart - ``` - -1. **(secondary)** Login to all **secondary** nodes and 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 Unicorn or Sidekiq needs to have the database - # password specified as below. - # This must be present in all application nodes. - gitlab_rails['db_password'] = '<your_password_here>' - - # Enable Foreign Data Wrapper - geo_secondary['db_fdw'] = true - - # Secondary address in CIDR format, for example '5.6.7.8/32' - postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32'] - ``` - - Still in the configuration file, locate and remove the `trust_auth_cidr_address`: - - ```ruby - postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/32','5.6.7.8/32'] # <- Remove this - ``` - -1. **(secondary)** Reconfigure and restart: - - ```shell - sudo gitlab-ctl reconfigure - sudo gitlab-ctl restart - ``` - -## Updating to GitLab 10.5 - -For Geo Disaster Recovery to work with minimum downtime, your **secondary** node -should use the same set of secrets as the **primary** node. However, setup instructions -prior to the 10.5 release only synchronized the `db_key_base` secret. - -To rectify this error on existing installations, you should **overwrite** the -contents of `/etc/gitlab/gitlab-secrets.json` on each **secondary** node with the -contents of `/etc/gitlab/gitlab-secrets.json` on the **primary** node, then run the -following command on each **secondary** node: - -```shell -sudo gitlab-ctl reconfigure -``` - -If you do not perform this step, you may find that two-factor authentication -[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 -you should perform the step to [Manually replicate **primary** SSH host keys](configuration.md#step-2-manually-replicate-the-primary-nodes-ssh-host-keys) in each -**secondary** node. - -## Updating to GitLab 10.3 - -### Support for SSH repository synchronization removed - -In GitLab 10.2, synchronizing secondaries over SSH was deprecated. In 10.3, -support is removed entirely. All installations will switch to the HTTP/HTTPS -cloning method instead. Before updating, ensure that all your Geo nodes are -configured to use this method and that it works for your installation. In -particular, ensure that [Git access over HTTP/HTTPS is enabled](configuration.md#step-5-enable-git-access-over-httphttps). - -Synchronizing repositories over the public Internet using HTTP is insecure, so -you should ensure that you have HTTPS configured before updating. Note that -file synchronization is **also** insecure in these cases! - -## Updating to GitLab 10.2 - -### Secure PostgreSQL replication - -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](../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 -`gitlab-ctl replicate-geo-database`. - -### HTTPS repository sync - -Support for replicating repositories and wikis over HTTP/HTTPS has been added. -Replicating over SSH has been deprecated, and support for this option will be -removed in a future release. - -To switch to HTTP/HTTPS replication, log into the **primary** node as an admin and visit -**Admin Area > Geo** (`/admin/geo/nodes`). For each **secondary** node listed, -press the "Edit" button, change the "Repository cloning" setting from -"SSH (deprecated)" to "HTTP/HTTPS", and press "Save changes". This should take -effect immediately. - -Any new secondaries should be created using HTTP/HTTPS replication - this is the -default setting. - -After you've verified that HTTP/HTTPS replication is working, you should remove -the now-unused SSH keys from your secondaries, as they may cause problems if the -**secondary** node if ever promoted to a **primary** node: - -1. **(secondary)** Login to **all** your **secondary** nodes and run: - - ```ruby - sudo -u git -H rm ~git/.ssh/id_rsa ~git/.ssh/id_rsa.pub - ``` - -### Hashed Storage - -WARNING: -Hashed storage is in **Alpha**. It is considered experimental and not -production-ready. See [Hashed Storage](../../repository_storage_types.md) for more detail. - -If you previously enabled Hashed Storage and migrated all your existing -projects to Hashed Storage, disabling hashed storage will not migrate projects -to their previous project based storage path. As such, once enabled and -migrated we recommend leaving Hashed Storage enabled. - -## Updating to GitLab 10.1 - -WARNING: -Hashed storage is in **Alpha**. It is considered experimental and not -production-ready. See [Hashed Storage](../../repository_storage_types.md) for more detail. - -[Hashed storage](../../repository_storage_types.md) was introduced in -GitLab 10.0, and a [migration path](../../raketasks/storage.md) for -existing repositories was added in GitLab 10.1. - -## Updating to GitLab 10.0 - -In GitLab 10.0 and later, we require all **Geo** systems to [use SSH key lookups via -the database](../../operations/fast_ssh_key_lookup.md) to avoid having to maintain consistency of the -`authorized_keys` file for SSH access. Failing to do this will prevent users -from being able to clone via SSH. - -Note that in older versions of Geo, attachments downloaded on the **secondary** -nodes would be saved to the wrong directory. We recommend that you do the -following to clean this up. - -On the **secondary** Geo nodes, run as root: - -```shell -mv /var/opt/gitlab/gitlab-rails/working /var/opt/gitlab/gitlab-rails/working.old -mkdir /var/opt/gitlab/gitlab-rails/working -chmod 700 /var/opt/gitlab/gitlab-rails/working -chown git:git /var/opt/gitlab/gitlab-rails/working -``` - -You may delete `/var/opt/gitlab/gitlab-rails/working.old` any time. - -Once this is done, we advise restarting GitLab on the **secondary** nodes for the -new working directory to be used: - -```shell -sudo gitlab-ctl restart -``` - -## Updating from GitLab 9.3 or older - -If you started running Geo on GitLab 9.3 or older, we recommend that you -resync your **secondary** PostgreSQL databases to use replication slots. If you -started using Geo with GitLab 9.4 or 10.x, no further action should be -required because replication slots are used by default. However, if you -started with GitLab 9.3 and updated later, you should still follow the -instructions below. - -When in doubt, it doesn't hurt to do a resync. The easiest way to do this in -Omnibus is the following: - -1. Make sure you have Omnibus GitLab on the **primary** server. -1. Run `gitlab-ctl reconfigure` and `gitlab-ctl restart postgresql`. This will enable replication slots on the **primary** database. -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](../setup/database.md#step-3-initiate-the-replication-process). - -## Updating to GitLab 9.0 - -> **IMPORTANT**: -With GitLab 9.0, the PostgreSQL version is updated to 9.6 and manual steps are -required to update the **secondary** nodes and keep the Streaming Replication -working. Downtime is required, so plan ahead. - -The following steps apply only if you update from a 8.17 GitLab version to -9.0+. For previous versions, update to GitLab 8.17 first before attempting to -update to 9.0+. - ---- - -Make sure to follow the steps in the exact order as they appear below and pay -extra attention in what node (either **primary** or **secondary**) you execute them! Each step -is prepended with the relevant node for better clarity: - -1. **(secondary)** Log in to **all** your **secondary** nodes and stop all services: - - ```ruby - sudo gitlab-ctl stop - ``` - -1. **(secondary)** Make a backup of the `recovery.conf` file on **all** - **secondary** nodes to preserve PostgreSQL's credentials: - - ```shell - sudo cp /var/opt/gitlab/postgresql/data/recovery.conf /var/opt/gitlab/ - ``` - -1. **(primary)** Update the **primary** node to GitLab 9.0 following the - [regular update docs](../../../update/README.md). At the end of the - update, the **primary** node will be running with PostgreSQL 9.6. - -1. **(primary)** To prevent a de-synchronization of the repository replication, - stop all services except `postgresql` as we will use it to re-initialize the - **secondary** node's database: - - ```shell - sudo gitlab-ctl stop - sudo gitlab-ctl start postgresql - ``` - -1. **(secondary)** Run the following steps on each of the **secondary** nodes: - - 1. **(secondary)** Stop all services: - - ```shell - sudo gitlab-ctl stop - ``` - - 1. **(secondary)** Prevent running database migrations: - - ```shell - sudo touch /etc/gitlab/skip-auto-migrations - ``` - - 1. **(secondary)** Move the old database to another directory: - - ```shell - sudo mv /var/opt/gitlab/postgresql{,.bak} - ``` - - 1. **(secondary)** Update to GitLab 9.0 following the [regular update docs](../../../update/README.md). - At the end of the update, the node will be running with PostgreSQL 9.6. - - 1. **(secondary)** Make sure all services are up: - - ```shell - sudo gitlab-ctl start - ``` - - 1. **(secondary)** Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - - 1. **(secondary)** Run the PostgreSQL upgrade command: - - ```shell - sudo gitlab-ctl pg-upgrade - ``` - - 1. **(secondary)** See the stored credentials for the database that you will - need to re-initialize the replication: - - ```shell - sudo grep -s primary_conninfo /var/opt/gitlab/recovery.conf - ``` - - 1. **(secondary)** Save the snippet below in a file, let's say `/tmp/replica.sh`. Modify the - embedded paths if necessary: - - ```shell - #!/bin/bash - - PORT="5432" - USER="gitlab_replicator" - echo --------------------------------------------------------------- - echo WARNING: Make sure this script is run from the secondary server - echo --------------------------------------------------------------- - echo - echo Enter the IP or FQDN of the primary PostgreSQL server - read HOST - echo Enter the password for $USER@$HOST - read -s PASSWORD - echo Enter the required sslmode - read SSLMODE - - echo Stopping PostgreSQL and all GitLab services - sudo service gitlab stop - sudo service postgresql stop - - echo Backing up postgresql.conf - sudo -u postgres mv /var/opt/gitlab/postgresql/data/postgresql.conf /var/opt/gitlab/postgresql/ - - echo Cleaning up old cluster directory - sudo -u postgres rm -rf /var/opt/gitlab/postgresql/data - - echo Starting base backup as the replicator user - echo Enter the password for $USER@$HOST - sudo -u postgres /opt/gitlab/embedded/bin/pg_basebackup -h $HOST -D /var/opt/gitlab/postgresql/data -U gitlab_replicator -v -x -P - - echo Writing recovery.conf file - sudo -u postgres bash -c "cat > /var/opt/gitlab/postgresql/data/recovery.conf <<- _EOF1_ - standby_mode = 'on' - primary_conninfo = 'host=$HOST port=$PORT user=$USER password=$PASSWORD sslmode=$SSLMODE' - _EOF1_ - " - - echo Restoring postgresql.conf - sudo -u postgres mv /var/opt/gitlab/postgresql/postgresql.conf /var/opt/gitlab/postgresql/data/ - - echo Starting PostgreSQL - sudo service postgresql start - ``` - - 1. **(secondary)** Run the recovery script using the credentials from the - previous step: - - ```shell - sudo bash /tmp/replica.sh - ``` - - 1. **(secondary)** Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - - 1. **(secondary)** Start all services: - - ```shell - sudo gitlab-ctl start - ``` - - 1. **(secondary)** Repeat the steps for the remaining **secondary** nodes. - -1. **(primary)** After all **secondary** nodes are updated, start all services in - **primary** node: - - ```shell - sudo gitlab-ctl start - ``` - -### Update tracking database on **secondary** node - -After updating a **secondary** node, you might need to run migrations on the -tracking database. The tracking database was added in GitLab 9.1, and is -required in GitLab 10.0 and later. - -1. Run database migrations on tracking database: - - ```shell - sudo gitlab-rake geo:db:migrate - ``` - -1. Repeat this step for each **secondary** node. +The issue is fixed in GitLab 12.1. Be sure to upgrade to GitLab 12.1 or later. diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md index 95f67b20ab5..c9fd94bf2b2 100644 --- a/doc/administration/geo/setup/database.md +++ b/doc/administration/geo/setup/database.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Geo database replication **(PREMIUM ONLY)** +# Geo database replication **(PREMIUM SELF)** NOTE: If your GitLab installation uses external (not managed by Omnibus) PostgreSQL @@ -472,7 +472,7 @@ information, see [High Availability with Omnibus GitLab](../../postgresql/replic ## Patroni support Support for Patroni is intended to replace `repmgr` as a -[highly availabile PostgreSQL solution](../../postgresql/replication_and_failover.md) +[highly available PostgreSQL solution](../../postgresql/replication_and_failover.md) on the primary node, but it can also be used for PostgreSQL HA on a secondary node. @@ -489,7 +489,7 @@ This experimental implementation has the following limitations: - Whenever `gitlab-ctl reconfigure` runs on a Patroni Leader instance, there's a chance the node will be demoted due to the required short-time restart. To avoid this, you can pause auto-failover by running `gitlab-ctl patroni pause`. - After a reconfigure, it unpauses on its own. + After a reconfigure, it resumes on its own. For instructions about how to set up Patroni on the primary node, see the [PostgreSQL replication and failover with Omnibus GitLab](../../postgresql/replication_and_failover.md#patroni) page. @@ -644,8 +644,8 @@ With Patroni it's now possible to support that. In order to migrate the existing 1. [Configure a permanent replication slot](#step-1-configure-patroni-permanent-replication-slot-on-the-primary-site). 1. [Configure a Standby Cluster](#step-2-configure-a-standby-cluster-on-the-secondary-site) on that single node machine. - -You will end up with a "Standby Cluster" with a single node. That allows you to later on add additional patroni nodes + +You will end up with a "Standby Cluster" with a single node. That allows you to later on add additional Patroni nodes by following the same instructions above. ## Troubleshooting diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md index 1fb41fbb53a..8e7d8049467 100644 --- a/doc/administration/geo/setup/external_database.md +++ b/doc/administration/geo/setup/external_database.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Geo with external PostgreSQL instances **(PREMIUM ONLY)** +# Geo with external PostgreSQL instances **(PREMIUM SELF)** 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 diff --git a/doc/administration/git_annex.md b/doc/administration/git_annex.md index e21a8ac7e84..07b7b1730e3 100644 --- a/doc/administration/git_annex.md +++ b/doc/administration/git_annex.md @@ -38,7 +38,7 @@ very fast file copying tool. ## GitLab git-annex Configuration -`git-annex` is disabled by default in GitLab. Below you will find the +`git-annex` is disabled by default in GitLab. Below are the configuration options required to enable it. ### Requirements @@ -60,7 +60,7 @@ sudo yum install epel-release && sudo yum install git-annex ### Configuration for Omnibus packages For Omnibus GitLab packages, only one configuration setting is needed. -The Omnibus package will internally set the correct options in all locations. +The Omnibus package internally sets the correct options in all locations. 1. In `/etc/gitlab/gitlab.rb` add the following line: @@ -148,15 +148,15 @@ To example.com:group/project.git ok ``` -Your files can be found in the `master` branch, but you'll notice that there -are more branches created by the `annex sync` command. +Your files can be found in the `master` branch, but more branches are created +by the `annex sync` command. -Git Annex will also create a new directory at `.git/annex/` and will record the +Git Annex creates a new directory at `.git/annex/` and records the tracked files in the `.git/config` file. The files you assign to be tracked -with `git-annex` will not affect the existing `.git/config` records. The files +with `git-annex` don't affect the existing `.git/config` records. The files are turned into symbolic links that point to data in `.git/annex/objects/`. -The `debian.iso` file in the example will contain the symbolic link: +The `debian.iso` file in the example contain the symbolic link: ```plaintext .git/annex/objects/ZW/1k/SHA256E-s82701--6384039733b5035b559efd5a2e25a493ab6e09aabfd5162cc03f6f0ec238429d.png/SHA256E-s82701--6384039733b5035b559efd5a2e25a493ab6e09aabfd5162cc03f6f0ec238429d.iso @@ -167,7 +167,7 @@ repository. --- -Downloading a single large file is also very simple: +You can download a single large file with these commands: ```shell git clone git@gitlab.example.com:group/project.git @@ -185,7 +185,7 @@ git annex sync --content # sync Git branches and download all the large files ``` By using `git-annex` without GitLab, anyone that can access the server can also -access the files of all projects, but GitLab Annex ensures that you can only +access the files of all projects. GitLab Annex ensures that you can only access files of projects you have access to (developer, maintainer, or owner role). ## How it works diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index ca4fa0549d0..e034314f6ce 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -29,11 +29,11 @@ server to accept the `GIT_PROTOCOL` environment. In installations using [GitLab Helm Charts](https://docs.gitlab.com/charts/) and [All-in-one Docker image](https://docs.gitlab.com/omnibus/docker/), the SSH -service is already configured to accept the `GIT_PROTOCOL` environment and users +service is already configured to accept the `GIT_PROTOCOL` environment. Users need not do anything more. -For Omnibus GitLab and installations from source, you have to manually update -the SSH configuration of your server by adding the line below to the `/etc/ssh/sshd_config` file: +For Omnibus GitLab and installations from source, update +the SSH configuration of your server manually by adding this line to the `/etc/ssh/sshd_config` file: ```plaintext AcceptEnv GIT_PROTOCOL diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 9577fb40abe..6738b912dab 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -40,7 +40,7 @@ The following is a high-level architecture overview of how Gitaly is used. ## Configure Gitaly -The Gitaly service itself is configured via a [TOML configuration file](reference.md). +The Gitaly service itself is configured by using a [TOML configuration file](reference.md). To change Gitaly settings: @@ -121,7 +121,7 @@ The following list depicts the network architecture of Gitaly: - GitLab Shell. - Elasticsearch indexer. - Gitaly itself. -- A Gitaly server must be able to make RPC calls **to itself** via its own +- A Gitaly server must be able to make RPC calls **to itself** by using its own `(Gitaly address, Gitaly token)` pair as specified in `/config/gitlab.yml`. - Authentication is done through a static token which is shared among the Gitaly and GitLab Rails nodes. @@ -502,8 +502,8 @@ If it's excluded, default Git storage directory is used for that storage shard. ### Disable Gitaly where not required (optional) -If you are running Gitaly [as a remote service](#run-gitaly-on-its-own-server), you may want to -disable the local Gitaly service that runs on your GitLab server by default and have it only running +If you run Gitaly [as a remote service](#run-gitaly-on-its-own-server), consider +disabling the local Gitaly service that runs on your GitLab server by default, and only run it where required. Disabling Gitaly on the GitLab instance only makes sense when you run GitLab in a custom cluster configuration, where @@ -538,7 +538,7 @@ To disable Gitaly on a GitLab server: > - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/3160) in GitLab 13.6, outgoing TLS connections to GitLab provide client certificates if configured. Gitaly supports TLS encryption. To communicate with a Gitaly instance that listens for secure -connections, you must use `tls://` URL scheme in the `gitaly_address` of the corresponding +connections, use the `tls://` URL scheme in the `gitaly_address` of the corresponding storage entry in the GitLab configuration. Gitaly provides the same server certificates as client certificates in TLS @@ -935,12 +935,13 @@ Note that `enforced="true"` means that authentication is being enforced. ## Direct Git access bypassing Gitaly -While it is possible to access Gitaly repositories stored on disk directly with a Git client, -it is not advisable because Gitaly is being continuously improved and changed. Theses improvements may invalidate assumptions, resulting in performance degradation, instability, and even data loss. +GitLab doesn't advise directly accessing Gitaly repositories stored on disk with +a Git client, because Gitaly is being continuously improved and changed. These +improvements may invalidate assumptions, resulting in performance degradation, instability, and even data loss. Gitaly has optimizations, such as the [`info/refs` advertisement cache](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/design_diskcache.md), -that rely on Gitaly controlling and monitoring access to repositories via the +that rely on Gitaly controlling and monitoring access to repositories by using the official gRPC interface. Likewise, Praefect has optimizations, such as fault tolerance and distributed reads, that depend on the gRPC interface and database to determine repository state. @@ -979,11 +980,11 @@ lookup. Even when Gitaly is able to re-use an already-running `git` process (for a commit), you still have: - The cost of a network roundtrip to Gitaly. -- Within Gitaly, a write/read roundtrip on the Unix pipes that connect Gitaly to the `git` process. +- Inside Gitaly, a write/read roundtrip on the Unix pipes that connect Gitaly to the `git` process. Using GitLab.com to measure, we reduced the number of Gitaly calls per request until the loss of Rugged's efficiency was no longer felt. It also helped that we run Gitaly itself directly on the Git -file severs, rather than via NFS mounts. This gave us a speed boost that counteracted the negative +file severs, rather than by using NFS mounts. This gave us a speed boost that counteracted the negative effect of not using Rugged anymore. Unfortunately, other deployments of GitLab could not remove NFS like we did on GitLab.com, and they @@ -1018,7 +1019,7 @@ The result of these checks is cached. To see if GitLab can access the repository file system directly, we use the following heuristic: - Gitaly ensures that the file system has a metadata file in its root with a UUID in it. -- Gitaly reports this UUID to GitLab via the `ServerInfo` RPC. +- Gitaly reports this UUID to GitLab by using the `ServerInfo` RPC. - GitLab Rails tries to read the metadata file directly. If it exists, and if the UUID's match, assume we have direct access. @@ -1085,7 +1086,7 @@ app nodes). ### Client side gRPC logs Gitaly uses the [gRPC](https://grpc.io/) RPC framework. The Ruby gRPC -client has its own log file which may contain useful information when +client has its own log file which may contain debugging information when you are seeing Gitaly errors. You can control the log level of the gRPC client with the `GRPC_LOG_LEVEL` environment variable. The default level is `WARN`. @@ -1100,7 +1101,7 @@ sudo GRPC_TRACE=all GRPC_VERBOSITY=DEBUG gitlab-rake gitlab:gitaly:check 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 +One method for doing this is by using `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 @@ -1137,16 +1138,19 @@ sum(rate(grpc_client_handled_total[5m])) by (grpc_method) > 0 ### Repository changes fail with a `401 Unauthorized` error -If you're running Gitaly on its own server and notice that users can -successfully clone and fetch repositories (via both SSH and HTTPS), but can't -push to them or make changes to the repository in the web UI without getting a -`401 Unauthorized` message, then it's possible Gitaly is failing to authenticate -with the Gitaly client due to having the [wrong secrets file](#configure-gitaly-servers). +If you run Gitaly on its own server and notice these conditions: + +- Users can successfully clone and fetch repositories by using both SSH and HTTPS. +- Users can't push to repositories, or receive a `401 Unauthorized` message when attempting to + make changes to them in the web UI. + +Gitaly may be failing to authenticate with the Gitaly client because it has the +[wrong secrets file](#configure-gitaly-servers). Confirm the following are all true: - When any user performs a `git push` to any repository on this Gitaly server, it - fails with the following error (note the `401 Unauthorized`): + fails with a `401 Unauthorized` error: ```shell remote: GitLab: 401 Unauthorized @@ -1158,7 +1162,7 @@ Confirm the following are all true: - When any user adds or modifies a file from the repository using the GitLab UI, it immediately fails with a red `401 Unauthorized` banner. - Creating a new project and [initializing it with a README](../../gitlab-basics/create-project.md#blank-projects) - successfully creates the project but doesn't create the README. + successfully creates the project, but doesn't create the README. - When [tailing the logs](https://docs.gitlab.com/omnibus/settings/logs.html#tail-logs-in-a-console-on-the-server) on a Gitaly client and reproducing the error, you get `401` errors when reaching the `/api/v4/internal/allowed` endpoint: @@ -1229,11 +1233,11 @@ update the secrets file on the Gitaly server to match the Gitaly client, then ### Command line tools cannot connect to Gitaly -If you are having trouble connecting to a Gitaly server with command line (CLI) tools, +If you can't connect to a Gitaly server with command line (CLI) tools, and certain actions result in a `14: Connect Failed` error message, -it means that gRPC cannot reach your Gitaly server. +gRPC cannot reach your Gitaly server. -Verify that you can reach Gitaly via TCP: +Verify you can reach Gitaly by using TCP: ```shell sudo gitlab-rake gitlab:tcp_check[GITALY_SERVER_IP,GITALY_LISTEN_PORT] diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index fe8b3e5f566..b4fd607c4be 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -5,12 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Gitaly Cluster **(CORE ONLY)** +# Gitaly Cluster **(FREE SELF)** [Gitaly](index.md), the service that provides storage for Git repositories, can be run in a clustered configuration to increase fault tolerance. In this configuration, every Git repository is stored on every Gitaly node in the -cluster. Multiple clusters (or shards) can be configured. +cluster. Multiple clusters (or storage shards) can be configured. NOTE: Technical support for Gitaly clusters is limited to GitLab Premium and Ultimate @@ -21,7 +21,7 @@ component for running a Gitaly Cluster.  -Using a Gitaly Cluster increase fault tolerance by: +Using a Gitaly Cluster increases fault tolerance by: - Replicating write operations to warm standby Gitaly nodes. - Detecting Gitaly node failures. @@ -53,7 +53,7 @@ Gitaly Cluster supports: - Reporting of possible data loss if replication queue is non-empty. - Marking repositories as [read only](#read-only-mode) if data loss is detected to prevent data inconsistencies. -Follow the [HA Gitaly epic](https://gitlab.com/groups/gitlab-org/-/epics/1489) +Follow the [Gitaly Cluster epic](https://gitlab.com/groups/gitlab-org/-/epics/1489) for improvements including [horizontally distributing reads](https://gitlab.com/groups/gitlab-org/-/epics/2013). @@ -65,7 +65,7 @@ Gitaly Cluster and [Geo](../geo/index.md) both provide redundancy. However the r not aware when Gitaly Cluster is used. - Geo provides [replication](../geo/index.md) and [disaster recovery](../geo/disaster_recovery/index.md) for an entire instance of GitLab. Users know when they are using Geo for - [replication](../geo/index.md). Geo [replicates multiple datatypes](../geo/replication/datatypes.md#limitations-on-replicationverification), + [replication](../geo/index.md). Geo [replicates multiple data types](../geo/replication/datatypes.md#limitations-on-replicationverification), including Git data. The following table outlines the major differences between Gitaly Cluster and Geo: @@ -80,23 +80,65 @@ For more information, see: - [Gitaly architecture](index.md#architecture). - Geo [use cases](../geo/index.md#use-cases) and [architecture](../geo/index.md#architecture). -## Cluster or shard +## Where Gitaly Cluster fits + +GitLab accesses [repositories](../../user/project/repository/index.md) through the configured +[repository storages](../repository_storage_paths.md). Each new repository is stored on one of the +repository storages based on their configured weights. Each repository storage is either: + +- A Gitaly storage served directly by Gitaly. These map to a directory on the file system of a + Gitaly node. +- A [virtual storage](#virtual-storage-or-direct-gitaly-storage) served by Praefect. A virtual + storage is a cluster of Gitaly storages that appear as a single repository storage. + +Virtual storages are a feature of Gitaly Cluster. They support replicating the repositories to +multiple storages for fault tolerance. Virtual storages can improve performance by distributing +requests across Gitaly nodes. Their distributed nature makes it viable to have a single repository +storage in GitLab to simplify repository management. + +## Components of Gitaly Cluster + +Gitaly Cluster consists of multiple components: + +- [Load balancer](#load-balancer) for distributing requests and providing fault-tolerant access to + Praefect nodes. +- [Praefect](#praefect) nodes for managing the cluster and routing requests to Gitaly nodes. +- [PostgreSQL database](#postgresql) for persisting cluster metadata and [PgBouncer](#pgbouncer), + recommended for pooling Praefect's database connections. +- [Gitaly](index.md) nodes to provide repository storage and Git access. + + + +In this example: + +- Repositories are stored on a virtual storage called `storage-1`. +- Three Gitaly nodes provide `storage-1` access: `gitaly-1`, `gitaly-2`, and `gitaly-3`. +- The three Gitaly nodes store data on their file systems. + +### Virtual storage or direct Gitaly storage Gitaly supports multiple models of scaling: - Clustering using Gitaly Cluster, where each repository is stored on multiple Gitaly nodes in the cluster. Read requests are distributed between repository replicas and write requests are - broadcast to repository replicas. -- Sharding using [repository storage paths](../repository_storage_paths.md), where each repository - is stored on the assigned Gitaly node. All requests are routed to this node. + broadcast to repository replicas. GitLab accesses virtual storage. +- Direct access to Gitaly storage using [repository storage paths](../repository_storage_paths.md), + where each repository is stored on the assigned Gitaly node. All requests are routed to this node. + +The following is Gitaly set up to use direct access to Gitaly instead of Gitaly Cluster: + + -| Cluster | Shard | -|:--------------------------------------------------|:----------------------------------------------| -|  |  | +In this example: -Generally, Gitaly Cluster can replace sharded configurations, at the expense of additional storage -needed to store each repository on multiple Gitaly nodes. The benefit of using Gitaly Cluster over -sharding is: +- Each repository is stored on one of three Gitaly storages: `storage-1`, `storage-2`, + or `storage-3`. +- Each storage is serviced by a Gitaly node. +- The three Gitaly nodes store data in three separate hashed storage locations. + +Generally, virtual storage with Gitaly Cluster can replace direct Gitaly storage configurations, at +the expense of additional storage needed to store each repository on multiple Gitaly nodes. The +benefit of using Gitaly Cluster over direct Gitaly storage is: - Improved fault tolerance, because each Gitaly node has a copy of every repository. - Improved resource utilization, reducing the need for over-provisioning for shard-specific peak @@ -105,7 +147,7 @@ sharding is: replicas. - Simpler management, because all Gitaly nodes are identical. -Under some workloads, CPU and memory requirements may require a large fleet of Gitaly nodes and it +Under some workloads, CPU and memory requirements may require a large fleet of Gitaly nodes. It can be uneconomical to have one to one replication factor. A hybrid approach can be used in these instances, where each shard is configured as a smaller @@ -168,7 +210,7 @@ If you are using Google Cloud Platform, SoftLayer, or any other vendor that prov The communication between components is secured with different secrets, which are described below. Before you begin, generate a unique secret for each, and -make note of it. This makes it easy to replace these placeholder tokens +make note of it. This enables you to replace these placeholder tokens with secure tokens as you complete the setup process. 1. `GITLAB_SHELL_SECRET_TOKEN`: this is used by Git hooks to make callback HTTP @@ -260,13 +302,12 @@ this, set the corresponding IP or host address of the PgBouncer instance in - `praefect['database_port']`, for the port. Because PgBouncer manages resources more efficiently, Praefect still requires a -direct connection to the PostgreSQL database because it uses +direct connection to the PostgreSQL database. It uses the [LISTEN](https://www.postgresql.org/docs/11/sql-listen.html) -functionality that is [not supported](https://www.pgbouncer.org/features.html) by +feature that is [not supported](https://www.pgbouncer.org/features.html) by PgBouncer with `pool_mode = transaction`. - -Therefore, `praefect['database_host_no_proxy']` and `praefect['database_port_no_proxy']` -should be set to a direct connection and not a PgBouncer connection. +Set `praefect['database_host_no_proxy']` and `praefect['database_port_no_proxy']` +to a direct connection, and not a PgBouncer connection. Save the changes to `/etc/gitlab/gitlab.rb` and [reconfigure Praefect](../restart_gitlab.md#omnibus-gitlab-reconfigure). @@ -774,7 +815,7 @@ configuration. ### Load Balancer -In a highly available Gitaly configuration, a load balancer is needed to route +In a fault-tolerant Gitaly configuration, a load balancer is needed to route internal traffic from the GitLab application to the Praefect nodes. The specifics on which load balancer to use or the exact configuration is beyond the scope of the GitLab documentation. @@ -786,7 +827,7 @@ addition to the GitLab nodes. Some requests handled by process. `gitaly-ruby` uses the Gitaly address set in the GitLab server's `git_data_dirs` setting to make this connection. -We hope that if you’re managing HA systems like GitLab, you have a load balancer +We hope that if you’re managing fault-tolerant systems like GitLab, you have a load balancer of choice already. Some examples include [HAProxy](https://www.haproxy.org/) (open-source), [Google Internal Load Balancer](https://cloud.google.com/load-balancing/docs/internal/), [AWS Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/), F5 @@ -960,14 +1001,14 @@ To get started quickly: gitlab-ctl reconfigure ``` -1. Set the Grafana admin password. This command prompts you to enter a new +1. Set the Grafana administrator password. This command prompts you to enter a new password: ```shell gitlab-ctl set-grafana-password ``` -1. In your web browser, open `/-/grafana` (e.g. +1. In your web browser, open `/-/grafana` (such as `https://gitlab.example.com/-/grafana`) on your GitLab server. Login using the password you set, and the username `admin`. @@ -975,7 +1016,7 @@ To get started quickly: 1. Go to **Explore** and query `gitlab_build_info` to verify that you are getting metrics from all your machines. -Congratulations! You've configured an observable highly available Praefect +Congratulations! You've configured an observable fault-tolerant Praefect cluster. ## Distributed reads @@ -983,18 +1024,12 @@ cluster. > - Introduced in GitLab 13.1 in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) with feature flag `gitaly_distributed_reads` set to disabled. > - [Made generally available and enabled by default](https://gitlab.com/gitlab-org/gitaly/-/issues/2951) in GitLab 13.3. > - [Disabled by default](https://gitlab.com/gitlab-org/gitaly/-/issues/3178) in GitLab 13.5. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitaly/-/issues/3334) in GitLab 13.8. Praefect supports distribution of read operations across Gitaly nodes that are configured for the virtual node. -The feature is disabled by default. To enable distributed reads, the `gitaly_distributed_reads` -[feature flag](../feature_flags.md) must be enabled in a Ruby console: - -```ruby -Feature.enable(:gitaly_distributed_reads) -``` - -If enabled, all RPCs marked with `ACCESSOR` option like +All RPCs marked with `ACCESSOR` option like [GetBlob](https://gitlab.com/gitlab-org/gitaly/-/blob/v12.10.6/proto/blob.proto#L16) are redirected to an up to date and healthy Gitaly node. @@ -1025,9 +1060,8 @@ Praefect guarantees eventual consistency by replicating all writes to secondary after the write to the primary Gitaly node has happened. Praefect can instead provide strong consistency by creating a transaction and writing -changes to all Gitaly nodes at once. Strong consistency is currently in -[alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) and not enabled by -default. If enabled, transactions are only available for a subset of RPCs. For more +changes to all Gitaly nodes at once. +If enabled, transactions are only available for a subset of RPCs. For more information, see the [strong consistency epic](https://gitlab.com/groups/gitlab-org/-/epics/1189). To enable strong consistency: @@ -1092,7 +1126,7 @@ specific storage nodes to host a repository. support configuring a default replication factor for a virtual storage. The default replication factor is applied to every newly-created repository. -Prafect does not store the actual replication factor, but assigns enough storages to host the repository +Praefect does not store the actual replication factor, but assigns enough storages to host the repository so the desired replication factor is met. If a storage node is later removed from the virtual storage, the replication factor of repositories assigned to the storage is decreased accordingly. @@ -1171,8 +1205,8 @@ To enable writes again, an administrator can: ### Check for data loss -The Praefect `dataloss` sub-command identifies replicas that are likely to be outdated. This is -useful for identifying potential data loss after a failover. The following parameters are +The Praefect `dataloss` sub-command identifies replicas that are likely to be outdated. This can help +identify potential data loss after a failover. The following parameters are available: - `-virtual-storage` that specifies which virtual storage to check. The default behavior is to @@ -1196,7 +1230,7 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t ``` Repositories which have assigned storage nodes that contain an outdated copy of the repository are listed -in the output. A number of useful information is printed for each repository: +in the output. This information is printed for each repository: - A repository's relative path to the storage directory identifies each repository and groups the related information. @@ -1213,7 +1247,7 @@ in the output. A number of useful information is printed for each repository: Whether a replica is assigned to host the repository is listed with each replica's status. `assigned host` is printed next to replicas which are assigned to store the repository. The text is omitted if the replica contains a copy of -the repository but is not assigned to store the repository. Such replicas won't be kept in-sync by Praefect but may +the repository but is not assigned to store the repository. Such replicas aren't kept in-sync by Praefect, but may act as replication sources to bring assigned replicas up to date. Example output: @@ -1282,7 +1316,7 @@ To check a project's repository checksums across on all Gitaly nodes, run the ### Enable writes or accept data loss -Praefect provides the following subcommands to re-enable writes: +Praefect provides the following sub-commands to re-enable writes: - In GitLab 13.2 and earlier, `enable-writes` to re-enable virtual storage for writes after data recovery attempts. @@ -1324,7 +1358,7 @@ These tools reconcile the outdated repositories to bring them fully up to date a 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 +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. @@ -1383,7 +1417,7 @@ To move repositories to Gitaly Cluster: - The moves are in progress. Re-query the repository move until it completes successfully. - The moves have failed. Most failures are temporary and are solved by rescheduling the move. -1. Once the moves are complete, [query projects](../../api/projects.md#list-all-projects) +1. After the moves are complete, [query projects](../../api/projects.md#list-all-projects) using the API to confirm that all projects have moved. No projects should be returned with `repository_storage` field set to the old storage. diff --git a/doc/administration/gitaly/reference.md b/doc/administration/gitaly/reference.md index 5a004d97220..5105b9ed0d4 100644 --- a/doc/administration/gitaly/reference.md +++ b/doc/administration/gitaly/reference.md @@ -95,13 +95,13 @@ key_path = '/home/git/key.pem' ### Storage -GitLab repositories are grouped into directories known as "storages" -(e.g., `/home/git/repositories`) containing bare repositories managed -by GitLab with names (e.g., `default`). +GitLab repositories are grouped into directories known as storages, such as +`/home/git/repositories`. They contain bare repositories managed +by GitLab with names, such as `default`. These names and paths are also defined in the `gitlab.yml` configuration file of -GitLab. When you run Gitaly on the same machine as GitLab, which is the default -and recommended configuration, storage paths defined in Gitaly's `config.toml` +GitLab. When you run Gitaly on the same machine as GitLab (the default +and recommended configuration) storage paths defined in Gitaly's `config.toml` must match those in `gitlab.yml`. | Name | Type | Required | Description | @@ -232,9 +232,9 @@ The following values configure logging in Gitaly under the `[logging]` section. | ---- | ---- | -------- | ----------- | | `format` | string | no | Log format: `text` or `json`. Default: `text`. | | `level` | string | no | Log level: `debug`, `info`, `warn`, `error`, `fatal`, or `panic`. Default: `info`. | -| `sentry_dsn` | string | no | Sentry DSN for exception monitoring. | +| `sentry_dsn` | string | no | Sentry DSN (Data Source Name) for exception monitoring. | | `sentry_environment` | string | no | [Sentry Environment](https://docs.sentry.io/product/sentry-basics/environments/) for exception monitoring. | -| `ruby_sentry_dsn` | string | no | Sentry DSN for `gitaly-ruby` exception monitoring. | +| `ruby_sentry_dsn` | string | no | Sentry DSN (Data Source Name) for `gitaly-ruby` exception monitoring. | While the main Gitaly application logs go to `stdout`, there are some extra log files that go to a configured directory, like the GitLab Shell logs. diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index 178fc438df2..8f369a05fbf 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -49,7 +49,7 @@ It is ultimately performed by the Gitaly RPC `FetchIntoObjectPool`. This is the current call stack by which it is invoked: 1. `Repositories::HousekeepingService#execute_gitlab_shell_gc` -1. `GitGarbageCollectWorker#perform` +1. `Projects::GitGarbageCollectWorker#perform` 1. `Projects::GitDeduplicationService#fetch_from_source` 1. `ObjectPool#fetch` 1. `ObjectPoolService#fetch` diff --git a/doc/administration/img/time_zone_settings.png b/doc/administration/img/time_zone_settings.png Binary files differnew file mode 100644 index 00000000000..73961b1090c --- /dev/null +++ b/doc/administration/img/time_zone_settings.png diff --git a/doc/administration/index.md b/doc/administration/index.md index f071fde2faa..f70948c63df 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated description: 'Learn how to install, configure, update, and maintain your GitLab instance.' --- -# Administrator documentation **(CORE ONLY)** +# Administrator documentation **(FREE SELF)** Learn how to administer your self-managed GitLab instance. @@ -17,7 +17,7 @@ GitLab has two product distributions available through [different subscriptions] You can [install either GitLab CE or GitLab EE](https://about.gitlab.com/install/ce-or-ee/). However, the features you have access to depend on your chosen [subscription](https://about.gitlab.com/pricing/). -GitLab Community Edition installations have access only to Core features. +GitLab Community Edition installations have access only to Free features. Non-administrator users can't access GitLab administration tools and settings. @@ -80,6 +80,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. emails with S/MIME. - [Enabling and disabling features flags](feature_flags.md): how to enable and disable GitLab features deployed behind feature flags. +- [Application settings cache expiry interval](application_settings_cache.md) #### Customizing GitLab appearance @@ -101,6 +102,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. #### Updating GitLab - [GitLab versions and maintenance policy](../policy/maintenance.md): Understand GitLab versions and releases (Major, Minor, Patch, Security), as well as update recommendations. +- [GitLab in maintenance mode](maintenance_mode/index.md): Put GitLab in maintenance mode. - [Update GitLab](../update/README.md): Update guides to upgrade your installation to a new version. - [Upgrading without downtime](../update/README.md#upgrading-without-downtime): Upgrade to a newer major, minor, or patch version of GitLab without taking your GitLab instance offline. - [Migrate your GitLab CI/CD data to another version of GitLab](../migrate_ci_to_ce/README.md): If you have an old GitLab installation (older than 8.0), follow this guide to migrate your existing GitLab CI/CD data to another version of GitLab. @@ -186,7 +188,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. ## Git configuration options -- [Server hooks](server_hooks.md): Server hooks (on the filesystem) for when webhooks aren't enough. +- [Server hooks](server_hooks.md): Server hooks (on the file system) for when webhooks aren't enough. - [Git LFS configuration](lfs/index.md): Learn how to configure LFS for GitLab. - [Housekeeping](housekeeping.md): Keep your Git repositories tidy and fast. - [Configuring Git Protocol v2](git_protocol.md): Git protocol version 2 support. diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index 0eede5f3ca5..882928a3628 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -127,6 +127,15 @@ It's possible that this limit will be changed to a lower number in the future. - **Max size:** ~1 million characters / ~1 MB +## Size of commit titles and descriptions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292039) in GitLab 13.9 + +Commits with arbitrarily large messages may be pushed to GitLab, but when +displaying commits, titles (the first line of the commit message) will be +limited to 1KiB, and descriptions (the rest of the message) will be limited to +1MiB. + ## Number of issues in the milestone overview > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39453) in GitLab 12.10. diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index 8f33ddf3ca5..56a305fa4da 100644 --- a/doc/administration/instance_review.md +++ b/doc/administration/instance_review.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Instance Review -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6995) in [GitLab Core](https://about.gitlab.com/pricing/) 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6995) in [GitLab Free](https://about.gitlab.com/pricing/) 11.3. If you run a medium-sized self-managed instance (50+ users) of a free version of GitLab, [either Community Edition or unlicensed Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/), diff --git a/doc/administration/integration/kroki.md b/doc/administration/integration/kroki.md index dead5640873..5e458399773 100644 --- a/doc/administration/integration/kroki.md +++ b/doc/administration/integration/kroki.md @@ -1,4 +1,10 @@ -# Kroki diagrams **(CORE ONLY)** +--- +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/#assignments +--- + +# Kroki diagrams **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241744) in GitLab 13.7. @@ -24,6 +30,8 @@ The **Kroki URL** is the hostname of the server running the container. The [`yuzutech/kroki`](https://hub.docker.com/r/yuzutech/kroki) image contains the following diagrams libraries out-of-the-box: +<!-- vale gitlab.Spelling = NO --> + - [Bytefield](https://bytefield-svg.deepsymmetry.org/) - [Ditaa](http://ditaa.sourceforge.net) - [Erd](https://github.com/BurntSushi/erd) @@ -37,6 +45,8 @@ The [`yuzutech/kroki`](https://hub.docker.com/r/yuzutech/kroki) image contains t - [Vega-Lite](https://github.com/vega/vega-lite) - [WaveDrom](https://wavedrom.com/) +<!-- vale gitlab.Spelling = YES --> + If you want to use additional diagram libraries, read the [Kroki installation](https://docs.kroki.io/kroki/setup/install/#_images) to learn how to start Kroki companion containers. @@ -138,8 +148,12 @@ Rel(banking_system, mainframe, "Uses")  +<!-- vale gitlab.Spelling = NO --> + **Nomnoml** +<!-- vale gitlab.Spelling = YES --> + ```plaintext [nomnoml] .... @@ -159,4 +173,4 @@ Rel(banking_system, mainframe, "Uses") .... ``` - + diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index cd61dc9a2bf..5f6222f1169 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -10,13 +10,13 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8537) in GitLab 8.16. When [PlantUML](https://plantuml.com) integration is enabled and configured in -GitLab we are able to create simple diagrams in AsciiDoc and Markdown documents +GitLab you can create diagrams in AsciiDoc and Markdown documents created in snippets, wikis, and repositories. ## PlantUML Server -Before you can enable PlantUML in GitLab; you need to set up your own PlantUML -server that will generate the diagrams. +Before you can enable PlantUML in GitLab; set up your own PlantUML +server to generate the diagrams. ### Docker @@ -26,12 +26,11 @@ With Docker, you can just run a container like this: docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat ``` -The **PlantUML URL** will be the hostname of the server running the container. +The **PlantUML URL** is the hostname of the server running the container. -When running GitLab in Docker, it will need to have access to the PlantUML container. -The easiest way to achieve that is by using [Docker Compose](https://docs.docker.com/compose/). - -A simple `docker-compose.yml` file would be: +When running GitLab in Docker, it must have access to the PlantUML container. +You can achieve that by using [Docker Compose](https://docs.docker.com/compose/). +A basic `docker-compose.yml` file could contain: ```yaml version: "3" @@ -47,13 +46,12 @@ services: container_name: plantuml ``` -In this scenario, PlantUML will be accessible for GitLab at the URL +In this scenario, PlantUML is accessible to GitLab at the URL `http://plantuml:8080/`. ### Debian/Ubuntu -Installing and configuring your -own PlantUML server is easy in Debian/Ubuntu distributions using Tomcat. +You can also install and configure a PlantUML server in Debian/Ubuntu distributions using Tomcat. First you need to create a `plantuml.war` file from the source code: @@ -64,8 +62,7 @@ cd plantuml-server mvn package ``` -The above sequence of commands will generate a WAR file that can be deployed -using Tomcat: +The above sequence of commands generates a `.war` file you can deploy with Tomcat: ```shell sudo apt-get install tomcat8 @@ -74,17 +71,18 @@ sudo chown tomcat8:tomcat8 /var/lib/tomcat8/webapps/plantuml.war sudo service tomcat8 restart ``` -Once the Tomcat service restarts the PlantUML service will be ready and +After the Tomcat service restarts, the PlantUML service is ready and listening for requests on port 8080: ```plaintext http://localhost:8080/plantuml ``` -you can change these defaults by editing the `/etc/tomcat8/server.xml` file. +To change these defaults, edit the `/etc/tomcat8/server.xml` file. -Note that the default URL is different than when using the Docker-based image, -where the service is available at the root of URL with no relative path. Adjust +NOTE: +The default URL is different when using this approach. The Docker-based image +makes the service available at the root URL, with no relative path. Adjust the configuration below accordingly. ### Making local PlantUML accessible using custom GitLab setup @@ -112,7 +110,7 @@ To activate the changes, run the following command: sudo gitlab-ctl reconfigure ``` -Note that the redirection through GitLab **must** be configured +Note that the redirection through GitLab must be configured when running [GitLab with TLS](https://docs.gitlab.com/omnibus/settings/ssl.html) due to PlantUML's use of the insecure HTTP protocol. Newer browsers such as [Google Chrome 86+](https://www.chromestatus.com/feature/4926989725073408) @@ -120,7 +118,7 @@ do not load insecure HTTP resources on a page served over HTTPS. ### Security -PlantUML has features that allows fetching network resources. +PlantUML has features that allow fetching network resources. ```plaintext @startuml @@ -136,18 +134,18 @@ stop; ## GitLab You need to enable PlantUML integration from Settings under Admin Area. To do -that, login with an Admin account and do following: +that, sign in with an Administrator account, and then do following: -- In GitLab, go to **Admin Area > Settings > General**. -- Expand the **PlantUML** section. -- Check **Enable PlantUML** checkbox. -- Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`. +1. In GitLab, go to **Admin Area > Settings > General**. +1. Expand the **PlantUML** section. +1. Select the **Enable PlantUML** check box. +1. Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`. NOTE: If you are using a PlantUML server running v1.2020.9 and above (for example, [plantuml.com](https://plantuml.com)), set the `PLANTUML_ENCODING` -environment variable to enable the `deflate` compression. On Omnibus, -this can be done set in `/etc/gitlab.rb`: +environment variable to enable the `deflate` compression. On Omnibus GitLab, +this can be set in `/etc/gitlab.rb`: ```ruby gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' } @@ -191,9 +189,11 @@ our AsciiDoc snippets, wikis, and repositories using delimited blocks: Alice -> Bob: hi ``` - You can also use the `uml::` directive for compatibility with [`sphinxcontrib-plantuml`](https://pypi.org/project/sphinxcontrib-plantuml/), but please note that we currently only support the `caption` option. + You can also use the `uml::` directive for compatibility with + [`sphinxcontrib-plantuml`](https://pypi.org/project/sphinxcontrib-plantuml/), + but GitLab only supports the `caption` option. -The above blocks will be converted to an HTML image tag with source pointing to the +The above blocks are converted to an HTML image tag with source pointing to the PlantUML instance. If the PlantUML server is correctly configured, this should render a nice diagram instead of the block: @@ -202,12 +202,18 @@ Bob -> Alice : hello Alice -> Bob : hi ``` -Inside the block you can add any of the supported diagrams by PlantUML such as -[Sequence](https://plantuml.com/sequence-diagram), [Use Case](https://plantuml.com/use-case-diagram), -[Class](https://plantuml.com/class-diagram), [Activity](https://plantuml.com/activity-diagram-legacy), -[Component](https://plantuml.com/component-diagram), [State](https://plantuml.com/state-diagram), -and [Object](https://plantuml.com/object-diagram) diagrams. You do not need to use the PlantUML -diagram delimiters `@startuml`/`@enduml` as these are replaced by the AsciiDoc `plantuml` block. +Inside the block you can add any of the diagrams PlantUML supports, such as: + +- [Sequence](https://plantuml.com/sequence-diagram) +- [Use Case](https://plantuml.com/use-case-diagram) +- [Class](https://plantuml.com/class-diagram) +- [Activity](https://plantuml.com/activity-diagram-legacy) +- [Component](https://plantuml.com/component-diagram) +- [State](https://plantuml.com/state-diagram), +- [Object](https://plantuml.com/object-diagram) + +You do not need to use the PlantUML +diagram delimiters `@startuml`/`@enduml`, as these are replaced by the AsciiDoc `plantuml` block. Some parameters can be added to the AsciiDoc block definition: @@ -217,4 +223,4 @@ Some parameters can be added to the AsciiDoc block definition: - `width`: Width attribute added to the image tag. - `height`: Height attribute added to the image tag. -Markdown does not support any parameters and will always use PNG format. +Markdown does not support any parameters and always uses PNG format. diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index f4c242b6e72..0f26eb83d17 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -8,14 +8,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7690) in GitLab 8.15. -NOTE: -Only project maintainers and owners can access web terminals. - With the introduction of the [Kubernetes integration](../../user/project/clusters/index.md), -GitLab gained the ability to store and use credentials for a Kubernetes cluster. -One of the things it uses these credentials for is providing access to +GitLab can store and use credentials for a Kubernetes cluster. +GitLab uses these credentials to provide access to [web terminals](../../ci/environments/index.md#web-terminals) for environments. +NOTE: +Only project maintainers and owners can access web terminals. + ## How it works A detailed overview of the architecture of web terminals and how they work @@ -53,15 +53,13 @@ detail below. NOTE: AWS Elastic Load Balancers (ELBs) do not support web sockets. -AWS Application Load Balancers (ALBs) must be used if you want web terminals -to work. See [AWS Elastic Load Balancing Product Comparison](https://aws.amazon.com/elasticloadbalancing/features/#compare) +If you want web terminals to work, use AWS Application Load Balancers (ALBs). +Read [AWS Elastic Load Balancing Product Comparison](https://aws.amazon.com/elasticloadbalancing/features/#compare) for more information. As web terminals use WebSockets, every HTTP/HTTPS reverse proxy in front of -Workhorse needs to be configured to pass the `Connection` and `Upgrade` headers -through to the next one in the chain. If you installed GitLab using Omnibus, or -from source, starting with GitLab 8.15, this should be done by the default -configuration, so there's no need for you to do anything. +Workhorse must be configured to pass the `Connection` and `Upgrade` headers +to the next one in the chain. GitLab is configured by default to do so. However, if you run a [load balancer](../load_balancer.md) in front of GitLab, you may need to make some changes to your configuration. These @@ -73,17 +71,17 @@ guides document the necessary steps for a selection of popular reverse proxies: - [Varnish](https://varnish-cache.org/docs/4.1/users-guide/vcl-example-websockets.html) Workhorse doesn't let WebSocket requests through to non-WebSocket endpoints, so -it's safe to enable support for these headers globally. If you'd rather had a -narrower set of rules, you can restrict it to URLs ending with `/terminal.ws` -(although this may still have a few false positives). +it's safe to enable support for these headers globally. If you prefer a +narrower set of rules, you can restrict it to URLs ending with `/terminal.ws`. +This approach may still result in a few false positives. If you installed from source, or have made any configuration changes to your Omnibus installation before upgrading to 8.15, you may need to make some changes -to your configuration. See the [Upgrading Community Edition and Enterprise -Edition from source](../../update/upgrading_from_source.md#nginx-configuration) -document for more details. +to your configuration. Read +[Upgrading Community Edition and Enterprise Edition from source](../../update/upgrading_from_source.md#nginx-configuration) +for more details. -If you'd like to disable web terminal support in GitLab, just stop passing +To disable web terminal support in GitLab, stop passing the `Connection` and `Upgrade` hop-by-hop headers in the *first* HTTP reverse proxy in the chain. For most users, this is the NGINX server bundled with Omnibus GitLab, in which case, you need to: @@ -104,4 +102,6 @@ they receive a `Connection failed` message. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8413) in GitLab 8.17. Terminal sessions, by default, do not expire. -You can limit terminal session lifetime in your GitLab instance. To do so, navigate to [**Admin Area > Settings > Web terminal**](../../user/admin_area/settings/index.md#general), and set a `max session time`. +You can limit terminal session lifetime in your GitLab instance. To do so, +go to [**Admin Area > Settings > Web terminal**](../../user/admin_area/settings/index.md#general), +and set a `max session time`. diff --git a/doc/administration/invalidate_markdown_cache.md b/doc/administration/invalidate_markdown_cache.md index 75bee6e0c9a..266e9d44ff7 100644 --- a/doc/administration/invalidate_markdown_cache.md +++ b/doc/administration/invalidate_markdown_cache.md @@ -8,10 +8,10 @@ type: reference # Invalidate Markdown Cache For performance reasons, GitLab caches the HTML version of Markdown text -(e.g. issue and merge request descriptions, comments). It's possible -that these cached versions become outdated, for example -when the `external_url` configuration option is changed - causing links -in the cached text to refer to the old URL. +in fields like comments, issue descriptions, and merge request descriptions. These +cached versions can become outdated, such as +when the `external_url` configuration option is changed. Links +in the cached text would still refer to the old URL. To avoid this problem, the administrator can invalidate the existing cache by increasing the `local_markdown_version` setting in application settings. This can diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index 6a5b90ae963..32d367bb15e 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Issue closing pattern **(CORE ONLY)** +# Issue closing pattern **(FREE SELF)** NOTE: This is the administration documentation. There is a separate [user documentation](../user/project/issues/managing_issues.md#closing-issues-automatically) diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 5d07e7d1b26..ba2cb05b449 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -91,7 +91,7 @@ _The artifacts are stored by default in > [GitLab Premium](https://about.gitlab.com/pricing/) 9.4. > - Since version 9.5, artifacts are [browsable](../ci/pipelines/job_artifacts.md#browsing-artifacts), > when object storage is enabled. 9.4 lacks this feature. -> - Since version 10.6, available in [GitLab Core](https://about.gitlab.com/pricing/) +> - Since version 10.6, available in [GitLab Free](https://about.gitlab.com/pricing/). > - Since version 11.0, we support `direct_upload` to S3. If you don't want to use the local disk where GitLab is installed to store the @@ -375,7 +375,7 @@ default artifacts expiration setting, which you can find in the [CI/CD Admin set > Introduced in GitLab 10.3. To disable [the dependencies validation](../ci/yaml/README.md#when-a-dependent-job-fails), -you can enable the `ci_disable_validates_dependencies` feature flag from a Rails console. +you can enable the `ci_validate_build_dependencies_override` feature flag from a Rails console. **In Omnibus installations:** @@ -388,7 +388,7 @@ you can enable the `ci_disable_validates_dependencies` feature flag from a Rails 1. Enable the feature flag to disable the validation: ```ruby - Feature.enable(:ci_disable_validates_dependencies) + Feature.enable(:ci_validate_build_dependencies_override) ``` **In installations from source:** @@ -403,7 +403,7 @@ you can enable the `ci_disable_validates_dependencies` feature flag from a Rails 1. Enable the feature flag to disable the validation: ```ruby - Feature.enable(:ci_disable_validates_dependencies) + Feature.enable(:ci_validate_build_dependencies_override) ``` ## Set the maximum file size of the artifacts diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index b2c6864e671..1afadcaf668 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -73,7 +73,7 @@ these steps to move the logs to a new location without losing any data. ``` Use `--ignore-existing` so you don't override new job logs with older versions of the same log. -1. Unpause continuous integration data processing by editing `/etc/gitlab/gitlab.rb` and removing the `sidekiq` setting you updated earlier. +1. Resume continuous integration data processing by editing `/etc/gitlab/gitlab.rb` and removing the `sidekiq` setting you updated earlier. 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. 1. Remove the old job logs storage location: diff --git a/doc/administration/job_traces.md b/doc/administration/job_traces.md deleted file mode 100644 index 2dbcf5d6705..00000000000 --- a/doc/administration/job_traces.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'job_logs.md' ---- - -This document was moved to [another location](job_logs.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/lfs/index.md b/doc/administration/lfs/index.md index bc349536a0c..862c26abac8 100644 --- a/doc/administration/lfs/index.md +++ b/doc/administration/lfs/index.md @@ -6,17 +6,17 @@ type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs_administration.html' --- -# GitLab Git Large File Storage (LFS) Administration **(CORE ONLY)** +# GitLab Git Large File Storage (LFS) Administration **(FREE SELF)** > - Git LFS is supported in GitLab starting with version 8.2. > - Support for object storage, such as AWS S3, was introduced in 10.0. > - LFS is enabled in GitLab self-managed instances by default. -Documentation on how to use Git LFS are under [Managing large binary files with Git LFS doc](../../topics/git/lfs/index.md). +Documentation about how to use Git LFS are under [Managing large binary files with Git LFS doc](../../topics/git/lfs/index.md). ## Requirements -- Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up. +- Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 or later. ## Configuration @@ -25,9 +25,9 @@ GitLab is installed on. There are various configuration options to help GitLab server administrators: -- Enabling/disabling Git LFS support -- Changing the location of LFS object storage -- Setting up object storage supported by [Fog](http://fog.io/about/provider_documentation.html) +- Enabling/disabling Git LFS support. +- Changing the location of LFS object storage. +- Setting up object storage supported by [Fog](http://fog.io/about/provider_documentation.html). ### Configuration for Omnibus installations @@ -43,7 +43,7 @@ gitlab_rails['lfs_enabled'] = false gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects" ``` -After you update settings in `/etc/gitlab/gitlab.rb`, make sure to run [Omnibus GitLab reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure). +After you update settings in `/etc/gitlab/gitlab.rb`, run [Omnibus GitLab reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure). ### Configuration for installations from source @@ -58,14 +58,12 @@ In `config/gitlab.yml`: ## Storing LFS objects in remote object storage -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2760) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. Brought to GitLab Core in 10.7. - -It is possible to store LFS objects in remote object storage which allows you -to offload local hard disk R/W operations, and free up disk space significantly. +You can store LFS objects in remote object storage. This allows you +to offload reads and writes to the local disk, and free up disk space significantly. GitLab is tightly integrated with `Fog`, so you can refer to its [documentation](http://fog.io/about/provider_documentation.html) to check which storage services can be integrated with GitLab. You can also use external object storage in a private local network. For example, -[MinIO](https://min.io/) is a standalone object storage service, is easy to set up, and works well with GitLab instances. +[MinIO](https://min.io/) is a standalone object storage service that works with GitLab instances. GitLab provides two different options for the uploading mechanism: "Direct upload" and "Background upload". @@ -78,26 +76,26 @@ This section describes the earlier configuration format. **Option 1. Direct upload** -1. User pushes an `lfs` file to the GitLab instance -1. GitLab-workhorse uploads the file directly to the external object storage -1. GitLab-workhorse notifies GitLab-rails that the upload process is complete +1. User pushes an `lfs` file to the GitLab instance. +1. GitLab-workhorse uploads the file directly to the external object storage. +1. GitLab-workhorse notifies GitLab-rails that the upload process is complete. **Option 2. Background upload** -1. User pushes an `lfs` file to the GitLab instance -1. GitLab-rails stores the file in the local file storage -1. GitLab-rails then uploads the file to the external object storage asynchronously +1. User pushes an `lfs` file to the GitLab instance. +1. GitLab-rails stores the file in the local file storage. +1. GitLab-rails then uploads the file to the external object storage asynchronously. The following general settings are supported. -| Setting | Description | Default | -|---------|-------------|---------| -| `enabled` | Enable/disable object storage | `false` | -| `remote_directory` | The bucket name where LFS objects will be stored| | -| `direct_upload` | Set to true to enable direct upload of LFS without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | `false` | -| `background_upload` | Set to false to disable automatic upload. Option may be removed once upload is direct to S3 | `true` | -| `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` | -| `connection` | Various connection options described below | | +| Setting | Description | Default | +|---------------------|-------------|---------| +| `enabled` | Enable/disable object storage. | `false` | +| `remote_directory` | The bucket name where LFS objects are stored. | | +| `direct_upload` | Set to true to enable direct upload of LFS without the need of local shared storage. Option may be removed after we decide to support only single storage for all files. | `false` | +| `background_upload` | Set to false to disable automatic upload. Option may be removed once upload is direct to S3. | `true` | +| `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data. | `false` | +| `connection` | Various connection options described below. | | See [the available connection settings for different providers](../object_storage.md#connection-settings). @@ -131,10 +129,9 @@ end ### S3 for Omnibus installations -On Omnibus installations, the settings are prefixed by `lfs_object_store_`: +On Omnibus GitLab installations, the settings are prefixed by `lfs_object_store_`: -1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with - the values you want: +1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, replacing values based on your needs: ```ruby gitlab_rails['lfs_object_store_enabled'] = true @@ -151,17 +148,17 @@ On Omnibus installations, the settings are prefixed by `lfs_object_store_`: } ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. 1. Migrate any existing local LFS objects to the object storage: ```shell gitlab-rake gitlab:lfs:migrate ``` - This will migrate existing LFS objects to object storage. New LFS objects - will be forwarded to object storage unless + This migrates existing LFS objects to object storage. New LFS objects + are forwarded to object storage unless `gitlab_rails['lfs_object_store_background_upload']` and `gitlab_rails['lfs_object_store_direct_upload']` is set to `false`. -1. Optional: Verify all files migrated properly. +1. (Optional) Verify all files migrated properly. From [PostgreSQL console](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database) (`sudo gitlab-psql -d gitlabhq_production`) verify `objectstg` below (where `file_store=2`) has count of all artifacts: @@ -204,17 +201,17 @@ For source installations the settings are nested under `lfs:` and then path_style: true ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file, and then [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. 1. Migrate any existing local LFS objects to the object storage: ```shell sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production ``` - This will migrate existing LFS objects to object storage. New LFS objects - will be forwarded to object storage unless `background_upload` and `direct_upload` is set to + This migrates existing LFS objects to object storage. New LFS objects + are forwarded to object storage unless `background_upload` and `direct_upload` is set to `false`. -1. Optional: Verify all files migrated properly. +1. (Optional) Verify all files migrated properly. From PostgreSQL console (`sudo -u git -H psql -d gitlabhq_production`) verify `objectstg` below (where `file_store=2`) has count of all artifacts: ```shell @@ -233,7 +230,7 @@ For source installations the settings are nested under `lfs:` and then ### Migrating back to local storage -In order to migrate back to local storage: +To migrate back to local storage: 1. Set both `direct_upload` and `background_upload` to `false` under the LFS object storage settings. Don't forget to restart GitLab. 1. Run `rake gitlab:lfs:migrate_to_local` on your console. @@ -241,17 +238,18 @@ In order to migrate back to local storage: ## Storage statistics -You can see the total storage used for LFS objects on groups and projects -in the administration area, as well as through the [groups](../../api/groups.md) -and [projects APIs](../../api/projects.md). +You can see the total storage used for LFS objects on groups and projects: + +- In the administration area. +- In the [groups](../../api/groups.md) and [projects APIs](../../api/projects.md). ## Troubleshooting: `Google::Apis::TransmissionError: execution expired` If LFS integration is configured with Google Cloud Storage and background uploads (`background_upload: true` and `direct_upload: false`), Sidekiq workers may encounter this error. This is because the uploading timed out with very large files. -LFS files up to 6Gb can be uploaded without any extra steps, otherwise you need to use the following workaround. +LFS files up to 6 GB can be uploaded without any extra steps, otherwise you need to use the following workaround. -Log into Rails console: +Sign in to Rails console: ```shell sudo gitlab-rails console @@ -282,6 +280,6 @@ See more information in [!19581](https://gitlab.com/gitlab-org/gitlab-foss/-/mer - Support for removing unreferenced LFS objects was added in 8.14 onward. - LFS authentications via SSH was added with GitLab 8.12. -- Only compatible with the Git LFS client versions 1.1.0 and up, or 1.0.2. -- The storage statistics currently count each LFS object multiple times for +- Only compatible with the Git LFS client versions 1.1.0 and later, or 1.0.2. +- The storage statistics count each LFS object multiple times for every project linking to it. diff --git a/doc/administration/lfs/lfs_administration.md b/doc/administration/lfs/lfs_administration.md deleted file mode 100644 index a275efce5bb..00000000000 --- a/doc/administration/lfs/lfs_administration.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'index.md' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/lfs/manage_large_binaries_with_git_lfs.md b/doc/administration/lfs/manage_large_binaries_with_git_lfs.md deleted file mode 100644 index 69c401acb86..00000000000 --- a/doc/administration/lfs/manage_large_binaries_with_git_lfs.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../topics/git/lfs/index.md' ---- - -This document was moved to [another location](../../topics/git/lfs/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/lfs/migrate_from_git_annex_to_git_lfs.md b/doc/administration/lfs/migrate_from_git_annex_to_git_lfs.md deleted file mode 100644 index 16095c1dbf6..00000000000 --- a/doc/administration/lfs/migrate_from_git_annex_to_git_lfs.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../topics/git/lfs/migrate_from_git_annex_to_git_lfs.md' ---- - -This document was moved to [another location](../../topics/git/lfs/migrate_from_git_annex_to_git_lfs.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/logs.md b/doc/administration/logs.md index 3d5ba903941..36172869493 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Log system +# Log system **(FREE SELF)** GitLab has an advanced log system where everything is logged, so you can analyze your instance using various system log files. In addition to @@ -381,10 +381,11 @@ only. For example: } ``` -## `audit_json.log` +## `audit_json.log` **(FREE)** NOTE: -Most log entries only exist in [GitLab Starter](https://about.gitlab.com/pricing/), however a few exist in GitLab Core. +GitLab Free tracks a small number of different audit events. +[GitLab Premium](https://about.gitlab.com/pricing/) tracks many more. This file lives in `/var/log/gitlab/gitlab-rails/audit_json.log` for Omnibus GitLab packages or in `/home/git/gitlab/log/audit_json.log` for @@ -772,7 +773,7 @@ are generated: - For Omnibus GitLab packages, in `/var/log/gitlab/gitlab-rails/web_exporter.log`. - For installations from source, in `/home/git/gitlab/log/web_exporter.log`. -## `database_load_balancing.log` **(PREMIUM ONLY)** +## `database_load_balancing.log` **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/15442) in GitLab 12.3. @@ -782,7 +783,7 @@ It's stored at: - `/var/log/gitlab/gitlab-rails/database_load_balancing.log` for Omnibus GitLab packages. - `/home/git/gitlab/log/database_load_balancing.log` for installations from source. -## `elasticsearch.log` **(STARTER ONLY)** +## `elasticsearch.log` **(PREMIUM SELF)** > Introduced in GitLab 12.6. @@ -856,7 +857,7 @@ For example: { "severity":"INFO", "time":"2020-04-22T16:04:50.691Z","correlation_id":"04f1366e-57a1-45b8-88c1-b00b23dc3616","class":"Projects::ImportExport::ExportService","current_user":"John Doe","project_full_path":"group1/test-export","file_path":"/path/to/archive","gc_stats":{"count":{"before":127,"after":127,"diff":0},"heap_allocated_pages":{"before":10369,"after":10369,"diff":0},"heap_sorted_length":{"before":10369,"after":10369,"diff":0},"heap_allocatable_pages":{"before":0,"after":0,"diff":0},"heap_available_slots":{"before":4226409,"after":4226409,"diff":0},"heap_live_slots":{"before":2542709,"after":2641420,"diff":98711},"heap_free_slots":{"before":1683700,"after":1584989,"diff":-98711},"heap_final_slots":{"before":0,"after":0,"diff":0},"heap_marked_slots":{"before":2542704,"after":2542704,"diff":0},"heap_eden_pages":{"before":10369,"after":10369,"diff":0},"heap_tomb_pages":{"before":0,"after":0,"diff":0},"total_allocated_pages":{"before":10369,"after":10369,"diff":0},"total_freed_pages":{"before":0,"after":0,"diff":0},"total_allocated_objects":{"before":24896308,"after":24995019,"diff":98711},"total_freed_objects":{"before":22353599,"after":22353599,"diff":0},"malloc_increase_bytes":{"before":140032,"after":6650240,"diff":6510208},"malloc_increase_bytes_limit":{"before":25804104,"after":25804104,"diff":0},"minor_gc_count":{"before":94,"after":94,"diff":0},"major_gc_count":{"before":33,"after":33,"diff":0},"remembered_wb_unprotected_objects":{"before":34284,"after":34284,"diff":0},"remembered_wb_unprotected_objects_limit":{"before":68568,"after":68568,"diff":0},"old_objects":{"before":2404725,"after":2404725,"diff":0},"old_objects_limit":{"before":4809450,"after":4809450,"diff":0},"oldmalloc_increase_bytes":{"before":140032,"after":6650240,"diff":6510208},"oldmalloc_increase_bytes_limit":{"before":68537556,"after":68537556,"diff":0}},"time_to_finish":0.12298400001600385,"number_of_sql_calls":70,"memory_usage":"0.0 MiB","label":"process_48616"} ``` -## `geo.log` **(PREMIUM ONLY)** +## `geo.log` **(PREMIUM SELF)** > Introduced in 9.5. @@ -973,9 +974,13 @@ For Omnibus GitLab installations, Redis logs reside in `/var/log/gitlab/redis/`. For Omnibus GitLab installations, Alertmanager logs reside in `/var/log/gitlab/alertmanager/`. +<!-- vale gitlab.Spelling = NO --> + ## Crond Logs -For Omnibus GitLab installations, `crond` logs reside in `/var/log/gitlab/crond/`. +For Omnibus GitLab installations, crond logs reside in `/var/log/gitlab/crond/`. + +<!-- vale gitlab.Spelling = YES --> ## Grafana Logs @@ -983,7 +988,7 @@ For Omnibus GitLab installations, Grafana logs reside in `/var/log/gitlab/grafan ## LogRotate Logs -For Omnibus GitLab installations, logrotate logs reside in `/var/log/gitlab/logrotate/`. +For Omnibus GitLab installations, `logrotate` logs reside in `/var/log/gitlab/logrotate/`. ## GitLab Monitor Logs @@ -1009,7 +1014,7 @@ installations from source. Performance bar statistics (currently only duration of SQL queries) are recorded in that file. For example: ```json -{"severity":"INFO","time":"2020-12-04T09:29:44.592Z","correlation_id":"33680b1490ccd35981b03639c406a697","filename":"app/models/ci/pipeline.rb","filenum":"395","method":"each_with_object","request_id":"rYHomD0VJS4","duration_ms":26.889,"type": "sql"} +{"severity":"INFO","time":"2020-12-04T09:29:44.592Z","correlation_id":"33680b1490ccd35981b03639c406a697","filename":"app/models/ci/pipeline.rb","method_path":"app/models/ci/pipeline.rb:each_with_object","request_id":"rYHomD0VJS4","duration_ms":26.889,"count":2,"type": "sql"} ``` These statistics are logged on .com only, disabled on self-deployments. @@ -1026,14 +1031,14 @@ GitLab Support often asks for one of these, and maintains the required tools. ### Briefly tail the main logs If the bug or error is readily reproducible, save the main GitLab logs -[to a file](troubleshooting/linux_cheat_sheet.md#files--dirs) while reproducing the +[to a file](troubleshooting/linux_cheat_sheet.md#files-and-directories) while reproducing the problem a few times: ```shell sudo gitlab-ctl tail | tee /tmp/<case-ID-and-keywords>.log ``` -Conclude the log gathering with <kbd>Ctrl</kbd> + <kbd>C</kbd>. +Conclude the log gathering with <kbd>Control</kbd> + <kbd>C</kbd>. ### GitLabSOS diff --git a/doc/administration/maintenance_mode/index.md b/doc/administration/maintenance_mode/index.md new file mode 100644 index 00000000000..c37eff53549 --- /dev/null +++ b/doc/administration/maintenance_mode/index.md @@ -0,0 +1,137 @@ +--- +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/#assignments +--- + +# GitLab in maintenance mode **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2149) in GitLab Premium 13.9. + +In maintenance mode, most write operations are disabled at the application level. +This means that GitLab is effectively in a read-only mode for all non-administrative +users (administrators are still able to edit application settings). Regular users +are able to log in to GitLab, view the interface and perform other read-only +operations, such as `git clone` or `git pull`. + +## Enable maintenance mode + +There are three ways to enable maintenance mode as an administrator: + +- **Web UI**: + 1. Navigate to the **Admin Area > Application settings > General** and toggle + the maintenance mode. You can optionally add a message for the banner as well. + 1. Click **Save** for the changes to take effect. + +- **API**: + + ```shell + curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=true" + ``` + +- [**Rails console**](../operations/rails_console.md#starting-a-rails-console-session): + + ```ruby + ::Gitlab::CurrentSettings.update_attributes!(maintenance_mode: true) + ::Gitlab::CurrentSettings.update_attributes!(maintenance_mode_message: "New message") + ``` + +## Disable maintenance mode + +There are three ways to disable maintenance mode: + +- **Web UI**: + 1. Navigate to the **Admin Area > Application settings > General** and toggle + the maintenance mode. You can optionally add a message for the banner as well. + 1. Click **Save** for the changes to take effect. + +- **API**: + + ```shell + curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=false" + ``` + +- [**Rails console**](../operations/rails_console.md#starting-a-rails-console-session): + + ```ruby + ::Gitlab::CurrentSettings.update_attributes!(maintenance_mode: false) + ``` + +## Behavior in maintenance mode + +When maintenance mode is enabled, a banner is displayed at the top of the page. +The banner can be customized with a specific message. + +An error is displayed when a user tries to perform a write operation that isn't allowed. +The API will return a 403 or 503 error for failed write requests. + +NOTE: +In some cases, the visual feedback from an action could be misleading, for example +when starring a project, the **Star** button changes to show the **Unstar** action, +however, this is only the frontend update, and it doesn't take into account the +failed status of the POST request. These visual bugs are to be fixed +[in follow-up iterations](https://gitlab.com/gitlab-org/gitlab/-/issues/295197). + +### Application settings + +In maintenance mode, admins can edit the application settings. This will allow +them to disable maintenance mode after it's been enabled. + +### Logging in/out + +All users can log in and out of the GitLab instance. + +### CI/CD + +In maintenance mode: + +- No new jobs are started. Already running jobs stay in 'running' + status but their logs are no longer updated. +- If the job has been in 'running' state for longer than the project's time limit, + it will **not** time out. +- Pipelines cannot be started, retried or canceled in maintenance mode. + No new jobs can be created either. + +Once maintenance mode is disabled, new jobs are picked up again. The jobs that were +in the running state before enabling maintenance mode, will resume, and their logs +will start getting updated again. + +### Git actions + +All read-only Git operations will continue to work in maintenance mode, for example +`git clone` and `git pull`, but all write operations will fail, both through the CLI +and Web IDE. + +Geo secondaries are read-only instances that allow Git pushes because they are +proxied to the primary instance. However, in maintenance mode, Git pushes to +both primary and secondaries will fail. + +### Merge requests, issues, epics + +All write actions except those mentioned above will fail. So, in maintenance mode, a user cannot update merge requests, issues, etc. + +### Container Registry + +In maintenance mode, `docker push` is blocked, but `docker pull` is available. + +### Auto Deploys + +It is recommended to disable auto deploys during maintenance mode, and enable +them once maintenance mode is disabled. + +### Background jobs + +Background jobs (cron jobs, Sidekiq) will continue running as is, because maintenance +mode does not disable any background jobs. + +[During a planned Geo failover](../geo/disaster_recovery/planned_failover.md#prevent-updates-to-the-primary-node), +it is recommended that you disable all cron jobs except for those related to Geo. + +You can monitor queues and disable jobs in **Admin Area > Monitoring > Background Jobs**. + +### Geo secondaries + +The maintenance mode setting will be propagated to the secondary as they sync up. +It is important that you do not disable replication before enabling maintenance mode. + +Replication and verification will continue to work in maintenance mode. diff --git a/doc/administration/maven_packages.md b/doc/administration/maven_packages.md deleted file mode 100644 index 690b6785941..00000000000 --- a/doc/administration/maven_packages.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'packages/index.md' ---- - -This document was moved to [another location](packages/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/maven_repository.md b/doc/administration/maven_repository.md deleted file mode 100644 index 690b6785941..00000000000 --- a/doc/administration/maven_repository.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'packages/index.md' ---- - -This document was moved to [another location](packages/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index 92fdba6216c..1133bff204c 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Merge request diffs storage **(CORE ONLY)** +# Merge request diffs storage **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52568) in GitLab 11.8. @@ -31,8 +31,8 @@ that only [stores outdated diffs](#alternative-in-database-storage) outside of d gitlab_rails['external_diffs_enabled'] = true ``` -1. _The external diffs will be stored in - `/var/opt/gitlab/gitlab-rails/shared/external-diffs`._ To change the path, +1. The external diffs are stored in + `/var/opt/gitlab/gitlab-rails/shared/external-diffs`. To change the path, for example, to `/mnt/storage/external-diffs`, edit `/etc/gitlab/gitlab.rb` and add the following line: @@ -52,8 +52,8 @@ that only [stores outdated diffs](#alternative-in-database-storage) outside of d enabled: true ``` -1. _The external diffs will be stored in - `/home/git/gitlab/shared/external-diffs`._ To change the path, for example, +1. The external diffs are stored in + `/home/git/gitlab/shared/external-diffs`. To change the path, for example, to `/mnt/storage/external-diffs`, edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: @@ -68,7 +68,7 @@ that only [stores outdated diffs](#alternative-in-database-storage) outside of d ## Using object storage WARNING: -Currently migrating to object storage is **non-reversible** +Migrating to object storage is not reversible. Instead of storing the external diffs on disk, we recommended the use of an object store like AWS S3 instead. This configuration relies on valid AWS credentials to @@ -114,7 +114,7 @@ then `object_store:`. On Omnibus installations, they are prefixed by | Setting | Description | Default | |---------|-------------|---------| | `enabled` | Enable/disable object storage | `false` | -| `remote_directory` | The bucket name where external diffs will be stored| | +| `remote_directory` | The bucket name where external diffs are stored| | | `direct_upload` | Set to `true` to enable direct upload of external diffs without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | `false` | | `background_upload` | Set to `false` to disable automatic upload. Option may be removed once upload is direct to S3 | `true` | | `proxy_download` | Set to `true` to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` | @@ -141,7 +141,7 @@ See [the available connection settings for different providers](object_storage.m } ``` - Note that, if you are using AWS IAM profiles, be sure to omit the + If you are using AWS IAM profiles, omit the AWS access key and secret access key/value pairs. For example: ```ruby @@ -206,8 +206,8 @@ To enable this feature, perform the following steps: 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. -With this feature enabled, diffs will initially stored in the database, rather -than externally. They will be moved to external storage once any of these +With this feature enabled, diffs are initially stored in the database, rather +than externally. They are moved to external storage after any of these conditions become true: - A newer version of the merge request diff exists @@ -225,15 +225,15 @@ of some merge request diffs when [external diffs in object storage](#object-stor were enabled. This mainly affected imported merge requests, and was resolved with [this merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31005). -If you are using object storage, have never used on-disk storage for external -diffs, the "changes" tab for some merge requests fails to load with a 500 error, +If you are using object storage, or have never used on-disk storage for external +diffs, the **Changes** tab for some merge requests fails to load with a 500 error, and the exception for that error is of this form: ```plain Errno::ENOENT (No such file or directory @ rb_sysopen - /var/opt/gitlab/gitlab-rails/shared/external-diffs/merge_request_diffs/mr-6167082/diff-8199789) ``` -Then you are affected by this issue. Since it's not possible to safely determine +Then you are affected by this issue. Because it's not possible to safely determine all these conditions automatically, we've provided a Rake task in GitLab v13.2.0 that you can run manually to correct the data: diff --git a/doc/administration/monitoring/github_imports.md b/doc/administration/monitoring/github_imports.md index cf7c105e8cf..736ff299a86 100644 --- a/doc/administration/monitoring/github_imports.md +++ b/doc/administration/monitoring/github_imports.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Monitoring GitHub imports +# Monitoring GitHub imports **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14731) in GitLab 10.2. diff --git a/doc/administration/monitoring/gitlab_instance_administration_project/index.md b/doc/administration/monitoring/gitlab_instance_administration_project/index.md deleted file mode 100644 index 59837dcdb20..00000000000 --- a/doc/administration/monitoring/gitlab_instance_administration_project/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../gitlab_self_monitoring_project/index.md' ---- - -This document was moved to [another location](../gitlab_self_monitoring_project/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md index 13d42ca2ee6..f7eb03b75ef 100644 --- a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md +++ b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# GitLab self monitoring project +# GitLab self monitoring project **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32351) in GitLab 12.7, behind a disabled feature flag (`self_monitoring_project`). > - The feature flag was removed and the Self Monitoring Project was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/198511) in GitLab 12.8. diff --git a/doc/administration/monitoring/index.md b/doc/administration/monitoring/index.md index 68dbe9f3cf9..ac09acf2d2e 100644 --- a/doc/administration/monitoring/index.md +++ b/doc/administration/monitoring/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Monitoring GitLab +# Monitoring GitLab **(FREE SELF)** Explore our features to monitor your GitLab instance: diff --git a/doc/administration/monitoring/ip_whitelist.md b/doc/administration/monitoring/ip_whitelist.md index 83fbec86f57..91f9c5d560f 100644 --- a/doc/administration/monitoring/ip_whitelist.md +++ b/doc/administration/monitoring/ip_whitelist.md @@ -4,7 +4,7 @@ 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/#assignments --- -# IP whitelist +# IP whitelist **(FREE SELF)** > Introduced in GitLab 9.4. diff --git a/doc/administration/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md index dd4481434a6..03eba67292d 100644 --- a/doc/administration/monitoring/performance/gitlab_configuration.md +++ b/doc/administration/monitoring/performance/gitlab_configuration.md @@ -4,22 +4,24 @@ 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/#assignments --- -# GitLab Configuration +# GitLab Configuration **(FREE SELF)** GitLab Performance Monitoring is disabled by default. To enable it and change any of its settings: 1. Navigate to **Admin Area > Settings > Metrics and profiling** - (`/admin/application_settings/metrics_and_profiling`): - -  - -1. You must restart all GitLab processes for the changes to take effect: + (`/admin/application_settings/metrics_and_profiling`). +1. Add the necessary configuration changes. +1. Restart all GitLab for the changes to take effect: - For Omnibus GitLab installations: `sudo gitlab-ctl restart` - For installations from source: `sudo service gitlab restart` -## Pending Migrations +NOTE: +Removed [in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30786). Use the +[Prometheus integration](../prometheus/index.md) instead. + +## Pending migrations When any migrations are pending, the metrics are disabled until the migrations have been performed. diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index e76e81c6499..e6dda2ac87a 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Grafana Configuration +# Grafana Configuration **(FREE SELF)** [Grafana](https://grafana.com/) is a tool that enables you to visualize time series metrics through graphs and dashboards. GitLab writes performance data to Prometheus, @@ -17,42 +17,38 @@ or Grafana supplies package repositories (Yum/Apt) for easy installation. See [Grafana installation documentation](https://grafana.com/docs/grafana/latest/installation/) for detailed steps. -Before starting Grafana for the first time, set the admin user +Before starting Grafana for the first time, set the administration user and password in `/etc/grafana/grafana.ini`. If you don't, the default password is `admin`. ## Configuration -1. Log in to Grafana as the admin user. -1. Expand the menu by clicking the Grafana logo in the top left corner. -1. Choose **Data Sources** from the menu. -1. Click **Add new** in the top bar: -  -1. Edit the data source to fit your needs: -  -1. Click **Save**. +1. Log in to Grafana as the administration user. +1. Select **Data Sources** from the **Configuration** menu. +1. Select the **Add data source** button. +1. Select the required data source type. For example, [Prometheus](../prometheus/index.md#prometheus-as-a-grafana-data-source). +1. Complete the details for the data source and select the **Save & Test** button. + +Grafana should indicate the data source is working. ## Import Dashboards You can now import a set of default dashboards to start displaying useful information. GitLab has published a set of default -[Grafana dashboards](https://gitlab.com/gitlab-org/grafana-dashboards) to get you started. -Clone the repository, or download a ZIP file or tarball, then follow these steps to import each -JSON file individually: +[Grafana dashboards](https://gitlab.com/gitlab-org/grafana-dashboards) to get you started. To use +them: -1. Log in to Grafana as the admin user. -1. Open the dashboard dropdown menu and click **Import**: -  -1. Click **Choose file**, and browse to the location where you downloaded or - cloned the dashboard repository. Select a JSON file to import: -  -1. After the dashboard is imported, click the **Save dashboard** icon in the top bar: -  +1. Clone the repository, or download a ZIP file or tarball. +1. Follow these steps to import each JSON file individually: - If you don't save the dashboard after importing it, the dashboard is removed - when you navigate away from the page. + 1. Log in to Grafana as the administration user. + 1. Select **Manage** from the **Dashboards** menu. + 1. Select the **Import** button, then the **Upload JSON file** button. + 1. Locate the JSON file to import and select **Choose for Upload**. Select the **Import** button. + 1. After the dashboard is imported, select the **Save dashboard** icon in the top bar. -Repeat this process for each dashboard you wish to import. +If you don't save the dashboard after importing it, the dashboard is removed +when you navigate away from the page. Repeat this process for each dashboard you wish to import. Alternatively, you can import all the dashboards into your Grafana instance. For more information about this process, see the @@ -103,7 +99,7 @@ sudo mv /var/opt/gitlab/grafana/data.bak.xxxx/ /var/opt/gitlab/grafana/data/ However, you should **not** reinstate your old data _except_ under one of the following conditions: -1. If you're certain that you changed your default admin password when you enabled Grafana. +1. If you're certain that you changed your default administration password when you enabled Grafana. 1. If you run GitLab in a private network, accessed only by trusted users, and your Grafana login page has not been exposed to the internet. @@ -121,8 +117,6 @@ existing data and dashboards. For more information and further mitigation details, please refer to our [blog post on the security release](https://about.gitlab.com/releases/2019/08/12/critical-security-release-gitlab-12-dot-1-dot-6-released/). ---- - Read more on: - [Introduction to GitLab Performance Monitoring](index.md) diff --git a/doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png b/doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png Binary files differdeleted file mode 100644 index 51eef90068d..00000000000 --- a/doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png +++ /dev/null diff --git a/doc/administration/monitoring/performance/img/grafana_dashboard_import.png b/doc/administration/monitoring/performance/img/grafana_dashboard_import.png Binary files differdeleted file mode 100644 index fd639ee0eb8..00000000000 --- a/doc/administration/monitoring/performance/img/grafana_dashboard_import.png +++ /dev/null diff --git a/doc/administration/monitoring/performance/img/grafana_data_source_configuration.png b/doc/administration/monitoring/performance/img/grafana_data_source_configuration.png Binary files differdeleted file mode 100644 index a98e0ed1e7d..00000000000 --- a/doc/administration/monitoring/performance/img/grafana_data_source_configuration.png +++ /dev/null diff --git a/doc/administration/monitoring/performance/img/grafana_data_source_empty.png b/doc/administration/monitoring/performance/img/grafana_data_source_empty.png Binary files differdeleted file mode 100644 index 549ada8343e..00000000000 --- a/doc/administration/monitoring/performance/img/grafana_data_source_empty.png +++ /dev/null diff --git a/doc/administration/monitoring/performance/img/grafana_save_icon.png b/doc/administration/monitoring/performance/img/grafana_save_icon.png Binary files differdeleted file mode 100644 index 68a071f5ae2..00000000000 --- a/doc/administration/monitoring/performance/img/grafana_save_icon.png +++ /dev/null diff --git a/doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png b/doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png Binary files differdeleted file mode 100644 index 13bfd097b81..00000000000 --- a/doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png +++ /dev/null diff --git a/doc/administration/monitoring/performance/img/performance_bar_external_http_calls.png b/doc/administration/monitoring/performance/img/performance_bar_external_http_calls.png Binary files differnew file mode 100644 index 00000000000..45f2b0956e9 --- /dev/null +++ b/doc/administration/monitoring/performance/img/performance_bar_external_http_calls.png diff --git a/doc/administration/monitoring/performance/index.md b/doc/administration/monitoring/performance/index.md index 072baa16e29..cdf78811092 100644 --- a/doc/administration/monitoring/performance/index.md +++ b/doc/administration/monitoring/performance/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# GitLab Performance Monitoring +# GitLab Performance Monitoring **(FREE SELF)** GitLab comes with its own application performance measuring system as of GitLab 8.4, called "GitLab Performance Monitoring". GitLab Performance Monitoring is available in both the diff --git a/doc/administration/monitoring/performance/influxdb_configuration.md b/doc/administration/monitoring/performance/influxdb_configuration.md deleted file mode 100644 index d793e014a18..00000000000 --- a/doc/administration/monitoring/performance/influxdb_configuration.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'prometheus.md' ---- - -Support for InfluxDB was removed in GitLab 13.0. Use [Prometheus](prometheus.md) for performance monitoring. diff --git a/doc/administration/monitoring/performance/influxdb_schema.md b/doc/administration/monitoring/performance/influxdb_schema.md deleted file mode 100644 index d793e014a18..00000000000 --- a/doc/administration/monitoring/performance/influxdb_schema.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'prometheus.md' ---- - -Support for InfluxDB was removed in GitLab 13.0. Use [Prometheus](prometheus.md) for performance monitoring. diff --git a/doc/administration/monitoring/performance/introduction.md b/doc/administration/monitoring/performance/introduction.md deleted file mode 100644 index a275efce5bb..00000000000 --- a/doc/administration/monitoring/performance/introduction.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'index.md' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md index a214660bd5c..0b67f8c11ba 100644 --- a/doc/administration/monitoring/performance/performance_bar.md +++ b/doc/administration/monitoring/performance/performance_bar.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Performance Bar +# Performance Bar **(FREE SELF)** You can display the GitLab Performance Bar to see statistics for the performance of a page. When activated, it looks as follows: @@ -31,6 +31,10 @@ From left to right, it displays:  - **Elasticsearch calls**: the time taken (in milliseconds) and the total number of Elasticsearch calls. Click to display a modal window with more details. +- **External HTTP calls**: the time taken (in milliseconds) and the total + number of external calls to other systems. Click to display a modal window + with more details +  - **Load timings** of the page: if your browser supports load timings (Chromium and Chrome) several values in milliseconds, separated by slashes. Click to display a modal window with more details. The values, from left to right: diff --git a/doc/administration/monitoring/performance/prometheus.md b/doc/administration/monitoring/performance/prometheus.md deleted file mode 100644 index 2978de865e2..00000000000 --- a/doc/administration/monitoring/performance/prometheus.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../prometheus/index.md' ---- - -This document was moved to [another location](../prometheus/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/monitoring/performance/request_profiling.md b/doc/administration/monitoring/performance/request_profiling.md index 23af50dec11..f0ac8f991d3 100644 --- a/doc/administration/monitoring/performance/request_profiling.md +++ b/doc/administration/monitoring/performance/request_profiling.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Request Profiling +# Request Profiling **(FREE SELF)** To profile a request: diff --git a/doc/administration/monitoring/prometheus/gitlab_exporter.md b/doc/administration/monitoring/prometheus/gitlab_exporter.md index 5add842bccc..589fa799cca 100644 --- a/doc/administration/monitoring/prometheus/gitlab_exporter.md +++ b/doc/administration/monitoring/prometheus/gitlab_exporter.md @@ -4,7 +4,7 @@ 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/#assignments --- -# GitLab exporter +# GitLab exporter **(FREE SELF)** >- Available since [Omnibus GitLab 8.17](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/1132). >- Renamed from `GitLab monitor exporter` to `GitLab exporter` in [GitLab 12.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16511). diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 4493c1677bc..cd26ef1aef2 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -4,7 +4,7 @@ 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/#assignments --- -# GitLab Prometheus metrics +# GitLab Prometheus metrics **(FREE SELF)** To enable the GitLab Prometheus metrics: @@ -33,87 +33,95 @@ For enabling and viewing metrics from Sidekiq nodes, see [Sidekiq metrics](#side The following metrics are available: -| Metric | Type | Since | Description | Labels | -|:---------------------------------------------------------------|:----------|-----------------------:|:----------------------------------------------------------------------------------------------------|:----------------------------------------------------| -| `gitlab_banzai_cached_render_real_duration_seconds` | Histogram | 9.4 | Duration of rendering Markdown into HTML when cached output exists | `controller`, `action` | -| `gitlab_banzai_cacheless_render_real_duration_seconds` | Histogram | 9.4 | Duration of rendering Markdown into HTML when cached output does not exist | `controller`, `action` | -| `gitlab_cache_misses_total` | Counter | 10.2 | Cache read miss | `controller`, `action` | -| `gitlab_cache_operation_duration_seconds` | Histogram | 10.2 | Cache access time | | -| `gitlab_cache_operations_total` | Counter | 12.2 | Cache operations by controller or action | `controller`, `action`, `operation` | -| `gitlab_ci_pipeline_creation_duration_seconds` | Histogram | 13.0 | Time in seconds it takes to create a CI/CD pipeline | | -| `gitlab_ci_pipeline_size_builds` | Histogram | 13.1 | Total number of builds within a pipeline grouped by a pipeline source | `source` | -| `job_waiter_started_total` | Counter | 12.9 | Number of batches of jobs started where a web request is waiting for the jobs to complete | `worker` | -| `job_waiter_timeouts_total` | Counter | 12.9 | Number of batches of jobs that timed out where a web request is waiting for the jobs to complete | `worker` | -| `gitlab_database_transaction_seconds` | Histogram | 12.1 | Time spent in database transactions, in seconds | | -| `gitlab_method_call_duration_seconds` | Histogram | 10.2 | Method calls real duration | `controller`, `action`, `module`, `method` | -| `gitlab_page_out_of_bounds` | Counter | 12.8 | Counter for the PageLimiter pagination limit being hit | `controller`, `action`, `bot` | -| `gitlab_rails_queue_duration_seconds` | Histogram | 9.4 | Measures latency between GitLab Workhorse forwarding a request to Rails | | -| `gitlab_sql_duration_seconds` | Histogram | 10.2 | SQL execution time, excluding `SCHEMA` operations and `BEGIN` / `COMMIT` | | -| `gitlab_ruby_threads_max_expected_threads` | Gauge | 13.3 | Maximum number of threads expected to be running and performing application work | -| `gitlab_ruby_threads_running_threads` | Gauge | 13.3 | Number of running Ruby threads by name | -| `gitlab_transaction_cache_<key>_count_total` | Counter | 10.2 | Counter for total Rails cache calls (per key) | | -| `gitlab_transaction_cache_<key>_duration_total` | Counter | 10.2 | Counter for total time (seconds) spent in Rails cache calls (per key) | | -| `gitlab_transaction_cache_count_total` | Counter | 10.2 | Counter for total Rails cache calls (aggregate) | | -| `gitlab_transaction_cache_duration_total` | Counter | 10.2 | Counter for total time (seconds) spent in Rails cache calls (aggregate) | | -| `gitlab_transaction_cache_read_hit_count_total` | Counter | 10.2 | Counter for cache hits for Rails cache calls | `controller`, `action` | -| `gitlab_transaction_cache_read_miss_count_total` | Counter | 10.2 | Counter for cache misses for Rails cache calls | `controller`, `action` | -| `gitlab_transaction_duration_seconds` | Histogram | 10.2 | Duration for all transactions (`gitlab_transaction_*` metrics) | `controller`, `action` | -| `gitlab_transaction_event_build_found_total` | Counter | 9.4 | Counter for build found for API /jobs/request | | -| `gitlab_transaction_event_build_invalid_total` | Counter | 9.4 | Counter for build invalid due to concurrency conflict for API /jobs/request | | -| `gitlab_transaction_event_build_not_found_cached_total` | Counter | 9.4 | Counter for cached response of build not found for API /jobs/request | | -| `gitlab_transaction_event_build_not_found_total` | Counter | 9.4 | Counter for build not found for API /jobs/request | | -| `gitlab_transaction_event_change_default_branch_total` | Counter | 9.4 | Counter when default branch is changed for any repository | | -| `gitlab_transaction_event_create_repository_total` | Counter | 9.4 | Counter when any repository is created | | -| `gitlab_transaction_event_etag_caching_cache_hit_total` | Counter | 9.4 | Counter for ETag cache hit. | `endpoint` | -| `gitlab_transaction_event_etag_caching_header_missing_total` | Counter | 9.4 | Counter for ETag cache miss - header missing | `endpoint` | -| `gitlab_transaction_event_etag_caching_key_not_found_total` | Counter | 9.4 | Counter for ETag cache miss - key not found | `endpoint` | -| `gitlab_transaction_event_etag_caching_middleware_used_total` | Counter | 9.4 | Counter for ETag middleware accessed | `endpoint` | -| `gitlab_transaction_event_etag_caching_resource_changed_total` | Counter | 9.4 | Counter for ETag cache miss - resource changed | `endpoint` | -| `gitlab_transaction_event_fork_repository_total` | Counter | 9.4 | Counter for repository forks (RepositoryForkWorker). Only incremented when source repository exists | | -| `gitlab_transaction_event_import_repository_total` | Counter | 9.4 | Counter for repository imports (RepositoryImportWorker) | | -| `gitlab_transaction_event_push_branch_total` | Counter | 9.4 | Counter for all branch pushes | | -| `gitlab_transaction_event_push_commit_total` | Counter | 9.4 | Counter for commits | `branch` | -| `gitlab_transaction_event_push_tag_total` | Counter | 9.4 | Counter for tag pushes | | -| `gitlab_transaction_event_rails_exception_total` | Counter | 9.4 | Counter for number of rails exceptions | | -| `gitlab_transaction_event_receive_email_total` | Counter | 9.4 | Counter for received emails | `handler` | -| `gitlab_transaction_event_remote_mirrors_failed_total` | Counter | 10.8 | Counter for failed remote mirrors | | -| `gitlab_transaction_event_remote_mirrors_finished_total` | Counter | 10.8 | Counter for finished remote mirrors | | -| `gitlab_transaction_event_remote_mirrors_running_total` | Counter | 10.8 | Counter for running remote mirrors | | -| `gitlab_transaction_event_remove_branch_total` | Counter | 9.4 | Counter when a branch is removed for any repository | | -| `gitlab_transaction_event_remove_repository_total` | Counter | 9.4 | Counter when a repository is removed | | -| `gitlab_transaction_event_remove_tag_total` | Counter | 9.4 | Counter when a tag is remove for any repository | | -| `gitlab_transaction_event_sidekiq_exception_total` | Counter | 9.4 | Counter of Sidekiq exceptions | | -| `gitlab_transaction_event_stuck_import_jobs_total` | Counter | 9.4 | Count of stuck import jobs | `projects_without_jid_count`, `projects_with_jid_count` | -| `gitlab_transaction_event_update_build_total` | Counter | 9.4 | Counter for update build for API `/jobs/request/:id` | | -| `gitlab_transaction_new_redis_connections_total` | Counter | 9.4 | Counter for new Redis connections | | -| `gitlab_transaction_queue_duration_total` | Counter | 9.4 | Duration jobs were enqueued before processing | | -| `gitlab_transaction_rails_queue_duration_total` | Counter | 9.4 | Measures latency between GitLab Workhorse forwarding a request to Rails | `controller`, `action` | -| `gitlab_transaction_view_duration_total` | Counter | 9.4 | Duration for views | `controller`, `action`, `view` | -| `gitlab_view_rendering_duration_seconds` | Histogram | 10.2 | Duration for views (histogram) | `controller`, `action`, `view` | -| `http_requests_total` | Counter | 9.4 | Rack request count | `method`, `status` | -| `http_request_duration_seconds` | Histogram | 9.4 | HTTP response time from rack middleware | `method` | -| `gitlab_transaction_db_count_total` | Counter | 13.1 | Counter for total number of SQL calls | `controller`, `action` | -| `gitlab_transaction_db_write_count_total` | Counter | 13.1 | Counter for total number of write SQL calls | `controller`, `action` | -| `gitlab_transaction_db_cached_count_total` | Counter | 13.1 | Counter for total number of cached SQL calls | `controller`, `action` | -| `http_elasticsearch_requests_duration_seconds` **(STARTER)** | Histogram | 13.1 | Elasticsearch requests duration during web transactions | `controller`, `action` | -| `http_elasticsearch_requests_total` **(STARTER)** | Counter | 13.1 | Elasticsearch requests count during web transactions | `controller`, `action` | -| `pipelines_created_total` | Counter | 9.4 | Counter of pipelines created | | -| `rack_uncaught_errors_total` | Counter | 9.4 | Rack connections handling uncaught errors count | | -| `user_session_logins_total` | Counter | 9.4 | Counter of how many users have logged in since GitLab was started or restarted | | -| `upload_file_does_not_exist` | Counter | 10.7 in EE, 11.5 in CE | Number of times an upload record could not find its file | | -| `failed_login_captcha_total` | Gauge | 11.0 | Counter of failed CAPTCHA attempts during login | | -| `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` | -| `gitlab_issuable_fast_count_by_state_total` | Counter | 13.5 | Total number of row count operations on issue/merge request list pages | | -| `gitlab_issuable_fast_count_by_state_failures_total` | Counter | 13.5 | Number of soft-failed row count operations on issue/merge request list pages | | +| Metric | Type | Since | Description | Labels | +|:---------------------------------------------------------------|:----------|------:|:------------------------------------------------------------------------------------------------------|:--------------------------------------------------------| +| `gitlab_banzai_cached_render_real_duration_seconds` | Histogram | 9.4 | Duration of rendering Markdown into HTML when cached output exists | `controller`, `action` | +| `gitlab_banzai_cacheless_render_real_duration_seconds` | Histogram | 9.4 | Duration of rendering Markdown into HTML when cached output does not exist | `controller`, `action` | +| `gitlab_cache_misses_total` | Counter | 10.2 | Cache read miss | `controller`, `action` | +| `gitlab_cache_operation_duration_seconds` | Histogram | 10.2 | Cache access time | | +| `gitlab_cache_operations_total` | Counter | 12.2 | Cache operations by controller or action | `controller`, `action`, `operation` | +| `gitlab_ci_pipeline_creation_duration_seconds` | Histogram | 13.0 | Time in seconds it takes to create a CI/CD pipeline | | +| `gitlab_ci_pipeline_size_builds` | Histogram | 13.1 | Total number of builds within a pipeline grouped by a pipeline source | `source` | +| `job_waiter_started_total` | Counter | 12.9 | Number of batches of jobs started where a web request is waiting for the jobs to complete | `worker` | +| `job_waiter_timeouts_total` | Counter | 12.9 | Number of batches of jobs that timed out where a web request is waiting for the jobs to complete | `worker` | +| `gitlab_database_transaction_seconds` | Histogram | 12.1 | Time spent in database transactions, in seconds | | +| `gitlab_method_call_duration_seconds` | Histogram | 10.2 | Method calls real duration | `controller`, `action`, `module`, `method` | +| `gitlab_page_out_of_bounds` | Counter | 12.8 | Counter for the PageLimiter pagination limit being hit | `controller`, `action`, `bot` | +| `gitlab_rails_queue_duration_seconds` | Histogram | 9.4 | Measures latency between GitLab Workhorse forwarding a request to Rails | | +| `gitlab_sql_duration_seconds` | Histogram | 10.2 | SQL execution time, excluding `SCHEMA` operations and `BEGIN` / `COMMIT` | | +| `gitlab_ruby_threads_max_expected_threads` | Gauge | 13.3 | Maximum number of threads expected to be running and performing application work | | +| `gitlab_ruby_threads_running_threads` | Gauge | 13.3 | Number of running Ruby threads by name | | +| `gitlab_transaction_cache_<key>_count_total` | Counter | 10.2 | Counter for total Rails cache calls (per key) | | +| `gitlab_transaction_cache_<key>_duration_total` | Counter | 10.2 | Counter for total time (seconds) spent in Rails cache calls (per key) | | +| `gitlab_transaction_cache_count_total` | Counter | 10.2 | Counter for total Rails cache calls (aggregate) | | +| `gitlab_transaction_cache_duration_total` | Counter | 10.2 | Counter for total time (seconds) spent in Rails cache calls (aggregate) | | +| `gitlab_transaction_cache_read_hit_count_total` | Counter | 10.2 | Counter for cache hits for Rails cache calls | `controller`, `action` | +| `gitlab_transaction_cache_read_miss_count_total` | Counter | 10.2 | Counter for cache misses for Rails cache calls | `controller`, `action` | +| `gitlab_transaction_duration_seconds` | Histogram | 10.2 | Duration for all transactions (`gitlab_transaction_*` metrics) | `controller`, `action` | +| `gitlab_transaction_event_build_found_total` | Counter | 9.4 | Counter for build found for API /jobs/request | | +| `gitlab_transaction_event_build_invalid_total` | Counter | 9.4 | Counter for build invalid due to concurrency conflict for API /jobs/request | | +| `gitlab_transaction_event_build_not_found_cached_total` | Counter | 9.4 | Counter for cached response of build not found for API /jobs/request | | +| `gitlab_transaction_event_build_not_found_total` | Counter | 9.4 | Counter for build not found for API /jobs/request | | +| `gitlab_transaction_event_change_default_branch_total` | Counter | 9.4 | Counter when default branch is changed for any repository | | +| `gitlab_transaction_event_create_repository_total` | Counter | 9.4 | Counter when any repository is created | | +| `gitlab_transaction_event_etag_caching_cache_hit_total` | Counter | 9.4 | Counter for ETag cache hit. | `endpoint` | +| `gitlab_transaction_event_etag_caching_header_missing_total` | Counter | 9.4 | Counter for ETag cache miss - header missing | `endpoint` | +| `gitlab_transaction_event_etag_caching_key_not_found_total` | Counter | 9.4 | Counter for ETag cache miss - key not found | `endpoint` | +| `gitlab_transaction_event_etag_caching_middleware_used_total` | Counter | 9.4 | Counter for ETag middleware accessed | `endpoint` | +| `gitlab_transaction_event_etag_caching_resource_changed_total` | Counter | 9.4 | Counter for ETag cache miss - resource changed | `endpoint` | +| `gitlab_transaction_event_fork_repository_total` | Counter | 9.4 | Counter for repository forks (RepositoryForkWorker). Only incremented when source repository exists | | +| `gitlab_transaction_event_import_repository_total` | Counter | 9.4 | Counter for repository imports (RepositoryImportWorker) | | +| `gitlab_transaction_event_patch_hard_limit_bytes_hit_total` | Counter | 13.9 | Counter for diff patch size limit hits | | +| `gitlab_transaction_event_push_branch_total` | Counter | 9.4 | Counter for all branch pushes | | +| `gitlab_transaction_event_push_commit_total` | Counter | 9.4 | Counter for commits | `branch` | +| `gitlab_transaction_event_push_tag_total` | Counter | 9.4 | Counter for tag pushes | | +| `gitlab_transaction_event_rails_exception_total` | Counter | 9.4 | Counter for number of rails exceptions | | +| `gitlab_transaction_event_receive_email_total` | Counter | 9.4 | Counter for received emails | `handler` | +| `gitlab_transaction_event_remote_mirrors_failed_total` | Counter | 10.8 | Counter for failed remote mirrors | | +| `gitlab_transaction_event_remote_mirrors_finished_total` | Counter | 10.8 | Counter for finished remote mirrors | | +| `gitlab_transaction_event_remote_mirrors_running_total` | Counter | 10.8 | Counter for running remote mirrors | | +| `gitlab_transaction_event_remove_branch_total` | Counter | 9.4 | Counter when a branch is removed for any repository | | +| `gitlab_transaction_event_remove_repository_total` | Counter | 9.4 | Counter when a repository is removed | | +| `gitlab_transaction_event_remove_tag_total` | Counter | 9.4 | Counter when a tag is remove for any repository | | +| `gitlab_transaction_event_sidekiq_exception_total` | Counter | 9.4 | Counter of Sidekiq exceptions | | +| `gitlab_transaction_event_stuck_import_jobs_total` | Counter | 9.4 | Count of stuck import jobs | `projects_without_jid_count`, `projects_with_jid_count` | +| `gitlab_transaction_event_update_build_total` | Counter | 9.4 | Counter for update build for API `/jobs/request/:id` | | +| `gitlab_transaction_new_redis_connections_total` | Counter | 9.4 | Counter for new Redis connections | | +| `gitlab_transaction_queue_duration_total` | Counter | 9.4 | Duration jobs were enqueued before processing | | +| `gitlab_transaction_rails_queue_duration_total` | Counter | 9.4 | Measures latency between GitLab Workhorse forwarding a request to Rails | `controller`, `action` | +| `gitlab_transaction_view_duration_total` | Counter | 9.4 | Duration for views | `controller`, `action`, `view` | +| `gitlab_view_rendering_duration_seconds` | Histogram | 10.2 | Duration for views (histogram) | `controller`, `action`, `view` | +| `http_requests_total` | Counter | 9.4 | Rack request count | `method`, `status` | +| `http_request_duration_seconds` | Histogram | 9.4 | HTTP response time from rack middleware | `method` | +| `gitlab_transaction_db_count_total` | Counter | 13.1 | Counter for total number of SQL calls | `controller`, `action` | +| `gitlab_transaction_db_write_count_total` | Counter | 13.1 | Counter for total number of write SQL calls | `controller`, `action` | +| `gitlab_transaction_db_cached_count_total` | Counter | 13.1 | Counter for total number of cached SQL calls | `controller`, `action` | +| `http_elasticsearch_requests_duration_seconds` **(PREMIUM)** | Histogram | 13.1 | Elasticsearch requests duration during web transactions | `controller`, `action` | +| `http_elasticsearch_requests_total` **(PREMIUM)** | Counter | 13.1 | Elasticsearch requests count during web transactions | `controller`, `action` | +| `pipelines_created_total` | Counter | 9.4 | Counter of pipelines created | | +| `rack_uncaught_errors_total` | Counter | 9.4 | Rack connections handling uncaught errors count | | +| `user_session_logins_total` | Counter | 9.4 | Counter of how many users have logged in since GitLab was started or restarted | | +| `upload_file_does_not_exist` | Counter | 10.7 | Number of times an upload record could not find its file. Made available in all tiers in GitLab 11.5. | | +| `failed_login_captcha_total` | Gauge | 11.0 | Counter of failed CAPTCHA attempts during login | | +| `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` | +| `gitlab_issuable_fast_count_by_state_total` | Counter | 13.5 | Total number of row count operations on issue/merge request list pages | | +| `gitlab_issuable_fast_count_by_state_failures_total` | Counter | 13.5 | Number of soft-failed row count operations on issue/merge request list pages | | +| `gitlab_external_http_total` | Counter | 13.8 | Total number of HTTP calls to external systems | `controller`, `action` | +| `gitlab_external_http_duration_seconds` | Counter | 13.8 | Duration in seconds spent on each HTTP call to external systems | | +| `gitlab_external_http_exception_total` | Counter | 13.8 | Total number of exceptions raised when making external HTTP calls | | +| `ci_report_parser_duration_seconds` | Histogram | 13.9 | Time to parse CI/CD report artifacts | `parser` | +| `pipeline_graph_link_calculation_duration_seconds` | Histogram | 13.9 | Total time spent calculating links, in seconds | `project` | +| `pipeline_graph_links_total` | Histogram | 13.9 | Number of links per graph | `project` | +| `pipeline_graph_links_per_job_ratio` | Histogram | 13.9 | Ratio of links to job per graph | `project` | ## Metrics controlled by a feature flag @@ -212,7 +220,7 @@ configuration option in `gitlab.yml`. These metrics are served from the | `destroyed_job_artifacts_count_total` | Counter | 13.6 | Number of destroyed expired job artifacts | | | `destroyed_pipeline_artifacts_count_total` | Counter | 13.8 | Number of destroyed expired pipeline artifacts | | -## Database load balancing metrics **(PREMIUM ONLY)** +## Database load balancing metrics **(PREMIUM SELF)** The following metrics are available: @@ -220,7 +228,7 @@ 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)** +## Database partitioning metrics **(PREMIUM SELF)** The following metrics are available: diff --git a/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md b/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md deleted file mode 100644 index 8fa2e16dcd0..00000000000 --- a/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'gitlab_exporter.md' ---- - -This document was moved to [another location](gitlab_exporter.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 80ddb87e727..23bffae99cf 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -4,7 +4,12 @@ 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/#assignments --- -# Monitoring GitLab with Prometheus +# Monitoring GitLab with Prometheus **(FREE SELF)** + +[Prometheus](https://prometheus.io) is a powerful time-series monitoring service, providing a flexible +platform for monitoring GitLab and other software products. +GitLab provides out-of-the-box monitoring with Prometheus, providing easy +access to high quality time-series monitoring of GitLab services. > **Notes:** > @@ -16,11 +21,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Prometheus and its exporters don't authenticate users, and are available > to anyone who can access them. -[Prometheus](https://prometheus.io) is a powerful time-series monitoring service, providing a flexible -platform for monitoring GitLab and other software products. -GitLab provides out of the box monitoring with Prometheus, providing easy -access to high quality time-series monitoring of GitLab services. - ## Overview Prometheus works by periodically connecting to data sources and collecting their diff --git a/doc/administration/monitoring/prometheus/node_exporter.md b/doc/administration/monitoring/prometheus/node_exporter.md index f27912d5806..6efc9d67e8d 100644 --- a/doc/administration/monitoring/prometheus/node_exporter.md +++ b/doc/administration/monitoring/prometheus/node_exporter.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Node exporter +# Node exporter **(FREE SELF)** The [node exporter](https://github.com/prometheus/node_exporter) enables you to measure various machine resources such as memory, disk and CPU utilization. diff --git a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md index 0dffad59793..df2aa08efaa 100644 --- a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md +++ b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md @@ -4,7 +4,7 @@ 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/#assignments --- -# PgBouncer exporter +# PgBouncer exporter **(FREE SELF)** > Introduced in [Omnibus GitLab 11.0](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/2493). diff --git a/doc/administration/monitoring/prometheus/postgres_exporter.md b/doc/administration/monitoring/prometheus/postgres_exporter.md index 8bc61ff53bb..8b6d3d82018 100644 --- a/doc/administration/monitoring/prometheus/postgres_exporter.md +++ b/doc/administration/monitoring/prometheus/postgres_exporter.md @@ -4,7 +4,7 @@ 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/#assignments --- -# PostgreSQL Server Exporter +# PostgreSQL Server Exporter **(FREE SELF)** The [PostgreSQL Server Exporter](https://github.com/wrouesnel/postgres_exporter) allows you to export various PostgreSQL metrics. diff --git a/doc/administration/monitoring/prometheus/redis_exporter.md b/doc/administration/monitoring/prometheus/redis_exporter.md index 03c215625ec..e9d656a6493 100644 --- a/doc/administration/monitoring/prometheus/redis_exporter.md +++ b/doc/administration/monitoring/prometheus/redis_exporter.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Redis exporter +# Redis exporter **(FREE SELF)** The [Redis exporter](https://github.com/oliver006/redis_exporter) enables you to measure various [Redis](https://redis.io) metrics. For more information on what is exported, diff --git a/doc/administration/monitoring/prometheus/registry_exporter.md b/doc/administration/monitoring/prometheus/registry_exporter.md index 009d94491f3..d2bd86aa908 100644 --- a/doc/administration/monitoring/prometheus/registry_exporter.md +++ b/doc/administration/monitoring/prometheus/registry_exporter.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Registry exporter +# Registry exporter **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/2884) in GitLab 11.9. diff --git a/doc/administration/nfs.md b/doc/administration/nfs.md index bddf770180b..a7009b702ed 100644 --- a/doc/administration/nfs.md +++ b/doc/administration/nfs.md @@ -20,10 +20,10 @@ From GitLab 14.0, technical support for NFS for Git repositories will no longer be provided. Upgrade to [Gitaly Cluster](gitaly/praefect.md) as soon as possible. -Filesystem performance can impact overall GitLab performance, especially for +File system performance can impact overall GitLab performance, especially for actions that read or write to Git repositories. For steps you can use to test -filesystem performance, see -[Filesystem Performance Benchmarking](operations/filesystem_benchmarking.md). +file system performance, see +[File system Performance Benchmarking](operations/filesystem_benchmarking.md). ## Known kernel version incompatibilities @@ -408,7 +408,7 @@ For supported database architecture, see our documentation about ### Finding the requests that are being made to NFS In case of NFS-related problems, it can be helpful to trace -the filesystem requests that are being made by using `perf`: +the file system requests that are being made by using `perf`: ```shell sudo perf trace -e 'nfs4:*' -p $(pgrep -fd ',' puma && pgrep -fd ',' unicorn) diff --git a/doc/administration/npm_registry.md b/doc/administration/npm_registry.md deleted file mode 100644 index 690b6785941..00000000000 --- a/doc/administration/npm_registry.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'packages/index.md' ---- - -This document was moved to [another location](packages/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index 999d9b87363..d1b460df273 100644 --- a/doc/administration/object_storage.md +++ b/doc/administration/object_storage.md @@ -551,17 +551,17 @@ supported by consolidated configuration form, refer to the following guides: | [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) | Yes | -| [Dependency Proxy](packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | -| [Pseudonymizer](pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | +| [Dependency Proxy](packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM SELF)** | Yes | +| [Pseudonymizer](pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | 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) | Yes | | [GitLab Pages content](pages/index.md#using-object-storage) | Yes | -### Other alternatives to filesystem storage +### Other alternatives to file system storage If you're working to [scale out](reference_architectures/index.md) your GitLab implementation, or add fault tolerance and redundancy, you may be -looking at removing dependencies on block or network filesystems. +looking at removing dependencies on block or network file systems. See the following additional guides and [note that Pages requires disk storage](#gitlab-pages-requires-nfs): diff --git a/doc/administration/operations.md b/doc/administration/operations.md deleted file mode 100644 index cfabb5ec27d..00000000000 --- a/doc/administration/operations.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'operations/index.md' ---- - -This document was moved to [another location](operations/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/operations/extra_sidekiq_processes.md b/doc/administration/operations/extra_sidekiq_processes.md index 1b7c0edab04..0157ea8f430 100644 --- a/doc/administration/operations/extra_sidekiq_processes.md +++ b/doc/administration/operations/extra_sidekiq_processes.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Run multiple Sidekiq processes **(CORE ONLY)** +# Run multiple Sidekiq processes **(FREE SELF)** GitLab allows you to start multiple Sidekiq processes. These processes can be used to consume a dedicated set @@ -27,7 +27,7 @@ can be started. ## Start multiple processes > - [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4006) in GitLab 12.10, starting multiple processes with Sidekiq cluster. -> - [Sidekiq cluster moved](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/181) to GitLab [Core](https://about.gitlab.com/pricing/#self-managed) in GitLab 12.10. +> - [Sidekiq cluster moved](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/181) to GitLab [Free](https://about.gitlab.com/pricing/) in GitLab 12.10. > - [Sidekiq cluster became default](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4140) in GitLab 13.0. To start multiple processes: @@ -113,7 +113,7 @@ you list: ## Queue selector > - [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/45) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. -> - [Sidekiq cluster including queue selector moved](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/181) to GitLab [Core](https://about.gitlab.com/pricing/#self-managed) in GitLab 12.10. +> - [Sidekiq cluster including queue selector moved](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/181) to GitLab [Free](https://about.gitlab.com/pricing/) in GitLab 12.10. > - [Renamed from `experimental_queue_selector` to `queue_selector`](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/147) in GitLab 13.6. In addition to selecting queues by name, as above, the `queue_selector` diff --git a/doc/administration/operations/filesystem_benchmarking.md b/doc/administration/operations/filesystem_benchmarking.md index 9072214eb02..6119fcdae45 100644 --- a/doc/administration/operations/filesystem_benchmarking.md +++ b/doc/administration/operations/filesystem_benchmarking.md @@ -4,15 +4,15 @@ 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/#assignments --- -# Filesystem Performance Benchmarking +# File system Performance Benchmarking -Filesystem performance has a big impact on overall GitLab performance, +File system performance has a big impact on overall GitLab performance, especially for actions that read or write to Git repositories. This information -will help benchmark filesystem performance against known good and bad real-world +will help benchmark file system performance against known good and bad real-world systems. -Normally when talking about filesystem performance the biggest concern is -with Network Filesystems (NFS). However, even some local disks can have slow +Normally when talking about file system performance the biggest concern is +with Network File Systems (NFS). However, even some local disks can have slow I/O. The information on this page can be used for either scenario. ## Executing benchmarks @@ -77,7 +77,7 @@ available on the system. It's possible to receive good results on this test but still have poor performance due to read speed and various other factors. -The following one-line commands provide a quick benchmark for filesystem write and read +The following one-line commands provide a quick benchmark for file system write and read performance. This will write 1,000 small files to the directory in which it is executed, and then read the same 1,000 files. @@ -125,4 +125,4 @@ sys 0m1.663s ``` From experience with multiple customers, this task should take under 10 -seconds to indicate good filesystem performance. +seconds to indicate good file system performance. diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index b15417ea8d9..eb1854fee10 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -20,17 +20,17 @@ Keep your GitLab instance up and running smoothly. by GitLab to another file system or another server. - [Sidekiq MemoryKiller](sidekiq_memory_killer.md): Configure Sidekiq MemoryKiller to restart Sidekiq. -- [Multiple Sidekiq processes](extra_sidekiq_processes.md): Configure multiple Sidekiq processes to ensure certain queues always have dedicated workers, no matter the number of jobs that need to be processed. **(CORE ONLY)** +- [Multiple Sidekiq processes](extra_sidekiq_processes.md): Configure multiple Sidekiq processes to ensure certain queues always have dedicated workers, no matter the number of jobs that need to be processed. **(FREE SELF)** - [Puma](puma.md): Understand Puma and puma-worker-killer. - [Unicorn](unicorn.md): Understand Unicorn and unicorn-worker-killer. - Speed up SSH operations by [Authorizing SSH users via a fast, indexed lookup to the GitLab database](fast_ssh_key_lookup.md), and/or by [doing away with user SSH keys stored on GitLab entirely in favor of SSH certificates](ssh_certificates.md). -- [Filesystem Performance Benchmarking](filesystem_benchmarking.md): Filesystem +- [File System Performance Benchmarking](filesystem_benchmarking.md): File system performance can have a big impact on GitLab performance, especially for actions that read or write Git repositories. This information will help benchmark - filesystem performance against known good and bad real-world systems. + file system performance against known good and bad real-world systems. - [The Rails Console](rails_console.md): Provides a way to interact with your GitLab instance from the command line. Used for troubleshooting a problem or retrieving some data that can only be done through direct access to GitLab. - [ChatOps Scripts](https://gitlab.com/gitlab-com/chatops): The GitLab.com Infrastructure team uses this repository to house diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 029f3bb01ed..9997dcb18dd 100644 --- a/doc/administration/operations/moving_repositories.md +++ b/doc/administration/operations/moving_repositories.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Moving repositories managed by GitLab **(CORE ONLY)** +# Moving repositories managed by GitLab **(FREE SELF)** Sometimes you need to move all repositories managed by GitLab to another file system or another server. @@ -20,8 +20,8 @@ The GitLab API is the recommended way to move Git repositories: For more information, see: -- [Configuring additional storage for Gitaly](../gitaly/index.md#network-architecture). Within this - example, additional storage called `storage1` and `storage2` is configured. +- [Configuring additional storage for Gitaly](../gitaly/index.md#network-architecture). This + example configures additional storage called `storage1` and `storage2`. - [The API documentation](../../api/project_repository_storage_moves.md) details the endpoints for querying and scheduling project repository moves. - [The API documentation](../../api/snippet_repository_storage_moves.md) details the endpoints for @@ -38,7 +38,7 @@ Read more in the [API documentation for projects](../../api/project_repository_s GitLab environment, for example: - From a single-node GitLab to a scaled-out architecture. -- From a GitLab instance in your private datacenter to a cloud provider. +- From a GitLab instance in your private data center to a cloud provider. The rest of the document looks at some of the ways you can copy all your repositories from @@ -103,8 +103,8 @@ Using `rsync` to migrate Git data can cause data loss and repository corruption. If the target directory already contains a partial / outdated copy of the repositories it may be wasteful to copy all the data again with `tar`. In this scenario it is better to use `rsync`. This utility -is either already installed on your system or easily installable -via `apt`, `yum`, and so on. +is either already installed on your system, or installable +by using `apt` or `yum`. ```shell sudo -u git sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ @@ -112,7 +112,7 @@ sudo -u git sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ ``` The `/.` in the command above is very important, without it you can -easily get the wrong directory structure in the target directory. +get the wrong directory structure in the target directory. If you want to see progress, replace `-a` with `-av`. #### Single `rsync` to another server @@ -135,20 +135,23 @@ WARNING: Using `rsync` to migrate Git data can cause data loss and repository corruption. [These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422). -Every time you start an `rsync` job it has to inspect all files in -the source directory, all files in the target directory, and then -decide what files to copy or not. If the source or target directory -has many contents this startup phase of `rsync` can become a burden -for your GitLab server. In cases like this you can make `rsync`'s -life easier by dividing its work in smaller pieces, and sync one -repository at a time. +Every time you start an `rsync` job it must: + +- Inspect all files in the source directory. +- Inspect all files in the target directory. +- Decide whether or not to copy files. + +If the source or target directory +has many contents, this startup phase of `rsync` can become a burden +for your GitLab server. You can reduce the workload of `rsync` by dividing its +work in smaller pieces, and sync one repository at a time. In addition to `rsync` we use [GNU Parallel](http://www.gnu.org/software/parallel/). -This utility is not included in GitLab so you need to install it yourself with `apt` -or `yum`. Also note that the GitLab scripts we used below were added in GitLab 8.1. +This utility is not included in GitLab, so you must install it yourself with `apt` +or `yum`. -**This process does not clean up repositories at the target location that no -longer exist at the source.** +This process does not clean up repositories at the target location that no +longer exist at the source. #### Parallel `rsync` for all repositories known to GitLab @@ -218,8 +221,8 @@ Using `rsync` to migrate Git data can cause data loss and repository corruption. [These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422). Suppose you have already done one sync that started after 2015-10-1 12:00 UTC. -Then you might only want to sync repositories that were changed via GitLab -_after_ that time. You can use the `SINCE` variable to tell `rake +Then you might only want to sync repositories that were changed by using GitLab +after that time. You can use the `SINCE` variable to tell `rake gitlab:list_repos` to only print repositories with recent activity. ```shell diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md index 44ac014650e..3b676010bfe 100644 --- a/doc/administration/operations/puma.md +++ b/doc/administration/operations/puma.md @@ -31,7 +31,7 @@ Unicorn in GitLab 14.0. When switching to Puma, Unicorn server configuration will _not_ carry over automatically, due to differences between the two application servers. For Omnibus-based deployments, see [Configuring Puma Settings](https://docs.gitlab.com/omnibus/settings/puma.html#configuring-puma-settings). -For Helm based deployments, see the [Webservice Chart documentation](https://docs.gitlab.com/charts/charts/gitlab/webservice/index.html). +For Helm based deployments, see the [`webservice` chart documentation](https://docs.gitlab.com/charts/charts/gitlab/webservice/index.html). Additionally we strongly recommend that multi-node deployments [configure their load balancers to use the readiness check](../load_balancer.md#readiness-check) due to a difference between Unicorn and Puma in how they handle connections during a restart of the service. diff --git a/doc/administration/operations/speed_up_ssh.md b/doc/administration/operations/speed_up_ssh.md deleted file mode 100644 index 2f3cf40a222..00000000000 --- a/doc/administration/operations/speed_up_ssh.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'fast_ssh_key_lookup.md' ---- - -This document was moved to [another location](fast_ssh_key_lookup.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/packages.md b/doc/administration/packages.md deleted file mode 100644 index 690b6785941..00000000000 --- a/doc/administration/packages.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'packages/index.md' ---- - -This document was moved to [another location](packages/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index ab6202fef4c..63bb969afce 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -312,14 +312,14 @@ configuration. The different supported drivers are: -| Driver | Description | -|------------|-------------------------------------| -| filesystem | Uses a path on the local filesystem | -| Azure | Microsoft Azure Blob Storage | -| gcs | Google Cloud Storage | -| s3 | Amazon Simple Storage Service. Be sure to configure your storage bucket with the correct [S3 Permission Scopes](https://docs.docker.com/registry/storage-drivers/s3/#s3-permission-scopes). | -| swift | OpenStack Swift Object Storage | -| oss | Aliyun OSS | +| Driver | Description | +|--------------|--------------------------------------| +| `filesystem` | Uses a path on the local file system | +| `Azure` | Microsoft Azure Blob Storage | +| `gcs` | Google Cloud Storage | +| `s3` | Amazon Simple Storage Service. Be sure to configure your storage bucket with the correct [S3 Permission Scopes](https://docs.docker.com/registry/storage-drivers/s3/#s3-permission-scopes). | +| `swift` | OpenStack Swift Object Storage | +| `oss` | Aliyun OSS | Although most S3 compatible services (like [MinIO](https://min.io/)) should work with the Container Registry, we only guarantee support for AWS S3. Because we cannot assert the correctness of third-party S3 implementations, we can debug issues, but we cannot patch the registry unless an issue is reproducible against an AWS S3 bucket. diff --git a/doc/administration/packages/dependency_proxy.md b/doc/administration/packages/dependency_proxy.md index 9e315722c24..16cfdc8c784 100644 --- a/doc/administration/packages/dependency_proxy.md +++ b/doc/administration/packages/dependency_proxy.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Dependency Proxy administration > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 13.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Free](https://about.gitlab.com/pricing/) in GitLab 13.6. GitLab can be used as a dependency proxy for a variety of common package managers. diff --git a/doc/administration/packages/index.md b/doc/administration/packages/index.md index 0f391371a6a..25fce08d3d2 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -35,6 +35,8 @@ The Package Registry supports the following formats: The below table lists formats that are not supported, but are accepting Community contributions for. Consider contributing to GitLab. This [development documentation](../../development/packages.md) guides you through the process. +<!-- vale gitlab.Spelling = NO --> + | Format | Status | | ------ | ------ | | Chef | [#36889](https://gitlab.com/gitlab-org/gitlab/-/issues/36889) | @@ -51,6 +53,8 @@ guides you through the process. | Terraform | [WIP: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) | | Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | +<!-- vale gitlab.Spelling = YES --> + ## Enabling the Packages feature NOTE: diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 9e949468805..2b7a7300ad8 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -190,7 +190,7 @@ outside world. ### Additional configuration for Docker container The GitLab Pages daemon doesn't have permissions to bind mounts when it runs -in a Docker container. To overcome this issue, you must change the chroot +in a Docker container. To overcome this issue, you must change the `chroot` behavior: 1. Edit `/etc/gitlab/gitlab.rb`. @@ -222,7 +222,7 @@ control over how the Pages daemon runs and serves content in your environment. | `api_secret_key` | Full path to file with secret key used to authenticate with the GitLab API. Auto-generated when left unset. | `artifacts_server` | Enable viewing [artifacts](../job_artifacts.md) in GitLab Pages. | `artifacts_server_timeout` | Timeout (in seconds) for a proxied request to the artifacts server. -| `artifacts_server_url` | API URL to proxy artifact requests to. Defaults to GitLab `external URL` + `/api/v4`, for example `https://gitlab.com/api/v4`. +| `artifacts_server_url` | API URL to proxy artifact requests to. Defaults to GitLab `external URL` + `/api/v4`, for example `https://gitlab.com/api/v4`. When running a [separate Pages server](#running-gitlab-pages-on-a-separate-server), this URL must point to the main GitLab server's API. | `auth_redirect_uri` | Callback URL for authenticating with GitLab. Defaults to project's subdomain of `pages_external_url` + `/auth`. | `auth_secret` | Secret key for signing authentication requests. Leave blank to pull automatically from GitLab during OAuth registration. | `dir` | Working directory for configuration and secrets files. @@ -236,7 +236,7 @@ control over how the Pages daemon runs and serves content in your environment. | `gitlab_secret` | The OAuth application secret. Leave blank to automatically fill when Pages authenticates with GitLab. | `gitlab_server` | Server to use for authentication when access control is enabled; defaults to GitLab `external_url`. | `headers` | Specify any additional http headers that should be sent to the client with each response. -| `inplace_chroot` | On [systems that don't support bind-mounts](index.md#additional-configuration-for-docker-container), this instructs GitLab Pages to chroot into its `pages_path` directory. Some caveats exist when using inplace chroot; refer to the GitLab Pages [README](https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md#caveats) for more information. +| `inplace_chroot` | On [systems that don't support bind-mounts](index.md#additional-configuration-for-docker-container), this instructs GitLab Pages to `chroot` into its `pages_path` directory. Some caveats exist when using in-place `chroot`; refer to the GitLab Pages [README](https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md#caveats) for more information. | `insecure_ciphers` | Use default list of cipher suites, may contain insecure ones like 3DES and RC4. | `internal_gitlab_server` | Internal GitLab server address used exclusively for API requests. Useful if you want to send that traffic over an internal load balancer. Defaults to GitLab `external_url`. | `listen_proxy` | The addresses to listen on for reverse-proxy requests. Pages binds to these addresses' network sockets and receives incoming requests from them. Sets the value of `proxy_pass` in `$nginx-dir/conf/gitlab-pages.conf`. @@ -538,7 +538,7 @@ the below steps to do a no downtime transfer to a new storage location. 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Verify Pages are still being served up as expected. -1. Unpause Pages deployments by removing from `/etc/gitlab/gitlab.rb` the `sidekiq` setting set above. +1. Resume Pages deployments by removing from `/etc/gitlab/gitlab.rb` the `sidekiq` setting set above. 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Trigger a new Pages deployment and verify it's working as expected. 1. Remove the old Pages storage location: `sudo rm -rf /var/opt/gitlab/gitlab-rails/shared/pages` @@ -573,7 +573,7 @@ You can configure the maximum size of the unpacked archive per project in **Admin Area > Settings > Preferences > Pages**, in **Maximum size of pages (MB)**. The default is 100MB. -### Override maximum pages size per project or group **(PREMIUM ONLY)** +### Override maximum pages size per project or group **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16610) in GitLab 12.7. @@ -629,7 +629,7 @@ database encryption. Proceed with caution. on the **Pages server** and configure this share to allow access from your main **GitLab server**. Note that the example there is more general and - shares several sub-directories from `/home` to several `/nfs/home` mountpoints. + shares several sub-directories from `/home` to several `/nfs/home` mount points. For our Pages-specific example here, we instead share only the default GitLab Pages folder `/var/opt/gitlab/gitlab-rails/shared/pages` from the **Pages server** and we mount it to `/mnt/pages` @@ -730,6 +730,13 @@ or report an issue. ### Object storage settings +WARNING: +With the following settings, Pages uses both NFS and Object Storage locations when deploying the +site. **Do not remove the existing NFS mount used by Pages** when applying these settings. For more +information, see the epics +[3901](https://gitlab.com/groups/gitlab-org/-/epics/3901#how-to-test-object-storage-integration-in-beta) +and [3910](https://gitlab.com/groups/gitlab-org/-/epics/3910). + The following settings are: - Nested under `pages:` and then `object_store:` on source installations. @@ -818,7 +825,7 @@ but commented out to help encourage others to add to it in the future. --> ### `open /etc/ssl/ca-bundle.pem: permission denied` -GitLab Pages runs inside a chroot jail, usually in a uniquely numbered directory like +GitLab Pages runs inside a `chroot` jail, usually in a uniquely numbered directory like `/tmp/gitlab-pages-*`. Within the jail, a bundle of trusted certificates is @@ -828,7 +835,7 @@ from `/opt/gitlab/embedded/ssl/certs/cacert.pem` as part of starting up Pages. If the permissions on the source file are incorrect (they should be `0644`), then -the file inside the chroot jail is also wrong. +the file inside the `chroot` jail is also wrong. Pages logs errors in `/var/log/gitlab/gitlab-pages/current` like: @@ -837,8 +844,8 @@ x509: failed to load system roots and no roots provided open /etc/ssl/ca-bundle.pem: permission denied ``` -The use of a chroot jail makes this error misleading, as it is not -referring to `/etc/ssl` on the root filesystem. +The use of a `chroot` jail makes this error misleading, as it is not +referring to `/etc/ssl` on the root file system. The fix is to correct the source file permissions and restart Pages: @@ -862,8 +869,8 @@ open /opt/gitlab/embedded/ssl/certs/cacert.pem: no such file or directory x509: certificate signed by unknown authority ``` -The reason for those errors is that the files `resolv.conf` and `ca-bundle.pem` are missing inside the chroot. -The fix is to copy the host's `/etc/resolv.conf` and the GitLab certificate bundle inside the chroot: +The reason for those errors is that the files `resolv.conf` and `ca-bundle.pem` are missing inside the `chroot`. +The fix is to copy the host's `/etc/resolv.conf` and the GitLab certificate bundle inside the `chroot`: ```shell sudo mkdir -p /var/opt/gitlab/gitlab-rails/shared/pages/etc/ssl @@ -895,7 +902,7 @@ 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 -another group or user, you must trigger adomain configuration update for Pages. To do +another group or user, you must trigger a domain configuration update for Pages. To do so, write something in the `.update` file. The Pages daemon monitors for changes to this file, and reloads the configuration when changes occur. @@ -928,11 +935,25 @@ For example, if there is a connection timeout: error="failed to connect to internal Pages API: Get \"https://gitlab.example.com:3000/api/v4/internal/pages/status\": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)" ``` +### Pages cannot communicate with an instance of the GitLab API + +If you use the default value for `domain_config_source=auto` and run multiple instances of GitLab +Pages, you may see intermittent 502 error responses while serving Pages content. You may also see +the following warning in the Pages logs: + +```plaintext +WARN[0010] Pages cannot communicate with an instance of the GitLab API. Please sync your gitlab-secrets.json file https://gitlab.com/gitlab-org/gitlab-pages/-/issues/535#workaround. error="pages endpoint unauthorized" +``` + +This can happen if your `gitlab-secrets.json` file is out of date between GitLab Rails and GitLab +Pages. Follow steps 8-10 of [Running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server), +in all of your GitLab Pages instances. + ### 500 error with `securecookie: failed to generate random iv` and `Failed to save the session` This problem most likely results from an [out-dated operating system](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html). -The [Pages daemon uses the `securecookie` library](https://gitlab.com/search?group_id=9970&project_id=734943&repository_ref=master&scope=blobs&search=securecookie&snippets=false) to get random strings via [crypto/rand in Go](https://golang.org/pkg/crypto/rand/#pkg-variables). -This requires the `getrandom` syscall or `/dev/urandom` to be available on the host OS. +The [Pages daemon uses the `securecookie` library](https://gitlab.com/search?group_id=9970&project_id=734943&repository_ref=master&scope=blobs&search=securecookie&snippets=false) to get random strings via [`crypto/rand` in Go](https://golang.org/pkg/crypto/rand/#pkg-variables). +This requires the `getrandom` system call or `/dev/urandom` to be available on the host OS. Upgrading to an [officially supported operating system](https://about.gitlab.com/install/) is recommended. ### The requested scope is invalid, malformed, or unknown @@ -940,6 +961,8 @@ Upgrading to an [officially supported operating system](https://about.gitlab.com This problem comes from the permissions of the GitLab Pages OAuth application. To fix it, go to **Admin > Applications > GitLab Pages** and edit the application. Under **Scopes**, ensure that the `api` scope is selected and save your changes. +When running a [separate Pages server](#running-gitlab-pages-on-a-separate-server), +this setting needs to be configured on the main GitLab server. ### Workaround in case no wildcard DNS entry can be set @@ -948,3 +971,21 @@ If the wildcard DNS [prerequisite](#prerequisites) can't be met, you can still u 1. [Move](../../user/project/settings/index.md#transferring-an-existing-project-into-another-namespace) all projects you need to use Pages with into a single group namespace, for example `pages`. 1. Configure a [DNS entry](#dns-configuration) without the `*.`-wildcard, for example `pages.example.io`. + +### Pages daemon fails with permission denied errors + +If `/tmp` is mounted with `noexec`, the Pages daemon fails to start with an error like: + +```plaintext +{"error":"fork/exec /gitlab-pages: permission denied","level":"fatal","msg":"could not create pages daemon","time":"2021-02-02T21:54:34Z"} +``` + +In this case, change `TMPDIR` to a location that is not mounted with `noexec`. Add the following to +`/etc/gitlab/gitlab.rb`: + +```ruby +gitlab_pages['env'] = {'TMPDIR' => '<new_tmp_path>'} +``` + +Once added, reconfigure with `sudo gitlab-ctl reconfigure` and restart GitLab with +`sudo gitlab-ctl restart`. diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 0aebeaf2ebe..d1a8b703860 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -407,7 +407,7 @@ Pages access control is disabled by default. To enable it: ``` 1. [Restart GitLab](../restart_gitlab.md#installations-from-source). -1. Create a new [system OAuth application](../../integration/oauth_provider.md#adding-an-application-through-the-profile). +1. Create a new [system OAuth application](../../integration/oauth_provider.md#add-an-application-through-the-profile). This should be called `GitLab Pages` and have a `Redirect URL` of `https://projects.example.io/auth`. It does not need to be a "trusted" application, but it does need the `api` scope. diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md deleted file mode 100644 index f5d4b3aa2ff..00000000000 --- a/doc/administration/plugins.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'file_hooks.md' ---- - -This document was moved to [File Hooks](file_hooks.md), after the Plugins feature was renamed to File Hooks. - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/postgresql/index.md b/doc/administration/postgresql/index.md index 0e6fd757421..eabb396aeab 100644 --- a/doc/administration/postgresql/index.md +++ b/doc/administration/postgresql/index.md @@ -11,7 +11,7 @@ In this section, you'll be guided through configuring a PostgreSQL database to be used with GitLab in one of our [reference architectures](../reference_architectures/index.md). There are essentially three setups to choose from. -## PostgreSQL replication and failover with Omnibus GitLab **(PREMIUM ONLY)** +## PostgreSQL replication and failover with Omnibus GitLab **(PREMIUM SELF)** This setup is for when you have installed GitLab using the [Omnibus GitLab **Enterprise Edition** (EE) package](https://about.gitlab.com/install/?version=ee). @@ -21,7 +21,7 @@ the package, so you can it to set up the whole PostgreSQL infrastructure (primar [> Read how to set up PostgreSQL replication and failover using Omnibus GitLab](replication_and_failover.md) -## Standalone PostgreSQL using Omnibus GitLab **(CORE ONLY)** +## Standalone PostgreSQL using Omnibus GitLab **(FREE SELF)** This setup is for when you have installed the [Omnibus GitLab packages](https://about.gitlab.com/install/) (CE or EE), @@ -29,7 +29,7 @@ to use the bundled PostgreSQL having only its service enabled. [> Read how to set up a standalone PostgreSQL instance using Omnibus GitLab](standalone.md) -## Provide your own PostgreSQL instance **(CORE ONLY)** +## Provide your own PostgreSQL instance **(FREE SELF)** This setup is for when you have installed GitLab using the [Omnibus GitLab packages](https://about.gitlab.com/install/) (CE or EE), diff --git a/doc/administration/postgresql/pgbouncer.md b/doc/administration/postgresql/pgbouncer.md index 951edfeaec2..791ca64b001 100644 --- a/doc/administration/postgresql/pgbouncer.md +++ b/doc/administration/postgresql/pgbouncer.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Working with the bundled PgBouncer service **(PREMIUM ONLY)** +# Working with the bundled PgBouncer service **(PREMIUM SELF)** [PgBouncer](http://www.pgbouncer.org/) is used to seamlessly migrate database connections between servers in a failover scenario. Additionally, it can be used diff --git a/doc/administration/postgresql/replication_and_failover.md b/doc/administration/postgresql/replication_and_failover.md index 75d0c558962..e80e38fe5d1 100644 --- a/doc/administration/postgresql/replication_and_failover.md +++ b/doc/administration/postgresql/replication_and_failover.md @@ -4,7 +4,7 @@ group: Database info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# PostgreSQL replication and failover with Omnibus GitLab **(PREMIUM ONLY)** +# PostgreSQL replication and failover with Omnibus GitLab **(PREMIUM SELF)** This document focuses on configuration supported with [GitLab Premium](https://about.gitlab.com/pricing/), using the Omnibus GitLab package. If you're a Community Edition or Starter user, consider using a cloud hosted solution. @@ -46,7 +46,7 @@ Each database node runs three services: `PostgreSQL` - The database itself. -`Patroni` - Communicates with other patroni services in the cluster and handles +`Patroni` - Communicates with other Patroni services in the cluster and handles failover when issues with the leader server occurs. The failover procedure consists of: diff --git a/doc/administration/postgresql/standalone.md b/doc/administration/postgresql/standalone.md index 30495824cd2..cca46a2ea8c 100644 --- a/doc/administration/postgresql/standalone.md +++ b/doc/administration/postgresql/standalone.md @@ -4,7 +4,7 @@ group: Database info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Standalone PostgreSQL using Omnibus GitLab **(CORE ONLY)** +# Standalone PostgreSQL using Omnibus GitLab **(FREE SELF)** If you wish to have your database service hosted separately from your GitLab application servers, you can do this using the PostgreSQL binaries packaged diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md index 41defd89df5..5ec268ac769 100644 --- a/doc/administration/raketasks/check.md +++ b/doc/administration/raketasks/check.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Integrity check Rake task **(CORE ONLY)** +# Integrity check Rake task **(FREE SELF)** GitLab provides Rake tasks to check the integrity of various components. diff --git a/doc/administration/raketasks/doctor.md b/doc/administration/raketasks/doctor.md index c80f580cce6..ec3f7835b9c 100644 --- a/doc/administration/raketasks/doctor.md +++ b/doc/administration/raketasks/doctor.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Doctor Rake tasks **(CORE ONLY)** +# Doctor Rake tasks **(FREE SELF)** This is a collection of tasks to help investigate and repair problems caused by data integrity issues. diff --git a/doc/administration/raketasks/geo.md b/doc/administration/raketasks/geo.md index 492fe4b52ca..3112e5f61b1 100644 --- a/doc/administration/raketasks/geo.md +++ b/doc/administration/raketasks/geo.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Geo Rake Tasks **(PREMIUM ONLY)** +# Geo Rake Tasks **(PREMIUM SELF)** The following Rake tasks are for [Geo installations](../geo/index.md). diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index 630570cb81f..c29865be56c 100644 --- a/doc/administration/raketasks/github_import.md +++ b/doc/administration/raketasks/github_import.md @@ -4,7 +4,7 @@ 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/#assignments --- -# GitHub import **(CORE ONLY)** +# GitHub import **(FREE SELF)** > [Introduced]( https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10308) in GitLab 9.1. diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md index 7dafda89e3c..531e9e89020 100644 --- a/doc/administration/raketasks/ldap.md +++ b/doc/administration/raketasks/ldap.md @@ -4,7 +4,7 @@ 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/#assignments --- -# LDAP Rake tasks **(CORE ONLY)** +# LDAP Rake tasks **(FREE SELF)** The following are LDAP-related Rake tasks. @@ -34,7 +34,7 @@ limit by passing a number to the check task: rake gitlab:ldap:check[50] ``` -## Run a group sync **(STARTER ONLY)** +## Run a group sync **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/14735) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.2. @@ -233,9 +233,9 @@ It can also be used as a receiving application for content encrypted with a KMS: gcloud kms decrypt --key my-key --keyring my-test-kms --plaintext-file=- --ciphertext-file=my-file --location=us-west1 | sudo gitlab-rake gitlab:ldap:secret:write ``` -**gcloud secret integration example** +**Google Cloud secret integration example** -It can also be used as a receiving application for secrets out of gcloud: +It can also be used as a receiving application for secrets out of Google Cloud: ```shell gcloud secrets versions access latest --secret="my-test-secret" > $1 | sudo gitlab-rake gitlab:ldap:secret:write diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index 26381434ad4..85e905702c8 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Maintenance Rake tasks **(CORE ONLY)** +# Maintenance Rake tasks **(FREE SELF)** GitLab provides Rake tasks for general maintenance. @@ -64,9 +64,10 @@ Repository storage paths: GitLab Shell path: /opt/gitlab/embedded/service/gitlab-shell ``` -## Show GitLab license information **(STARTER ONLY)** +## Show GitLab license information **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20501) in GitLab Starter 12.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20501) in GitLab 12.6. +> - [Moved](../../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. This command shows information about your [GitLab license](../../user/admin_area/license.md) and how many seats are used. It is only available on GitLab Enterprise @@ -325,6 +326,39 @@ sudo gitlab-rake db:migrate After the command completes, run `sudo gitlab-rake db:migrate:status` to check if all migrations are completed (have an `up` status). +## Rebuild database indexes + +WARNING: +This is an experimental feature that isn't enabled by default. + +Database indexes can be rebuilt regularly to reclaim space and maintain healthy levels of index bloat over time. + +In order to rebuild the two indexes with the highest estimated bloat, use the following Rake task: + +```shell +sudo gitlab-rake gitlab:db:reindex +``` + +In order to target a specific index, use the following Rake task: + +```shell +sudo gitlab-rake gitlab:db:reindex['public.a_specific_index'] +``` + +The following index types are not supported: + +1. Unique and primary key indexes +1. Indexes used for constraint exclusion +1. Partitioned indexes +1. Expression indexes + +Optionally, this Rake task sends annotations to a Grafana (4.6 or later) endpoint. Use the following custom environment variables in order to enable annotations: + +1. `GRAFANA_API_URL` - Grafana's base URL, for example `http://some-host:3000`. +1. `GRAFANA_API_KEY` - Grafana API key with at least `Editor role`. + +You can also [enable reindexing as a regular cron job](https://docs.gitlab.com/omnibus/settings/database.html#automatic-database-reindexing). + ## Import common metrics Sometimes you may need to re-import the common metrics that power the Metrics dashboards. diff --git a/doc/administration/raketasks/praefect.md b/doc/administration/raketasks/praefect.md index 17c3e44bb7e..5fe0546999b 100644 --- a/doc/administration/raketasks/praefect.md +++ b/doc/administration/raketasks/praefect.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Praefect Rake tasks **(CORE ONLY)** +# Praefect Rake tasks **(FREE SELF)** > [Introduced]( https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28369) in GitLab 12.10. diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md index 0ea0bb3c28f..0fe15f2b5ba 100644 --- a/doc/administration/raketasks/project_import_export.md +++ b/doc/administration/raketasks/project_import_export.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Project import/export administration **(CORE ONLY)** +# Project import/export administration **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3050) in GitLab 8.9. > - From GitLab 11.3, import/export can use object storage automatically. diff --git a/doc/administration/raketasks/storage.md b/doc/administration/raketasks/storage.md index 158b541b36b..7fedcbf3c1a 100644 --- a/doc/administration/raketasks/storage.md +++ b/doc/administration/raketasks/storage.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Repository storage Rake tasks **(CORE ONLY)** +# Repository storage Rake tasks **(FREE SELF)** This is a collection of Rake tasks to help you list and migrate existing projects and their attachments to the new diff --git a/doc/administration/raketasks/uploads/migrate.md b/doc/administration/raketasks/uploads/migrate.md index 2f51bf9357f..ab0a51ba8d6 100644 --- a/doc/administration/raketasks/uploads/migrate.md +++ b/doc/administration/raketasks/uploads/migrate.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Uploads migrate Rake tasks **(CORE ONLY)** +# Uploads migrate Rake tasks **(FREE SELF)** There is a Rake task for migrating uploads between different storage types. diff --git a/doc/administration/raketasks/uploads/sanitize.md b/doc/administration/raketasks/uploads/sanitize.md index 637992d52ca..7dc813de14e 100644 --- a/doc/administration/raketasks/uploads/sanitize.md +++ b/doc/administration/raketasks/uploads/sanitize.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Uploads sanitize Rake tasks **(CORE ONLY)** +# Uploads sanitize Rake tasks **(FREE SELF)** In GitLab 11.9 and later, EXIF data is automatically stripped from JPG or TIFF image uploads. diff --git a/doc/administration/read_only_gitlab.md b/doc/administration/read_only_gitlab.md index d1cb53d0090..23f55cb8463 100644 --- a/doc/administration/read_only_gitlab.md +++ b/doc/administration/read_only_gitlab.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Place GitLab into a read-only state **(CORE ONLY)** +# Place GitLab into a read-only state **(FREE SELF)** WARNING: This document should be used as a temporary solution. diff --git a/doc/administration/redis/replication_and_failover.md b/doc/administration/redis/replication_and_failover.md index 1abc52b65cc..20a9fbd7d68 100644 --- a/doc/administration/redis/replication_and_failover.md +++ b/doc/administration/redis/replication_and_failover.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Redis replication and failover with Omnibus GitLab **(PREMIUM ONLY)** +# Redis replication and failover with Omnibus GitLab **(PREMIUM SELF)** NOTE: This is the documentation for the Omnibus GitLab packages. For using your own diff --git a/doc/administration/redis/replication_and_failover_external.md b/doc/administration/redis/replication_and_failover_external.md index 3bcefe2ef13..1b2e93cccd9 100644 --- a/doc/administration/redis/replication_and_failover_external.md +++ b/doc/administration/redis/replication_and_failover_external.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Redis replication and failover providing your own instance **(CORE ONLY)** +# Redis replication and failover providing your own instance **(FREE SELF)** If you’re hosting GitLab on a cloud provider, you can optionally use a managed service for Redis. For example, AWS offers ElastiCache that runs Redis. diff --git a/doc/administration/redis/standalone.md b/doc/administration/redis/standalone.md index 0e7eca84d17..42482475d26 100644 --- a/doc/administration/redis/standalone.md +++ b/doc/administration/redis/standalone.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Standalone Redis using Omnibus GitLab **(CORE ONLY)** +# Standalone Redis using Omnibus GitLab **(FREE SELF)** The Omnibus GitLab package can be used to configure a standalone Redis server. In this configuration, Redis is not scaled, and represents a single diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index afa53b5efa8..f9765183e64 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Reference architecture: up to 10,000 users **(PREMIUM ONLY)** +# Reference architecture: up to 10,000 users **(PREMIUM SELF)** This page describes GitLab reference architecture for up to 10,000 users. For a full list of reference architectures, see @@ -17,21 +17,21 @@ full list of reference architectures, see | Service | Nodes | Configuration | GCP | AWS | Azure | |--------------------------------------------|-------------|-------------------------|-----------------|-------------|----------| -| External load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Consul | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| PostgreSQL | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Internal load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | -| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | -| Gitaly | 2 (minimum) | 16 vCPU, 60 GB memory | n1-standard-16 | m5.4xlarge | D16s v3 | -| Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| GitLab Rails | 3 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | c5.9xlarge | F32s v2 | -| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| External load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| Consul | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| PostgreSQL | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | `m5.xlarge` | D4s v3 | +| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| Internal load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | `m5.xlarge` | D4s v3 | +| Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | `m5.xlarge` | D4s v3 | +| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | `t3.small` | B1MS | +| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | `t3.small` | B1MS | +| Gitaly | 2 (minimum) | 16 vCPU, 60 GB memory | n1-standard-16 | `m5.4xlarge` | D16s v3 | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | `m5.xlarge` | D4s v3 | +| GitLab Rails | 3 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | `c5.9xlarge` | F32s v2 | +| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | `c5.xlarge` | F4s v2 | | Object storage | n/a | n/a | n/a | n/a | n/a | -| NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | `c5.xlarge` | F4s v2 | ```mermaid stateDiagram-v2 @@ -1928,7 +1928,7 @@ GitLab has been tested on a number of object storage providers: - [Google Cloud Storage](https://cloud.google.com/storage) - [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) +- [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. @@ -1957,7 +1957,7 @@ on what features you intend to use: | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | | [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | | [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes | -| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | +| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | 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) | Yes | @@ -1983,7 +1983,7 @@ work. </a> </div> -## Configure Advanced Search **(STARTER ONLY)** +## Configure Advanced Search **(PREMIUM SELF)** You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) for faster, more advanced code search across your entire GitLab instance. diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index 161964353f5..138d3c34389 100644 --- a/doc/administration/reference_architectures/1k_users.md +++ b/doc/administration/reference_architectures/1k_users.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Reference architecture: up to 1,000 users **(CORE ONLY)** +# Reference architecture: up to 1,000 users **(FREE SELF)** This page describes GitLab reference architecture for up to 1,000 users. For a full list of reference architectures, see @@ -21,8 +21,8 @@ many organizations . | Users | Configuration | GCP | AWS | Azure | |--------------|-------------------------|----------------|-----------------|----------------| -| Up to 500 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | -| Up to 1,000 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | +| Up to 500 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | `c5.xlarge` | F4s v2 | +| Up to 1,000 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | `c5.2xlarge` | F8s v2 | The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) @@ -45,9 +45,9 @@ To install GitLab for this default reference architecture, use the standard You can also optionally configure GitLab to use an [external PostgreSQL service](../postgresql/external.md) or an [external object storage service](../object_storage.md) for added -performance and reliability at a reduced complexity cost. +performance and reliability at an increased complexity cost. -## Configure Advanced Search **(STARTER ONLY)** +## Configure Advanced Search **(PREMIUM SELF)** You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) for faster, more advanced code search across your entire GitLab instance. diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index d96e93d4ab4..66a9c4adbac 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Reference architecture: up to 25,000 users **(PREMIUM ONLY)** +# Reference architecture: up to 25,000 users **(PREMIUM SELF)** This page describes GitLab reference architecture for up to 25,000 users. For a full list of reference architectures, see @@ -17,21 +17,21 @@ full list of reference architectures, see | Service | Nodes | Configuration | GCP | AWS | Azure | |-----------------------------------------|-------------|-------------------------|-----------------|-------------|----------| -| External load balancing node | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | -| Consul | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| PostgreSQL | 3 | 8 vCPU, 30 GB memory | n1-standard-8 | m5.2xlarge | D8s v3 | -| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Internal load balancing node | 1 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | c5.large | F2s v2 | -| Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | -| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | -| Gitaly | 2 (minimum) | 32 vCPU, 120 GB memory | n1-standard-32 | m5.8xlarge | D32s v3 | -| Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| GitLab Rails | 5 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | c5.9xlarge | F32s v2 | -| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| External load balancing node | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | `c5.xlarge` | F4s v2 | +| Consul | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| PostgreSQL | 3 | 8 vCPU, 30 GB memory | n1-standard-8 | `m5.2xlarge` | D8s v3 | +| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| Internal load balancing node | 1 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | `c5.large` | F2s v2 | +| Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | `m5.xlarge` | D4s v3 | +| Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | `m5.xlarge` | D4s v3 | +| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | `t3.small` | B1MS | +| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | `t3.small` | B1MS | +| Gitaly | 2 (minimum) | 32 vCPU, 120 GB memory | n1-standard-32 | `m5.8xlarge` | D32s v3 | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | `m5.xlarge` | D4s v3 | +| GitLab Rails | 5 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | `c5.9xlarge` | F32s v2 | +| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | `c5.xlarge` | F4s v2 | | Object storage | n/a | n/a | n/a | n/a | n/a | -| NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | `c5.xlarge` | F4s v2 | ```mermaid stateDiagram-v2 @@ -1928,7 +1928,7 @@ GitLab has been tested on a number of object storage providers: - [Google Cloud Storage](https://cloud.google.com/storage) - [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) +- [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. @@ -1957,7 +1957,7 @@ on what features you intend to use: | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | | [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | | [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes | -| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | +| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | 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) | Yes | @@ -1983,7 +1983,7 @@ work. </a> </div> -## Configure Advanced Search **(STARTER ONLY)** +## Configure Advanced Search **(PREMIUM SELF)** You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) for faster, more advanced code search across your entire GitLab instance. diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index 3d38586fa62..1d11f972c2a 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Reference architecture: up to 2,000 users **(CORE ONLY)** +# Reference architecture: up to 2,000 users **(FREE SELF)** This page describes GitLab reference architecture for up to 2,000 users. For a full list of reference architectures, see @@ -18,14 +18,14 @@ For a full list of reference architectures, see | Service | Nodes | Configuration | GCP | AWS | Azure | |------------------------------------------|--------|-------------------------|----------------|--------------|---------| -| Load balancer | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| PostgreSQL | 1 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | -| Redis | 1 | 1 vCPU, 3.75 GB memory | n1-standard-1 | m5.large | D2s v3 | -| Gitaly | 1 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| GitLab Rails | 2 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | -| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| Load balancer | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| PostgreSQL | 1 | 2 vCPU, 7.5 GB memory | n1-standard-2 | `m5.large` | D2s v3 | +| Redis | 1 | 1 vCPU, 3.75 GB memory | n1-standard-1 | `m5.large` | D2s v3 | +| Gitaly | 1 | 4 vCPU, 15 GB memory | n1-standard-4 | `m5.xlarge` | D4s v3 | +| GitLab Rails | 2 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | `c5.2xlarge` | F8s v2 | +| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | | Object storage | n/a | n/a | n/a | n/a | n/a | -| NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | `c5.xlarge` | F4s v2 | ```mermaid stateDiagram-v2 @@ -789,7 +789,7 @@ running [Prometheus](../monitoring/prometheus/index.md) and gitlab_exporter['enable'] = false ``` -1. Prometheus also needs some scrape configs to pull all the data from the various +1. Prometheus also needs some scrape configurations to pull all the data from the various nodes where we configured exporters. Assuming that your nodes' IPs are: ```plaintext @@ -879,7 +879,7 @@ GitLab has been tested on a number of object storage providers: - [Google Cloud Storage](https://cloud.google.com/storage) - [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) +- [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. @@ -908,7 +908,7 @@ on what features you intend to use: | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | | [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | | [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes | -| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | +| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | 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) | Yes | @@ -932,7 +932,7 @@ functioning backups is encountered. </a> </div> -## Configure Advanced Search **(STARTER ONLY)** +## Configure Advanced Search **(PREMIUM SELF)** You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) for faster, more advanced code search across your entire GitLab instance. diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index 648fac8025f..0fc48657c05 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Reference architecture: up to 3,000 users **(PREMIUM ONLY)** +# Reference architecture: up to 3,000 users **(PREMIUM SELF)** This page describes GitLab reference architecture for up to 3,000 users. It is designed to help your organization achieve a @@ -25,18 +25,18 @@ For a full list of reference architectures, see | Service | Nodes | Configuration | GCP | AWS | Azure | |--------------------------------------------|-------------|-----------------------|----------------|-------------|---------| -| External load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Redis | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | -| Consul + Sentinel | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| PostgreSQL | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | -| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Internal load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Gitaly | 2 (minimum) | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | -| GitLab Rails | 3 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | -| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| External load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| Redis | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | `m5.large` | D2s v3 | +| Consul + Sentinel | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| PostgreSQL | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | `m5.large` | D2s v3 | +| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| Internal load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| Gitaly | 2 (minimum) | 4 vCPU, 15 GB memory | n1-standard-4 | `m5.xlarge` | D4s v3 | +| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | n1-standard-2 | `m5.large` | D2s v3 | +| GitLab Rails | 3 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | `c5.2xlarge` | F8s v2 | +| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | | Object storage | n/a | n/a | n/a | n/a | n/a | -| NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | `c5.xlarge` | F4s v2 | ```mermaid stateDiagram-v2 @@ -1621,7 +1621,7 @@ GitLab has been tested on a number of object storage providers: - [Google Cloud Storage](https://cloud.google.com/storage) - [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) +- [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. @@ -1650,7 +1650,7 @@ on what features you intend to use: | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | | [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | | [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes | -| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | +| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | 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) | Yes | @@ -1676,7 +1676,7 @@ work. </a> </div> -## Configure Advanced Search **(STARTER ONLY)** +## Configure Advanced Search **(PREMIUM SELF)** You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) for faster, more advanced code search across your entire GitLab instance. diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index 093869d331b..7eb56f62774 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Reference architecture: up to 50,000 users **(PREMIUM ONLY)** +# Reference architecture: up to 50,000 users **(PREMIUM SELF)** This page describes GitLab reference architecture for up to 50,000 users. For a full list of reference architectures, see @@ -17,21 +17,21 @@ full list of reference architectures, see | Service | Nodes | Configuration | GCP | AWS | Azure | |-----------------------------------------|-------------|-------------------------|-----------------|--------------|----------| -| External load balancing node | 1 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | -| Consul | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| PostgreSQL | 3 | 16 vCPU, 60 GB memory | n1-standard-16 | m5.4xlarge | D16s v3 | -| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Internal load balancing node | 1 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | -| Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | -| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | -| Gitaly | 2 (minimum) | 64 vCPU, 240 GB memory | n1-standard-64 | m5.16xlarge | D64s v3 | -| Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| GitLab Rails | 12 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | c5.9xlarge | F32s v2 | -| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| External load balancing node | 1 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | `c5.2xlarge` | F8s v2 | +| Consul | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| PostgreSQL | 3 | 16 vCPU, 60 GB memory | n1-standard-16 | `m5.4xlarge` | D16s v3 | +| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| Internal load balancing node | 1 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | `c5.2xlarge` | F8s v2 | +| Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | `m5.xlarge` | D4s v3 | +| Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | `m5.xlarge` | D4s v3 | +| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | `t3.small` | B1MS | +| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | `t3.small` | B1MS | +| Gitaly | 2 (minimum) | 64 vCPU, 240 GB memory | n1-standard-64 | `m5.16xlarge` | D64s v3 | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | `m5.xlarge` | D4s v3 | +| GitLab Rails | 12 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | `c5.9xlarge` | F32s v2 | +| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | `c5.xlarge` | F4s v2 | | Object storage | n/a | n/a | n/a | n/a | n/a | -| NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | `c5.xlarge` | F4s v2 | ```mermaid stateDiagram-v2 @@ -1928,7 +1928,7 @@ GitLab has been tested on a number of object storage providers: - [Google Cloud Storage](https://cloud.google.com/storage) - [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) +- [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. @@ -1957,7 +1957,7 @@ on what features you intend to use: | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | | [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | | [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes | -| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | +| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | 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) | Yes | @@ -1983,7 +1983,7 @@ work. </a> </div> -## Configure Advanced Search **(STARTER ONLY)** +## Configure Advanced Search **(PREMIUM SELF)** You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) for faster, more advanced code search across your entire GitLab instance. diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index 16ad866a108..d617920e2e4 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Reference architecture: up to 5,000 users **(PREMIUM ONLY)** +# Reference architecture: up to 5,000 users **(PREMIUM SELF)** This page describes GitLab reference architecture for up to 5,000 users. For a full list of reference architectures, see @@ -24,18 +24,18 @@ costly-to-operate environment by using the | Service | Nodes | Configuration | GCP | AWS | Azure | |--------------------------------------------|-------------|-------------------------|----------------|-------------|----------| -| External load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Redis | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | -| Consul + Sentinel | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| PostgreSQL | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | -| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Internal load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Gitaly | 2 (minimum) | 8 vCPU, 30 GB memory | n1-standard-8 | m5.2xlarge | D8s v3 | -| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | -| GitLab Rails | 3 | 16 vCPU, 14.4 GB memory | n1-highcpu-16 | c5.4xlarge | F16s v2 | -| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| External load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| Redis | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | `m5.large` | D2s v3 | +| Consul + Sentinel | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| PostgreSQL | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | `m5.large` | D2s v3 | +| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| Internal load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | +| Gitaly | 2 (minimum) | 8 vCPU, 30 GB memory | n1-standard-8 | `m5.2xlarge` | D8s v3 | +| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | n1-standard-2 | `m5.large` | D2s v3 | +| GitLab Rails | 3 | 16 vCPU, 14.4 GB memory | n1-highcpu-16 | `c5.4xlarge` | F16s v2 | +| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | `c5.large` | F2s v2 | | Object storage | n/a | n/a | n/a | n/a | n/a | -| NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | `c5.xlarge` | F4s v2 | ```mermaid stateDiagram-v2 @@ -1620,7 +1620,7 @@ GitLab has been tested on a number of object storage providers: - [Google Cloud Storage](https://cloud.google.com/storage) - [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) +- [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. @@ -1649,7 +1649,7 @@ on what features you intend to use: | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | | [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | | [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes | -| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | +| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | 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) | Yes | @@ -1675,7 +1675,7 @@ work. </a> </div> -## Configure Advanced Search **(STARTER ONLY)** +## Configure Advanced Search **(PREMIUM SELF)** You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) for faster, more advanced code search across your entire GitLab instance. diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index b90b8d67b68..035811cd494 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -91,7 +91,7 @@ Also, not implementing extra servers for GitLab doesn't necessarily mean that yo more downtime. Depending on your needs and experience level, single servers can have more actual perceived uptime for your users. -### Automated backups **(CORE ONLY)** +### Automated backups **(FREE SELF)** > - Level of complexity: **Low** > - Required domain knowledge: PostgreSQL, GitLab configurations, Git @@ -102,7 +102,7 @@ this can be an optimal solution if you don't have strict requirements. [Automated backups](../../raketasks/backup_restore.md#configuring-cron-to-make-daily-backups) is the least complex to setup. This provides a point-in-time recovery of a predetermined schedule. -### Traffic load balancer **(STARTER ONLY)** +### Traffic load balancer **(PREMIUM SELF)** > - Level of complexity: **Medium** > - Required domain knowledge: HAProxy, shared storage, distributed systems @@ -124,7 +124,7 @@ to the default installation: For more details on how to configure a traffic load balancer with GitLab, you can refer to any of the [available reference architectures](#available-reference-architectures) with more than 1,000 users. -### Zero downtime updates **(STARTER ONLY)** +### Zero downtime updates **(PREMIUM SELF)** > - Level of complexity: **Medium** > - Required domain knowledge: PostgreSQL, HAProxy, shared storage, distributed systems @@ -134,7 +134,7 @@ Single GitLab nodes can be updated with only a [few minutes of downtime](https:/ To avoid this, we recommend to separate GitLab into several application nodes. As long as at least one of each component is online and capable of handling the instance's usage load, your team's productivity will not be interrupted during the update. -### Automated database failover **(PREMIUM ONLY)** +### Automated database failover **(PREMIUM SELF)** > - Level of complexity: **High** > - Required domain knowledge: PgBouncer, Repmgr or Patroni, shared storage, distributed systems @@ -145,7 +145,7 @@ cluster management and failover policies. [PgBouncer in conjunction with Repmgr or Patroni](../postgresql/replication_and_failover.md) is recommended. -### Instance level replication with GitLab Geo **(PREMIUM ONLY)** +### Instance level replication with GitLab Geo **(PREMIUM SELF)** > - Level of complexity: **Very High** > - Required domain knowledge: Storage replication diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index 6f7a72a0ef2..6c7069a5ac6 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -14,25 +14,24 @@ integrity of all data committed to a repository. GitLab administrators can trigger such a check for a project via the project page under the admin panel. The checks run asynchronously so it may take a few minutes before the check result is visible on the project admin page. If the -checks failed you can see their output on in the [`repocheck.log` -file.](logs.md#repochecklog) +checks failed you can see their output on in the +[`repocheck.log` file.](logs.md#repochecklog) -NOTE: -It is OFF by default because it still causes too many false alarms. +This setting is off by default, because it can cause many false alarms. ## Periodic checks When enabled, GitLab periodically runs a repository check on all project repositories and wiki repositories in order to detect data corruption. -A project will be checked no more than once per month. If any projects -fail their repository checks all GitLab administrators will receive an email +A project is checked no more than once per month. If any projects +fail their repository checks all GitLab administrators receive an email notification of the situation. This notification is sent out once a week, by default, midnight at the start of Sunday. Repositories with known check failures can be found at `/admin/projects?last_repository_check_failed=1`. ## Disabling periodic checks -You can disable the periodic checks on the 'Settings' page of the admin +You can disable the periodic checks on the **Settings** page of the admin panel. ## What to do if a check failed @@ -40,9 +39,9 @@ panel. If the repository check fails for some repository you should look up the error in the [`repocheck.log` file](logs.md#repochecklog) on disk: -- `/var/log/gitlab/gitlab-rails` for Omnibus installations +- `/var/log/gitlab/gitlab-rails` for Omnibus GitLab installations - `/home/git/gitlab/log` for installations from source If the periodic repository check causes false alarms, you can clear all repository check states by -navigating to **Admin Area > Settings > Repository** +going to **Admin Area > Settings > Repository** (`/admin/application_settings/repository`) and clicking **Clear all repository checks**. diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index c71d1a5714c..1c6218b22be 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -40,9 +40,9 @@ storage2: ## Configure GitLab -In order for [backups](../raketasks/backup_restore.md) to work correctly, the storage path must **not** be a -mount point and the GitLab user should have correct permissions for the parent -directory of the path. In Omnibus GitLab this is taken care of automatically, +For [backups](../raketasks/backup_restore.md) to work correctly, the storage path cannot be a +mount point, and the GitLab user must have correct permissions for the parent +directory of the path. Omnibus GitLab takes care of these issues for you, but for source installations you should be extra careful. The thing is that for compatibility reasons `gitlab.yml` has a different @@ -52,22 +52,26 @@ indicate `git_data_dirs`, which for the example above would be `/home/git`. Then, Omnibus creates a `repositories` directory under that path to use with `gitlab.yml`. -This little detail matters because while restoring a backup, the current -contents of `/home/git/repositories` [are moved to](https://gitlab.com/gitlab-org/gitlab/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56) `/home/git/repositories.old`, -so if `/home/git/repositories` is the mount point, then `mv` would be moving +WARNING: +This detail matters because while restoring a backup, the current +contents of `/home/git/repositories` +[are moved to](https://gitlab.com/gitlab-org/gitlab/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56) +`/home/git/repositories.old`. +If `/home/git/repositories` is the mount point, then `mv` would be moving things between mount points, and bad things could happen. Ideally, -`/home/git` would be the mount point, so then things would be moving within the -same mount point. This is guaranteed with Omnibus installations (because they -don't specify the full repository path but the parent path), but not for source -installations. +`/home/git` would be the mount point, so things would remain inside the +same mount point. Omnibus installations guarantee this, because they +don't specify the full repository path but instead the parent path, but source +installations do not. -Now that you've read that big fat warning above, let's edit the configuration -files and add the full paths of the alternative repository storage paths. In +Next, edit the configuration +files, and add the full paths of the alternative repository storage paths. In the example below, we add two more mount points that are named `nfs_1` and `nfs_2` respectively. NOTE: -This example uses NFS. We do not recommend using EFS for storage as it may impact GitLab performance. See the [relevant documentation](nfs.md#avoid-using-awss-elastic-file-system-efs) for more details. +This example uses NFS. We do not recommend using EFS for storage as it may impact GitLab performance. Read +the [relevant documentation](nfs.md#avoid-using-awss-elastic-file-system-efs) for more details. **For installations from source** @@ -112,7 +116,7 @@ working, you can remove the `repos_path` line. ## Choose where new repositories are stored -Once you set the multiple storage paths, you can choose where new repositories +After you set the multiple storage paths, you can choose where new repositories are stored in the Admin Area under **Settings > Repository > Repository storage > Storage nodes for new repositories**. Each storage can be assigned a weight from 0-100. When a new project is created, these diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index 6ec43a8ce06..52e4db6ca31 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Repository storage types **(CORE ONLY)** +# Repository storage types **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28283) in GitLab 10.0. > - Hashed storage became the default for new installations in GitLab 12.0 @@ -38,13 +38,13 @@ been disabled. Hashed storage is the storage behavior we rolled out with 10.0. Instead of coupling project URL and the folder structure where the repository is -stored on disk, we are coupling a hash, based on the project's ID. This makes +stored on disk, we couple a hash based on the project's ID. This makes the folder structure immutable, and therefore eliminates any requirement to synchronize state from URLs to disk structure. This means that renaming a group, user, or project costs only the database transaction, and takes effect immediately. -The hash also helps to spread the repositories more evenly on the disk, so the +The hash also helps spread the repositories more evenly on the disk. The top-level directory contains fewer folders than the total number of top-level namespaces. @@ -136,8 +136,8 @@ when housekeeping is run on the source project. ### Hashed storage coverage migration Files stored in an S3-compatible endpoint do not have the downsides -mentioned earlier, if they are not prefixed with `#{namespace}/#{project_name}`, -which is true for CI Cache and LFS Objects. +mentioned earlier, if they are not prefixed with `#{namespace}/#{project_name}`. +This is true for CI Cache and LFS Objects. In the table below, you can find the coverage of the migration to the hashed storage. @@ -161,7 +161,8 @@ When avatar is replaced, `Upload` model is destroyed and a new one takes place w #### CI artifacts -CI Artifacts are S3 compatible since **9.4** (GitLab Premium), and available in GitLab Core since **10.6**. +CI Artifacts are S3 compatible since **9.4** (GitLab Premium), and available in GitLab Free since +**10.6**. #### LFS objects @@ -194,10 +195,10 @@ reasons, GitLab replicated the same mapping structure from the projects URLs: - Project's repository: `#{namespace}/#{project_name}.git` - Project's wiki: `#{namespace}/#{project_name}.wiki.git` -This structure made it simple to migrate from existing solutions to GitLab and -easy for Administrators to find where the repository is stored. +This structure enables you to migrate from existing solutions to GitLab, and +for Administrators to find where the repository is stored. -On the other hand this has some drawbacks: +This approach also has some drawbacks: Storage location concentrates a huge number of top-level namespaces. The impact can be reduced by the introduction of @@ -211,4 +212,4 @@ is at that same URL today. Any change in the URL needs to be reflected on disk (when groups / users or projects are renamed). This can add a lot of load in big installations, -especially if using any type of network based filesystem. +especially if using any type of network based file system. diff --git a/doc/administration/repository_storages.md b/doc/administration/repository_storages.md deleted file mode 100644 index 93d0ee3cac9..00000000000 --- a/doc/administration/repository_storages.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'repository_storage_paths.md' ---- - -This document was moved to [another location](repository_storage_paths.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md index 4f104c6a63f..69b3ae5282f 100644 --- a/doc/administration/restart_gitlab.md +++ b/doc/administration/restart_gitlab.md @@ -140,7 +140,7 @@ your server in `/etc/init.d/gitlab`. --- -If you are using other init systems, like systemd, you can check the +If you are using other init systems, like `systemd`, you can check the [GitLab Recipes](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/init) repository for some unofficial services. These are **not** officially supported so use them at your own risk. diff --git a/doc/administration/scaling/index.md b/doc/administration/scaling/index.md deleted file mode 100644 index 4f934646ed6..00000000000 --- a/doc/administration/scaling/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: ../reference_architectures/index.md ---- - -This document was moved to [another location](../reference_architectures/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md index 645d3bc4e9f..93b899d5146 100644 --- a/doc/administration/server_hooks.md +++ b/doc/administration/server_hooks.md @@ -6,7 +6,7 @@ type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/administration/custom_hooks.html' --- -# Server hooks **(CORE ONLY)** +# Server hooks **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196051) in GitLab 12.8 replacing Custom Hooks. diff --git a/doc/administration/snippets/index.md b/doc/administration/snippets/index.md index 0bf0eb3b1ed..61d0b1ec50a 100644 --- a/doc/administration/snippets/index.md +++ b/doc/administration/snippets/index.md @@ -5,7 +5,7 @@ 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/#assignments" --- -# Snippets settings **(CORE ONLY)** +# Snippets settings **(FREE SELF)** Adjust the snippets' settings of your GitLab instance. @@ -18,7 +18,7 @@ abuse of the feature. The default value is **52428800 Bytes** (50 MB). ### How does it work? -The content size limit will be applied when a snippet is created or updated. +The content size limit is applied when a snippet is created or updated. This limit doesn't affect existing snippets until they're updated and their content changes. @@ -60,8 +60,8 @@ To retrieve the current value, start the Rails console and run: #### Through the API -The process to set the snippets size limit through the Application Settings API is -exactly the same as you would do to [update any other setting](../../api/settings.md#change-application-settings). +To set the snippets size limit through the Application Settings API (similar to +[updating any other setting](../../api/settings.md#change-application-settings)), use this command: ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings?snippet_size_limit=52428800" diff --git a/doc/administration/static_objects_external_storage.md b/doc/administration/static_objects_external_storage.md index b10af12de67..947e2d43fe9 100644 --- a/doc/administration/static_objects_external_storage.md +++ b/doc/administration/static_objects_external_storage.md @@ -9,8 +9,8 @@ type: reference > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31025) in GitLab 12.3. -GitLab can be configured to serve repository static objects (for example, archives or raw blobs) from an external -storage, such as a Content Delivery Network (CDN). +You can configure GitLab to serve repository static objects, like archives or raw blobs, +from an external storage, such as a Content Delivery Network (CDN). ## Configuring @@ -19,19 +19,22 @@ To configure external storage for static objects: 1. Navigate to **Admin Area > Settings > Repository**. 1. Expand the **Repository static objects** section. 1. Enter the base URL and an arbitrary token. When you [set up external storage](#set-up-external-storage), -you'll use a script that uses these values as `ORIGIN_HOSTNAME` and `STORAGE_TOKEN`. + use a script that sets these values as `ORIGIN_HOSTNAME` and `STORAGE_TOKEN`. The token is required to distinguish requests coming from the external storage, so users don't -circumvent the external storage and go for the application directly. The token is expected to be -set in the `X-Gitlab-External-Storage-Token` header in requests originating from the external -storage. +circumvent the external storage and access the application directly. GitLab expects +this token to be set in the `X-Gitlab-External-Storage-Token` header in requests +originating from the external storage. ## Serving private static objects -GitLab will append a user-specific token for static object URLs that belong to private projects, -so an external storage can be authenticated on behalf of the user. When processing requests originating -from the external storage, GitLab will look for the token in the `token` query parameter or in -the `X-Gitlab-Static-Object-Token` header to check the user's ability to access the requested object. +GitLab appends a user-specific token for static object URLs belonging to private projects, +so an external storage can be authenticated on the user's behalf. When processing requests originating +from the external storage, GitLab checks the following places to confirm the user may +access the requested object: + +- The `token` query parameter. +- The `X-Gitlab-Static-Object-Token` header. ## Requests flow example @@ -66,8 +69,8 @@ other CDNs or Function as a Service (FaaS) systems should work using the same pr 1. In the following script, set the following values for the first two constants: - `ORIGIN_HOSTNAME`: the hostname of your GitLab installation. - - `STORAGE_TOKEN`: any arbitrary secure token (e.g. you can get one by running - `pwgen -cn1 64` on a UNIX machine). Save this token for the admin panel, as + - `STORAGE_TOKEN`: any arbitrary secure token. You can get a token by running + `pwgen -cn1 64` on a UNIX machine. Save this token for the admin panel, as described in the [configuring](#configuring) section. ```javascript diff --git a/doc/administration/terraform_state.md b/doc/administration/terraform_state.md index be5647aa133..5cc377a45fc 100644 --- a/doc/administration/terraform_state.md +++ b/doc/administration/terraform_state.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Terraform state administration (alpha) +# Terraform state administration (alpha) **(CORE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 12.10. @@ -47,7 +47,7 @@ Terraform state files are stored locally, follow the steps below. 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. -## Using object storage **(CORE ONLY)** +## Using object storage **(FREE SELF)** Instead of storing Terraform state files on disk, we recommend the use of [one of the supported object storage options](object_storage.md#options). This configuration relies on valid credentials to @@ -100,6 +100,11 @@ See [the available connection settings for different providers](object_storage.m ``` 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. Migrate any existing local states to the object storage (GitLab 13.9 and later): + + ```shell + gitlab-rake gitlab:terraform_states:migrate + ``` **In installations from source:** @@ -120,3 +125,8 @@ See [the available connection settings for different providers](object_storage.m ``` 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Migrate any existing local states to the object storage (GitLab 13.9 and later): + + ```shell + sudo -u git -H bundle exec rake gitlab:terraform_states:migrate RAILS_ENV=production + ``` diff --git a/doc/administration/timezone.md b/doc/administration/timezone.md index 798e7f5050c..6f460ed0ea8 100644 --- a/doc/administration/timezone.md +++ b/doc/administration/timezone.md @@ -41,3 +41,18 @@ After adding the configuration parameter, reconfigure and restart your GitLab in gitlab-ctl reconfigure gitlab-ctl restart ``` + +## Changing time zone per user + +To allow users to change the time zone in their profile, the feature flag `user_time_settings` should be enabled: + +1. [Start a Rails console session](operations/rails_console.md). +1. Enable the feature flag: + + ```ruby + Feature.enable(:user_time_settings) + ``` + +1. You should now be able to see the timezone dropdown in the users' **Settings > Profile** page. + +  diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md index 8c8fa25aa5e..7b57cdbf17f 100644 --- a/doc/administration/troubleshooting/debug.md +++ b/doc/administration/troubleshooting/debug.md @@ -126,7 +126,7 @@ an SMTP server, but you're not seeing mail delivered. Here's how to check the se For more advanced issues, `gdb` is a must-have tool for debugging issues. -### The GNU Project Debugger (gdb) +### The GNU Project Debugger (GDB) To install on Ubuntu/Debian: @@ -140,9 +140,13 @@ On CentOS: sudo yum install gdb ``` +<!-- vale gitlab.Spelling = NO --> + ### rbtrace -GitLab 11.2 ships with [rbtrace](https://github.com/tmm1/rbtrace), which +<!-- vale gitlab.Spelling = YES --> + +GitLab 11.2 ships with [`rbtrace`](https://github.com/tmm1/rbtrace), which allows you to trace Ruby code, view all running threads, take memory dumps, and more. However, this is not enabled by default. To enable it, define the `ENABLE_RBTRACE` variable to the environment. For example, in Omnibus: @@ -175,7 +179,7 @@ downtime. Otherwise skip to the next section. 1. Load the problematic URL 1. Run `sudo gdb -p <PID>` to attach to the Unicorn process. -1. In the gdb window, type: +1. In the GDB window, type: ```plaintext call (void) rb_backtrace() @@ -210,7 +214,7 @@ downtime. Otherwise skip to the next section. ``` Note that if the Unicorn process terminates before you are able to run these -commands, gdb will report an error. To buy more time, you can always raise the +commands, GDB will report an error. To buy more time, you can always raise the Unicorn timeout. For omnibus users, you can edit `/etc/gitlab/gitlab.rb` and increase it from 60 seconds to 300: @@ -246,7 +250,7 @@ separate Rails process to debug the issue: ``` 1. In a new window, run `top`. It should show this Ruby process using 100% CPU. Write down the PID. -1. Follow step 2 from the previous section on using gdb. +1. Follow step 2 from the previous section on using GDB. ### GitLab: API is not accessible @@ -279,4 +283,4 @@ The output in `/tmp/unicorn.txt` may help diagnose the root cause. ## More information - [Debugging Stuck Ruby Processes](https://blog.newrelic.com/engineering/debugging-stuck-ruby-processes-what-to-do-before-you-kill-9/) -- [Cheatsheet of using gdb and Ruby processes](gdb-stuck-ruby.txt) +- [Cheat sheet of using GDB and Ruby processes](gdb-stuck-ruby.txt) diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index 4a112733bfa..c654e029a9c 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab Rails Console Cheat Sheet **(CORE ONLY)** +# GitLab Rails Console Cheat Sheet **(FREE SELF)** This is the GitLab Support Team's collection of information regarding the GitLab Rails console, for use while troubleshooting. It is listed here for transparency, diff --git a/doc/administration/troubleshooting/group_saml_scim.md b/doc/administration/troubleshooting/group_saml_scim.md index e9dbbfbde12..f0d44a578ff 100644 --- a/doc/administration/troubleshooting/group_saml_scim.md +++ b/doc/administration/troubleshooting/group_saml_scim.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Troubleshooting Group SAML and SCIM **(SILVER ONLY)** +# Troubleshooting Group SAML and SCIM **(PREMIUM SAAS)** These are notes and screenshots regarding Group SAML and SCIM that the GitLab Support Team sometimes uses while troubleshooting, but which do not fit into the official documentation. GitLab is making this public, so that anyone can make use of the Support team’s collected knowledge. diff --git a/doc/administration/troubleshooting/index.md b/doc/administration/troubleshooting/index.md index 67115ce31c0..63b056df8b7 100644 --- a/doc/administration/troubleshooting/index.md +++ b/doc/administration/troubleshooting/index.md @@ -13,7 +13,7 @@ in case something goes wrong: - [Diagnostics tools](diagnostics_tools.md) - [Elasticsearch](elasticsearch.md) - [GitLab Rails console cheat sheet](gitlab_rails_cheat_sheet.md) -- [Group SAML and SCIM troubleshooting](group_saml_scim.md) **(SILVER ONLY)** +- [Group SAML and SCIM troubleshooting](group_saml_scim.md) **(PREMIUM SAAS)** - [Kubernetes cheat sheet](kubernetes_cheat_sheet.md) - [Linux cheat sheet](linux_cheat_sheet.md) - [Parsing GitLab logs with `jq`](log_parsing.md) diff --git a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md index 07a7baf338b..7b8828dc14e 100644 --- a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md +++ b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md @@ -70,7 +70,7 @@ and they will assist you with any issues you are having. kubectl logs <pod-name> --previous ``` - No logs are kept in the containers/pods themselves. Everything is written to stdout. + No logs are kept in the containers/pods themselves. Everything is written to `stdout`. This is the principle of Kubernetes, read [Twelve-factor app](https://12factor.net/) for details. @@ -88,7 +88,7 @@ and they will assist you with any issues you are having. - Minimal configuration that can be used to [test a Kubernetes Helm chart](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/620). -- Tailing logs of a separate pod. An example for a Webservice pod: +- Tailing logs of a separate pod. An example for a `webservice` pod: ```shell kubectl logs gitlab-webservice-54fbf6698b-hpckq -c webservice diff --git a/doc/administration/troubleshooting/linux_cheat_sheet.md b/doc/administration/troubleshooting/linux_cheat_sheet.md index c61a78624c3..c4e991ccc1b 100644 --- a/doc/administration/troubleshooting/linux_cheat_sheet.md +++ b/doc/administration/troubleshooting/linux_cheat_sheet.md @@ -55,7 +55,7 @@ chown root:git <file_or_dir> chmod u+x <file> ``` -### Files & Dirs +### Files and directories ```shell # create a new directory and all subdirectories @@ -202,7 +202,7 @@ or you can build it from source if you have the Rust compiler. First run the tool with no arguments other than the strace output filename to get a summary of the top processes sorted by time spent actively performing tasks. You -can also sort based on total time, # of syscalls made, PID #, and # of child processes +can also sort based on total time, # of system calls made, PID #, and # of child processes using the `-S` or `--sort` flag. The number of results defaults to 25 processes, but can be changed using the `-c`/`--count` option. See `--help` for full details. @@ -220,7 +220,7 @@ Top 25 PIDs ... ``` -Based on the summary, you can then view the details of syscalls made by one or more +Based on the summary, you can then view the details of system calls made by one or more processes using the `-p`/`--pid` for a specific process, or `-s`/`--stats` flags for a sorted list. `--stats` takes the same sorting and count options as summary. @@ -266,7 +266,7 @@ Rough numbers for calls to `open` and `openat` (used to access files) on various Slow storage can cause the dreaded `DeadlineExceeded` error in Gitaly. Also [see this entry](../operations/filesystem_benchmarking.md) -in the handbook for quick tests customers can perform to check their filesystem performance. +in the handbook for quick tests customers can perform to check their file system performance. Keep in mind that timing information from `strace` is often somewhat inaccurate, so small differences should not be considered significant. @@ -304,6 +304,24 @@ whois <ip_address> | grep -i "orgname\|netname" # Curl headers with redirect curl --head --location "https://example.com" + +# Test if a host is reachable on the network. `ping6` works on IPv6 networks. +ping example.com + +# Show the route taken to a host. `traceroute6` works on IPv6 networks. +traceroute example.com +mtr example.com + +# List details of network interfaces +ip address + +# Check local DNS settings +cat /etc/hosts +cat /etc/resolv.conf +systemd-resolve --status + +# Capture traffic to/from a host +sudo tcpdump host www.example.com ``` ## Package Management diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 49af8358e29..d3a9777775f 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Uploads administration **(CORE ONLY)** +# Uploads administration **(FREE SELF)** 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. @@ -49,12 +49,12 @@ _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. -## Using object storage **(CORE ONLY)** +## Using object storage **(FREE SELF)** > **Notes:** > > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3867) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17358) in [GitLab Core](https://about.gitlab.com/pricing/) 10.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17358) in [GitLab Free](https://about.gitlab.com/pricing/) 10.7. > - Since version 11.1, we support direct_upload to S3. If you don't want to use the local disk where GitLab is installed to store the @@ -112,7 +112,24 @@ _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:all` Rake task](raketasks/uploads/migrate.md). +1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` Rake task](raketasks/uploads/migrate.md). +1. Optional: Verify all files migrated properly. + From [PostgreSQL console](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database) + (`sudo gitlab-psql -d gitlabhq_production`) verify `objectstg` below (where `store=2`) has count of all artifacts: + + ```shell + gitlabhq_production=# SELECT count(*) AS total, sum(case when store = '1' then 1 else 0 end) AS filesystem, sum(case when store = '2' then 1 else 0 end) AS objectstg FROM uploads; + + total | filesystem | objectstg + ------+------------+----------- + 2409 | 0 | 2409 + ``` + + Verify no files on disk in `artifacts` folder: + + ```shell + sudo find /var/opt/gitlab/gitlab-rails/uploads -type f | grep -v tmp | wc -l + ``` **In installations from source:** @@ -136,6 +153,22 @@ _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:all` Rake task](raketasks/uploads/migrate.md). +1. Optional: Verify all files migrated properly. + From PostgreSQL console (`sudo -u git -H psql -d gitlabhq_production`) verify `objectstg` below (where `file_store=2`) has count of all artifacts: + + ```shell + gitlabhq_production=# SELECT count(*) AS total, sum(case when store = '1' then 1 else 0 end) AS filesystem, sum(case when store = '2' then 1 else 0 end) AS objectstg FROM uploads; + + total | filesystem | objectstg + ------+------------+----------- + 2409 | 0 | 2409 + ``` + + Verify no files on disk in `artifacts` folder: + + ```shell + sudo find /var/opt/gitlab/gitlab-rails/uploads -type f | grep -v tmp | wc -l + ``` #### OpenStack example @@ -162,6 +195,23 @@ _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:all` Rake task](raketasks/uploads/migrate.md). +1. Optional: Verify all files migrated properly. + From [PostgreSQL console](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database) + (`sudo gitlab-psql -d gitlabhq_production`) verify `objectstg` below (where `store=2`) has count of all artifacts: + + ```shell + gitlabhq_production=# SELECT count(*) AS total, sum(case when store = '1' then 1 else 0 end) AS filesystem, sum(case when store = '2' then 1 else 0 end) AS objectstg FROM uploads; + + total | filesystem | objectstg + ------+------------+----------- + 2409 | 0 | 2409 + ``` + + Verify no files on disk in `artifacts` folder: + + ```shell + sudo find /var/opt/gitlab/gitlab-rails/uploads -type f | grep -v tmp | wc -l + ``` --- @@ -193,3 +243,19 @@ _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:all` Rake task](raketasks/uploads/migrate.md). +1. Optional: Verify all files migrated properly. + From PostgreSQL console (`sudo -u git -H psql -d gitlabhq_production`) verify `objectstg` below (where `file_store=2`) has count of all artifacts: + + ```shell + gitlabhq_production=# SELECT count(*) AS total, sum(case when store = '1' then 1 else 0 end) AS filesystem, sum(case when store = '2' then 1 else 0 end) AS objectstg FROM uploads; + + total | filesystem | objectstg + ------+------------+----------- + 2409 | 0 | 2409 + ``` + + Verify no files on disk in `artifacts` folder: + + ```shell + sudo find /var/opt/gitlab/gitlab-rails/uploads -type f | grep -v tmp | wc -l + ``` diff --git a/doc/administration/user_settings.md b/doc/administration/user_settings.md index 9892d2a0764..681ce87edb6 100644 --- a/doc/administration/user_settings.md +++ b/doc/administration/user_settings.md @@ -1,6 +1,6 @@ --- -stage: Enablement -group: Distribution +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/#assignments --- @@ -10,7 +10,8 @@ GitLab administrators can modify user settings for the entire GitLab instance. ## Disallow users creating top-level groups -By default, new users can create top-level groups. To disable this, modify the appropriate configuration file. +By default, new users can create top-level groups. To disable this, modify the appropriate configuration file, +and then [reconfigure and restart GitLab](restart_gitlab.md). For Omnibus installations, add the following to `/etc/gitlab/gitlab.rb`: @@ -26,7 +27,8 @@ For source installations, uncomment the following line in `config/gitlab.yml`: ## Disallow users changing usernames -By default, new users can change their usernames. To disable this, modify the appropriate configuration file. +By default, new users can change their usernames. To disable this, modify the appropriate configuration file, +and then [reconfigure and restart GitLab](restart_gitlab.md). For Omnibus installations, add the following to `/etc/gitlab/gitlab.rb`: diff --git a/doc/administration/wikis/index.md b/doc/administration/wikis/index.md index 026f9b6f471..57bbe913216 100644 --- a/doc/administration/wikis/index.md +++ b/doc/administration/wikis/index.md @@ -1,11 +1,11 @@ --- type: reference, howto stage: Create -group: Knowledge +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/#assignments --- -# Wiki settings **(CORE ONLY)** +# Wiki settings **(FREE SELF)** Adjust the wiki settings of your GitLab instance. @@ -18,24 +18,24 @@ abuse of the feature. The default value is **52428800 Bytes** (50 MB). ### How does it work? -The content size limit will be applied when a wiki page is created or updated -through the GitLab UI or API. Local changes pushed via Git will not be validated. +The content size limit is applied when a wiki page is created or updated +through the GitLab UI or API. Local changes pushed via Git are not validated. -In order not to break any existing wiki pages, the limit doesn't have any -effect on them until a wiki page is edited again and the content changes. +To break any existing wiki pages, the limit doesn't take effect until a wiki page +is edited again and the content changes. ### Wiki page content size limit configuration This setting is not available through the [Admin Area settings](../../user/admin_area/settings/index.md). -In order to configure this setting, use either the Rails console +To configure this setting, use either the Rails console or the [Application settings API](../../api/settings.md). NOTE: -The value of the limit **must** be in bytes. The minimum value is 1024 bytes. +The value of the limit must be in bytes. The minimum value is 1024 bytes. #### Through the Rails console -The steps to configure this setting through the Rails console are: +To configure this setting through the Rails console: 1. Start the Rails console: @@ -61,14 +61,14 @@ To retrieve the current value, start the Rails console and run: #### Through the API -The process to set the wiki page size limit through the Application Settings API is -exactly the same as you would do to [update any other setting](../../api/settings.md#change-application-settings). +To set the wiki page size limit through the Application Settings API, use a command, +as you would to [update any other setting](../../api/settings.md#change-application-settings): ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings?wiki_page_max_content_bytes=52428800" ``` -You can also use the API to [retrieve the current value](../../api/settings.md#get-current-application-settings). +You can also use the API to [retrieve the current value](../../api/settings.md#get-current-application-settings): ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings" diff --git a/doc/analytics/README.md b/doc/analytics/README.md deleted file mode 100644 index 7c732f48ba8..00000000000 --- a/doc/analytics/README.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/group/index.md#user-contribution-analysis' ---- - -This document was moved to [another location](../user/group/index.md#user-contribution-analysis) - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/analytics/contribution_analytics.md b/doc/analytics/contribution_analytics.md deleted file mode 100644 index b9a52d9ca68..00000000000 --- a/doc/analytics/contribution_analytics.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/group/contribution_analytics/index.md' ---- - -This document was moved to [another location](../user/group/contribution_analytics/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/README.md b/doc/api/README.md index 8fb3269d28b..3ba88132c25 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -21,7 +21,7 @@ Contributions are welcome. For a list of the available resources and their endpoints, see [API resources](api_resources.md). -## SCIM **(SILVER ONLY)** +## SCIM **(PREMIUM SAAS)** GitLab provides an [SCIM API](scim.md) that both implements [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) and provides the @@ -124,7 +124,7 @@ There are several methods you can use to authenticate with the GitLab API: - [GitLab CI/CD job token](#gitlab-ci-job-token) **(Specific endpoints only)** NOTE: -Project access tokens are supported for self-managed instances on Core and +Project access tokens are supported for self-managed instances on Free and higher. They're also supported on GitLab.com Bronze and higher. For administrators who want to authenticate with the API as a specific user, or who want @@ -207,7 +207,7 @@ to authenticate with the API: - [Go Proxy](../user/packages/go_proxy/index.md) - [Maven Repository](../user/packages/maven_repository/index.md#authenticate-with-a-ci-job-token-in-maven) - [NPM Repository](../user/packages/npm_registry/index.md#authenticate-with-a-ci-job-token) - - [Nuget Repository](../user/packages/nuget_repository/index.md) + - [NuGet Repository](../user/packages/nuget_repository/index.md) - [PyPI Repository](../user/packages/pypi_repository/index.md#authenticate-with-a-ci-job-token) - [Generic packages](../user/packages/generic_packages/index.md#publish-a-generic-package-by-using-cicd) - [Get job artifacts](job_artifacts.md#get-job-artifacts) @@ -744,3 +744,15 @@ For administrator documentation on rate limit settings, see [Rate limits](../security/rate_limits.md). To find the settings that are specifically used by GitLab.com, see [GitLab.com-specific rate limits](../user/gitlab_com/index.md#gitlabcom-specific-rate-limits). + +## Content type + +The GitLab API supports the `application/json` content type by default, though +some API endpoints also support `text/plain`. + +In [GitLab 13.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/250342), +API endpoints do not support `text/plain` by default, unless it's explicitly documented. + +This change is deployed behind the `:api_always_use_application_json` [feature flag](../user/feature_flags.md), +enabled by default. On GitLab self-managed instances, GitLab administrators can choose +to [disable it](../administration/feature_flags.md). **(FREE SELF)** diff --git a/doc/api/admin_sidekiq_queues.md b/doc/api/admin_sidekiq_queues.md index 7f2f2b8668c..9cbdcb863d6 100644 --- a/doc/api/admin_sidekiq_queues.md +++ b/doc/api/admin_sidekiq_queues.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Sidekiq queues administration API **(CORE ONLY)** +# Sidekiq queues administration API **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25998) in GitLab 12.9 diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 029e434749f..7bb0c4ec67e 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -25,6 +25,7 @@ The following API resources are available in the project context: | Resource | Available endpoints | |:--------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Access requests](access_requests.md) | `/projects/:id/access_requests` (also available for groups) | +| [Access tokens](resource_access_tokens.md) | `/projects/:id/access_tokens` | | [Award emoji](award_emoji.md) | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji` | | [Branches](branches.md) | `/projects/:id/repository/branches/`, `/projects/:id/repository/merged_branches` | | [Commits](commits.md) | `/projects/:id/repository/commits`, `/projects/:id/statuses` | @@ -76,7 +77,7 @@ The following API resources are available in the project context: | [Remote mirrors](remote_mirrors.md) | `/projects/:id/remote_mirrors` | | [Repositories](repositories.md) | `/projects/:id/repository` | | [Repository files](repository_files.md) | `/projects/:id/repository/files` | -| [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` | +| [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` | | [Resource label events](resource_label_events.md) | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events` (also available for groups) | | [Runners](runners.md) | `/projects/:id/runners` (also available standalone) | | [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) | @@ -127,10 +128,10 @@ 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` | -| [Sidekiq queues administration](admin_sidekiq_queues.md) **(CORE ONLY)** | `/admin/sidekiq/queues/:queue_name` | -| [Appearance](appearance.md) **(CORE ONLY)** | `/application/appearance` | +| [Sidekiq queues administration](admin_sidekiq_queues.md) **(FREE SELF)** | `/admin/sidekiq/queues/:queue_name` | +| [Appearance](appearance.md) **(FREE SELF)** | `/application/appearance` | | [Applications](applications.md) | `/applications` | -| [Audit Events](audit_events.md) **(PREMIUM ONLY)** | `/audit_events` | +| [Audit Events](audit_events.md) **(PREMIUM SELF)** | `/audit_events` | | [Avatar](avatar.md) | `/avatar` | | [Broadcast messages](broadcast_messages.md) | `/broadcast_messages` | | [Code snippets](snippets.md) | `/snippets` | @@ -138,14 +139,14 @@ The following API resources are available outside of project and group contexts | [Deploy keys](deploy_keys.md) | `/deploy_keys` (also available for projects) | | [Events](events.md) | `/events`, `/users/:id/events` (also available for projects) | | [Feature flags](features.md) | `/features` | -| [Geo Nodes](geo_nodes.md) **(PREMIUM ONLY)** | `/geo_nodes` | +| [Geo Nodes](geo_nodes.md) **(PREMIUM SELF)** | `/geo_nodes` | | [Group Activity Analytics](group_activity_analytics.md) **(STARTER)** | `/analytics/group_activity/{issues_count | merge_requests_count | new_members_count }` | | [Import repository from GitHub](import.md) | `/import/github` | | [Instance clusters](instance_clusters.md) | `/admin/clusters` | | [Issues](issues.md) | `/issues` (also available for groups and projects) | | [Issues Statistics](issues_statistics.md) | `/issues_statistics` (also available for groups and projects) | | [Keys](keys.md) | `/keys` | -| [License](license.md) **(CORE ONLY)** | `/license` | +| [License](license.md) **(FREE SELF)** | `/license` | | [Markdown](markdown.md) | `/markdown` | | [Merge requests](merge_requests.md) | `/merge_requests` (also available for groups and projects) | | [Metrics dashboard annotations](metrics_dashboard_annotations.md) | `/environments/:id/metrics_dashboard/annotations`, `/clusters/:id/metrics_dashboard/annotations` | @@ -154,13 +155,13 @@ The following API resources are available outside of project and group contexts | [Pages domains](pages_domains.md) | `/pages/domains` (also available for projects) | | [Personal access tokens](personal_access_tokens.md) | `/personal_access_tokens` | | [Projects](projects.md) | `/users/:id/projects` (also available for projects) | -| [Project repository storage moves](project_repository_storage_moves.md) **(CORE ONLY)** | `/project_repository_storage_moves` | +| [Project repository storage moves](project_repository_storage_moves.md) **(FREE SELF)** | `/project_repository_storage_moves` | | [Runners](runners.md) | `/runners` (also available for projects) | | [Search](search.md) | `/search` (also available for groups and projects) | -| [Settings](settings.md) **(CORE ONLY)** | `/application/settings` | -| [Snippet repository storage moves](snippet_repository_storage_moves.md) **(CORE ONLY)** | `/snippet_repository_storage_moves` | +| [Settings](settings.md) **(FREE SELF)** | `/application/settings` | +| [Snippet repository storage moves](snippet_repository_storage_moves.md) **(FREE SELF)** | `/snippet_repository_storage_moves` | | [Statistics](statistics.md) | `/application/statistics` | -| [Sidekiq metrics](sidekiq_metrics.md) **(CORE ONLY)** | `/sidekiq` | +| [Sidekiq metrics](sidekiq_metrics.md) **(FREE SELF)** | `/sidekiq` | | [Suggestions](suggestions.md) | `/suggestions` | | [System hooks](system_hooks.md) | `/hooks` | | [To-dos](todos.md) | `/todos` | diff --git a/doc/api/appearance.md b/doc/api/appearance.md index d03fc94cfcf..5689cacd9ce 100644 --- a/doc/api/appearance.md +++ b/doc/api/appearance.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Appearance API **(CORE ONLY)** +# Appearance API **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16647) in GitLab 12.7. diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md index 5017c8defaf..78bf292a3d7 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Audit Events API -## Instance Audit Events **(PREMIUM ONLY)** +## Instance Audit Events **(PREMIUM SELF)** The Audit Events API allows you to retrieve [instance audit events](../administration/audit_events.md#instance-events). @@ -126,7 +126,7 @@ Example response: } ``` -## Group Audit Events **(STARTER)** +## Group Audit Events **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34078) in GitLab 12.5. @@ -233,7 +233,7 @@ Example response: } ``` -## Project Audit Events **(STARTER)** +## Project Audit Events **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219238) in GitLab 13.1. diff --git a/doc/api/boards.md b/doc/api/boards.md index e86f0d846ed..021e4103228 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -8,8 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w Every API call to boards must be authenticated. -If a user is not a member of a project and the project is private, a `GET` -request on that project will result to a `404` status code. +If a user is not a member of a private project, +a `GET` request on that project results in a `404` status code. ## List project issue boards @@ -488,7 +488,7 @@ Example response: ## Delete a board list from a board -Only for admins and project owners. Deletes the board list in question. +Only for administrators and project owners. Deletes a board list. ```plaintext DELETE /projects/:id/boards/:board_id/lists/:list_id diff --git a/doc/api/build_triggers.md b/doc/api/build_triggers.md deleted file mode 100644 index 13adf949981..00000000000 --- a/doc/api/build_triggers.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'pipeline_triggers.md' ---- - -This document was moved to [another location](pipeline_triggers.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/builds.md b/doc/api/builds.md deleted file mode 100644 index b7b61e853a8..00000000000 --- a/doc/api/builds.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'jobs.md' ---- - -This document was moved to [another location](jobs.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md index ab691aaecea..8448edef9c5 100644 --- a/doc/api/dependency_proxy.md +++ b/doc/api/dependency_proxy.md @@ -9,9 +9,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Purge the dependency proxy for a group > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11631) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 13.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Free](https://about.gitlab.com/pricing/) in GitLab 13.6. -Deletes the cached manifests and blobs for a group. This endpoint requires group admin access. +Deletes the cached manifests and blobs for a group. This endpoint requires group owner access. WARNING: [A bug exists](https://gitlab.com/gitlab-org/gitlab/-/issues/277161) for this API. diff --git a/doc/api/deploy_key_multiple_projects.md b/doc/api/deploy_key_multiple_projects.md deleted file mode 100644 index 16ce201c1c0..00000000000 --- a/doc/api/deploy_key_multiple_projects.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: deploy_keys.md#adding-deploy-keys-to-multiple-projects ---- - -This document was moved to [another location](deploy_keys.md#adding-deploy-keys-to-multiple-projects). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index cabab18ed71..228f68531fd 100644 --- a/doc/api/epic_links.md +++ b/doc/api/epic_links.md @@ -12,9 +12,10 @@ Manages parent-child [epic relationships](../user/group/epics/index.md#multi-lev Every API call to `epic_links` must be authenticated. -If a user makes a `GET` request to a private group they are not a member of, the result is a `404` status code. +If a user is not a member of a private group, a `GET` request on that +group results in a `404` status code. -Multi-level Epics are available only in GitLab [Ultimate/Gold](https://about.gitlab.com/pricing/). +Multi-level Epics are available only in GitLab [Ultimate](https://about.gitlab.com/pricing/). If the Multi-level Epics feature is not available, a `403` status code is returned. ## List epics related to a given epic diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index 12ff0148661..c737edbdc44 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Error Tracking settings API +# Error Tracking settings API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34940) in GitLab 12.7. diff --git a/doc/api/events.md b/doc/api/events.md index d073e7ed633..e2ff779f3bf 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -25,7 +25,7 @@ Available action types for the `action` parameter are: - `destroyed` - `expired` -Note that these options are downcased. +Note that these options are in lower case. ### Target Types @@ -39,7 +39,7 @@ Available target types for the `target_type` parameter are: - `snippet` - `user` -Note that these options are downcased. +Note that these options are in lower case. ### Date formatting diff --git a/doc/api/feature_flag_user_lists.md b/doc/api/feature_flag_user_lists.md index ba03b81ebfd..e0a5fe99663 100644 --- a/doc/api/feature_flag_user_lists.md +++ b/doc/api/feature_flag_user_lists.md @@ -4,10 +4,10 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Feature flag user lists API **(CORE)** +# Feature flag user lists API **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205409) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to GitLab Core in 13.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to GitLab Free in 13.5. API for accessing GitLab Feature Flag User Lists. diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md index e8d6911463d..77d30475555 100644 --- a/doc/api/feature_flags.md +++ b/doc/api/feature_flags.md @@ -4,11 +4,11 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Feature Flags API **(CORE)** +# Feature Flags API **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.5. API for accessing resources of [GitLab Feature Flags](../operations/feature_flags.md). diff --git a/doc/api/feature_flags_legacy.md b/doc/api/feature_flags_legacy.md index 8a5af39a37f..33ea2727fb9 100644 --- a/doc/api/feature_flags_legacy.md +++ b/doc/api/feature_flags_legacy.md @@ -4,11 +4,11 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Legacy Feature Flags API **(CORE)** +# Legacy Feature Flags API **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.5. WARNING: This API is deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369). Use [this API](feature_flags.md) instead. diff --git a/doc/api/features.md b/doc/api/features.md index 0ed0dec1b6d..cb3ee04d076 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -128,7 +128,7 @@ POST /features/:name | `user` | string | no | A GitLab username | | `group` | string | no | A GitLab group's path, for example `gitlab-org` | | `project` | string | no | A projects path, for example `gitlab-org/gitlab-foss` | -| `force` | boolean | no | Skip feature flag validation checks, ie. YAML definition | +| `force` | boolean | no | Skip feature flag validation checks, such as a YAML definition | Note that you can enable or disable a feature for a `feature_group`, a `user`, a `group`, and a `project` in a single API call. diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index 280d02ced32..386472a23f6 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Geo Nodes API **(PREMIUM ONLY)** +# Geo Nodes API **(PREMIUM SELF)** To interact with Geo node endpoints, you need to authenticate yourself as an admin. @@ -307,37 +307,37 @@ Example response: "health_status": "Healthy", "missing_oauth_application": false, "attachments_count": 1, - "attachments_synced_count": nil, - "attachments_failed_count": nil, + "attachments_synced_count": null, + "attachments_failed_count": null, "attachments_synced_missing_on_primary_count": 0, "attachments_synced_in_percentage": "0.00%", - "db_replication_lag_seconds": nil, + "db_replication_lag_seconds": null, "lfs_objects_count": 0, - "lfs_objects_synced_count": nil, - "lfs_objects_failed_count": nil, + "lfs_objects_synced_count": null, + "lfs_objects_failed_count": null, "lfs_objects_synced_missing_on_primary_count": 0, "lfs_objects_synced_in_percentage": "0.00%", "job_artifacts_count": 2, - "job_artifacts_synced_count": nil, - "job_artifacts_failed_count": nil, + "job_artifacts_synced_count": null, + "job_artifacts_failed_count": null, "job_artifacts_synced_missing_on_primary_count": 0, "job_artifacts_synced_in_percentage": "0.00%", "container_repositories_count": 3, - "container_repositories_synced_count": nil, - "container_repositories_failed_count": nil, + "container_repositories_synced_count": null, + "container_repositories_failed_count": null, "container_repositories_synced_in_percentage": "0.00%", "design_repositories_count": 3, - "design_repositories_synced_count": nil, - "design_repositories_failed_count": nil, + "design_repositories_synced_count": null, + "design_repositories_failed_count": null, "design_repositories_synced_in_percentage": "0.00%", "projects_count": 41, "repositories_count": 41, - "repositories_failed_count": nil, - "repositories_synced_count": nil, + "repositories_failed_count": null, + "repositories_synced_count": null, "repositories_synced_in_percentage": "0.00%", "wikis_count": 41, - "wikis_failed_count": nil, - "wikis_synced_count": nil, + "wikis_failed_count": null, + "wikis_synced_count": null, "wikis_synced_in_percentage": "0.00%", "replication_slots_count": 1, "replication_slots_used_count": 1, @@ -367,7 +367,7 @@ Example response: "repositories_checked_in_percentage": "17.07%", "last_event_id": 23, "last_event_timestamp": 1509681166, - "cursor_last_event_id": nil, + "cursor_last_event_id": null, "cursor_last_event_timestamp": 0, "last_successful_status_check_timestamp": 1510125024, "version": "10.3.0", @@ -408,12 +408,12 @@ Example response: "job_artifacts_synced_missing_on_primary_count": 0, "job_artifacts_synced_in_percentage": "50.00%", "container_repositories_count": 3, - "container_repositories_synced_count": nil, - "container_repositories_failed_count": nil, + "container_repositories_synced_count": null, + "container_repositories_failed_count": null, "container_repositories_synced_in_percentage": "0.00%", "design_repositories_count": 3, - "design_repositories_synced_count": nil, - "design_repositories_failed_count": nil, + "design_repositories_synced_count": null, + "design_repositories_failed_count": null, "design_repositories_synced_in_percentage": "0.00%", "projects_count": 41, "repositories_count": 41, @@ -424,10 +424,10 @@ Example response: "wikis_failed_count": 0, "wikis_synced_count": 41, "wikis_synced_in_percentage": "100.00%", - "replication_slots_count": nil, - "replication_slots_used_count": nil, + "replication_slots_count": null, + "replication_slots_used_count": null, "replication_slots_used_in_percentage": "0.00%", - "replication_slots_max_retained_wal_bytes": nil, + "replication_slots_max_retained_wal_bytes": null, "repositories_checksummed_count": 20, "repositories_checksum_failed_count": 5, "repositories_checksummed_in_percentage": "48.78%", @@ -518,12 +518,12 @@ Example response: "job_artifacts_synced_missing_on_primary_count": 0, "job_artifacts_synced_in_percentage": "50.00%", "container_repositories_count": 3, - "container_repositories_synced_count": nil, - "container_repositories_failed_count": nil, + "container_repositories_synced_count": null, + "container_repositories_failed_count": null, "container_repositories_synced_in_percentage": "0.00%", "design_repositories_count": 3, - "design_repositories_synced_count": nil, - "design_repositories_failed_count": nil, + "design_repositories_synced_count": null, + "design_repositories_failed_count": null, "design_repositories_synced_in_percentage": "0.00%", "projects_count": 41, "repositories_count": 41, @@ -534,10 +534,10 @@ Example response: "wikis_failed_count": 0, "wikis_synced_count": 41, "wikis_synced_in_percentage": "100.00%", - "replication_slots_count": nil, - "replication_slots_used_count": nil, + "replication_slots_count": null, + "replication_slots_used_count": null, "replication_slots_used_in_percentage": "0.00%", - "replication_slots_max_retained_wal_bytes": nil, + "replication_slots_max_retained_wal_bytes": null, "last_event_id": 23, "last_event_timestamp": 1509681166, "cursor_last_event_id": 23, diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index ca2b7989700..1b7e273f7a1 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -314,9 +314,10 @@ Pagination is a way of only asking for a subset of the records (say, the first 1 If we want more of them, we can make another request for the next 10 from the server (in the form of something like "please give me the next 10 records"). -By default, the GitLab GraphQL API returns only the first 100 records of any collection. +By default, the GitLab GraphQL API returns 100 records per page. This can be changed by using `first` or `last` arguments. Both arguments take a value, so `first: 10` returns the first 10 records, and `last: 10` the last 10 records. +There is a limit on how many records will be returned per page, which is generally `100`. Example: Retrieve only the first 2 issues (slicing). The `cursor` field gives us a position from which we can retrieve further records relative to that one. diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 45a327d323b..a97d892dbc4 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -117,6 +117,43 @@ information about multiplexed queries is also available for [GraphQL Ruby](https://graphql-ruby.org/queries/multiplex.html), the library GitLab uses on the backend. +## Limits + +The following limits apply to the GitLab GraphQL API. + +### Max page size + +By default, connections return at most `100` records ("nodes") per page, +and this limit applies to most connections in the API. Particular connections +may have different max page size limits that are higher or lower. + +### Max query complexity + +The GitLab GraphQL API scores the _complexity_ of a query. Generally, larger +queries will have a higher complexity score. This limit is designed to protect +the API from performing queries that could negatively impact its overall performance. + +The complexity of a single query is limited to a maximum of: + +- `200` for unauthenticated requests. +- `250` for authenticated requests. + +There is no way to discover the complexity of a query except by exceeding the limit. + +If a query exceeds the complexity limit an error message response will +be returned. + +In general, each field in a query will add `1` to the complexity score, although +this can be higher or lower for particular fields. Sometimes the addition of +certain arguments may also increase the complexity of a query. + +The complexity limits may be revised in future, and additionally, the complexity +of a query may be altered. + +### Request timeout + +Requests time out at 30 seconds. + ## Reference The GitLab GraphQL reference [is available](reference/index.md). diff --git a/doc/api/graphql/reference/gitlab_schema.graphql b/doc/api/graphql/reference/gitlab_schema.graphql index 94792a49933..c3120d8417d 100644 --- a/doc/api/graphql/reference/gitlab_schema.graphql +++ b/doc/api/graphql/reference/gitlab_schema.graphql @@ -3,12 +3,12 @@ Represents the access level of a relationship between a User and object that it """ type AccessLevel { """ - Integer representation of access level + Integer representation of access level. """ integerValue: Int """ - String representation of access level + String representation of access level. """ stringValue: AccessLevelEnum } @@ -40,7 +40,7 @@ input AddAwardEmojiInput { clientMutationId: String """ - The emoji name + The emoji name. """ name: String! } @@ -180,7 +180,7 @@ Describes an alert from the project's Alert Management """ type AlertManagementAlert implements Noteable { """ - Assignees of the alert + Assignees of the alert. """ assignees( """ @@ -205,22 +205,22 @@ type AlertManagementAlert implements Noteable { ): UserConnection """ - Timestamp the alert was created + Timestamp the alert was created. """ createdAt: Time """ - Description of the alert + Description of the alert. """ description: String """ - Alert details + Alert details. """ details: JSON """ - The URL of the alert detail page + The URL of the alert detail page. """ detailsUrl: String! @@ -250,42 +250,42 @@ type AlertManagementAlert implements Noteable { ): DiscussionConnection! """ - Timestamp the alert ended + Timestamp the alert ended. """ endedAt: Time """ - Environment for the alert + Environment for the alert. """ environment: Environment """ - Number of events of this alert + Number of events of this alert. """ eventCount: Int """ - List of hosts the alert came from + List of hosts the alert came from. """ hosts: [String!] """ - Internal ID of the alert + Internal ID of the alert. """ iid: ID! """ - Internal ID of the GitLab issue attached to the alert + Internal ID of the GitLab issue attached to the alert. """ issueIid: ID """ - URL for metrics embed for the alert + URL for metrics embed for the alert. """ metricsDashboardUrl: String """ - Monitoring tool the alert came from + Monitoring tool the alert came from. """ monitoringTool: String @@ -315,42 +315,42 @@ type AlertManagementAlert implements Noteable { ): NoteConnection! """ - The alert condition for Prometheus + The alert condition for Prometheus. """ prometheusAlert: PrometheusAlert """ - Runbook for the alert as defined in alert details + Runbook for the alert as defined in alert details. """ runbook: String """ - Service the alert came from + Service the alert came from. """ service: String """ - Severity of the alert + Severity of the alert. """ severity: AlertManagementSeverity """ - Timestamp the alert was raised + Timestamp the alert was raised. """ startedAt: Time """ - Status of the alert + Status of the alert. """ status: AlertManagementStatus """ - Title of the alert + Title of the alert. """ title: String """ - Todos of the current user for the alert + To-do items of the current user for the alert. """ todos( """ @@ -405,7 +405,7 @@ type AlertManagementAlert implements Noteable { ): TodoConnection """ - Timestamp the alert was last updated + Timestamp the alert was last updated. """ updatedAt: Time } @@ -570,7 +570,7 @@ type AlertManagementAlertStatusCountsType { acknowledged: Int """ - Total number of alerts for the project + Total number of alerts for the project. """ all: Int @@ -580,7 +580,7 @@ type AlertManagementAlertStatusCountsType { ignored: Int """ - Number of alerts with status TRIGGERED or ACKNOWLEDGED for the project + Number of alerts with status TRIGGERED or ACKNOWLEDGED for the project. """ open: Int @@ -615,79 +615,79 @@ An endpoint and credentials used to accept alerts for a project """ type AlertManagementHttpIntegration implements AlertManagementIntegration { """ - Whether the endpoint is currently accepting alerts + Whether the endpoint is currently accepting alerts. """ active: Boolean """ - URL at which Prometheus metrics can be queried to populate the metrics dashboard + URL at which Prometheus metrics can be queried to populate the metrics dashboard. """ apiUrl: String """ - ID of the integration + ID of the integration. """ id: ID! """ - Name of the integration + Name of the integration. """ name: String """ - Token used to authenticate alert notification requests + Token used to authenticate alert notification requests. """ token: String """ - Type of integration + Type of integration. """ type: AlertManagementIntegrationType! """ - Endpoint which accepts alert notifications + Endpoint which accepts alert notifications. """ url: String } """ -Identifier of AlertManagement::HttpIntegration +Identifier of AlertManagement::HttpIntegration. """ scalar AlertManagementHttpIntegrationID interface AlertManagementIntegration { """ - Whether the endpoint is currently accepting alerts + Whether the endpoint is currently accepting alerts. """ active: Boolean """ - URL at which Prometheus metrics can be queried to populate the metrics dashboard + URL at which Prometheus metrics can be queried to populate the metrics dashboard. """ apiUrl: String """ - ID of the integration + ID of the integration. """ id: ID! """ - Name of the integration + Name of the integration. """ name: String """ - Token used to authenticate alert notification requests + Token used to authenticate alert notification requests. """ token: String """ - Type of integration + Type of integration. """ type: AlertManagementIntegrationType! """ - Endpoint which accepts alert notifications + Endpoint which accepts alert notifications. """ url: String } @@ -743,6 +743,26 @@ enum AlertManagementIntegrationType { } """ +Parsed field from an alert used for custom mappings +""" +type AlertManagementPayloadAlertField { + """ + Human-readable label of the payload path. + """ + label: String + + """ + Path to value inside payload JSON. + """ + path: [String!] + + """ + Type of the parsed value. + """ + type: AlertManagementPayloadAlertFieldType +} + +""" Field that are available while modifying the custom mapping attributes for an HTTP integration """ input AlertManagementPayloadAlertFieldInput { @@ -847,37 +867,37 @@ An endpoint and credentials used to accept Prometheus alerts for a project """ type AlertManagementPrometheusIntegration implements AlertManagementIntegration { """ - Whether the endpoint is currently accepting alerts + Whether the endpoint is currently accepting alerts. """ active: Boolean """ - URL at which Prometheus metrics can be queried to populate the metrics dashboard + URL at which Prometheus metrics can be queried to populate the metrics dashboard. """ apiUrl: String """ - ID of the integration + ID of the integration. """ id: ID! """ - Name of the integration + Name of the integration. """ name: String """ - Token used to authenticate alert notification requests + Token used to authenticate alert notification requests. """ token: String """ - Type of integration + Type of integration. """ type: AlertManagementIntegrationType! """ - Endpoint which accepts alert notifications + Endpoint which accepts alert notifications. """ url: String } @@ -997,7 +1017,7 @@ type AlertSetAssigneesPayload { issue: Issue """ - The todo after mutation. + The to-do item after mutation. """ todo: Todo } @@ -1047,13 +1067,13 @@ type AlertTodoCreatePayload { issue: Issue """ - The todo after mutation. + The to-do item after mutation. """ todo: Todo } """ -Identifier of Analytics::DevopsAdoption::Segment +Identifier of Analytics::DevopsAdoption::Segment. """ scalar AnalyticsDevopsAdoptionSegmentID @@ -1077,32 +1097,32 @@ An emoji awarded by a user """ type AwardEmoji { """ - The emoji description + The emoji description. """ description: String! """ - The emoji as an icon + The emoji as an icon. """ emoji: String! """ - The emoji name + The emoji name. """ name: String! """ - The emoji in unicode + The emoji in Unicode. """ unicode: String! """ - The unicode version for this emoji + The Unicode version for this emoji. """ unicodeVersion: String! """ - The user who awarded the emoji + The user who awarded the emoji. """ user: User! } @@ -1122,7 +1142,7 @@ input AwardEmojiAddInput { clientMutationId: String """ - The emoji name + The emoji name. """ name: String! } @@ -1148,6 +1168,41 @@ type AwardEmojiAddPayload { } """ +The connection type for AwardEmoji. +""" +type AwardEmojiConnection { + """ + A list of edges. + """ + edges: [AwardEmojiEdge] + + """ + A list of nodes. + """ + nodes: [AwardEmoji] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type AwardEmojiEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: AwardEmoji +} + +""" Autogenerated input type of AwardEmojiRemove """ input AwardEmojiRemoveInput { @@ -1162,7 +1217,7 @@ input AwardEmojiRemoveInput { clientMutationId: String """ - The emoji name + The emoji name. """ name: String! } @@ -1202,7 +1257,7 @@ input AwardEmojiToggleInput { clientMutationId: String """ - The emoji name + The emoji name. """ name: String! } @@ -1233,7 +1288,7 @@ type AwardEmojiTogglePayload { } """ -Identifier of Awardable +Identifier of Awardable. """ scalar AwardableID @@ -1287,7 +1342,7 @@ type Blob implements Entry { path: String! """ - Last commit sha for the entry + Last commit SHA for the entry """ sha: String! @@ -1391,17 +1446,17 @@ type Board { ): BoardEpicConnection """ - Whether or not backlog list is hidden + Whether or not backlog list is hidden. """ hideBacklogList: Boolean """ - Whether or not closed list is hidden + Whether or not closed list is hidden. """ hideClosedList: Boolean """ - ID (global ID) of the board + ID (global ID) of the board. """ id: ID! @@ -1436,7 +1491,7 @@ type Board { ): LabelConnection """ - Lists of the board + Lists of the board. """ lists( """ @@ -1476,7 +1531,7 @@ type Board { milestone: Milestone """ - Name of the board + Name of the board. """ name: String @@ -1536,12 +1591,37 @@ Represents an epic on an issue board """ type BoardEpic implements CurrentUserTodos & Noteable { """ - Author of the epic + Author of the epic. """ author: User! """ - Children (sub-epics) of the epic + A list of award emojis associated with the epic. + """ + awardEmoji( + """ + 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 + ): AwardEmojiConnection + + """ + Children (sub-epics) of the epic. """ children( """ @@ -1639,22 +1719,22 @@ type BoardEpic implements CurrentUserTodos & Noteable { ): EpicConnection """ - Timestamp of when the epic was closed + Timestamp of when the epic was closed. """ closedAt: Time """ - Indicates if the epic is confidential + Indicates if the epic is confidential. """ confidential: Boolean """ - Timestamp of when the epic was created + Timestamp of when the epic was created. """ createdAt: Time """ - Todos for the current user + To-do items for the current user. """ currentUserTodos( """ @@ -1678,23 +1758,23 @@ type BoardEpic implements CurrentUserTodos & Noteable { last: Int """ - State of the todos + State of the to-do items. """ state: TodoStateEnum ): TodoConnection! """ - Number of open and closed descendant epics and issues + Number of open and closed descendant epics and issues. """ descendantCounts: EpicDescendantCount """ - Total weight of open and closed issues in the epic and its descendants + Total weight of open and closed issues in the epic and its descendants. """ descendantWeightSum: EpicDescendantWeights """ - Description of the epic + Description of the epic. """ description: String @@ -1724,67 +1804,67 @@ type BoardEpic implements CurrentUserTodos & Noteable { ): DiscussionConnection! """ - Number of downvotes the epic has received + Number of downvotes the epic has received. """ downvotes: Int! """ - Due date of the epic + Due date of the epic. """ dueDate: Time """ - Fixed due date of the epic + Fixed due date of the epic. """ dueDateFixed: Time """ - Inherited due date of the epic from milestones + Inherited due date of the epic from milestones. """ dueDateFromMilestones: Time """ - Indicates if the due date has been manually set + Indicates if the due date has been manually set. """ dueDateIsFixed: Boolean """ - Group to which the epic belongs + Group to which the epic belongs. """ group: Group! """ - Indicates if the epic has children + Indicates if the epic has children. """ hasChildren: Boolean! """ - Indicates if the epic has direct issues + Indicates if the epic has direct issues. """ hasIssues: Boolean! """ - Indicates if the epic has a parent epic + Indicates if the epic has a parent epic. """ hasParent: Boolean! """ - Current health status of the epic + Current health status of the epic. """ healthStatus: EpicHealthStatus """ - ID of the epic + ID of the epic. """ id: ID! """ - Internal ID of the epic + Internal ID of the epic. """ iid: ID! """ - A list of issues associated with the epic + A list of issues associated with the epic. """ issues( """ @@ -1809,7 +1889,7 @@ type BoardEpic implements CurrentUserTodos & Noteable { ): EpicIssueConnection """ - Labels assigned to the epic + Labels assigned to the epic. """ labels( """ @@ -1859,12 +1939,12 @@ type BoardEpic implements CurrentUserTodos & Noteable { ): NoteConnection! """ - Parent epic of the epic + Parent epic of the epic. """ parent: Epic """ - List of participants for the epic + List of participants for the epic. """ participants( """ @@ -1889,77 +1969,77 @@ type BoardEpic implements CurrentUserTodos & Noteable { ): UserConnection """ - Internal reference of the epic. Returned in shortened format by default + Internal reference of the epic. Returned in shortened format by default. """ reference( """ - Indicates if the reference should be returned in full + Indicates if the reference should be returned in full. """ full: Boolean = false ): String! """ - URI path of the epic-issue relationship + URI path of the epic-issue relationship. """ relationPath: String """ - The relative position of the epic in the epic tree + The relative position of the epic in the epic tree. """ relativePosition: Int """ - Start date of the epic + Start date of the epic. """ startDate: Time """ - Fixed start date of the epic + Fixed start date of the epic. """ startDateFixed: Time """ - Inherited start date of the epic from milestones + Inherited start date of the epic from milestones. """ startDateFromMilestones: Time """ - Indicates if the start date has been manually set + Indicates if the start date has been manually set. """ startDateIsFixed: Boolean """ - State of the epic + State of the epic. """ state: EpicState! """ - Indicates the currently logged in user is subscribed to the epic + Indicates the currently logged in user is subscribed to the epic. """ subscribed: Boolean! """ - Title of the epic + Title of the epic. """ title: String """ - Timestamp of when the epic was updated + Timestamp of when the epic was updated. """ updatedAt: Time """ - Number of upvotes the epic has received + Number of upvotes the epic has received. """ upvotes: Int! """ - Number of user discussions in the epic + Number of user discussions in the epic. """ userDiscussionsCount: Int! """ - Number of user notes of the epic + Number of user notes of the epic. """ userNotesCount: Int! @@ -1974,12 +2054,12 @@ type BoardEpic implements CurrentUserTodos & Noteable { userPreferences: BoardEpicUserPreferences """ - Web path of the epic + Web path of the epic. """ webPath: String! """ - Web URL of the epic + Web URL of the epic. """ webUrl: String! } @@ -2030,18 +2110,18 @@ type BoardEpicUserPreferences { } """ -Identifier of Board +Identifier of Board. """ scalar BoardID input BoardIssueInput { """ - Filter by assignee username + Filter by assignee username. """ assigneeUsername: [String] """ - Filter by author username + Filter by author username. """ authorUsername: String @@ -2066,32 +2146,32 @@ input BoardIssueInput { iterationWildcardId: IterationWildcardId """ - Filter by label name + Filter by label name. """ labelName: [String] """ - Filter by milestone title + Filter by milestone title. """ milestoneTitle: String """ - Filter by reaction emoji + Filter by reaction emoji. """ myReactionEmoji: String """ - List of negated params. Warning: this argument is experimental and a subject to change in future + List of negated params. Warning: this argument is experimental and a subject to change in future. """ not: NegatedBoardIssueInput """ - Filter by release tag + Filter by release tag. """ releaseTag: String """ - Search query for issue title or description + Search query for issue title or description. """ search: String @@ -2111,17 +2191,17 @@ type BoardList { assignee: User """ - Indicates if list is collapsed for this user + Indicates if list is collapsed for this user. """ collapsed: Boolean """ - ID (global ID) of the list + ID (global ID) of the list. """ id: ID! """ - Board issues + Board issues. """ issues( """ @@ -2151,7 +2231,7 @@ type BoardList { ): IssueConnection """ - Count of issues in the list + Count of issues in the list. """ issuesCount: Int @@ -2161,7 +2241,7 @@ type BoardList { iteration: Iteration """ - Label of the list + Label of the list. """ label: Label @@ -2171,7 +2251,7 @@ type BoardList { limitMetric: ListLimitMetric """ - Type of the list + Type of the list. """ listType: String! @@ -2191,12 +2271,12 @@ type BoardList { milestone: Milestone """ - Position of list within the board + Position of list within the board. """ position: Int """ - Title of the list + Title of the list. """ title: String! @@ -2352,23 +2432,23 @@ type BoardListUpdateLimitMetricsPayload { } """ -Identifier of Boards::EpicBoard +Identifier of Boards::EpicBoard. """ scalar BoardsEpicBoardID """ -Identifier of Boards::EpicList +Identifier of Boards::EpicList. """ scalar BoardsEpicListID type Branch { """ - Commit for the branch + Commit for the branch. """ commit: Commit """ - Name of the branch + Name of the branch. """ name: String! } @@ -2482,17 +2562,17 @@ type CiCdSettingsUpdatePayload { type CiConfig { """ - Linting errors + Linting errors. """ errors: [String!] """ - Merged CI config YAML + Merged CI configuration YAML. """ mergedYaml: String """ - Stages of the pipeline + Stages of the pipeline. """ stages( """ @@ -2517,14 +2597,14 @@ type CiConfig { ): CiConfigStageConnection """ - Status of linting, can be either valid or invalid + Status of linting, can be either valid or invalid. """ status: CiConfigStatus } type CiConfigGroup { """ - Jobs in group + Jobs in group. """ jobs( """ @@ -2549,12 +2629,12 @@ type CiConfigGroup { ): CiConfigJobConnection """ - Name of the job group + Name of the job group. """ name: String """ - Size of the job group + Size of the job group. """ size: Int } @@ -2725,7 +2805,7 @@ type CiConfigJobRestriction { type CiConfigNeed { """ - Name of the need + Name of the need. """ name: String } @@ -2767,7 +2847,7 @@ type CiConfigNeedEdge { type CiConfigStage { """ - Groups of jobs for the stage + Groups of jobs for the stage. """ groups( """ @@ -2792,7 +2872,7 @@ type CiConfigStage { ): CiConfigGroupConnection """ - Name of the stage + Name of the stage. """ name: String } @@ -2849,12 +2929,12 @@ enum CiConfigStatus { type CiGroup { """ - Detailed status of the group + Detailed status of the group. """ detailedStatus: DetailedStatus """ - Jobs in group + Jobs in group. """ jobs( """ @@ -2879,12 +2959,12 @@ type CiGroup { ): CiJobConnection """ - Name of the job group + Name of the job group. """ name: String """ - Size of the group + Size of the group. """ size: Int } @@ -2926,7 +3006,7 @@ type CiGroupEdge { type CiJob { """ - Artifacts generated by the job + Artifacts generated by the job. """ artifacts( """ @@ -2951,17 +3031,17 @@ type CiJob { ): CiJobArtifactConnection """ - Detailed status of the job + Detailed status of the job. """ detailedStatus: DetailedStatus """ - Name of the job + Name of the job. """ name: String """ - References to builds that must complete before the jobs run + References to builds that must complete before the jobs run. """ needs( """ @@ -2986,24 +3066,24 @@ type CiJob { ): CiBuildNeedConnection """ - Pipeline the job belongs to + Pipeline the job belongs to. """ pipeline: Pipeline """ - Schedule for the build + Schedule for the build. """ scheduledAt: Time } type CiJobArtifact { """ - URL for downloading the artifact's file + URL for downloading the artifact's file. """ downloadPath: String """ - File type of the artifact + File type of the artifact. """ fileType: JobArtifactFileType } @@ -3079,18 +3159,18 @@ type CiJobEdge { } """ -Identifier of Ci::Pipeline +Identifier of Ci::Pipeline. """ scalar CiPipelineID type CiStage { """ - Detailed status of the stage + Detailed status of the stage. """ detailedStatus: DetailedStatus """ - Group of jobs for the stage + Group of jobs for the stage. """ groups( """ @@ -3115,7 +3195,7 @@ type CiStage { ): CiGroupConnection """ - Name of the stage + Name of the stage. """ name: String } @@ -3212,7 +3292,7 @@ The connection type for ClusterAgent. """ type ClusterAgentConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -3299,7 +3379,7 @@ The connection type for ClusterAgentToken. """ type ClusterAgentTokenConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -3405,17 +3485,17 @@ type ClusterAgentTokenEdge { } """ -Identifier of Clusters::Agent +Identifier of Clusters::Agent. """ scalar ClustersAgentID """ -Identifier of Clusters::AgentToken +Identifier of Clusters::AgentToken. """ scalar ClustersAgentTokenID """ -Identifier of Clusters::Cluster +Identifier of Clusters::Cluster. """ scalar ClustersClusterID @@ -3501,27 +3581,27 @@ type CodeCoverageSummary { type Commit { """ - Author of the commit + Author of the commit. """ author: User """ - Commit authors gravatar + Commit authors gravatar. """ authorGravatar: String """ - Commit authors name + Commit authors name. """ authorName: String """ - Timestamp of when the commit was authored + Timestamp of when the commit was authored. """ authoredDate: Time """ - Description of the commit message + Description of the commit message. """ description: String @@ -3531,17 +3611,17 @@ type Commit { descriptionHtml: String """ - ID (global ID) of the commit + ID (global ID) of the commit. """ id: ID! """ - Raw commit message + Raw commit message. """ message: String """ - Pipelines of the commit ordered latest first + Pipelines of the commit ordered latest first. """ pipelines( """ @@ -3581,22 +3661,22 @@ type Commit { ): PipelineConnection """ - SHA1 ID of the commit + SHA1 ID of the commit. """ sha: String! """ - Short SHA1 ID of the commit + Short SHA1 ID of the commit. """ shortId: String! """ - Rendered HTML of the commit signature + Rendered HTML of the commit signature. """ signatureHtml: String """ - Title of the commit message + Title of the commit message. """ title: String @@ -3606,49 +3686,49 @@ type Commit { titleHtml: String """ - Web path of the commit + Web path of the commit. """ webPath: String! """ - Web URL of the commit + Web URL of the commit. """ webUrl: String! } input CommitAction { """ - The action to perform, create, delete, move, update, chmod + The action to perform, create, delete, move, update, chmod. """ action: CommitActionMode! """ - Content of the file + Content of the file. """ content: String """ - Encoding of the file. Default is text + Encoding of the file. Default is text. """ encoding: CommitEncoding """ - Enables/disables the execute flag on the file + Enables/disables the execute flag on the file. """ executeFilemode: Boolean """ - Full path to the file + Full path to the file. """ filePath: String! """ - Last known file commit ID + Last known file commit ID. """ lastCommitId: String """ - Original full path to the file being moved + Original full path to the file being moved. """ previousPath: String } @@ -3723,7 +3803,7 @@ input CommitCreateInput { clientMutationId: String """ - Raw commit message + Raw commit message. """ message: String! @@ -3808,6 +3888,12 @@ type ComplianceFramework { Name of the compliance framework """ name: String! + + """ + Full path of the compliance pipeline configuration stored in a project + repository, such as `.gitlab/compliance/soc2/.gitlab-ci.yml`. + """ + pipelineConfigurationFullPath: String } """ @@ -3860,14 +3946,35 @@ input ComplianceFrameworkInput { New name for the compliance framework. """ name: String + + """ + Full path of the compliance pipeline configuration stored in a project + repository, such as `.gitlab/compliance/soc2/.gitlab-ci.yml`. + """ + pipelineConfigurationFullPath: String } """ -Identifier of ComplianceManagement::Framework +Identifier of ComplianceManagement::Framework. """ scalar ComplianceManagementFrameworkID """ +Composer metadata +""" +type ComposerMetadata { + """ + Data of the Composer JSON file. + """ + composerJson: PackageComposerJsonType! + + """ + Target SHA of the package. + """ + targetSha: String! +} + +""" Autogenerated input type of ConfigureSast """ input ConfigureSastInput { @@ -3917,47 +4024,47 @@ A tag expiration policy designed to keep only the images that matter most """ type ContainerExpirationPolicy { """ - This container expiration policy schedule + This container expiration policy schedule. """ cadence: ContainerExpirationPolicyCadenceEnum! """ - Timestamp of when the container expiration policy was created + Timestamp of when the container expiration policy was created. """ createdAt: Time! """ - Indicates whether this container expiration policy is enabled + Indicates whether this container expiration policy is enabled. """ enabled: Boolean! """ - Number of tags to retain + Number of tags to retain. """ keepN: ContainerExpirationPolicyKeepEnum """ - Tags with names matching this regex pattern will expire + Tags with names matching this regex pattern will expire. """ nameRegex: UntrustedRegexp """ - Tags with names matching this regex pattern will be preserved + Tags with names matching this regex pattern will be preserved. """ nameRegexKeep: UntrustedRegexp """ - Next time that this container expiration policy will get executed + Next time that this container expiration policy will get executed. """ nextRunAt: Time """ - Tags older that this will expire + Tags older that this will expire. """ olderThan: ContainerExpirationPolicyOlderThanEnum """ - Timestamp of when the container expiration policy was updated + Timestamp of when the container expiration policy was updated. """ updatedAt: Time! } @@ -4088,7 +4195,7 @@ type ContainerRepository { path: String! """ - Project of the container registry + Project of the container registry. """ project: Project! @@ -4198,7 +4305,7 @@ type ContainerRepositoryDetails { path: String! """ - Project of the container registry + Project of the container registry. """ project: Project! @@ -4208,7 +4315,7 @@ type ContainerRepositoryDetails { status: ContainerRepositoryStatus """ - Tags of the container repository + Tags of the container repository. """ tags( """ @@ -4259,7 +4366,7 @@ type ContainerRepositoryEdge { } """ -Identifier of ContainerRepository +Identifier of ContainerRepository. """ scalar ContainerRepositoryID @@ -4408,7 +4515,7 @@ type CreateAlertIssuePayload { issue: Issue """ - The todo after mutation. + The to-do item after mutation. """ todo: Todo } @@ -4488,17 +4595,17 @@ input CreateBoardInput { clientMutationId: String """ - The group full path the resource is associated with. + Full path of the group with which the resource is associated. """ groupPath: ID """ - Whether or not backlog list is hidden + Whether or not backlog list is hidden. """ hideBacklogList: Boolean """ - Whether or not closed list is hidden + Whether or not closed list is hidden. """ hideClosedList: Boolean @@ -4528,7 +4635,7 @@ input CreateBoardInput { name: String """ - The project full path the resource is associated with. + Full path of the project with which the resource is associated. """ projectPath: ID @@ -5083,12 +5190,12 @@ input CreateIterationInput { dueDate: String """ - The target group for the iteration. + Full path of the group with which the resource is associated. """ groupPath: ID """ - The target project for the iteration. + Full path of the project with which the resource is associated. """ projectPath: ID @@ -5228,6 +5335,13 @@ input CreateSnippetInput { blobActions: [SnippetBlobActionInputType!] """ + A valid CAPTCHA response value obtained by using the provided captchaSiteKey + with a CAPTCHA API to present a challenge to be solved on the client. Required + to resubmit if the previous operation returned "NeedsCaptchaResponse: true". + """ + captchaResponse: String + + """ A unique identifier for the client performing the mutation. """ clientMutationId: String @@ -5243,6 +5357,13 @@ input CreateSnippetInput { projectPath: ID """ + The spam log ID which must be passed along with a valid CAPTCHA response for + the operation to be completed. Required to resubmit if the previous operation + returned "NeedsCaptchaResponse: true". + """ + spamLogId: Int + + """ Title of the snippet. """ title: String! @@ -5263,6 +5384,13 @@ Autogenerated return type of CreateSnippet """ type CreateSnippetPayload { """ + The CAPTCHA site key which must be used to render a challenge for the user to + solve to obtain a valid captchaResponse value. Included only when an operation + was not completed because "NeedsCaptchaResponse" is true. + """ + captchaSiteKey: String + + """ A unique identifier for the client performing the mutation. """ clientMutationId: String @@ -5273,14 +5401,31 @@ type CreateSnippetPayload { errors: [String!]! """ + Indicates whether the operation was detected as possible spam and not + completed. If CAPTCHA is enabled, the request must be resubmitted with a valid + CAPTCHA response and spam_log_id included for the operation to be completed. + Included only when an operation was not completed because + "NeedsCaptchaResponse" is true. + """ + needsCaptchaResponse: Boolean + + """ The snippet after mutation. """ snippet: Snippet """ - Indicates whether the operation returns a record detected as spam. + Indicates whether the operation was detected as definite spam. There is no + option to resubmit the request with a CAPTCHA response. """ spam: Boolean + + """ + The spam log ID which must be passed along with a valid CAPTCHA response for + an operation to be completed. Included only when an operation was not + completed because "NeedsCaptchaResponse" is true. + """ + spamLogId: Int } """ @@ -5335,7 +5480,7 @@ type CreateTestCasePayload { interface CurrentUserTodos { """ - Todos for the current user + To-do items for the current user. """ currentUserTodos( """ @@ -5359,7 +5504,7 @@ interface CurrentUserTodos { last: Int """ - State of the todos + State of the to-do items. """ state: TodoStateEnum ): TodoConnection! @@ -5370,22 +5515,22 @@ A custom emoji uploaded by user """ type CustomEmoji { """ - Whether the emoji is an external link + Whether the emoji is an external link. """ external: Boolean! """ - The ID of the emoji + The ID of the emoji. """ id: CustomEmojiID! """ - The name of the emoji + The name of the emoji. """ name: String! """ - The link to file of the emoji + The link to file of the emoji. """ url: String! } @@ -5426,7 +5571,7 @@ type CustomEmojiEdge { } """ -Identifier of CustomEmoji +Identifier of CustomEmoji. """ scalar CustomEmojiID @@ -5475,6 +5620,146 @@ type DastOnDemandScanCreatePayload { pipelineUrl: String } +""" +Represents a DAST Profile +""" +type DastProfile { + """ + The associated scanner profile. + """ + dastScannerProfile: DastScannerProfile + + """ + The associated site profile. + """ + dastSiteProfile: DastSiteProfile + + """ + The description of the scan. + """ + description: String + + """ + Relative web path to the edit page of a profile. + """ + editPath: String + + """ + ID of the profile. + """ + id: DastProfileID! + + """ + The name of the profile. + """ + name: String +} + +""" +The connection type for DastProfile. +""" +type DastProfileConnection { + """ + A list of edges. + """ + edges: [DastProfileEdge] + + """ + A list of nodes. + """ + nodes: [DastProfile] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +Autogenerated input type of DastProfileCreate +""" +input DastProfileCreateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + ID of the scanner profile to be associated. + """ + dastScannerProfileId: DastScannerProfileID! + + """ + ID of the site profile to be associated. + """ + dastSiteProfileId: DastSiteProfileID! + + """ + The description of the profile. Defaults to an empty string. + """ + description: String = "" + + """ + The project the profile belongs to. + """ + fullPath: ID! + + """ + The name of the profile. + """ + name: String! + + """ + Run scan using profile after creation. Defaults to false. + """ + runAfterCreate: Boolean = false +} + +""" +Autogenerated return type of DastProfileCreate +""" +type DastProfileCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The created profile. + """ + dastProfile: DastProfile + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The URL of the pipeline that was created. Requires `runAfterCreate` to be set to `true`. + """ + pipelineUrl: String! +} + +""" +An edge in a connection. +""" +type DastProfileEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: DastProfile +} + +""" +Identifier of Dast::Profile. +""" +scalar DastProfileID + enum DastScanTypeEnum { """ Active DAST scan. This scan will make active attacks against the target site. @@ -5682,7 +5967,7 @@ type DastScannerProfileEdge { } """ -Identifier of DastScannerProfile +Identifier of DastScannerProfile. """ scalar DastScannerProfileID @@ -5914,7 +6199,7 @@ type DastSiteProfileEdge { } """ -Identifier of DastSiteProfile +Identifier of DastSiteProfile. """ scalar DastSiteProfileID @@ -6056,7 +6341,7 @@ type DastSiteTokenCreatePayload { } """ -Identifier of DastSiteToken +Identifier of DastSiteToken. """ scalar DastSiteTokenID @@ -6171,10 +6456,45 @@ type DastSiteValidationEdge { } """ -Identifier of DastSiteValidation +Identifier of DastSiteValidation. """ scalar DastSiteValidationID +""" +Autogenerated input type of DastSiteValidationRevoke +""" +input DastSiteValidationRevokeInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The project the site validation belongs to. + """ + fullPath: ID! + + """ + Normalized URL of the target to be revoked. + """ + normalizedTargetUrl: String! +} + +""" +Autogenerated return type of DastSiteValidationRevoke +""" +type DastSiteValidationRevokePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + enum DastSiteValidationStrategyEnum { """ Header validation @@ -6347,17 +6667,17 @@ The response from the AdminSidekiqQueuesDeleteJobs mutation """ type DeleteJobsResponse { """ - Whether or not the entire queue was processed in time; if not, retrying the same request is safe + Whether or not the entire queue was processed in time; if not, retrying the same request is safe. """ completed: Boolean """ - The number of matching jobs deleted + The number of matching jobs deleted. """ deletedJobs: Int """ - The queue size after processing + The queue size after processing. """ queueSize: Int } @@ -6367,7 +6687,7 @@ A single design """ type Design implements CurrentUserTodos & DesignFields & Noteable { """ - Todos for the current user + To-do items for the current user. """ currentUserTodos( """ @@ -6391,13 +6711,13 @@ type Design implements CurrentUserTodos & DesignFields & Noteable { last: Int """ - State of the todos + State of the to-do items. """ state: TodoStateEnum ): TodoConnection! """ - The diff refs for this design + The diff refs for this design. """ diffRefs: DiffRefs! @@ -6427,27 +6747,27 @@ type Design implements CurrentUserTodos & DesignFields & Noteable { ): DiscussionConnection! """ - How this design was changed in the current version + How this design was changed in the current version. """ event: DesignVersionEvent! """ - The filename of the design + The filename of the design. """ filename: String! """ - The full path to the design file + The full path to the design file. """ fullPath: String! """ - The ID of this design + The ID of this design. """ id: ID! """ - The URL of the full-sized image + The URL of the full-sized image. """ image: String! @@ -6457,7 +6777,7 @@ type Design implements CurrentUserTodos & DesignFields & Noteable { imageV432x230: String """ - The issue the design belongs to + The issue the design belongs to. """ issue: Issue! @@ -6487,17 +6807,17 @@ type Design implements CurrentUserTodos & DesignFields & Noteable { ): NoteConnection! """ - The total count of user-created notes for this design + The total count of user-created notes for this design. """ notesCount: Int! """ - The project the design belongs to + The project the design belongs to. """ project: Project! """ - All versions related to this design ordered newest first + All versions related to this design ordered newest first. """ versions( """ @@ -6537,37 +6857,37 @@ A design pinned to a specific version. The image field reflects the design as of """ type DesignAtVersion implements DesignFields { """ - The underlying design + The underlying design. """ design: Design! """ - The diff refs for this design + The diff refs for this design. """ diffRefs: DiffRefs! """ - How this design was changed in the current version + How this design was changed in the current version. """ event: DesignVersionEvent! """ - The filename of the design + The filename of the design. """ filename: String! """ - The full path to the design file + The full path to the design file. """ fullPath: String! """ - The ID of this design + The ID of this design. """ id: ID! """ - The URL of the full-sized image + The URL of the full-sized image. """ image: String! @@ -6577,22 +6897,22 @@ type DesignAtVersion implements DesignFields { imageV432x230: String """ - The issue the design belongs to + The issue the design belongs to. """ issue: Issue! """ - The total count of user-created notes for this design + The total count of user-created notes for this design. """ notesCount: Int! """ - The project the design belongs to + The project the design belongs to. """ project: Project! """ - The version this design-at-versions is pinned to + The version this design-at-versions is pinned to. """ version: DesignVersion! } @@ -6637,12 +6957,12 @@ A collection of designs """ type DesignCollection { """ - Copy state of the design collection + Copy state of the design collection. """ copyState: DesignCollectionCopyState """ - Find a specific design + Find a specific design. """ design( """ @@ -6657,7 +6977,7 @@ type DesignCollection { ): Design """ - Find a design as of a version + Find a design as of a version. """ designAtVersion( """ @@ -6667,7 +6987,7 @@ type DesignCollection { ): DesignAtVersion """ - All designs for the design collection + All designs for the design collection. """ designs( """ @@ -6708,17 +7028,17 @@ type DesignCollection { ): DesignConnection! """ - Issue associated with the design collection + Issue associated with the design collection. """ issue: Issue! """ - Project associated with the design collection + Project associated with the design collection. """ project: Project! """ - A specific version + A specific version. """ version( """ @@ -6733,7 +7053,7 @@ type DesignCollection { ): DesignVersion """ - All versions related to all designs, ordered newest first + All versions related to all designs, ordered newest first. """ versions( """ @@ -6825,32 +7145,32 @@ type DesignEdge { interface DesignFields { """ - The diff refs for this design + The diff refs for this design. """ diffRefs: DiffRefs! """ - How this design was changed in the current version + How this design was changed in the current version. """ event: DesignVersionEvent! """ - The filename of the design + The filename of the design. """ filename: String! """ - The full path to the design file + The full path to the design file. """ fullPath: String! """ - The ID of this design + The ID of this design. """ id: ID! """ - The URL of the full-sized image + The URL of the full-sized image. """ image: String! @@ -6860,24 +7180,24 @@ interface DesignFields { imageV432x230: String """ - The issue the design belongs to + The issue the design belongs to. """ issue: Issue! """ - The total count of user-created notes for this design + The total count of user-created notes for this design. """ notesCount: Int! """ - The project the design belongs to + The project the design belongs to. """ project: Project! } type DesignManagement { """ - Find a design as of a version + Find a design as of a version. """ designAtVersion( """ @@ -6887,7 +7207,7 @@ type DesignManagement { ): DesignAtVersion """ - Find a version + Find a version. """ version( """ @@ -6943,12 +7263,12 @@ type DesignManagementDeletePayload { } """ -Identifier of DesignManagement::DesignAtVersion +Identifier of DesignManagement::DesignAtVersion. """ scalar DesignManagementDesignAtVersionID """ -Identifier of DesignManagement::Design +Identifier of DesignManagement::Design. """ scalar DesignManagementDesignID @@ -7048,7 +7368,7 @@ type DesignManagementUploadPayload { } """ -Identifier of DesignManagement::Version +Identifier of DesignManagement::Version. """ scalar DesignManagementVersionID @@ -7057,7 +7377,7 @@ A specific version in which designs were added, modified or deleted """ type DesignVersion { """ - A particular design as of this version, provided it is visible at this version + A particular design as of this version, provided it is visible at this version. """ designAtVersion( """ @@ -7077,7 +7397,7 @@ type DesignVersion { ): DesignAtVersion! """ - All designs that were changed in the version + All designs that were changed in the version. """ designs( """ @@ -7102,7 +7422,7 @@ type DesignVersion { ): DesignConnection! """ - All designs that are visible at this version, as of this version + All designs that are visible at this version, as of this version. """ designsAtVersion( """ @@ -7137,12 +7457,12 @@ type DesignVersion { ): DesignAtVersionConnection! """ - ID of the design version + ID of the design version. """ id: ID! """ - SHA of the design version + SHA of the design version. """ sha: ID! } @@ -7454,47 +7774,47 @@ type DestroySnippetPayload { type DetailedStatus { """ - Action information for the status. This includes method, button title, icon, path, and title + Action information for the status. This includes method, button title, icon, path, and title. """ action: StatusAction """ - Path of the details for the status + Path of the details for the status. """ detailsPath: String """ - Favicon of the status + Favicon of the status. """ favicon: String """ - Group of the status + Group of the status. """ group: String """ - Indicates if the status has further details + Indicates if the status has further details. """ hasDetails: Boolean """ - Icon of the status + Icon of the status. """ icon: String """ - Label of the status + Label of the status. """ label: String """ - Text of the status + Text of the status. """ text: String """ - Tooltip associated with the status + Tooltip associated with the status. """ tooltip: String } @@ -7616,12 +7936,12 @@ type DevopsAdoptionSnapshot { input DiffImagePositionInput { """ - Merge base of the branch the comment was made on + Merge base of the branch the comment was made on. """ baseSha: String """ - SHA of the HEAD at the time the comment was made + SHA of the HEAD at the time the comment was made. """ headSha: String! @@ -7637,7 +7957,7 @@ input DiffImagePositionInput { paths: DiffPathsInput! """ - SHA of the branch being compared against + SHA of the branch being compared against. """ startSha: String! @@ -7658,18 +7978,18 @@ input DiffImagePositionInput { } """ -Identifier of DiffNote +Identifier of DiffNote. """ scalar DiffNoteID input DiffPathsInput { """ - The path of the file on the head sha + The path of the file on the head sha. """ newPath: String """ - The path of the file on the start sha + The path of the file on the start sha. """ oldPath: String } @@ -7733,12 +8053,12 @@ type DiffPosition { input DiffPositionInput { """ - Merge base of the branch the comment was made on + Merge base of the branch the comment was made on. """ baseSha: String """ - SHA of the HEAD at the time the comment was made + SHA of the HEAD at the time the comment was made. """ headSha: String! @@ -7759,7 +8079,7 @@ input DiffPositionInput { paths: DiffPathsInput! """ - SHA of the branch being compared against + SHA of the branch being compared against. """ startSha: String! } @@ -7774,17 +8094,17 @@ enum DiffPositionType { type DiffRefs { """ - Merge base of the branch the comment was made on + Merge base of the branch the comment was made on. """ baseSha: String """ - SHA of the HEAD at the time the comment was made + SHA of the HEAD at the time the comment was made. """ headSha: String! """ - SHA of the branch being compared against + SHA of the branch being compared against. """ startSha: String! } @@ -7794,17 +8114,17 @@ Changes to a single file """ type DiffStats { """ - Number of lines added to this file + Number of lines added to this file. """ additions: Int! """ - Number of lines deleted from this file + Number of lines deleted from this file. """ deletions: Int! """ - File path, relative to repository root + File path, relative to repository root. """ path: String! } @@ -7814,22 +8134,22 @@ Aggregated summary of changes """ type DiffStatsSummary { """ - Number of lines added + Number of lines added. """ additions: Int! """ - Number of lines changed + Number of lines changed. """ changes: Int! """ - Number of lines deleted + Number of lines deleted. """ deletions: Int! """ - Number of files changed + Number of files changed. """ fileCount: Int! } @@ -7843,7 +8163,7 @@ type Discussion implements ResolvableInterface { """ ID of this discussion """ - id: ID! + id: DiscussionID! """ All notes in the discussion @@ -7873,7 +8193,7 @@ type Discussion implements ResolvableInterface { """ ID used to reply to this discussion """ - replyId: ID! + replyId: DiscussionID! """ Indicates if the object can be resolved @@ -7932,7 +8252,7 @@ type DiscussionEdge { } """ -Identifier of Discussion +Identifier of Discussion. """ scalar DiscussionID @@ -8043,7 +8363,7 @@ interface Entry { path: String! """ - Last commit sha for the entry + Last commit SHA for the entry """ sha: String! @@ -8067,17 +8387,17 @@ Describes where code is deployed for a project """ type Environment { """ - ID of the environment + ID of the environment. """ id: ID! """ - The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned + The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned. """ latestOpenedMostSevereAlert: AlertManagementAlert """ - Metrics dashboard schema for the environment + Metrics dashboard schema for the environment. """ metricsDashboard( """ @@ -8087,7 +8407,7 @@ type Environment { ): MetricsDashboard """ - Human-readable name of the environment + Human-readable name of the environment. """ name: String! @@ -8097,7 +8417,7 @@ type Environment { path: String! """ - State of the environment, for example: available/stopped + State of the environment, for example: available/stopped. """ state: String! } @@ -8138,7 +8458,7 @@ type EnvironmentEdge { } """ -Identifier of Environment +Identifier of Environment. """ scalar EnvironmentID @@ -8182,12 +8502,37 @@ Represents an epic """ type Epic implements CurrentUserTodos & Noteable { """ - Author of the epic + Author of the epic. """ author: User! """ - Children (sub-epics) of the epic + A list of award emojis associated with the epic. + """ + awardEmoji( + """ + 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 + ): AwardEmojiConnection + + """ + Children (sub-epics) of the epic. """ children( """ @@ -8285,22 +8630,22 @@ type Epic implements CurrentUserTodos & Noteable { ): EpicConnection """ - Timestamp of when the epic was closed + Timestamp of when the epic was closed. """ closedAt: Time """ - Indicates if the epic is confidential + Indicates if the epic is confidential. """ confidential: Boolean """ - Timestamp of when the epic was created + Timestamp of when the epic was created. """ createdAt: Time """ - Todos for the current user + To-do items for the current user. """ currentUserTodos( """ @@ -8324,23 +8669,23 @@ type Epic implements CurrentUserTodos & Noteable { last: Int """ - State of the todos + State of the to-do items. """ state: TodoStateEnum ): TodoConnection! """ - Number of open and closed descendant epics and issues + Number of open and closed descendant epics and issues. """ descendantCounts: EpicDescendantCount """ - Total weight of open and closed issues in the epic and its descendants + Total weight of open and closed issues in the epic and its descendants. """ descendantWeightSum: EpicDescendantWeights """ - Description of the epic + Description of the epic. """ description: String @@ -8370,67 +8715,67 @@ type Epic implements CurrentUserTodos & Noteable { ): DiscussionConnection! """ - Number of downvotes the epic has received + Number of downvotes the epic has received. """ downvotes: Int! """ - Due date of the epic + Due date of the epic. """ dueDate: Time """ - Fixed due date of the epic + Fixed due date of the epic. """ dueDateFixed: Time """ - Inherited due date of the epic from milestones + Inherited due date of the epic from milestones. """ dueDateFromMilestones: Time """ - Indicates if the due date has been manually set + Indicates if the due date has been manually set. """ dueDateIsFixed: Boolean """ - Group to which the epic belongs + Group to which the epic belongs. """ group: Group! """ - Indicates if the epic has children + Indicates if the epic has children. """ hasChildren: Boolean! """ - Indicates if the epic has direct issues + Indicates if the epic has direct issues. """ hasIssues: Boolean! """ - Indicates if the epic has a parent epic + Indicates if the epic has a parent epic. """ hasParent: Boolean! """ - Current health status of the epic + Current health status of the epic. """ healthStatus: EpicHealthStatus """ - ID of the epic + ID of the epic. """ id: ID! """ - Internal ID of the epic + Internal ID of the epic. """ iid: ID! """ - A list of issues associated with the epic + A list of issues associated with the epic. """ issues( """ @@ -8455,7 +8800,7 @@ type Epic implements CurrentUserTodos & Noteable { ): EpicIssueConnection """ - Labels assigned to the epic + Labels assigned to the epic. """ labels( """ @@ -8505,12 +8850,12 @@ type Epic implements CurrentUserTodos & Noteable { ): NoteConnection! """ - Parent epic of the epic + Parent epic of the epic. """ parent: Epic """ - List of participants for the epic + List of participants for the epic. """ participants( """ @@ -8535,77 +8880,77 @@ type Epic implements CurrentUserTodos & Noteable { ): UserConnection """ - Internal reference of the epic. Returned in shortened format by default + Internal reference of the epic. Returned in shortened format by default. """ reference( """ - Indicates if the reference should be returned in full + Indicates if the reference should be returned in full. """ full: Boolean = false ): String! """ - URI path of the epic-issue relationship + URI path of the epic-issue relationship. """ relationPath: String """ - The relative position of the epic in the epic tree + The relative position of the epic in the epic tree. """ relativePosition: Int """ - Start date of the epic + Start date of the epic. """ startDate: Time """ - Fixed start date of the epic + Fixed start date of the epic. """ startDateFixed: Time """ - Inherited start date of the epic from milestones + Inherited start date of the epic from milestones. """ startDateFromMilestones: Time """ - Indicates if the start date has been manually set + Indicates if the start date has been manually set. """ startDateIsFixed: Boolean """ - State of the epic + State of the epic. """ state: EpicState! """ - Indicates the currently logged in user is subscribed to the epic + Indicates the currently logged in user is subscribed to the epic. """ subscribed: Boolean! """ - Title of the epic + Title of the epic. """ title: String """ - Timestamp of when the epic was updated + Timestamp of when the epic was updated. """ updatedAt: Time """ - Number of upvotes the epic has received + Number of upvotes the epic has received. """ upvotes: Int! """ - Number of user discussions in the epic + Number of user discussions in the epic. """ userDiscussionsCount: Int! """ - Number of user notes of the epic + Number of user notes of the epic. """ userNotesCount: Int! @@ -8615,12 +8960,12 @@ type Epic implements CurrentUserTodos & Noteable { userPermissions: EpicPermissions! """ - Web path of the epic + Web path of the epic. """ webPath: String! """ - Web URL of the epic + Web URL of the epic. """ webUrl: String! } @@ -8746,6 +9091,56 @@ type EpicBoardConnection { } """ +Autogenerated input type of EpicBoardCreate +""" +input EpicBoardCreateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Full path of the group with which the resource is associated. + """ + groupPath: ID + + """ + Whether or not backlog list is hidden. + """ + hideBacklogList: Boolean + + """ + Whether or not closed list is hidden. + """ + hideClosedList: Boolean + + """ + The board name. + """ + name: String +} + +""" +Autogenerated return type of EpicBoardCreate +""" +type EpicBoardCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The created epic board. + """ + epicBoard: EpicBoard + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" An edge in a connection. """ type EpicBoardEdge { @@ -8856,7 +9251,7 @@ type EpicHealthStatus { } """ -Identifier of Epic +Identifier of Epic. """ scalar EpicID @@ -8930,7 +9325,7 @@ type EpicIssue implements CurrentUserTodos & Noteable { createdAt: Time! """ - Todos for the current user + To-do items for the current user. """ currentUserTodos( """ @@ -8954,7 +9349,7 @@ type EpicIssue implements CurrentUserTodos & Noteable { last: Int """ - State of the todos + State of the to-do items. """ state: TodoStateEnum ): TodoConnection! @@ -9280,7 +9675,7 @@ The connection type for EpicIssue. """ type EpicIssueConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -9610,7 +10005,7 @@ type EpicTreeReorderPayload { } """ -Identifier of EpicTreeSorting +Identifier of EpicTreeSorting. """ scalar EpicTreeSortingID @@ -9654,6 +10049,11 @@ input ExportRequirementsInput { search: String """ + List of selected requirements fields to be exported. + """ + selectedFields: [String!] + + """ List requirements by sort order. """ sort: Sort @@ -9937,33 +10337,63 @@ type GeoNode { } """ -Identifier of Gitlab::ErrorTracking::DetailedError +Identifier of Gitlab::ErrorTracking::DetailedError. """ scalar GitlabErrorTrackingDetailedErrorID +""" +Autogenerated input type of GitlabSubscriptionActivate +""" +input GitlabSubscriptionActivateInput { + """ + Activation code received after purchasing a GitLab subscription. + """ + activationCode: String! + + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String +} + +""" +Autogenerated return type of GitlabSubscriptionActivate +""" +type GitlabSubscriptionActivatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + type GrafanaIntegration { """ - Timestamp of the issue's creation + Timestamp of the issue's creation. """ createdAt: Time! """ - Indicates whether Grafana integration is enabled + Indicates whether Grafana integration is enabled. """ enabled: Boolean! """ - URL for the Grafana host for the Grafana integration + URL for the Grafana host for the Grafana integration. """ grafanaUrl: String! """ - Internal ID of the Grafana integration + Internal ID of the Grafana integration. """ id: ID! """ - Timestamp of the issue's last activity + Timestamp of the issue's last activity. """ updatedAt: Time! } @@ -9980,17 +10410,17 @@ type Group { additionalPurchasedStorageSize: Float """ - Indicates whether Auto DevOps is enabled for all projects within this group + Indicates whether Auto DevOps is enabled for all projects within this group. """ autoDevopsEnabled: Boolean """ - Avatar URL of the group + Avatar URL of the group. """ avatarUrl: String """ - A single board of the group + A single board of the group. """ board( """ @@ -10000,7 +10430,7 @@ type Group { ): Board """ - Boards of the group + Boards of the group. """ boards( """ @@ -10091,7 +10521,7 @@ type Group { ): ComplianceFrameworkConnection """ - Container repositories of the group + Container repositories of the group. """ containerRepositories( """ @@ -10121,7 +10551,7 @@ type Group { ): ContainerRepositoryConnection """ - Number of container repositories in the group + Number of container repositories in the group. """ containerRepositoriesCount: Int! @@ -10131,7 +10561,7 @@ type Group { containsLockedProjects: Boolean! """ - Custom emoji within this namespace Available only when feature flag `custom_emoji` is enabled. + Custom emoji within this namespace. Available only when feature flag `custom_emoji` is enabled. """ customEmoji( """ @@ -10166,7 +10596,7 @@ type Group { descriptionHtml: String """ - Indicates if a group has email notifications disabled + Indicates if a group has email notifications disabled. """ emailsDisabled: Boolean @@ -10397,7 +10827,7 @@ type Group { fullPath: ID! """ - A membership of a user within this group + A membership of a user within this group. """ groupMembers( """ @@ -10447,7 +10877,7 @@ type Group { isTemporaryStorageIncreaseEnabled: Boolean! """ - Issues for projects in this group + Issues for projects in this group. """ issues( """ @@ -10645,17 +11075,17 @@ type Group { ): IterationConnection """ - A label available on this group + A label available on this group. """ label( """ - Title of the label + Title of the label. """ title: String! ): Label """ - Labels available on this group + Labels available on this group. """ labels( """ @@ -10679,7 +11109,7 @@ type Group { last: Int """ - A search term to find labels with + A search term to find labels with. """ searchTerm: String ): LabelConnection @@ -10690,12 +11120,12 @@ type Group { lfsEnabled: Boolean """ - Indicates if a group is disabled from getting mentioned + Indicates if a group is disabled from getting mentioned. """ mentionsDisabled: Boolean """ - Merge requests for projects in this group + Merge requests for projects in this group. """ mergeRequests( """ @@ -10780,7 +11210,7 @@ type Group { ): MergeRequestConnection """ - Milestones of the group + Milestones of the group. """ milestones( """ @@ -10863,7 +11293,7 @@ type Group { packageSettings: PackageSettings """ - Parent group + Parent group. """ parent: Group @@ -10873,7 +11303,7 @@ type Group { path: String! """ - The permission level required to create projects in the group + The permission level required to create projects in the group. """ projectCreationLevel: String @@ -10933,7 +11363,7 @@ type Group { requestAccessEnabled: Boolean """ - Indicates if all users in this group are required to set up two-factor authentication + Indicates if all users in this group are required to set up two-factor authentication. """ requireTwoFactorAuthentication: Boolean @@ -10943,7 +11373,7 @@ type Group { rootStorageStatistics: RootStorageStatistics """ - Indicates if sharing a project with another group within this group is prevented + Indicates if sharing a project with another group within this group is prevented. """ shareWithGroupLock: Boolean @@ -10958,7 +11388,7 @@ type Group { storageSizeLimit: Float """ - The permission level required to create subgroups within the group + The permission level required to create subgroups within the group. """ subgroupCreationLevel: String @@ -11023,7 +11453,7 @@ type Group { totalRepositorySizeExcess: Float """ - Time before two-factor authentication is enforced + Time before two-factor authentication is enforced. """ twoFactorGracePeriod: Int @@ -11184,7 +11614,7 @@ type Group { ): [VulnerableProjectsByGrade!]! """ - Vulnerability scanners reported on the project vulnerabilties of the group and its subgroups + Vulnerability scanners reported on the project vulnerabilities of the group and its subgroups """ vulnerabilityScanners( """ @@ -11239,13 +11669,13 @@ type Group { ): VulnerabilitySeveritiesCount """ - Web URL of the group + Web URL of the group. """ webUrl: String! } """ -Identifier of Group +Identifier of Group. """ scalar GroupID @@ -11274,7 +11704,7 @@ type GroupMember implements MemberInterface { expiresAt: Time """ - Group that a User is a member of + Group that a User is a member of. """ group: Group @@ -11545,6 +11975,16 @@ input HttpIntegrationUpdateInput { The name of the integration. """ name: String + + """ + The custom mapping of GitLab alert attributes to fields from the payload_example. + """ + payloadAttributeMappings: [AlertManagementPayloadAlertFieldInput!] + + """ + The example of an alert payload. + """ + payloadExample: JsonString } """ @@ -11573,7 +12013,7 @@ An ISO 8601-encoded date scalar ISO8601Date """ -Identifier of IncidentManagement::OncallParticipant +Identifier of IncidentManagement::OncallParticipant. """ scalar IncidentManagementOncallParticipantID @@ -11627,6 +12067,41 @@ type IncidentManagementOncallRotation { ): OncallParticipantTypeConnection """ + Blocks of time for which a participant is on-call within a given time frame. Time frame cannot exceed one month. + """ + shifts( + """ + 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 + + """ + End of timeframe to include shifts for. Cannot exceed one month after start. + """ + endTime: Time! + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + Start of timeframe to include shifts for. + """ + startTime: Time! + ): IncidentManagementOncallShiftConnection + + """ Start date of the on-call rotation. """ startsAt: Time @@ -11668,7 +12143,7 @@ type IncidentManagementOncallRotationEdge { } """ -Identifier of IncidentManagement::OncallRotation +Identifier of IncidentManagement::OncallRotation. """ scalar IncidentManagementOncallRotationID @@ -11757,6 +12232,61 @@ type IncidentManagementOncallScheduleEdge { node: IncidentManagementOncallSchedule } +""" +A block of time for which a participant is on-call. +""" +type IncidentManagementOncallShift { + """ + End time of the on-call shift. + """ + endsAt: Time + + """ + Participant assigned to the on-call shift. + """ + participant: OncallParticipantType + + """ + Start time of the on-call shift. + """ + startsAt: Time +} + +""" +The connection type for IncidentManagementOncallShift. +""" +type IncidentManagementOncallShiftConnection { + """ + A list of edges. + """ + edges: [IncidentManagementOncallShiftEdge] + + """ + A list of nodes. + """ + nodes: [IncidentManagementOncallShift] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type IncidentManagementOncallShiftEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: IncidentManagementOncallShift +} + type InstanceSecurityDashboard { """ Projects selected in Instance Security Dashboard @@ -11789,7 +12319,7 @@ type InstanceSecurityDashboard { vulnerabilityGrades: [VulnerableProjectsByGrade!]! """ - Vulnerability scanners reported on the vulnerabilties from projects selected in Instance Security Dashboard + Vulnerability scanners reported on the vulnerabilities from projects selected in Instance Security Dashboard """ vulnerabilityScanners( """ @@ -11849,17 +12379,17 @@ Represents a recorded measurement (object count) for the Admins """ type InstanceStatisticsMeasurement { """ - Object count + Object count. """ count: Int! """ - The type of objects being measured + The type of objects being measured. """ identifier: MeasurementIdentifier! """ - The time the measurement was recorded + The time the measurement was recorded. """ recordedAt: Time } @@ -12006,7 +12536,7 @@ type Issue implements CurrentUserTodos & Noteable { createdAt: Time! """ - Todos for the current user + To-do items for the current user. """ currentUserTodos( """ @@ -12030,7 +12560,7 @@ type Issue implements CurrentUserTodos & Noteable { last: Int """ - State of the todos + State of the to-do items. """ state: TodoStateEnum ): TodoConnection! @@ -12346,7 +12876,7 @@ The connection type for Issue. """ type IssueConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -12387,7 +12917,7 @@ type IssueEdge { } """ -Identifier of Issue +Identifier of Issue. """ scalar IssueID @@ -13272,7 +13802,7 @@ type IterationEdge { } """ -Identifier of Iteration +Identifier of Iteration. """ scalar IterationID @@ -13684,7 +14214,7 @@ The connection type for Label. """ type LabelConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -13726,12 +14256,12 @@ input LabelCreateInput { description: String """ - The group full path the resource is associated with. + Full path of the group with which the resource is associated. """ groupPath: ID """ - The project full path the resource is associated with. + Full path of the project with which the resource is associated. """ projectPath: ID @@ -13777,12 +14307,12 @@ type LabelEdge { } """ -Identifier of Label +Identifier of Label. """ scalar LabelID """ -Identifier of List +Identifier of List. """ scalar ListID @@ -14089,7 +14619,7 @@ type MergeRequest implements CurrentUserTodos & Noteable { createdAt: Time! """ - Todos for the current user + To-do items for the current user. """ currentUserTodos( """ @@ -14113,7 +14643,7 @@ type MergeRequest implements CurrentUserTodos & Noteable { last: Int """ - State of the todos + State of the to-do items. """ state: TodoStateEnum ): TodoConnection! @@ -14604,7 +15134,7 @@ The connection type for MergeRequest. """ type MergeRequestConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -14785,7 +15315,7 @@ type MergeRequestEdge { } """ -Identifier of MergeRequest +Identifier of MergeRequest. """ scalar MergeRequestID @@ -14840,6 +15370,51 @@ type MergeRequestPermissions { } """ +Autogenerated input type of MergeRequestReviewerRereview +""" +input MergeRequestReviewerRereviewInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The IID of the merge request to mutate. + """ + iid: String! + + """ + The project the merge request to mutate is in. + """ + projectPath: ID! + + """ + The user ID for the user that has been requested for a new review. + """ + userId: UserID! +} + +""" +Autogenerated return type of MergeRequestReviewerRereview +""" +type MergeRequestReviewerRereviewPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The merge request after mutation. + """ + mergeRequest: MergeRequest +} + +""" Autogenerated input type of MergeRequestSetAssignees """ input MergeRequestSetAssigneesInput { @@ -15211,6 +15786,10 @@ enum MergeRequestState { all closed locked + + """ + Merge Request has been merged + """ merged opened } @@ -15422,7 +16001,7 @@ type MetricsDashboardAnnotationEdge { } """ -Identifier of Metrics::Dashboard::Annotation +Identifier of Metrics::Dashboard::Annotation. """ scalar MetricsDashboardAnnotationID @@ -15537,12 +16116,22 @@ type MilestoneEdge { } """ -Identifier of Milestone +Identifier of Milestone. """ scalar MilestoneID +""" +Current state of milestone +""" enum MilestoneStateEnum { + """ + Milestone is currently active + """ active + + """ + Milestone is closed + """ closed } @@ -15615,6 +16204,7 @@ type Mutation { createSnippet(input: CreateSnippetInput!): CreateSnippetPayload createTestCase(input: CreateTestCaseInput!): CreateTestCasePayload dastOnDemandScanCreate(input: DastOnDemandScanCreateInput!): DastOnDemandScanCreatePayload + dastProfileCreate(input: DastProfileCreateInput!): DastProfileCreatePayload dastScannerProfileCreate(input: DastScannerProfileCreateInput!): DastScannerProfileCreatePayload dastScannerProfileDelete(input: DastScannerProfileDeleteInput!): DastScannerProfileDeletePayload dastScannerProfileUpdate(input: DastScannerProfileUpdateInput!): DastScannerProfileUpdatePayload @@ -15623,6 +16213,7 @@ type Mutation { dastSiteProfileUpdate(input: DastSiteProfileUpdateInput!): DastSiteProfileUpdatePayload dastSiteTokenCreate(input: DastSiteTokenCreateInput!): DastSiteTokenCreatePayload dastSiteValidationCreate(input: DastSiteValidationCreateInput!): DastSiteValidationCreatePayload + dastSiteValidationRevoke(input: DastSiteValidationRevokeInput!): DastSiteValidationRevokePayload deleteAnnotation(input: DeleteAnnotationInput!): DeleteAnnotationPayload deleteDevopsAdoptionSegment(input: DeleteDevopsAdoptionSegmentInput!): DeleteDevopsAdoptionSegmentPayload designManagementDelete(input: DesignManagementDeleteInput!): DesignManagementDeletePayload @@ -15643,9 +16234,11 @@ type Mutation { dismissVulnerability(input: DismissVulnerabilityInput!): DismissVulnerabilityPayload @deprecated(reason: "Use vulnerabilityDismiss. Deprecated in 13.5.") environmentsCanaryIngressUpdate(input: EnvironmentsCanaryIngressUpdateInput!): EnvironmentsCanaryIngressUpdatePayload epicAddIssue(input: EpicAddIssueInput!): EpicAddIssuePayload + epicBoardCreate(input: EpicBoardCreateInput!): EpicBoardCreatePayload epicSetSubscription(input: EpicSetSubscriptionInput!): EpicSetSubscriptionPayload epicTreeReorder(input: EpicTreeReorderInput!): EpicTreeReorderPayload exportRequirements(input: ExportRequirementsInput!): ExportRequirementsPayload + gitlabSubscriptionActivate(input: GitlabSubscriptionActivateInput!): GitlabSubscriptionActivatePayload httpIntegrationCreate(input: HttpIntegrationCreateInput!): HttpIntegrationCreatePayload httpIntegrationDestroy(input: HttpIntegrationDestroyInput!): HttpIntegrationDestroyPayload httpIntegrationResetToken(input: HttpIntegrationResetTokenInput!): HttpIntegrationResetTokenPayload @@ -15666,6 +16259,7 @@ type Mutation { labelCreate(input: LabelCreateInput!): LabelCreatePayload markAsSpamSnippet(input: MarkAsSpamSnippetInput!): MarkAsSpamSnippetPayload mergeRequestCreate(input: MergeRequestCreateInput!): MergeRequestCreatePayload + mergeRequestReviewerRereview(input: MergeRequestReviewerRereviewInput!): MergeRequestReviewerRereviewPayload mergeRequestSetAssignees(input: MergeRequestSetAssigneesInput!): MergeRequestSetAssigneesPayload mergeRequestSetLabels(input: MergeRequestSetLabelsInput!): MergeRequestSetLabelsPayload mergeRequestSetLocked(input: MergeRequestSetLockedInput!): MergeRequestSetLockedPayload @@ -15679,6 +16273,7 @@ type Mutation { mergeRequestUpdate(input: MergeRequestUpdateInput!): MergeRequestUpdatePayload namespaceIncreaseStorageTemporarily(input: NamespaceIncreaseStorageTemporarilyInput!): NamespaceIncreaseStorageTemporarilyPayload oncallRotationCreate(input: OncallRotationCreateInput!): OncallRotationCreatePayload + oncallRotationDestroy(input: OncallRotationDestroyInput!): OncallRotationDestroyPayload oncallScheduleCreate(input: OncallScheduleCreateInput!): OncallScheduleCreatePayload oncallScheduleDestroy(input: OncallScheduleDestroyInput!): OncallScheduleDestroyPayload oncallScheduleUpdate(input: OncallScheduleUpdateInput!): OncallScheduleUpdatePayload @@ -15983,7 +16578,7 @@ type NamespaceEdge { } """ -Identifier of Namespace +Identifier of Namespace. """ scalar NamespaceID @@ -16039,12 +16634,12 @@ enum NamespaceProjectSort { input NegatedBoardIssueInput { """ - Filter by assignee username + Filter by assignee username. """ assigneeUsername: [String] """ - Filter by author username + Filter by author username. """ authorUsername: String @@ -16059,22 +16654,22 @@ input NegatedBoardIssueInput { iterationTitle: String """ - Filter by label name + Filter by label name. """ labelName: [String] """ - Filter by milestone title + Filter by milestone title. """ milestoneTitle: String """ - Filter by reaction emoji + Filter by reaction emoji. """ myReactionEmoji: String """ - Filter by release tag + Filter by release tag. """ releaseTag: String @@ -16118,7 +16713,7 @@ type Note implements ResolvableInterface { """ ID of the note """ - id: ID! + id: NoteID! """ The position of this note on a diff @@ -16212,7 +16807,7 @@ type NoteEdge { } """ -Identifier of Note +Identifier of Note. """ scalar NoteID @@ -16301,7 +16896,7 @@ interface Noteable { } """ -Identifier of Noteable +Identifier of Noteable. """ scalar NoteableID @@ -16441,6 +17036,51 @@ input OncallRotationDateInputType { } """ +Autogenerated input type of OncallRotationDestroy +""" +input OncallRotationDestroyInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The ID of the on-call rotation to remove. + """ + id: IncidentManagementOncallRotationID! + + """ + The project to remove the on-call schedule from. + """ + projectPath: ID! + + """ + The IID of the on-call schedule to the on-call rotation belongs to. + """ + scheduleIid: String! +} + +""" +Autogenerated return type of OncallRotationDestroy +""" +type OncallRotationDestroyPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The on-call rotation. + """ + oncallRotation: IncidentManagementOncallRotation +} + +""" The rotation length of the on-call rotation """ input OncallRotationLengthInputType { @@ -16645,142 +17285,27 @@ Represents a package in the Package Registry """ type Package { """ - The created date. + Date of creation. """ createdAt: Time! """ - The ID of the package. - """ - id: ID! - - """ - The name of the package. + ID of the package. """ - name: String! + id: PackagesPackageID! """ - The type of the package. + Package metadata. """ - packageType: PackageTypeEnum! + metadata: PackageMetadata """ - Pipelines that built the package. - """ - pipelines( - """ - 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 - ): PipelineConnection - - """ - Project where the package is stored. - """ - project: Project! - - """ - The package tags. - """ - tags( - """ - 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 - ): PackageTagConnection - - """ - The updated date. - """ - updatedAt: Time! - - """ - The version of the package. - """ - version: String - - """ - The other versions of the package. - """ - versions( - """ - 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 - ): PackageConnection -} - -""" -Details of a Composer package -""" -type PackageComposerDetails { - """ - The Composer metadatum. - """ - composerMetadatum: PackageComposerMetadatumType! - - """ - The created date. - """ - createdAt: Time! - - """ - The ID of the package. - """ - id: ID! - - """ - The name of the package. + Name of the package. """ name: String! """ - The type of the package. + Package type. """ packageType: PackageTypeEnum! @@ -16815,7 +17340,7 @@ type PackageComposerDetails { project: Project! """ - The package tags. + Package tags. """ tags( """ @@ -16840,12 +17365,12 @@ type PackageComposerDetails { ): PackageTagConnection """ - The updated date. + Date of most recent update. """ updatedAt: Time! """ - The version of the package. + Version string. """ version: String @@ -16872,7 +17397,7 @@ type PackageComposerDetails { Returns the last _n_ elements from the list. """ last: Int - ): PackageConnection + ): PackageWithoutVersionsConnection } """ @@ -16901,21 +17426,6 @@ type PackageComposerJsonType { } """ -Composer metadatum -""" -type PackageComposerMetadatumType { - """ - Data of the Composer JSON file. - """ - composerJson: PackageComposerJsonType! - - """ - Target SHA of the package. - """ - targetSha: String! -} - -""" The connection type for Package. """ type PackageConnection { @@ -17031,6 +17541,11 @@ type PackageFileRegistryEdge { } """ +Represents metadata associated with a Package +""" +union PackageMetadata = ComposerMetadata + +""" Namespace-level Package Registry settings """ type PackageSettings { @@ -17154,7 +17669,137 @@ enum PackageTypeEnum { } """ -Identifier of Packages::Package +Represents a version of a package in the Package Registry +""" +type PackageWithoutVersions { + """ + Date of creation. + """ + createdAt: Time! + + """ + ID of the package. + """ + id: PackagesPackageID! + + """ + Package metadata. + """ + metadata: PackageMetadata + + """ + Name of the package. + """ + name: String! + + """ + Package type. + """ + packageType: PackageTypeEnum! + + """ + Pipelines that built the package. + """ + pipelines( + """ + 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 + ): PipelineConnection + + """ + Project where the package is stored. + """ + project: Project! + + """ + Package tags. + """ + tags( + """ + 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 + ): PackageTagConnection + + """ + Date of most recent update. + """ + updatedAt: Time! + + """ + Version string. + """ + version: String +} + +""" +The connection type for PackageWithoutVersions. +""" +type PackageWithoutVersionsConnection { + """ + A list of edges. + """ + edges: [PackageWithoutVersionsEdge] + + """ + A list of nodes. + """ + nodes: [PackageWithoutVersions] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type PackageWithoutVersionsEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: PackageWithoutVersions +} + +""" +Identifier of Packages::Package. """ scalar PackagesPackageID @@ -17185,49 +17830,49 @@ type PageInfo { type Pipeline { """ - Indicates if the pipeline is active + Indicates if the pipeline is active. """ active: Boolean! """ - Base SHA of the source branch + Base SHA of the source branch. """ beforeSha: String """ - Specifies if a pipeline can be canceled + Specifies if a pipeline can be canceled. """ cancelable: Boolean! """ - Timestamp of the pipeline's commit + Timestamp of the pipeline's commit. """ committedAt: Time """ - Config source of the pipeline (UNKNOWN_SOURCE, REPOSITORY_SOURCE, + Configuration source of the pipeline (UNKNOWN_SOURCE, REPOSITORY_SOURCE, AUTO_DEVOPS_SOURCE, WEBIDE_SOURCE, REMOTE_SOURCE, EXTERNAL_PROJECT_SOURCE, BRIDGE_SOURCE, PARAMETER_SOURCE) """ configSource: PipelineConfigSourceEnum """ - Coverage percentage + Coverage percentage. """ coverage: Float """ - Timestamp of the pipeline's creation + Timestamp of the pipeline's creation. """ createdAt: Time! """ - Detailed status of the pipeline + Detailed status of the pipeline. """ detailedStatus: DetailedStatus! """ - Pipelines this pipeline will trigger + Pipelines this pipeline will trigger. """ downstream( """ @@ -17252,27 +17897,27 @@ type Pipeline { ): PipelineConnection """ - Duration of the pipeline in seconds + Duration of the pipeline in seconds. """ duration: Int """ - Timestamp of the pipeline's completion + Timestamp of the pipeline's completion. """ finishedAt: Time """ - ID of the pipeline + ID of the pipeline. """ id: ID! """ - Internal ID of the pipeline + Internal ID of the pipeline. """ iid: String! """ - Jobs belonging to the pipeline + Jobs belonging to the pipeline. """ jobs( """ @@ -17302,17 +17947,17 @@ type Pipeline { ): CiJobConnection """ - Relative path to the pipeline's page + Relative path to the pipeline's page. """ path: String """ - Project the pipeline belongs to + Project the pipeline belongs to. """ project: Project """ - Specifies if a pipeline can be retried + Specifies if a pipeline can be retried. """ retryable: Boolean! @@ -17322,17 +17967,17 @@ type Pipeline { securityReportSummary: SecurityReportSummary """ - SHA of the pipeline's commit + SHA of the pipeline's commit. """ sha: String! """ - Job where pipeline was triggered from + Job where pipeline was triggered from. """ sourceJob: CiJob """ - Stages of the pipeline + Stages of the pipeline. """ stages( """ @@ -17357,7 +18002,7 @@ type Pipeline { ): CiStageConnection """ - Timestamp when the pipeline was started + Timestamp when the pipeline was started. """ startedAt: Time @@ -17368,17 +18013,17 @@ type Pipeline { status: PipelineStatusEnum! """ - Timestamp of the pipeline's last activity + Timestamp of the pipeline's last activity. """ updatedAt: Time! """ - Pipeline that triggered the pipeline + Pipeline that triggered the pipeline. """ upstream: Pipeline """ - Pipeline user + Pipeline user. """ user: User @@ -17390,57 +18035,57 @@ type Pipeline { type PipelineAnalytics { """ - Labels for the monthly pipeline count + Labels for the monthly pipeline count. """ monthPipelinesLabels: [String!] """ - Total monthly successful pipeline count + Total monthly successful pipeline count. """ monthPipelinesSuccessful: [Int!] """ - Total monthly pipeline count + Total monthly pipeline count. """ monthPipelinesTotals: [Int!] """ - Pipeline times labels + Pipeline times labels. """ pipelineTimesLabels: [String!] """ - Pipeline times + Pipeline times. """ pipelineTimesValues: [Int!] """ - Labels for the weekly pipeline count + Labels for the weekly pipeline count. """ weekPipelinesLabels: [String!] """ - Total weekly successful pipeline count + Total weekly successful pipeline count. """ weekPipelinesSuccessful: [Int!] """ - Total weekly pipeline count + Total weekly pipeline count. """ weekPipelinesTotals: [Int!] """ - Labels for the yearly pipeline count + Labels for the yearly pipeline count. """ yearPipelinesLabels: [String!] """ - Total yearly successful pipeline count + Total yearly successful pipeline count. """ yearPipelinesSuccessful: [Int!] """ - Total yearly pipeline count + Total yearly pipeline count. """ yearPipelinesTotals: [Int!] } @@ -17491,7 +18136,7 @@ The connection type for Pipeline. """ type PipelineConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -17759,6 +18404,16 @@ type Project { ): AlertManagementIntegrationConnection """ + Extract alert fields from payload for custom mapping + """ + alertManagementPayloadFields( + """ + Sample payload for extracting alert fields for custom mappings. + """ + payloadExample: String! + ): [AlertManagementPayloadAlertField!] + + """ If `only_allow_merge_if_pipeline_succeeds` is true, indicates if merge requests of the project can also be merged with skipped jobs """ @@ -17940,7 +18595,32 @@ type Project { createdAt: Time """ - The DAST scanner profiles associated with the project + DAST Profiles associated with the project. Always returns no nodes if `dast_saved_scans` is disabled. + """ + dastProfiles( + """ + 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 + ): DastProfileConnection + + """ + The DAST scanner profiles associated with the project. """ dastScannerProfiles( """ @@ -17965,7 +18645,7 @@ type Project { ): DastScannerProfileConnection """ - DAST Site Profile associated with the project + DAST Site Profile associated with the project. """ dastSiteProfile( """ @@ -17975,7 +18655,7 @@ type Project { ): DastSiteProfile """ - DAST Site Profiles associated with the project + DAST Site Profiles associated with the project. """ dastSiteProfiles( """ @@ -18000,8 +18680,8 @@ type Project { ): DastSiteProfileConnection """ - DAST Site Validations associated with the project. Will always return no nodes - if `security_on_demand_scans_site_validation` is disabled + DAST Site Validations associated with the project. Always returns no nodes if + `security_on_demand_scans_site_validation` is disabled. """ dastSiteValidations( """ @@ -19250,7 +19930,7 @@ type Project { snippetsEnabled: Boolean """ - Indicates if squash readonly is enabled + Indicates if `squashReadOnly` is enabled """ squashReadOnly: Boolean! @@ -19280,7 +19960,17 @@ type Project { tagList: String """ - Terraform states associated with the project + Find a single Terraform state by name. + """ + terraformState( + """ + Name of the Terraform state. + """ + name: String! + ): TerraformState + + """ + Terraform states associated with the project. """ terraformStates( """ @@ -19415,7 +20105,7 @@ type Project { ): VulnerabilitiesCountByDayConnection """ - Vulnerability scanners reported on the project vulnerabilties + Vulnerability scanners reported on the project vulnerabilities """ vulnerabilityScanners( """ @@ -19538,7 +20228,7 @@ type ProjectEdge { } """ -Identifier of Project +Identifier of Project. """ scalar ProjectID @@ -20052,7 +20742,7 @@ type PrometheusIntegrationUpdatePayload { } """ -Identifier of PrometheusService +Identifier of PrometheusService. """ scalar PrometheusServiceID @@ -20293,14 +20983,14 @@ type Query { ): Namespace """ - Find a composer package + Find a package """ - packageComposerDetails( + package( """ The global ID of the package. """ id: PackagesPackageID! - ): PackageComposerDetails + ): Package """ Find a project @@ -21015,7 +21705,7 @@ The connection type for Release. """ type ReleaseConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -21165,22 +21855,22 @@ Evidence for a release """ type ReleaseEvidence { """ - Timestamp when the evidence was collected + Timestamp when the evidence was collected. """ collectedAt: Time """ - URL from where the evidence can be downloaded + URL from where the evidence can be downloaded. """ filepath: String """ - ID of the evidence + ID of the evidence. """ id: ID! """ - SHA1 ID of the evidence hash + SHA1 ID of the evidence hash. """ sha: String } @@ -21407,7 +22097,7 @@ input RemoveAwardEmojiInput { clientMutationId: String """ - The emoji name + The emoji name. """ name: String! } @@ -21888,12 +22578,12 @@ type RunDASTScanPayload { type RunnerArchitecture { """ - Download location for the runner for the platform architecture + Download location for the runner for the platform architecture. """ downloadLocation: String! """ - Name of the runner platform architecture + Name of the runner platform architecture. """ name: String! } @@ -21935,7 +22625,7 @@ type RunnerArchitectureEdge { type RunnerPlatform { """ - Runner architectures supported for the platform + Runner architectures supported for the platform. """ architectures( """ @@ -21960,12 +22650,12 @@ type RunnerPlatform { ): RunnerArchitectureConnection """ - Human readable name of the runner platform + Human readable name of the runner platform. """ humanReadableName: String! """ - Name slug of the runner platform + Name slug of the runner platform. """ name: String! } @@ -22007,12 +22697,12 @@ type RunnerPlatformEdge { type RunnerSetup { """ - Instructions for installing the runner on the specified architecture + Instructions for installing the runner on the specified architecture. """ installInstructions: String! """ - Instructions for registering the runner + Instructions for registering the runner. """ registerInstructions: String } @@ -22102,27 +22792,27 @@ 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 + List of supported variables. """ variables( """ @@ -22187,17 +22877,17 @@ Represents the analyzers entity in SAST CI configuration """ input SastCiConfigurationAnalyzersEntityInput { """ - State of the analyzer + State of the analyzer. """ enabled: Boolean! """ - Name of analyzer + Name of analyzer. """ name: String! """ - List of variables for the analyzer + List of variables for the analyzer. """ variables: [SastCiConfigurationEntityInput!] } @@ -22307,17 +22997,17 @@ Represents an entity in SAST CI configuration """ input SastCiConfigurationEntityInput { """ - Default value that is used if value is empty + Default value that is used if value is empty. """ defaultValue: String! """ - CI keyword of entity + CI keyword of entity. """ field: String! """ - Current value of the entity + Current value of the entity. """ value: String! } @@ -22327,17 +23017,17 @@ Represents a CI configuration of SAST """ input SastCiConfigurationInput { """ - List of analyzers and related variables for the SAST configuration + List of analyzers and related variables for the SAST configuration. """ analyzers: [SastCiConfigurationAnalyzersEntityInput!] """ - List of global entities related to SAST configuration + List of global entities related to SAST configuration. """ global: [SastCiConfigurationEntityInput!] """ - List of pipeline entities related to SAST configuration + List of pipeline entities related to SAST configuration. """ pipeline: [SastCiConfigurationEntityInput!] } @@ -22456,37 +23146,37 @@ Represents summary of a security report """ type SecurityReportSummary { """ - Aggregated counts for the api_fuzzing scan + Aggregated counts for the `api_fuzzing` scan """ apiFuzzing: SecurityReportSummarySection """ - Aggregated counts for the container_scanning scan + Aggregated counts for the `container_scanning` scan """ containerScanning: SecurityReportSummarySection """ - Aggregated counts for the coverage_fuzzing scan + Aggregated counts for the `coverage_fuzzing` scan """ coverageFuzzing: SecurityReportSummarySection """ - Aggregated counts for the dast scan + Aggregated counts for the `dast` scan """ dast: SecurityReportSummarySection """ - Aggregated counts for the dependency_scanning scan + Aggregated counts for the `dependency_scanning` scan """ dependencyScanning: SecurityReportSummarySection """ - Aggregated counts for the sast scan + Aggregated counts for the `sast` scan """ sast: SecurityReportSummarySection """ - Aggregated counts for the secret_detection scan + Aggregated counts for the `secret_detection` scan """ secretDetection: SecurityReportSummarySection } @@ -22611,142 +23301,142 @@ A Sentry error """ type SentryDetailedError { """ - Count of occurrences + Count of occurrences. """ count: Int! """ - Culprit of the error + Culprit of the error. """ culprit: String! """ - External Base URL of the Sentry Instance + External Base URL of the Sentry Instance. """ externalBaseUrl: String! """ - External URL of the error + External URL of the error. """ externalUrl: String! """ - Commit the error was first seen + Commit the error was first seen. """ firstReleaseLastCommit: String """ - Release short version the error was first seen + Release short version the error was first seen. """ firstReleaseShortVersion: String """ - Release version the error was first seen + Release version the error was first seen. """ firstReleaseVersion: String """ - Timestamp when the error was first seen + Timestamp when the error was first seen. """ firstSeen: Time! """ - Last 24hr stats of the error + Last 24hr stats of the error. """ frequency: [SentryErrorFrequency!]! """ - GitLab commit SHA attributed to the Error based on the release version + GitLab commit SHA attributed to the Error based on the release version. """ gitlabCommit: String """ - Path to the GitLab page for the GitLab commit attributed to the error + Path to the GitLab page for the GitLab commit attributed to the error. """ gitlabCommitPath: String """ - URL of GitLab Issue + URL of GitLab Issue. """ gitlabIssuePath: String """ - ID (global ID) of the error + ID (global ID) of the error. """ id: ID! """ - Commit the error was last seen + Commit the error was last seen. """ lastReleaseLastCommit: String """ - Release short version the error was last seen + Release short version the error was last seen. """ lastReleaseShortVersion: String """ - Release version the error was last seen + Release version the error was last seen. """ lastReleaseVersion: String """ - Timestamp when the error was last seen + Timestamp when the error was last seen. """ lastSeen: Time! """ - Sentry metadata message of the error + Sentry metadata message of the error. """ message: String """ - ID (Sentry ID) of the error + ID (Sentry ID) of the error. """ sentryId: String! """ - ID of the project (Sentry project) + ID of the project (Sentry project). """ sentryProjectId: ID! """ - Name of the project affected by the error + Name of the project affected by the error. """ sentryProjectName: String! """ - Slug of the project affected by the error + Slug of the project affected by the error. """ sentryProjectSlug: String! """ - Short ID (Sentry ID) of the error + Short ID (Sentry ID) of the error. """ shortId: String! """ - Status of the error + Status of the error. """ status: SentryErrorStatus! """ - Tags associated with the Sentry Error + Tags associated with the Sentry Error. """ tags: SentryErrorTags! """ - Title of the error + Title of the error. """ title: String! """ - Type of the error + Type of the error. """ type: String! """ - Count of users affected by the error + Count of users affected by the error. """ userCount: Int! } @@ -22756,87 +23446,87 @@ A Sentry error. A simplified version of SentryDetailedError """ type SentryError { """ - Count of occurrences + Count of occurrences. """ count: Int! """ - Culprit of the error + Culprit of the error. """ culprit: String! """ - External URL of the error + External URL of the error. """ externalUrl: String! """ - Timestamp when the error was first seen + Timestamp when the error was first seen. """ firstSeen: Time! """ - Last 24hr stats of the error + Last 24hr stats of the error. """ frequency: [SentryErrorFrequency!]! """ - ID (global ID) of the error + ID (global ID) of the error. """ id: ID! """ - Timestamp when the error was last seen + Timestamp when the error was last seen. """ lastSeen: Time! """ - Sentry metadata message of the error + Sentry metadata message of the error. """ message: String """ - ID (Sentry ID) of the error + ID (Sentry ID) of the error. """ sentryId: String! """ - ID of the project (Sentry project) + ID of the project (Sentry project). """ sentryProjectId: ID! """ - Name of the project affected by the error + Name of the project affected by the error. """ sentryProjectName: String! """ - Slug of the project affected by the error + Slug of the project affected by the error. """ sentryProjectSlug: String! """ - Short ID (Sentry ID) of the error + Short ID (Sentry ID) of the error. """ shortId: String! """ - Status of the error + Status of the error. """ status: SentryErrorStatus! """ - Title of the error + Title of the error. """ title: String! """ - Type of the error + Type of the error. """ type: String! """ - Count of users affected by the error + Count of users affected by the error. """ userCount: Int! } @@ -22846,7 +23536,7 @@ An object containing a collection of Sentry errors, and a detailed error """ type SentryErrorCollection { """ - Detailed version of a Sentry error on the project + Detailed version of a Sentry error on the project. """ detailedError( """ @@ -22856,7 +23546,7 @@ type SentryErrorCollection { ): SentryDetailedError """ - Stack Trace of Sentry Error + Stack Trace of Sentry Error. """ errorStackTrace( """ @@ -22866,7 +23556,7 @@ type SentryErrorCollection { ): SentryErrorStackTrace """ - Collection of Sentry Errors + Collection of Sentry Errors. """ errors( """ @@ -22901,7 +23591,7 @@ type SentryErrorCollection { ): SentryErrorConnection """ - External URL for Sentry + External URL for Sentry. """ externalUrl: String } @@ -22943,12 +23633,12 @@ type SentryErrorEdge { type SentryErrorFrequency { """ - Count of errors received since the previously recorded time + Count of errors received since the previously recorded time. """ count: Int! """ - Time the error frequency stats were recorded + Time the error frequency stats were recorded. """ time: Time! } @@ -22958,17 +23648,17 @@ An object containing a stack trace entry for a Sentry error """ type SentryErrorStackTrace { """ - Time the stack trace was received by Sentry + Time the stack trace was received by Sentry. """ dateReceived: String! """ - ID of the Sentry error + ID of the Sentry error. """ issueId: String! """ - Stack trace entries for the Sentry error + Stack trace entries for the Sentry error. """ stackTraceEntries: [SentryErrorStackTraceEntry!]! } @@ -22978,12 +23668,12 @@ An object context for a Sentry error stack trace """ type SentryErrorStackTraceContext { """ - Code number of the context + Code number of the context. """ code: String! """ - Line number of the context + Line number of the context. """ line: Int! } @@ -22993,27 +23683,27 @@ An object containing a stack trace entry for a Sentry error """ type SentryErrorStackTraceEntry { """ - Function in which the Sentry error occurred + Function in which the Sentry error occurred. """ col: String """ - File in which the Sentry error occurred + File in which the Sentry error occurred. """ fileName: String """ - Function in which the Sentry error occurred + Function in which the Sentry error occurred. """ function: String """ - Function in which the Sentry error occurred + Function in which the Sentry error occurred. """ line: String """ - Context of the Sentry error + Context of the Sentry error. """ traceContext: [SentryErrorStackTraceContext!] } @@ -23048,12 +23738,12 @@ State of a Sentry error """ type SentryErrorTags { """ - Severity level of the Sentry Error + Severity level of the Sentry Error. """ level: String """ - Logger of the Sentry Error + Logger of the Sentry Error. """ logger: String } @@ -23459,7 +24149,7 @@ type SnippetBlobViewer { fileType: String! """ - Shows whether the blob content is loaded async + Shows whether the blob content is loaded asynchronously """ loadAsync: Boolean! @@ -23520,7 +24210,7 @@ type SnippetEdge { } """ -Identifier of Snippet +Identifier of Snippet. """ scalar SnippetID @@ -23683,27 +24373,27 @@ enum Sort { type StatusAction { """ - Title for the button, for example: Retry this job + Title for the button, for example: Retry this job. """ buttonTitle: String """ - Icon used in the action button + Icon used in the action button. """ icon: String """ - Method for the action, for example: :post + Method for the action, for example: :post. """ method: String """ - Path for the action + Path for the action. """ path: String """ - Title for the action, for example: Retry + Title for the action, for example: Retry. """ title: String } @@ -23730,7 +24420,7 @@ type Submodule implements Entry { path: String! """ - Last commit sha for the entry + Last commit SHA for the entry """ sha: String! @@ -23842,7 +24532,7 @@ The connection type for TerraformState. """ type TerraformStateConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -23908,7 +24598,7 @@ type TerraformStateEdge { } """ -Identifier of Terraform::State +Identifier of Terraform::State. """ scalar TerraformStateID @@ -24297,51 +24987,51 @@ type TimelogEdge { } """ -Representing a todo entry +Representing a to-do entry """ type Todo { """ - Action of the todo + Action of the to-do item """ action: TodoActionEnum! """ - The author of this todo + The author of this to-do item """ author: User! """ - Body of the todo + Body of the to-do item """ body: String! """ - Timestamp this todo was created + Timestamp this to-do item was created """ createdAt: Time! """ - Group this todo is associated with + Group this to-do item is associated with """ group: Group """ - ID of the todo + ID of the to-do item """ id: ID! """ - The project this todo is associated with + The project this to-do item is associated with """ project: Project """ - State of the todo + State of the to-do item """ state: TodoStateEnum! """ - Target type of the todo + Target type of the to-do item """ targetType: TodoTargetEnum! } @@ -24406,7 +25096,7 @@ type TodoCreatePayload { errors: [String!]! """ - The to-do created. + The to-do item created. """ todo: Todo } @@ -24427,7 +25117,7 @@ type TodoEdge { } """ -Identifier of Todo +Identifier of Todo. """ scalar TodoID @@ -24441,7 +25131,7 @@ input TodoMarkDoneInput { clientMutationId: String """ - The global ID of the todo to mark as done. + The global ID of the to-do item to mark as done. """ id: TodoID! } @@ -24461,7 +25151,7 @@ type TodoMarkDonePayload { errors: [String!]! """ - The requested todo. + The requested to-do item. """ todo: Todo! } @@ -24476,7 +25166,7 @@ input TodoRestoreInput { clientMutationId: String """ - The global ID of the todo to restore. + The global ID of the to-do item to restore. """ id: TodoID! } @@ -24491,7 +25181,7 @@ input TodoRestoreManyInput { clientMutationId: String """ - The global IDs of the todos to restore (a maximum of 50 is supported at once). + The global IDs of the to-do items to restore (a maximum of 50 is supported at once). """ ids: [TodoID!]! } @@ -24511,14 +25201,14 @@ type TodoRestoreManyPayload { errors: [String!]! """ - Updated todos. + Updated to-do items. """ todos: [Todo!]! """ - The IDs of the updated todo items. Deprecated in 13.2: Use todos. + The IDs of the updated to-do items. Deprecated in 13.2: Use to-do items. """ - updatedIds: [TodoID!]! @deprecated(reason: "Use todos. Deprecated in 13.2.") + updatedIds: [TodoID!]! @deprecated(reason: "Use to-do items. Deprecated in 13.2.") } """ @@ -24536,7 +25226,7 @@ type TodoRestorePayload { errors: [String!]! """ - The requested todo. + The requested to-do item. """ todo: Todo! } @@ -24579,7 +25269,7 @@ enum TodoTargetEnum { } """ -Identifier of Todoable +Identifier of Todoable. """ scalar TodoableID @@ -24608,14 +25298,14 @@ type TodosMarkAllDonePayload { errors: [String!]! """ - Updated todos. + Updated to-do items. """ todos: [Todo!]! """ - Ids of the updated todos. Deprecated in 13.2: Use todos. + IDs of the updated to-do items. Deprecated in 13.2: Use to-do items. """ - updatedIds: [TodoID!]! @deprecated(reason: "Use todos. Deprecated in 13.2.") + updatedIds: [TodoID!]! @deprecated(reason: "Use to-do items. Deprecated in 13.2.") } """ @@ -24633,7 +25323,7 @@ input ToggleAwardEmojiInput { clientMutationId: String """ - The emoji name + The emoji name. """ name: String! } @@ -24770,7 +25460,7 @@ type TreeEntry implements Entry { path: String! """ - Last commit sha for the entry + Last commit SHA for the entry """ sha: String! @@ -24885,7 +25575,7 @@ type UpdateAlertStatusPayload { issue: Issue """ - The todo after mutation. + The to-do item after mutation. """ todo: Todo } @@ -24950,12 +25640,12 @@ input UpdateBoardInput { clientMutationId: String """ - Whether or not backlog list is hidden + Whether or not backlog list is hidden. """ hideBacklogList: Boolean """ - Whether or not closed list is hidden + Whether or not closed list is hidden. """ hideClosedList: Boolean @@ -25105,7 +25795,7 @@ Autogenerated input type of UpdateContainerExpirationPolicy """ input UpdateContainerExpirationPolicyInput { """ - This container expiration policy schedule + This container expiration policy schedule. """ cadence: ContainerExpirationPolicyCadenceEnum @@ -25115,27 +25805,27 @@ input UpdateContainerExpirationPolicyInput { clientMutationId: String """ - Indicates whether this container expiration policy is enabled + Indicates whether this container expiration policy is enabled. """ enabled: Boolean """ - Number of tags to retain + Number of tags to retain. """ keepN: ContainerExpirationPolicyKeepEnum """ - Tags with names matching this regex pattern will expire + Tags with names matching this regex pattern will expire. """ nameRegex: UntrustedRegexp """ - Tags with names matching this regex pattern will be preserved + Tags with names matching this regex pattern will be preserved. """ nameRegexKeep: UntrustedRegexp """ - Tags older that this will expire + Tags older that this will expire. """ olderThan: ContainerExpirationPolicyOlderThanEnum @@ -25688,6 +26378,13 @@ input UpdateSnippetInput { blobActions: [SnippetBlobActionInputType!] """ + A valid CAPTCHA response value obtained by using the provided captchaSiteKey + with a CAPTCHA API to present a challenge to be solved on the client. Required + to resubmit if the previous operation returned "NeedsCaptchaResponse: true". + """ + captchaResponse: String + + """ A unique identifier for the client performing the mutation. """ clientMutationId: String @@ -25703,6 +26400,13 @@ input UpdateSnippetInput { id: SnippetID! """ + The spam log ID which must be passed along with a valid CAPTCHA response for + the operation to be completed. Required to resubmit if the previous operation + returned "NeedsCaptchaResponse: true". + """ + spamLogId: Int + + """ Title of the snippet. """ title: String @@ -25718,6 +26422,13 @@ Autogenerated return type of UpdateSnippet """ type UpdateSnippetPayload { """ + The CAPTCHA site key which must be used to render a challenge for the user to + solve to obtain a valid captchaResponse value. Included only when an operation + was not completed because "NeedsCaptchaResponse" is true. + """ + captchaSiteKey: String + + """ A unique identifier for the client performing the mutation. """ clientMutationId: String @@ -25728,14 +26439,31 @@ type UpdateSnippetPayload { errors: [String!]! """ + Indicates whether the operation was detected as possible spam and not + completed. If CAPTCHA is enabled, the request must be resubmitted with a valid + CAPTCHA response and spam_log_id included for the operation to be completed. + Included only when an operation was not completed because + "NeedsCaptchaResponse" is true. + """ + needsCaptchaResponse: Boolean + + """ The snippet after mutation. """ snippet: Snippet """ - Indicates whether the operation returns a record detected as spam. + Indicates whether the operation was detected as definite spam. There is no + option to resubmit the request with a CAPTCHA response. """ spam: Boolean + + """ + The spam log ID which must be passed along with a valid CAPTCHA response for + an operation to be completed. Included only when an operation was not + completed because "NeedsCaptchaResponse" is true. + """ + spamLogId: Int } scalar Upload @@ -26177,7 +26905,7 @@ type User { status: UserStatus """ - Todos of the user + To-do items of the user """ todos( """ @@ -26288,7 +27016,7 @@ type UserEdge { } """ -Identifier of User +Identifier of User. """ scalar UserID @@ -26489,7 +27217,7 @@ type VulnerabilitiesCountByDayEdge { } """ -Identifier of Vulnerabilities::ExternalIssueLink +Identifier of Vulnerabilities::ExternalIssueLink. """ scalar VulnerabilitiesExternalIssueLinkID @@ -26513,6 +27241,11 @@ type Vulnerability implements Noteable { description: String """ + Details of the vulnerability + """ + details: [VulnerabilityDetail!]! + + """ Timestamp of when the vulnerability was first detected """ detectedAt: Time! @@ -26781,6 +27514,366 @@ type VulnerabilityConnection { } """ +Represents a vulnerability detail field. The fields with data will depend on the vulnerability detail type +""" +union VulnerabilityDetail = VulnerabilityDetailBase | VulnerabilityDetailBoolean | VulnerabilityDetailCode | VulnerabilityDetailCommit | VulnerabilityDetailDiff | VulnerabilityDetailFileLocation | VulnerabilityDetailInt | VulnerabilityDetailList | VulnerabilityDetailMarkdown | VulnerabilityDetailModuleLocation | VulnerabilityDetailTable | VulnerabilityDetailText | VulnerabilityDetailUrl + +""" +Represents the vulnerability details base +""" +type VulnerabilityDetailBase { + """ + Description of the field. + """ + description: String! + + """ + Name of the field. + """ + fieldName: String + + """ + Name of the field. + """ + name: String! +} + +""" +Represents the vulnerability details boolean value +""" +type VulnerabilityDetailBoolean { + """ + Description of the field. + """ + description: String! + + """ + Name of the field. + """ + fieldName: String + + """ + Name of the field. + """ + name: String! + + """ + Value of the field. + """ + value: Boolean! +} + +""" +Represents the vulnerability details code field +""" +type VulnerabilityDetailCode { + """ + Description of the field. + """ + description: String! + + """ + Name of the field. + """ + fieldName: String + + """ + Language of the code. + """ + lang: String + + """ + Name of the field. + """ + name: String! + + """ + Source code. + """ + value: String! +} + +""" +Represents the vulnerability details commit field +""" +type VulnerabilityDetailCommit { + """ + Description of the field. + """ + description: String! + + """ + Name of the field. + """ + fieldName: String + + """ + Name of the field. + """ + name: String! + + """ + The commit SHA value. + """ + value: String! +} + +""" +Represents the vulnerability details diff field +""" +type VulnerabilityDetailDiff { + """ + Value of the field after the change. + """ + after: String! + + """ + Value of the field before the change. + """ + before: String! + + """ + Description of the field. + """ + description: String! + + """ + Name of the field. + """ + fieldName: String + + """ + Name of the field. + """ + name: String! +} + +""" +Represents the vulnerability details location within a file in the project +""" +type VulnerabilityDetailFileLocation { + """ + Description of the field. + """ + description: String! + + """ + Name of the field. + """ + fieldName: String + + """ + File name. + """ + fileName: String! + + """ + End line number of the file location. + """ + lineEnd: Int! + + """ + Start line number of the file location. + """ + lineStart: Int! + + """ + Name of the field. + """ + name: String! +} + +""" +Represents the vulnerability details integer value +""" +type VulnerabilityDetailInt { + """ + Description of the field. + """ + description: String! + + """ + Name of the field. + """ + fieldName: String + + """ + Name of the field. + """ + name: String! + + """ + Value of the field. + """ + value: Int! +} + +""" +Represents the vulnerability details list value +""" +type VulnerabilityDetailList { + """ + Description of the field. + """ + description: String! + + """ + Name of the field. + """ + fieldName: String + + """ + List of details. + """ + items: [VulnerabilityDetail!]! + + """ + Name of the field. + """ + name: String! +} + +""" +Represents the vulnerability details Markdown field +""" +type VulnerabilityDetailMarkdown { + """ + Description of the field. + """ + description: String! + + """ + Name of the field. + """ + fieldName: String + + """ + Name of the field. + """ + name: String! + + """ + Value of the Markdown field. + """ + value: String! +} + +""" +Represents the vulnerability details location within a file in the project +""" +type VulnerabilityDetailModuleLocation { + """ + Description of the field. + """ + description: String! + + """ + Name of the field. + """ + fieldName: String + + """ + Module name. + """ + moduleName: String! + + """ + Name of the field. + """ + name: String! + + """ + Offset of the module location. + """ + offset: Int! +} + +""" +Represents the vulnerability details table value +""" +type VulnerabilityDetailTable { + """ + Description of the field. + """ + description: String! + + """ + Name of the field. + """ + fieldName: String + + """ + Table headers. + """ + headers: [VulnerabilityDetail!]! + + """ + Name of the field. + """ + name: String! + + """ + Table rows. + """ + rows: [VulnerabilityDetail!]! +} + +""" +Represents the vulnerability details text field +""" +type VulnerabilityDetailText { + """ + Description of the field. + """ + description: String! + + """ + Name of the field. + """ + fieldName: String + + """ + Name of the field. + """ + name: String! + + """ + Value of the text field. + """ + value: String! +} + +""" +Represents the vulnerability details URL field +""" +type VulnerabilityDetailUrl { + """ + Description of the field. + """ + description: String! + + """ + Name of the field. + """ + fieldName: String + + """ + Href of the URL. + """ + href: String! + + """ + Name of the field. + """ + name: String! + + """ + Text of the URL. + """ + text: String +} + +""" Autogenerated input type of VulnerabilityDismiss """ input VulnerabilityDismissInput { @@ -27032,7 +28125,7 @@ enum VulnerabilityGrade { } """ -Identifier of Vulnerability +Identifier of Vulnerability. """ scalar VulnerabilityID @@ -27154,6 +28247,11 @@ Represents the location of a vulnerability found by a Coverage Fuzzing scan """ type VulnerabilityLocationCoverageFuzzing { """ + Blob path to the vulnerable file + """ + blobPath: String + + """ Number of the last relevant line in the vulnerable file """ endLine: String @@ -27209,6 +28307,11 @@ Represents the location of a vulnerability found by a dependency security scan """ type VulnerabilityLocationDependencyScanning { """ + Blob path to the vulnerable file + """ + blobPath: String + + """ Dependency containing the vulnerability """ dependency: VulnerableDependency @@ -27224,6 +28327,11 @@ Represents the location of a vulnerability found by a SAST scan """ type VulnerabilityLocationSast { """ + Blob path to the vulnerable file + """ + blobPath: String + + """ Number of the last relevant line in the vulnerable file """ endLine: String @@ -27254,6 +28362,11 @@ Represents the location of a vulnerability found by a secret detection scan """ type VulnerabilityLocationSecretDetection { """ + Blob path to the vulnerable file + """ + blobPath: String + + """ Number of the last relevant line in the vulnerable file """ endLine: String diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json index 138530abb17..47855e1cf98 100644 --- a/doc/api/graphql/reference/gitlab_schema.json +++ b/doc/api/graphql/reference/gitlab_schema.json @@ -16,7 +16,7 @@ "fields": [ { "name": "integerValue", - "description": "Integer representation of access level", + "description": "Integer representation of access level.", "args": [ ], @@ -30,7 +30,7 @@ }, { "name": "stringValue", - "description": "String representation of access level", + "description": "String representation of access level.", "args": [ ], @@ -119,7 +119,7 @@ }, { "name": "name", - "description": "The emoji name", + "description": "The emoji name.", "type": { "kind": "NON_NULL", "name": null, @@ -504,7 +504,7 @@ "fields": [ { "name": "assignees", - "description": "Assignees of the alert", + "description": "Assignees of the alert.", "args": [ { "name": "after", @@ -557,7 +557,7 @@ }, { "name": "createdAt", - "description": "Timestamp the alert was created", + "description": "Timestamp the alert was created.", "args": [ ], @@ -571,7 +571,7 @@ }, { "name": "description", - "description": "Description of the alert", + "description": "Description of the alert.", "args": [ ], @@ -585,7 +585,7 @@ }, { "name": "details", - "description": "Alert details", + "description": "Alert details.", "args": [ ], @@ -599,7 +599,7 @@ }, { "name": "detailsUrl", - "description": "The URL of the alert detail page", + "description": "The URL of the alert detail page.", "args": [ ], @@ -674,7 +674,7 @@ }, { "name": "endedAt", - "description": "Timestamp the alert ended", + "description": "Timestamp the alert ended.", "args": [ ], @@ -688,7 +688,7 @@ }, { "name": "environment", - "description": "Environment for the alert", + "description": "Environment for the alert.", "args": [ ], @@ -702,7 +702,7 @@ }, { "name": "eventCount", - "description": "Number of events of this alert", + "description": "Number of events of this alert.", "args": [ ], @@ -716,7 +716,7 @@ }, { "name": "hosts", - "description": "List of hosts the alert came from", + "description": "List of hosts the alert came from.", "args": [ ], @@ -738,7 +738,7 @@ }, { "name": "iid", - "description": "Internal ID of the alert", + "description": "Internal ID of the alert.", "args": [ ], @@ -756,7 +756,7 @@ }, { "name": "issueIid", - "description": "Internal ID of the GitLab issue attached to the alert", + "description": "Internal ID of the GitLab issue attached to the alert.", "args": [ ], @@ -770,7 +770,7 @@ }, { "name": "metricsDashboardUrl", - "description": "URL for metrics embed for the alert", + "description": "URL for metrics embed for the alert.", "args": [ ], @@ -784,7 +784,7 @@ }, { "name": "monitoringTool", - "description": "Monitoring tool the alert came from", + "description": "Monitoring tool the alert came from.", "args": [ ], @@ -855,7 +855,7 @@ }, { "name": "prometheusAlert", - "description": "The alert condition for Prometheus", + "description": "The alert condition for Prometheus.", "args": [ ], @@ -869,7 +869,7 @@ }, { "name": "runbook", - "description": "Runbook for the alert as defined in alert details", + "description": "Runbook for the alert as defined in alert details.", "args": [ ], @@ -883,7 +883,7 @@ }, { "name": "service", - "description": "Service the alert came from", + "description": "Service the alert came from.", "args": [ ], @@ -897,7 +897,7 @@ }, { "name": "severity", - "description": "Severity of the alert", + "description": "Severity of the alert.", "args": [ ], @@ -911,7 +911,7 @@ }, { "name": "startedAt", - "description": "Timestamp the alert was raised", + "description": "Timestamp the alert was raised.", "args": [ ], @@ -925,7 +925,7 @@ }, { "name": "status", - "description": "Status of the alert", + "description": "Status of the alert.", "args": [ ], @@ -939,7 +939,7 @@ }, { "name": "title", - "description": "Title of the alert", + "description": "Title of the alert.", "args": [ ], @@ -953,7 +953,7 @@ }, { "name": "todos", - "description": "Todos of the current user for the alert", + "description": "To-do items of the current user for the alert.", "args": [ { "name": "action", @@ -1114,7 +1114,7 @@ }, { "name": "updatedAt", - "description": "Timestamp the alert was last updated", + "description": "Timestamp the alert was last updated.", "args": [ ], @@ -1414,7 +1414,7 @@ }, { "name": "all", - "description": "Total number of alerts for the project", + "description": "Total number of alerts for the project.", "args": [ ], @@ -1442,7 +1442,7 @@ }, { "name": "open", - "description": "Number of alerts with status TRIGGERED or ACKNOWLEDGED for the project", + "description": "Number of alerts with status TRIGGERED or ACKNOWLEDGED for the project.", "args": [ ], @@ -1520,7 +1520,7 @@ "fields": [ { "name": "active", - "description": "Whether the endpoint is currently accepting alerts", + "description": "Whether the endpoint is currently accepting alerts.", "args": [ ], @@ -1534,7 +1534,7 @@ }, { "name": "apiUrl", - "description": "URL at which Prometheus metrics can be queried to populate the metrics dashboard", + "description": "URL at which Prometheus metrics can be queried to populate the metrics dashboard.", "args": [ ], @@ -1548,7 +1548,7 @@ }, { "name": "id", - "description": "ID of the integration", + "description": "ID of the integration.", "args": [ ], @@ -1566,7 +1566,7 @@ }, { "name": "name", - "description": "Name of the integration", + "description": "Name of the integration.", "args": [ ], @@ -1580,7 +1580,7 @@ }, { "name": "token", - "description": "Token used to authenticate alert notification requests", + "description": "Token used to authenticate alert notification requests.", "args": [ ], @@ -1594,7 +1594,7 @@ }, { "name": "type", - "description": "Type of integration", + "description": "Type of integration.", "args": [ ], @@ -1612,7 +1612,7 @@ }, { "name": "url", - "description": "Endpoint which accepts alert notifications", + "description": "Endpoint which accepts alert notifications.", "args": [ ], @@ -1639,7 +1639,7 @@ { "kind": "SCALAR", "name": "AlertManagementHttpIntegrationID", - "description": "Identifier of AlertManagement::HttpIntegration", + "description": "Identifier of AlertManagement::HttpIntegration.", "fields": null, "inputFields": null, "interfaces": null, @@ -1653,7 +1653,7 @@ "fields": [ { "name": "active", - "description": "Whether the endpoint is currently accepting alerts", + "description": "Whether the endpoint is currently accepting alerts.", "args": [ ], @@ -1667,7 +1667,7 @@ }, { "name": "apiUrl", - "description": "URL at which Prometheus metrics can be queried to populate the metrics dashboard", + "description": "URL at which Prometheus metrics can be queried to populate the metrics dashboard.", "args": [ ], @@ -1681,7 +1681,7 @@ }, { "name": "id", - "description": "ID of the integration", + "description": "ID of the integration.", "args": [ ], @@ -1699,7 +1699,7 @@ }, { "name": "name", - "description": "Name of the integration", + "description": "Name of the integration.", "args": [ ], @@ -1713,7 +1713,7 @@ }, { "name": "token", - "description": "Token used to authenticate alert notification requests", + "description": "Token used to authenticate alert notification requests.", "args": [ ], @@ -1727,7 +1727,7 @@ }, { "name": "type", - "description": "Type of integration", + "description": "Type of integration.", "args": [ ], @@ -1745,7 +1745,7 @@ }, { "name": "url", - "description": "Endpoint which accepts alert notifications", + "description": "Endpoint which accepts alert notifications.", "args": [ ], @@ -1910,6 +1910,69 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "AlertManagementPayloadAlertField", + "description": "Parsed field from an alert used for custom mappings", + "fields": [ + { + "name": "label", + "description": "Human-readable label of the payload path.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "path", + "description": "Path to value inside payload JSON.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "type", + "description": "Type of the parsed value.", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "AlertManagementPayloadAlertFieldType", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "INPUT_OBJECT", "name": "AlertManagementPayloadAlertFieldInput", "description": "Field that are available while modifying the custom mapping attributes for an HTTP integration", @@ -2087,7 +2150,7 @@ "fields": [ { "name": "active", - "description": "Whether the endpoint is currently accepting alerts", + "description": "Whether the endpoint is currently accepting alerts.", "args": [ ], @@ -2101,7 +2164,7 @@ }, { "name": "apiUrl", - "description": "URL at which Prometheus metrics can be queried to populate the metrics dashboard", + "description": "URL at which Prometheus metrics can be queried to populate the metrics dashboard.", "args": [ ], @@ -2115,7 +2178,7 @@ }, { "name": "id", - "description": "ID of the integration", + "description": "ID of the integration.", "args": [ ], @@ -2133,7 +2196,7 @@ }, { "name": "name", - "description": "Name of the integration", + "description": "Name of the integration.", "args": [ ], @@ -2147,7 +2210,7 @@ }, { "name": "token", - "description": "Token used to authenticate alert notification requests", + "description": "Token used to authenticate alert notification requests.", "args": [ ], @@ -2161,7 +2224,7 @@ }, { "name": "type", - "description": "Type of integration", + "description": "Type of integration.", "args": [ ], @@ -2179,7 +2242,7 @@ }, { "name": "url", - "description": "Endpoint which accepts alert notifications", + "description": "Endpoint which accepts alert notifications.", "args": [ ], @@ -2441,7 +2504,7 @@ }, { "name": "todo", - "description": "The todo after mutation.", + "description": "The to-do item after mutation.", "args": [ ], @@ -2585,7 +2648,7 @@ }, { "name": "todo", - "description": "The todo after mutation.", + "description": "The to-do item after mutation.", "args": [ ], @@ -2608,7 +2671,7 @@ { "kind": "SCALAR", "name": "AnalyticsDevopsAdoptionSegmentID", - "description": "Identifier of Analytics::DevopsAdoption::Segment", + "description": "Identifier of Analytics::DevopsAdoption::Segment.", "fields": null, "inputFields": null, "interfaces": null, @@ -2645,7 +2708,7 @@ "fields": [ { "name": "description", - "description": "The emoji description", + "description": "The emoji description.", "args": [ ], @@ -2663,7 +2726,7 @@ }, { "name": "emoji", - "description": "The emoji as an icon", + "description": "The emoji as an icon.", "args": [ ], @@ -2681,7 +2744,7 @@ }, { "name": "name", - "description": "The emoji name", + "description": "The emoji name.", "args": [ ], @@ -2699,7 +2762,7 @@ }, { "name": "unicode", - "description": "The emoji in unicode", + "description": "The emoji in Unicode.", "args": [ ], @@ -2717,7 +2780,7 @@ }, { "name": "unicodeVersion", - "description": "The unicode version for this emoji", + "description": "The Unicode version for this emoji.", "args": [ ], @@ -2735,7 +2798,7 @@ }, { "name": "user", - "description": "The user who awarded the emoji", + "description": "The user who awarded the emoji.", "args": [ ], @@ -2781,7 +2844,7 @@ }, { "name": "name", - "description": "The emoji name", + "description": "The emoji name.", "type": { "kind": "NON_NULL", "name": null, @@ -2876,6 +2939,118 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "AwardEmojiConnection", + "description": "The connection type for AwardEmoji.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "AwardEmojiEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "AwardEmoji", + "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": "AwardEmojiEdge", + "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": "AwardEmoji", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "INPUT_OBJECT", "name": "AwardEmojiRemoveInput", "description": "Autogenerated input type of AwardEmojiRemove", @@ -2897,7 +3072,7 @@ }, { "name": "name", - "description": "The emoji name", + "description": "The emoji name.", "type": { "kind": "NON_NULL", "name": null, @@ -3013,7 +3188,7 @@ }, { "name": "name", - "description": "The emoji name", + "description": "The emoji name.", "type": { "kind": "NON_NULL", "name": null, @@ -3128,7 +3303,7 @@ { "kind": "SCALAR", "name": "AwardableID", - "description": "Identifier of Awardable", + "description": "Identifier of Awardable.", "fields": null, "inputFields": null, "interfaces": null, @@ -3297,7 +3472,7 @@ }, { "name": "sha", - "description": "Last commit sha for the entry", + "description": "Last commit SHA for the entry", "args": [ ], @@ -3596,7 +3771,7 @@ }, { "name": "hideBacklogList", - "description": "Whether or not backlog list is hidden", + "description": "Whether or not backlog list is hidden.", "args": [ ], @@ -3610,7 +3785,7 @@ }, { "name": "hideClosedList", - "description": "Whether or not closed list is hidden", + "description": "Whether or not closed list is hidden.", "args": [ ], @@ -3624,7 +3799,7 @@ }, { "name": "id", - "description": "ID (global ID) of the board", + "description": "ID (global ID) of the board.", "args": [ ], @@ -3709,7 +3884,7 @@ }, { "name": "lists", - "description": "Lists of the board", + "description": "Lists of the board.", "args": [ { "name": "id", @@ -3796,7 +3971,7 @@ }, { "name": "name", - "description": "Name of the board", + "description": "Name of the board.", "args": [ ], @@ -3985,7 +4160,7 @@ "fields": [ { "name": "author", - "description": "Author of the epic", + "description": "Author of the epic.", "args": [ ], @@ -4002,8 +4177,61 @@ "deprecationReason": null }, { + "name": "awardEmoji", + "description": "A list of award emojis associated with the epic.", + "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": "AwardEmojiConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "children", - "description": "Children (sub-epics) of the epic", + "description": "Children (sub-epics) of the epic.", "args": [ { "name": "startDate", @@ -4212,7 +4440,7 @@ }, { "name": "closedAt", - "description": "Timestamp of when the epic was closed", + "description": "Timestamp of when the epic was closed.", "args": [ ], @@ -4226,7 +4454,7 @@ }, { "name": "confidential", - "description": "Indicates if the epic is confidential", + "description": "Indicates if the epic is confidential.", "args": [ ], @@ -4240,7 +4468,7 @@ }, { "name": "createdAt", - "description": "Timestamp of when the epic was created", + "description": "Timestamp of when the epic was created.", "args": [ ], @@ -4254,7 +4482,7 @@ }, { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -4298,7 +4526,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -4321,7 +4549,7 @@ }, { "name": "descendantCounts", - "description": "Number of open and closed descendant epics and issues", + "description": "Number of open and closed descendant epics and issues.", "args": [ ], @@ -4335,7 +4563,7 @@ }, { "name": "descendantWeightSum", - "description": "Total weight of open and closed issues in the epic and its descendants", + "description": "Total weight of open and closed issues in the epic and its descendants.", "args": [ ], @@ -4349,7 +4577,7 @@ }, { "name": "description", - "description": "Description of the epic", + "description": "Description of the epic.", "args": [ ], @@ -4420,7 +4648,7 @@ }, { "name": "downvotes", - "description": "Number of downvotes the epic has received", + "description": "Number of downvotes the epic has received.", "args": [ ], @@ -4438,7 +4666,7 @@ }, { "name": "dueDate", - "description": "Due date of the epic", + "description": "Due date of the epic.", "args": [ ], @@ -4452,7 +4680,7 @@ }, { "name": "dueDateFixed", - "description": "Fixed due date of the epic", + "description": "Fixed due date of the epic.", "args": [ ], @@ -4466,7 +4694,7 @@ }, { "name": "dueDateFromMilestones", - "description": "Inherited due date of the epic from milestones", + "description": "Inherited due date of the epic from milestones.", "args": [ ], @@ -4480,7 +4708,7 @@ }, { "name": "dueDateIsFixed", - "description": "Indicates if the due date has been manually set", + "description": "Indicates if the due date has been manually set.", "args": [ ], @@ -4494,7 +4722,7 @@ }, { "name": "group", - "description": "Group to which the epic belongs", + "description": "Group to which the epic belongs.", "args": [ ], @@ -4512,7 +4740,7 @@ }, { "name": "hasChildren", - "description": "Indicates if the epic has children", + "description": "Indicates if the epic has children.", "args": [ ], @@ -4530,7 +4758,7 @@ }, { "name": "hasIssues", - "description": "Indicates if the epic has direct issues", + "description": "Indicates if the epic has direct issues.", "args": [ ], @@ -4548,7 +4776,7 @@ }, { "name": "hasParent", - "description": "Indicates if the epic has a parent epic", + "description": "Indicates if the epic has a parent epic.", "args": [ ], @@ -4566,7 +4794,7 @@ }, { "name": "healthStatus", - "description": "Current health status of the epic", + "description": "Current health status of the epic.", "args": [ ], @@ -4580,7 +4808,7 @@ }, { "name": "id", - "description": "ID of the epic", + "description": "ID of the epic.", "args": [ ], @@ -4598,7 +4826,7 @@ }, { "name": "iid", - "description": "Internal ID of the epic", + "description": "Internal ID of the epic.", "args": [ ], @@ -4616,7 +4844,7 @@ }, { "name": "issues", - "description": "A list of issues associated with the epic", + "description": "A list of issues associated with the epic.", "args": [ { "name": "after", @@ -4669,7 +4897,7 @@ }, { "name": "labels", - "description": "Labels assigned to the epic", + "description": "Labels assigned to the epic.", "args": [ { "name": "after", @@ -4779,7 +5007,7 @@ }, { "name": "parent", - "description": "Parent epic of the epic", + "description": "Parent epic of the epic.", "args": [ ], @@ -4793,7 +5021,7 @@ }, { "name": "participants", - "description": "List of participants for the epic", + "description": "List of participants for the epic.", "args": [ { "name": "after", @@ -4846,11 +5074,11 @@ }, { "name": "reference", - "description": "Internal reference of the epic. Returned in shortened format by default", + "description": "Internal reference of the epic. Returned in shortened format by default.", "args": [ { "name": "full", - "description": "Indicates if the reference should be returned in full", + "description": "Indicates if the reference should be returned in full.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -4873,7 +5101,7 @@ }, { "name": "relationPath", - "description": "URI path of the epic-issue relationship", + "description": "URI path of the epic-issue relationship.", "args": [ ], @@ -4887,7 +5115,7 @@ }, { "name": "relativePosition", - "description": "The relative position of the epic in the epic tree", + "description": "The relative position of the epic in the epic tree.", "args": [ ], @@ -4901,7 +5129,7 @@ }, { "name": "startDate", - "description": "Start date of the epic", + "description": "Start date of the epic.", "args": [ ], @@ -4915,7 +5143,7 @@ }, { "name": "startDateFixed", - "description": "Fixed start date of the epic", + "description": "Fixed start date of the epic.", "args": [ ], @@ -4929,7 +5157,7 @@ }, { "name": "startDateFromMilestones", - "description": "Inherited start date of the epic from milestones", + "description": "Inherited start date of the epic from milestones.", "args": [ ], @@ -4943,7 +5171,7 @@ }, { "name": "startDateIsFixed", - "description": "Indicates if the start date has been manually set", + "description": "Indicates if the start date has been manually set.", "args": [ ], @@ -4957,7 +5185,7 @@ }, { "name": "state", - "description": "State of the epic", + "description": "State of the epic.", "args": [ ], @@ -4975,7 +5203,7 @@ }, { "name": "subscribed", - "description": "Indicates the currently logged in user is subscribed to the epic", + "description": "Indicates the currently logged in user is subscribed to the epic.", "args": [ ], @@ -4993,7 +5221,7 @@ }, { "name": "title", - "description": "Title of the epic", + "description": "Title of the epic.", "args": [ ], @@ -5007,7 +5235,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of when the epic was updated", + "description": "Timestamp of when the epic was updated.", "args": [ ], @@ -5021,7 +5249,7 @@ }, { "name": "upvotes", - "description": "Number of upvotes the epic has received", + "description": "Number of upvotes the epic has received.", "args": [ ], @@ -5039,7 +5267,7 @@ }, { "name": "userDiscussionsCount", - "description": "Number of user discussions in the epic", + "description": "Number of user discussions in the epic.", "args": [ ], @@ -5057,7 +5285,7 @@ }, { "name": "userNotesCount", - "description": "Number of user notes of the epic", + "description": "Number of user notes of the epic.", "args": [ ], @@ -5107,7 +5335,7 @@ }, { "name": "webPath", - "description": "Web path of the epic", + "description": "Web path of the epic.", "args": [ ], @@ -5125,7 +5353,7 @@ }, { "name": "webUrl", - "description": "Web URL of the epic", + "description": "Web URL of the epic.", "args": [ ], @@ -5304,7 +5532,7 @@ { "kind": "SCALAR", "name": "BoardID", - "description": "Identifier of Board", + "description": "Identifier of Board.", "fields": null, "inputFields": null, "interfaces": null, @@ -5319,7 +5547,7 @@ "inputFields": [ { "name": "labelName", - "description": "Filter by label name", + "description": "Filter by label name.", "type": { "kind": "LIST", "name": null, @@ -5333,7 +5561,7 @@ }, { "name": "milestoneTitle", - "description": "Filter by milestone title", + "description": "Filter by milestone title.", "type": { "kind": "SCALAR", "name": "String", @@ -5343,7 +5571,7 @@ }, { "name": "assigneeUsername", - "description": "Filter by assignee username", + "description": "Filter by assignee username.", "type": { "kind": "LIST", "name": null, @@ -5357,7 +5585,7 @@ }, { "name": "authorUsername", - "description": "Filter by author username", + "description": "Filter by author username.", "type": { "kind": "SCALAR", "name": "String", @@ -5367,7 +5595,7 @@ }, { "name": "releaseTag", - "description": "Filter by release tag", + "description": "Filter by release tag.", "type": { "kind": "SCALAR", "name": "String", @@ -5377,7 +5605,7 @@ }, { "name": "myReactionEmoji", - "description": "Filter by reaction emoji", + "description": "Filter by reaction emoji.", "type": { "kind": "SCALAR", "name": "String", @@ -5417,7 +5645,7 @@ }, { "name": "not", - "description": "List of negated params. Warning: this argument is experimental and a subject to change in future", + "description": "List of negated params. Warning: this argument is experimental and a subject to change in future.", "type": { "kind": "INPUT_OBJECT", "name": "NegatedBoardIssueInput", @@ -5427,7 +5655,7 @@ }, { "name": "search", - "description": "Search query for issue title or description", + "description": "Search query for issue title or description.", "type": { "kind": "SCALAR", "name": "String", @@ -5481,7 +5709,7 @@ }, { "name": "collapsed", - "description": "Indicates if list is collapsed for this user", + "description": "Indicates if list is collapsed for this user.", "args": [ ], @@ -5495,7 +5723,7 @@ }, { "name": "id", - "description": "ID (global ID) of the list", + "description": "ID (global ID) of the list.", "args": [ ], @@ -5513,7 +5741,7 @@ }, { "name": "issues", - "description": "Board issues", + "description": "Board issues.", "args": [ { "name": "filters", @@ -5576,7 +5804,7 @@ }, { "name": "issuesCount", - "description": "Count of issues in the list", + "description": "Count of issues in the list.", "args": [ ], @@ -5604,7 +5832,7 @@ }, { "name": "label", - "description": "Label of the list", + "description": "Label of the list.", "args": [ ], @@ -5632,7 +5860,7 @@ }, { "name": "listType", - "description": "Type of the list", + "description": "Type of the list.", "args": [ ], @@ -5692,7 +5920,7 @@ }, { "name": "position", - "description": "Position of list within the board", + "description": "Position of list within the board.", "args": [ ], @@ -5706,7 +5934,7 @@ }, { "name": "title", - "description": "Title of the list", + "description": "Title of the list.", "args": [ ], @@ -6143,7 +6371,7 @@ { "kind": "SCALAR", "name": "BoardsEpicBoardID", - "description": "Identifier of Boards::EpicBoard", + "description": "Identifier of Boards::EpicBoard.", "fields": null, "inputFields": null, "interfaces": null, @@ -6153,7 +6381,7 @@ { "kind": "SCALAR", "name": "BoardsEpicListID", - "description": "Identifier of Boards::EpicList", + "description": "Identifier of Boards::EpicList.", "fields": null, "inputFields": null, "interfaces": null, @@ -6177,7 +6405,7 @@ "fields": [ { "name": "commit", - "description": "Commit for the branch", + "description": "Commit for the branch.", "args": [ ], @@ -6191,7 +6419,7 @@ }, { "name": "name", - "description": "Name of the branch", + "description": "Name of the branch.", "args": [ ], @@ -6562,7 +6790,7 @@ "fields": [ { "name": "errors", - "description": "Linting errors", + "description": "Linting errors.", "args": [ ], @@ -6584,7 +6812,7 @@ }, { "name": "mergedYaml", - "description": "Merged CI config YAML", + "description": "Merged CI configuration YAML.", "args": [ ], @@ -6598,7 +6826,7 @@ }, { "name": "stages", - "description": "Stages of the pipeline", + "description": "Stages of the pipeline.", "args": [ { "name": "after", @@ -6651,7 +6879,7 @@ }, { "name": "status", - "description": "Status of linting, can be either valid or invalid", + "description": "Status of linting, can be either valid or invalid.", "args": [ ], @@ -6678,7 +6906,7 @@ "fields": [ { "name": "jobs", - "description": "Jobs in group", + "description": "Jobs in group.", "args": [ { "name": "after", @@ -6731,7 +6959,7 @@ }, { "name": "name", - "description": "Name of the job group", + "description": "Name of the job group.", "args": [ ], @@ -6745,7 +6973,7 @@ }, { "name": "size", - "description": "Size of the job group", + "description": "Size of the job group.", "args": [ ], @@ -7297,7 +7525,7 @@ "fields": [ { "name": "name", - "description": "Name of the need", + "description": "Name of the need.", "args": [ ], @@ -7436,7 +7664,7 @@ "fields": [ { "name": "groups", - "description": "Groups of jobs for the stage", + "description": "Groups of jobs for the stage.", "args": [ { "name": "after", @@ -7489,7 +7717,7 @@ }, { "name": "name", - "description": "Name of the stage", + "description": "Name of the stage.", "args": [ ], @@ -7651,7 +7879,7 @@ "fields": [ { "name": "detailedStatus", - "description": "Detailed status of the group", + "description": "Detailed status of the group.", "args": [ ], @@ -7665,7 +7893,7 @@ }, { "name": "jobs", - "description": "Jobs in group", + "description": "Jobs in group.", "args": [ { "name": "after", @@ -7718,7 +7946,7 @@ }, { "name": "name", - "description": "Name of the job group", + "description": "Name of the job group.", "args": [ ], @@ -7732,7 +7960,7 @@ }, { "name": "size", - "description": "Size of the group", + "description": "Size of the group.", "args": [ ], @@ -7871,7 +8099,7 @@ "fields": [ { "name": "artifacts", - "description": "Artifacts generated by the job", + "description": "Artifacts generated by the job.", "args": [ { "name": "after", @@ -7924,7 +8152,7 @@ }, { "name": "detailedStatus", - "description": "Detailed status of the job", + "description": "Detailed status of the job.", "args": [ ], @@ -7938,7 +8166,7 @@ }, { "name": "name", - "description": "Name of the job", + "description": "Name of the job.", "args": [ ], @@ -7952,7 +8180,7 @@ }, { "name": "needs", - "description": "References to builds that must complete before the jobs run", + "description": "References to builds that must complete before the jobs run.", "args": [ { "name": "after", @@ -8005,7 +8233,7 @@ }, { "name": "pipeline", - "description": "Pipeline the job belongs to", + "description": "Pipeline the job belongs to.", "args": [ ], @@ -8019,7 +8247,7 @@ }, { "name": "scheduledAt", - "description": "Schedule for the build", + "description": "Schedule for the build.", "args": [ ], @@ -8046,7 +8274,7 @@ "fields": [ { "name": "downloadPath", - "description": "URL for downloading the artifact's file", + "description": "URL for downloading the artifact's file.", "args": [ ], @@ -8060,7 +8288,7 @@ }, { "name": "fileType", - "description": "File type of the artifact", + "description": "File type of the artifact.", "args": [ ], @@ -8307,7 +8535,7 @@ { "kind": "SCALAR", "name": "CiPipelineID", - "description": "Identifier of Ci::Pipeline", + "description": "Identifier of Ci::Pipeline.", "fields": null, "inputFields": null, "interfaces": null, @@ -8321,7 +8549,7 @@ "fields": [ { "name": "detailedStatus", - "description": "Detailed status of the stage", + "description": "Detailed status of the stage.", "args": [ ], @@ -8335,7 +8563,7 @@ }, { "name": "groups", - "description": "Group of jobs for the stage", + "description": "Group of jobs for the stage.", "args": [ { "name": "after", @@ -8388,7 +8616,7 @@ }, { "name": "name", - "description": "Name of the stage", + "description": "Name of the stage.", "args": [ ], @@ -8667,7 +8895,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -8944,7 +9172,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -9274,7 +9502,7 @@ { "kind": "SCALAR", "name": "ClustersAgentID", - "description": "Identifier of Clusters::Agent", + "description": "Identifier of Clusters::Agent.", "fields": null, "inputFields": null, "interfaces": null, @@ -9284,7 +9512,7 @@ { "kind": "SCALAR", "name": "ClustersAgentTokenID", - "description": "Identifier of Clusters::AgentToken", + "description": "Identifier of Clusters::AgentToken.", "fields": null, "inputFields": null, "interfaces": null, @@ -9294,7 +9522,7 @@ { "kind": "SCALAR", "name": "ClustersClusterID", - "description": "Identifier of Clusters::Cluster", + "description": "Identifier of Clusters::Cluster.", "fields": null, "inputFields": null, "interfaces": null, @@ -9548,7 +9776,7 @@ "fields": [ { "name": "author", - "description": "Author of the commit", + "description": "Author of the commit.", "args": [ ], @@ -9562,7 +9790,7 @@ }, { "name": "authorGravatar", - "description": "Commit authors gravatar", + "description": "Commit authors gravatar.", "args": [ ], @@ -9576,7 +9804,7 @@ }, { "name": "authorName", - "description": "Commit authors name", + "description": "Commit authors name.", "args": [ ], @@ -9590,7 +9818,7 @@ }, { "name": "authoredDate", - "description": "Timestamp of when the commit was authored", + "description": "Timestamp of when the commit was authored.", "args": [ ], @@ -9604,7 +9832,7 @@ }, { "name": "description", - "description": "Description of the commit message", + "description": "Description of the commit message.", "args": [ ], @@ -9632,7 +9860,7 @@ }, { "name": "id", - "description": "ID (global ID) of the commit", + "description": "ID (global ID) of the commit.", "args": [ ], @@ -9650,7 +9878,7 @@ }, { "name": "message", - "description": "Raw commit message", + "description": "Raw commit message.", "args": [ ], @@ -9664,7 +9892,7 @@ }, { "name": "pipelines", - "description": "Pipelines of the commit ordered latest first", + "description": "Pipelines of the commit ordered latest first.", "args": [ { "name": "status", @@ -9747,7 +9975,7 @@ }, { "name": "sha", - "description": "SHA1 ID of the commit", + "description": "SHA1 ID of the commit.", "args": [ ], @@ -9765,7 +9993,7 @@ }, { "name": "shortId", - "description": "Short SHA1 ID of the commit", + "description": "Short SHA1 ID of the commit.", "args": [ ], @@ -9783,7 +10011,7 @@ }, { "name": "signatureHtml", - "description": "Rendered HTML of the commit signature", + "description": "Rendered HTML of the commit signature.", "args": [ ], @@ -9797,7 +10025,7 @@ }, { "name": "title", - "description": "Title of the commit message", + "description": "Title of the commit message.", "args": [ ], @@ -9825,7 +10053,7 @@ }, { "name": "webPath", - "description": "Web path of the commit", + "description": "Web path of the commit.", "args": [ ], @@ -9843,7 +10071,7 @@ }, { "name": "webUrl", - "description": "Web URL of the commit", + "description": "Web URL of the commit.", "args": [ ], @@ -9875,7 +10103,7 @@ "inputFields": [ { "name": "action", - "description": "The action to perform, create, delete, move, update, chmod", + "description": "The action to perform, create, delete, move, update, chmod.", "type": { "kind": "NON_NULL", "name": null, @@ -9889,7 +10117,7 @@ }, { "name": "filePath", - "description": "Full path to the file", + "description": "Full path to the file.", "type": { "kind": "NON_NULL", "name": null, @@ -9903,7 +10131,7 @@ }, { "name": "content", - "description": "Content of the file", + "description": "Content of the file.", "type": { "kind": "SCALAR", "name": "String", @@ -9913,7 +10141,7 @@ }, { "name": "previousPath", - "description": "Original full path to the file being moved", + "description": "Original full path to the file being moved.", "type": { "kind": "SCALAR", "name": "String", @@ -9923,7 +10151,7 @@ }, { "name": "lastCommitId", - "description": "Last known file commit ID", + "description": "Last known file commit ID.", "type": { "kind": "SCALAR", "name": "String", @@ -9933,7 +10161,7 @@ }, { "name": "executeFilemode", - "description": "Enables/disables the execute flag on the file", + "description": "Enables/disables the execute flag on the file.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -9943,7 +10171,7 @@ }, { "name": "encoding", - "description": "Encoding of the file. Default is text", + "description": "Encoding of the file. Default is text.", "type": { "kind": "ENUM", "name": "CommitEncoding", @@ -10110,7 +10338,7 @@ }, { "name": "message", - "description": "Raw commit message", + "description": "Raw commit message.", "type": { "kind": "NON_NULL", "name": null, @@ -10370,6 +10598,20 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "pipelineConfigurationFullPath", + "description": "Full path of the compliance pipeline configuration stored in a project repository, such as `.gitlab/compliance/soc2/.gitlab-ci.yml`.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -10526,6 +10768,16 @@ "ofType": null }, "defaultValue": null + }, + { + "name": "pipelineConfigurationFullPath", + "description": "Full path of the compliance pipeline configuration stored in a project repository, such as `.gitlab/compliance/soc2/.gitlab-ci.yml`.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null } ], "interfaces": null, @@ -10535,7 +10787,7 @@ { "kind": "SCALAR", "name": "ComplianceManagementFrameworkID", - "description": "Identifier of ComplianceManagement::Framework", + "description": "Identifier of ComplianceManagement::Framework.", "fields": null, "inputFields": null, "interfaces": null, @@ -10543,6 +10795,55 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "ComposerMetadata", + "description": "Composer metadata", + "fields": [ + { + "name": "composerJson", + "description": "Data of the Composer JSON file.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PackageComposerJsonType", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "targetSha", + "description": "Target SHA of the package.", + "args": [ + + ], + "type": { + "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": "ConfigureSastInput", "description": "Autogenerated input type of ConfigureSast", @@ -10683,7 +10984,7 @@ "fields": [ { "name": "cadence", - "description": "This container expiration policy schedule", + "description": "This container expiration policy schedule.", "args": [ ], @@ -10701,7 +11002,7 @@ }, { "name": "createdAt", - "description": "Timestamp of when the container expiration policy was created", + "description": "Timestamp of when the container expiration policy was created.", "args": [ ], @@ -10719,7 +11020,7 @@ }, { "name": "enabled", - "description": "Indicates whether this container expiration policy is enabled", + "description": "Indicates whether this container expiration policy is enabled.", "args": [ ], @@ -10737,7 +11038,7 @@ }, { "name": "keepN", - "description": "Number of tags to retain", + "description": "Number of tags to retain.", "args": [ ], @@ -10751,7 +11052,7 @@ }, { "name": "nameRegex", - "description": "Tags with names matching this regex pattern will expire", + "description": "Tags with names matching this regex pattern will expire.", "args": [ ], @@ -10765,7 +11066,7 @@ }, { "name": "nameRegexKeep", - "description": "Tags with names matching this regex pattern will be preserved", + "description": "Tags with names matching this regex pattern will be preserved.", "args": [ ], @@ -10779,7 +11080,7 @@ }, { "name": "nextRunAt", - "description": "Next time that this container expiration policy will get executed", + "description": "Next time that this container expiration policy will get executed.", "args": [ ], @@ -10793,7 +11094,7 @@ }, { "name": "olderThan", - "description": "Tags older that this will expire", + "description": "Tags older that this will expire.", "args": [ ], @@ -10807,7 +11108,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of when the container expiration policy was updated", + "description": "Timestamp of when the container expiration policy was updated.", "args": [ ], @@ -11097,7 +11398,7 @@ }, { "name": "project", - "description": "Project of the container registry", + "description": "Project of the container registry.", "args": [ ], @@ -11416,7 +11717,7 @@ }, { "name": "project", - "description": "Project of the container registry", + "description": "Project of the container registry.", "args": [ ], @@ -11448,7 +11749,7 @@ }, { "name": "tags", - "description": "Tags of the container repository", + "description": "Tags of the container repository.", "args": [ { "name": "after", @@ -11591,7 +11892,7 @@ { "kind": "SCALAR", "name": "ContainerRepositoryID", - "description": "Identifier of ContainerRepository", + "description": "Identifier of ContainerRepository.", "fields": null, "inputFields": null, "interfaces": null, @@ -12012,7 +12313,7 @@ }, { "name": "todo", - "description": "The todo after mutation.", + "description": "The to-do item after mutation.", "args": [ ], @@ -12200,7 +12501,7 @@ "inputFields": [ { "name": "projectPath", - "description": "The project full path the resource is associated with.", + "description": "Full path of the project with which the resource is associated.", "type": { "kind": "SCALAR", "name": "ID", @@ -12210,7 +12511,7 @@ }, { "name": "groupPath", - "description": "The group full path the resource is associated with.", + "description": "Full path of the group with which the resource is associated.", "type": { "kind": "SCALAR", "name": "ID", @@ -12230,7 +12531,7 @@ }, { "name": "hideBacklogList", - "description": "Whether or not backlog list is hidden", + "description": "Whether or not backlog list is hidden.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -12240,7 +12541,7 @@ }, { "name": "hideClosedList", - "description": "Whether or not closed list is hidden", + "description": "Whether or not closed list is hidden.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -13803,8 +14104,8 @@ "fields": null, "inputFields": [ { - "name": "groupPath", - "description": "The target group for the iteration.", + "name": "projectPath", + "description": "Full path of the project with which the resource is associated.", "type": { "kind": "SCALAR", "name": "ID", @@ -13813,8 +14114,8 @@ "defaultValue": null }, { - "name": "projectPath", - "description": "The target project for the iteration.", + "name": "groupPath", + "description": "Full path of the group with which the resource is associated.", "type": { "kind": "SCALAR", "name": "ID", @@ -14209,6 +14510,26 @@ "fields": null, "inputFields": [ { + "name": "captchaResponse", + "description": "A valid CAPTCHA response value obtained by using the provided captchaSiteKey with a CAPTCHA API to present a challenge to be solved on the client. Required to resubmit if the previous operation returned \"NeedsCaptchaResponse: true\".", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "spamLogId", + "description": "The spam log ID which must be passed along with a valid CAPTCHA response for the operation to be completed. Required to resubmit if the previous operation returned \"NeedsCaptchaResponse: true\".", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { "name": "title", "description": "Title of the snippet.", "type": { @@ -14313,6 +14634,20 @@ "description": "Autogenerated return type of CreateSnippet", "fields": [ { + "name": "captchaSiteKey", + "description": "The CAPTCHA site key which must be used to render a challenge for the user to solve to obtain a valid captchaResponse value. Included only when an operation was not completed because \"NeedsCaptchaResponse\" is true.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", "args": [ @@ -14353,6 +14688,20 @@ "deprecationReason": null }, { + "name": "needsCaptchaResponse", + "description": "Indicates whether the operation was detected as possible spam and not completed. If CAPTCHA is enabled, the request must be resubmitted with a valid CAPTCHA response and spam_log_id included for the operation to be completed. Included only when an operation was not completed because \"NeedsCaptchaResponse\" is true.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "snippet", "description": "The snippet after mutation.", "args": [ @@ -14368,7 +14717,7 @@ }, { "name": "spam", - "description": "Indicates whether the operation returns a record detected as spam.", + "description": "Indicates whether the operation was detected as definite spam. There is no option to resubmit the request with a CAPTCHA response.", "args": [ ], @@ -14379,6 +14728,20 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "spamLogId", + "description": "The spam log ID which must be passed along with a valid CAPTCHA response for an operation to be completed. Included only when an operation was not completed because \"NeedsCaptchaResponse\" is true.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -14539,7 +14902,7 @@ "fields": [ { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -14583,7 +14946,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -14648,7 +15011,7 @@ "fields": [ { "name": "external", - "description": "Whether the emoji is an external link", + "description": "Whether the emoji is an external link.", "args": [ ], @@ -14666,7 +15029,7 @@ }, { "name": "id", - "description": "The ID of the emoji", + "description": "The ID of the emoji.", "args": [ ], @@ -14684,7 +15047,7 @@ }, { "name": "name", - "description": "The name of the emoji", + "description": "The name of the emoji.", "args": [ ], @@ -14702,7 +15065,7 @@ }, { "name": "url", - "description": "The link to file of the emoji", + "description": "The link to file of the emoji.", "args": [ ], @@ -14841,7 +15204,7 @@ { "kind": "SCALAR", "name": "CustomEmojiID", - "description": "Identifier of CustomEmoji", + "description": "Identifier of CustomEmoji.", "fields": null, "inputFields": null, "interfaces": null, @@ -14975,6 +15338,411 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "DastProfile", + "description": "Represents a DAST Profile", + "fields": [ + { + "name": "dastScannerProfile", + "description": "The associated scanner profile.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "DastScannerProfile", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "dastSiteProfile", + "description": "The associated site profile.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "DastSiteProfile", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "description", + "description": "The description of the scan.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "editPath", + "description": "Relative web path to the edit page of a profile.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the profile.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "DastProfileID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "The name of the profile.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "DastProfileConnection", + "description": "The connection type for DastProfile.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "DastProfileEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "DastProfile", + "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": "DastProfileCreateInput", + "description": "Autogenerated input type of DastProfileCreate", + "fields": null, + "inputFields": [ + { + "name": "fullPath", + "description": "The project the profile belongs to.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "name", + "description": "The name of the profile.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "description", + "description": "The description of the profile. Defaults to an empty string.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": "\"\"" + }, + { + "name": "dastSiteProfileId", + "description": "ID of the site profile to be associated.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "DastSiteProfileID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "dastScannerProfileId", + "description": "ID of the scanner profile to be associated.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "DastScannerProfileID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "runAfterCreate", + "description": "Run scan using profile after creation. Defaults to false.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "false" + }, + { + "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": "DastProfileCreatePayload", + "description": "Autogenerated return type of DastProfileCreate", + "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": "dastProfile", + "description": "The created profile.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "DastProfile", + "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": "pipelineUrl", + "description": "The URL of the pipeline that was created. Requires `runAfterCreate` to be set to `true`.", + "args": [ + + ], + "type": { + "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": "DastProfileEdge", + "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": "DastProfile", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", + "name": "DastProfileID", + "description": "Identifier of Dast::Profile.", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "ENUM", "name": "DastScanTypeEnum", "description": null, @@ -15549,7 +16317,7 @@ { "kind": "SCALAR", "name": "DastScannerProfileID", - "description": "Identifier of DastScannerProfile", + "description": "Identifier of DastScannerProfile.", "fields": null, "inputFields": null, "interfaces": null, @@ -16206,7 +16974,7 @@ { "kind": "SCALAR", "name": "DastSiteProfileID", - "description": "Identifier of DastSiteProfile", + "description": "Identifier of DastSiteProfile.", "fields": null, "inputFields": null, "interfaces": null, @@ -16568,7 +17336,7 @@ { "kind": "SCALAR", "name": "DastSiteTokenID", - "description": "Identifier of DastSiteToken", + "description": "Identifier of DastSiteToken.", "fields": null, "inputFields": null, "interfaces": null, @@ -16907,7 +17675,7 @@ { "kind": "SCALAR", "name": "DastSiteValidationID", - "description": "Identifier of DastSiteValidation", + "description": "Identifier of DastSiteValidation.", "fields": null, "inputFields": null, "interfaces": null, @@ -16915,6 +17683,108 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "DastSiteValidationRevokeInput", + "description": "Autogenerated input type of DastSiteValidationRevoke", + "fields": null, + "inputFields": [ + { + "name": "fullPath", + "description": "The project the site validation belongs to.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "normalizedTargetUrl", + "description": "Normalized URL of the target to be revoked.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "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": "DastSiteValidationRevokePayload", + "description": "Autogenerated return type of DastSiteValidationRevoke", + "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": "DastSiteValidationStrategyEnum", "description": null, @@ -17248,7 +18118,7 @@ "fields": [ { "name": "completed", - "description": "Whether or not the entire queue was processed in time; if not, retrying the same request is safe", + "description": "Whether or not the entire queue was processed in time; if not, retrying the same request is safe.", "args": [ ], @@ -17262,7 +18132,7 @@ }, { "name": "deletedJobs", - "description": "The number of matching jobs deleted", + "description": "The number of matching jobs deleted.", "args": [ ], @@ -17276,7 +18146,7 @@ }, { "name": "queueSize", - "description": "The queue size after processing", + "description": "The queue size after processing.", "args": [ ], @@ -17303,7 +18173,7 @@ "fields": [ { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -17347,7 +18217,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -17370,7 +18240,7 @@ }, { "name": "diffRefs", - "description": "The diff refs for this design", + "description": "The diff refs for this design.", "args": [ ], @@ -17445,7 +18315,7 @@ }, { "name": "event", - "description": "How this design was changed in the current version", + "description": "How this design was changed in the current version.", "args": [ ], @@ -17463,7 +18333,7 @@ }, { "name": "filename", - "description": "The filename of the design", + "description": "The filename of the design.", "args": [ ], @@ -17481,7 +18351,7 @@ }, { "name": "fullPath", - "description": "The full path to the design file", + "description": "The full path to the design file.", "args": [ ], @@ -17499,7 +18369,7 @@ }, { "name": "id", - "description": "The ID of this design", + "description": "The ID of this design.", "args": [ ], @@ -17517,7 +18387,7 @@ }, { "name": "image", - "description": "The URL of the full-sized image", + "description": "The URL of the full-sized image.", "args": [ ], @@ -17549,7 +18419,7 @@ }, { "name": "issue", - "description": "The issue the design belongs to", + "description": "The issue the design belongs to.", "args": [ ], @@ -17624,7 +18494,7 @@ }, { "name": "notesCount", - "description": "The total count of user-created notes for this design", + "description": "The total count of user-created notes for this design.", "args": [ ], @@ -17642,7 +18512,7 @@ }, { "name": "project", - "description": "The project the design belongs to", + "description": "The project the design belongs to.", "args": [ ], @@ -17660,7 +18530,7 @@ }, { "name": "versions", - "description": "All versions related to this design ordered newest first", + "description": "All versions related to this design ordered newest first.", "args": [ { "name": "earlierOrEqualToSha", @@ -17764,7 +18634,7 @@ "fields": [ { "name": "design", - "description": "The underlying design", + "description": "The underlying design.", "args": [ ], @@ -17782,7 +18652,7 @@ }, { "name": "diffRefs", - "description": "The diff refs for this design", + "description": "The diff refs for this design.", "args": [ ], @@ -17800,7 +18670,7 @@ }, { "name": "event", - "description": "How this design was changed in the current version", + "description": "How this design was changed in the current version.", "args": [ ], @@ -17818,7 +18688,7 @@ }, { "name": "filename", - "description": "The filename of the design", + "description": "The filename of the design.", "args": [ ], @@ -17836,7 +18706,7 @@ }, { "name": "fullPath", - "description": "The full path to the design file", + "description": "The full path to the design file.", "args": [ ], @@ -17854,7 +18724,7 @@ }, { "name": "id", - "description": "The ID of this design", + "description": "The ID of this design.", "args": [ ], @@ -17872,7 +18742,7 @@ }, { "name": "image", - "description": "The URL of the full-sized image", + "description": "The URL of the full-sized image.", "args": [ ], @@ -17904,7 +18774,7 @@ }, { "name": "issue", - "description": "The issue the design belongs to", + "description": "The issue the design belongs to.", "args": [ ], @@ -17922,7 +18792,7 @@ }, { "name": "notesCount", - "description": "The total count of user-created notes for this design", + "description": "The total count of user-created notes for this design.", "args": [ ], @@ -17940,7 +18810,7 @@ }, { "name": "project", - "description": "The project the design belongs to", + "description": "The project the design belongs to.", "args": [ ], @@ -17958,7 +18828,7 @@ }, { "name": "version", - "description": "The version this design-at-versions is pinned to", + "description": "The version this design-at-versions is pinned to.", "args": [ ], @@ -18105,7 +18975,7 @@ "fields": [ { "name": "copyState", - "description": "Copy state of the design collection", + "description": "Copy state of the design collection.", "args": [ ], @@ -18119,7 +18989,7 @@ }, { "name": "design", - "description": "Find a specific design", + "description": "Find a specific design.", "args": [ { "name": "id", @@ -18152,7 +19022,7 @@ }, { "name": "designAtVersion", - "description": "Find a design as of a version", + "description": "Find a design as of a version.", "args": [ { "name": "id", @@ -18179,7 +19049,7 @@ }, { "name": "designs", - "description": "All designs for the design collection", + "description": "All designs for the design collection.", "args": [ { "name": "ids", @@ -18282,7 +19152,7 @@ }, { "name": "issue", - "description": "Issue associated with the design collection", + "description": "Issue associated with the design collection.", "args": [ ], @@ -18300,7 +19170,7 @@ }, { "name": "project", - "description": "Project associated with the design collection", + "description": "Project associated with the design collection.", "args": [ ], @@ -18318,7 +19188,7 @@ }, { "name": "version", - "description": "A specific version", + "description": "A specific version.", "args": [ { "name": "sha", @@ -18351,7 +19221,7 @@ }, { "name": "versions", - "description": "All versions related to all designs, ordered newest first", + "description": "All versions related to all designs, ordered newest first.", "args": [ { "name": "earlierOrEqualToSha", @@ -18582,7 +19452,7 @@ "fields": [ { "name": "diffRefs", - "description": "The diff refs for this design", + "description": "The diff refs for this design.", "args": [ ], @@ -18600,7 +19470,7 @@ }, { "name": "event", - "description": "How this design was changed in the current version", + "description": "How this design was changed in the current version.", "args": [ ], @@ -18618,7 +19488,7 @@ }, { "name": "filename", - "description": "The filename of the design", + "description": "The filename of the design.", "args": [ ], @@ -18636,7 +19506,7 @@ }, { "name": "fullPath", - "description": "The full path to the design file", + "description": "The full path to the design file.", "args": [ ], @@ -18654,7 +19524,7 @@ }, { "name": "id", - "description": "The ID of this design", + "description": "The ID of this design.", "args": [ ], @@ -18672,7 +19542,7 @@ }, { "name": "image", - "description": "The URL of the full-sized image", + "description": "The URL of the full-sized image.", "args": [ ], @@ -18704,7 +19574,7 @@ }, { "name": "issue", - "description": "The issue the design belongs to", + "description": "The issue the design belongs to.", "args": [ ], @@ -18722,7 +19592,7 @@ }, { "name": "notesCount", - "description": "The total count of user-created notes for this design", + "description": "The total count of user-created notes for this design.", "args": [ ], @@ -18740,7 +19610,7 @@ }, { "name": "project", - "description": "The project the design belongs to", + "description": "The project the design belongs to.", "args": [ ], @@ -18780,7 +19650,7 @@ "fields": [ { "name": "designAtVersion", - "description": "Find a design as of a version", + "description": "Find a design as of a version.", "args": [ { "name": "id", @@ -18807,7 +19677,7 @@ }, { "name": "version", - "description": "Find a version", + "description": "Find a version.", "args": [ { "name": "id", @@ -18981,7 +19851,7 @@ { "kind": "SCALAR", "name": "DesignManagementDesignAtVersionID", - "description": "Identifier of DesignManagement::DesignAtVersion", + "description": "Identifier of DesignManagement::DesignAtVersion.", "fields": null, "inputFields": null, "interfaces": null, @@ -18991,7 +19861,7 @@ { "kind": "SCALAR", "name": "DesignManagementDesignID", - "description": "Identifier of DesignManagement::Design", + "description": "Identifier of DesignManagement::Design.", "fields": null, "inputFields": null, "interfaces": null, @@ -19299,7 +20169,7 @@ { "kind": "SCALAR", "name": "DesignManagementVersionID", - "description": "Identifier of DesignManagement::Version", + "description": "Identifier of DesignManagement::Version.", "fields": null, "inputFields": null, "interfaces": null, @@ -19313,7 +20183,7 @@ "fields": [ { "name": "designAtVersion", - "description": "A particular design as of this version, provided it is visible at this version", + "description": "A particular design as of this version, provided it is visible at this version.", "args": [ { "name": "id", @@ -19360,7 +20230,7 @@ }, { "name": "designs", - "description": "All designs that were changed in the version", + "description": "All designs that were changed in the version.", "args": [ { "name": "after", @@ -19417,7 +20287,7 @@ }, { "name": "designsAtVersion", - "description": "All designs that are visible at this version, as of this version", + "description": "All designs that are visible at this version, as of this version.", "args": [ { "name": "ids", @@ -19510,7 +20380,7 @@ }, { "name": "id", - "description": "ID of the design version", + "description": "ID of the design version.", "args": [ ], @@ -19528,7 +20398,7 @@ }, { "name": "sha", - "description": "SHA of the design version", + "description": "SHA of the design version.", "args": [ ], @@ -20444,7 +21314,7 @@ "fields": [ { "name": "action", - "description": "Action information for the status. This includes method, button title, icon, path, and title", + "description": "Action information for the status. This includes method, button title, icon, path, and title.", "args": [ ], @@ -20458,7 +21328,7 @@ }, { "name": "detailsPath", - "description": "Path of the details for the status", + "description": "Path of the details for the status.", "args": [ ], @@ -20472,7 +21342,7 @@ }, { "name": "favicon", - "description": "Favicon of the status", + "description": "Favicon of the status.", "args": [ ], @@ -20486,7 +21356,7 @@ }, { "name": "group", - "description": "Group of the status", + "description": "Group of the status.", "args": [ ], @@ -20500,7 +21370,7 @@ }, { "name": "hasDetails", - "description": "Indicates if the status has further details", + "description": "Indicates if the status has further details.", "args": [ ], @@ -20514,7 +21384,7 @@ }, { "name": "icon", - "description": "Icon of the status", + "description": "Icon of the status.", "args": [ ], @@ -20528,7 +21398,7 @@ }, { "name": "label", - "description": "Label of the status", + "description": "Label of the status.", "args": [ ], @@ -20542,7 +21412,7 @@ }, { "name": "text", - "description": "Text of the status", + "description": "Text of the status.", "args": [ ], @@ -20556,7 +21426,7 @@ }, { "name": "tooltip", - "description": "Tooltip associated with the status", + "description": "Tooltip associated with the status.", "args": [ ], @@ -20974,7 +21844,7 @@ "inputFields": [ { "name": "headSha", - "description": "SHA of the HEAD at the time the comment was made", + "description": "SHA of the HEAD at the time the comment was made.", "type": { "kind": "NON_NULL", "name": null, @@ -20988,7 +21858,7 @@ }, { "name": "baseSha", - "description": "Merge base of the branch the comment was made on", + "description": "Merge base of the branch the comment was made on.", "type": { "kind": "SCALAR", "name": "String", @@ -20998,7 +21868,7 @@ }, { "name": "startSha", - "description": "SHA of the branch being compared against", + "description": "SHA of the branch being compared against.", "type": { "kind": "NON_NULL", "name": null, @@ -21088,7 +21958,7 @@ { "kind": "SCALAR", "name": "DiffNoteID", - "description": "Identifier of DiffNote", + "description": "Identifier of DiffNote.", "fields": null, "inputFields": null, "interfaces": null, @@ -21103,7 +21973,7 @@ "inputFields": [ { "name": "oldPath", - "description": "The path of the file on the start sha", + "description": "The path of the file on the start sha.", "type": { "kind": "SCALAR", "name": "String", @@ -21113,7 +21983,7 @@ }, { "name": "newPath", - "description": "The path of the file on the head sha", + "description": "The path of the file on the head sha.", "type": { "kind": "SCALAR", "name": "String", @@ -21313,7 +22183,7 @@ "inputFields": [ { "name": "headSha", - "description": "SHA of the HEAD at the time the comment was made", + "description": "SHA of the HEAD at the time the comment was made.", "type": { "kind": "NON_NULL", "name": null, @@ -21327,7 +22197,7 @@ }, { "name": "baseSha", - "description": "Merge base of the branch the comment was made on", + "description": "Merge base of the branch the comment was made on.", "type": { "kind": "SCALAR", "name": "String", @@ -21337,7 +22207,7 @@ }, { "name": "startSha", - "description": "SHA of the branch being compared against", + "description": "SHA of the branch being compared against.", "type": { "kind": "NON_NULL", "name": null, @@ -21422,7 +22292,7 @@ "fields": [ { "name": "baseSha", - "description": "Merge base of the branch the comment was made on", + "description": "Merge base of the branch the comment was made on.", "args": [ ], @@ -21436,7 +22306,7 @@ }, { "name": "headSha", - "description": "SHA of the HEAD at the time the comment was made", + "description": "SHA of the HEAD at the time the comment was made.", "args": [ ], @@ -21454,7 +22324,7 @@ }, { "name": "startSha", - "description": "SHA of the branch being compared against", + "description": "SHA of the branch being compared against.", "args": [ ], @@ -21485,7 +22355,7 @@ "fields": [ { "name": "additions", - "description": "Number of lines added to this file", + "description": "Number of lines added to this file.", "args": [ ], @@ -21503,7 +22373,7 @@ }, { "name": "deletions", - "description": "Number of lines deleted from this file", + "description": "Number of lines deleted from this file.", "args": [ ], @@ -21521,7 +22391,7 @@ }, { "name": "path", - "description": "File path, relative to repository root", + "description": "File path, relative to repository root.", "args": [ ], @@ -21552,7 +22422,7 @@ "fields": [ { "name": "additions", - "description": "Number of lines added", + "description": "Number of lines added.", "args": [ ], @@ -21570,7 +22440,7 @@ }, { "name": "changes", - "description": "Number of lines changed", + "description": "Number of lines changed.", "args": [ ], @@ -21588,7 +22458,7 @@ }, { "name": "deletions", - "description": "Number of lines deleted", + "description": "Number of lines deleted.", "args": [ ], @@ -21606,7 +22476,7 @@ }, { "name": "fileCount", - "description": "Number of files changed", + "description": "Number of files changed.", "args": [ ], @@ -21664,7 +22534,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "DiscussionID", "ofType": null } }, @@ -21739,7 +22609,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "DiscussionID", "ofType": null } }, @@ -21937,7 +22807,7 @@ { "kind": "SCALAR", "name": "DiscussionID", - "description": "Identifier of Discussion", + "description": "Identifier of Discussion.", "fields": null, "inputFields": null, "interfaces": null, @@ -22261,7 +23131,7 @@ }, { "name": "sha", - "description": "Last commit sha for the entry", + "description": "Last commit SHA for the entry", "args": [ ], @@ -22353,7 +23223,7 @@ "fields": [ { "name": "id", - "description": "ID of the environment", + "description": "ID of the environment.", "args": [ ], @@ -22371,7 +23241,7 @@ }, { "name": "latestOpenedMostSevereAlert", - "description": "The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned", + "description": "The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned.", "args": [ ], @@ -22385,7 +23255,7 @@ }, { "name": "metricsDashboard", - "description": "Metrics dashboard schema for the environment", + "description": "Metrics dashboard schema for the environment.", "args": [ { "name": "path", @@ -22412,7 +23282,7 @@ }, { "name": "name", - "description": "Human-readable name of the environment", + "description": "Human-readable name of the environment.", "args": [ ], @@ -22448,7 +23318,7 @@ }, { "name": "state", - "description": "State of the environment, for example: available/stopped", + "description": "State of the environment, for example: available/stopped.", "args": [ ], @@ -22587,7 +23457,7 @@ { "kind": "SCALAR", "name": "EnvironmentID", - "description": "Identifier of Environment", + "description": "Identifier of Environment.", "fields": null, "inputFields": null, "interfaces": null, @@ -22703,7 +23573,7 @@ "fields": [ { "name": "author", - "description": "Author of the epic", + "description": "Author of the epic.", "args": [ ], @@ -22720,8 +23590,61 @@ "deprecationReason": null }, { + "name": "awardEmoji", + "description": "A list of award emojis associated with the epic.", + "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": "AwardEmojiConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "children", - "description": "Children (sub-epics) of the epic", + "description": "Children (sub-epics) of the epic.", "args": [ { "name": "startDate", @@ -22930,7 +23853,7 @@ }, { "name": "closedAt", - "description": "Timestamp of when the epic was closed", + "description": "Timestamp of when the epic was closed.", "args": [ ], @@ -22944,7 +23867,7 @@ }, { "name": "confidential", - "description": "Indicates if the epic is confidential", + "description": "Indicates if the epic is confidential.", "args": [ ], @@ -22958,7 +23881,7 @@ }, { "name": "createdAt", - "description": "Timestamp of when the epic was created", + "description": "Timestamp of when the epic was created.", "args": [ ], @@ -22972,7 +23895,7 @@ }, { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -23016,7 +23939,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -23039,7 +23962,7 @@ }, { "name": "descendantCounts", - "description": "Number of open and closed descendant epics and issues", + "description": "Number of open and closed descendant epics and issues.", "args": [ ], @@ -23053,7 +23976,7 @@ }, { "name": "descendantWeightSum", - "description": "Total weight of open and closed issues in the epic and its descendants", + "description": "Total weight of open and closed issues in the epic and its descendants.", "args": [ ], @@ -23067,7 +23990,7 @@ }, { "name": "description", - "description": "Description of the epic", + "description": "Description of the epic.", "args": [ ], @@ -23138,7 +24061,7 @@ }, { "name": "downvotes", - "description": "Number of downvotes the epic has received", + "description": "Number of downvotes the epic has received.", "args": [ ], @@ -23156,7 +24079,7 @@ }, { "name": "dueDate", - "description": "Due date of the epic", + "description": "Due date of the epic.", "args": [ ], @@ -23170,7 +24093,7 @@ }, { "name": "dueDateFixed", - "description": "Fixed due date of the epic", + "description": "Fixed due date of the epic.", "args": [ ], @@ -23184,7 +24107,7 @@ }, { "name": "dueDateFromMilestones", - "description": "Inherited due date of the epic from milestones", + "description": "Inherited due date of the epic from milestones.", "args": [ ], @@ -23198,7 +24121,7 @@ }, { "name": "dueDateIsFixed", - "description": "Indicates if the due date has been manually set", + "description": "Indicates if the due date has been manually set.", "args": [ ], @@ -23212,7 +24135,7 @@ }, { "name": "group", - "description": "Group to which the epic belongs", + "description": "Group to which the epic belongs.", "args": [ ], @@ -23230,7 +24153,7 @@ }, { "name": "hasChildren", - "description": "Indicates if the epic has children", + "description": "Indicates if the epic has children.", "args": [ ], @@ -23248,7 +24171,7 @@ }, { "name": "hasIssues", - "description": "Indicates if the epic has direct issues", + "description": "Indicates if the epic has direct issues.", "args": [ ], @@ -23266,7 +24189,7 @@ }, { "name": "hasParent", - "description": "Indicates if the epic has a parent epic", + "description": "Indicates if the epic has a parent epic.", "args": [ ], @@ -23284,7 +24207,7 @@ }, { "name": "healthStatus", - "description": "Current health status of the epic", + "description": "Current health status of the epic.", "args": [ ], @@ -23298,7 +24221,7 @@ }, { "name": "id", - "description": "ID of the epic", + "description": "ID of the epic.", "args": [ ], @@ -23316,7 +24239,7 @@ }, { "name": "iid", - "description": "Internal ID of the epic", + "description": "Internal ID of the epic.", "args": [ ], @@ -23334,7 +24257,7 @@ }, { "name": "issues", - "description": "A list of issues associated with the epic", + "description": "A list of issues associated with the epic.", "args": [ { "name": "after", @@ -23387,7 +24310,7 @@ }, { "name": "labels", - "description": "Labels assigned to the epic", + "description": "Labels assigned to the epic.", "args": [ { "name": "after", @@ -23497,7 +24420,7 @@ }, { "name": "parent", - "description": "Parent epic of the epic", + "description": "Parent epic of the epic.", "args": [ ], @@ -23511,7 +24434,7 @@ }, { "name": "participants", - "description": "List of participants for the epic", + "description": "List of participants for the epic.", "args": [ { "name": "after", @@ -23564,11 +24487,11 @@ }, { "name": "reference", - "description": "Internal reference of the epic. Returned in shortened format by default", + "description": "Internal reference of the epic. Returned in shortened format by default.", "args": [ { "name": "full", - "description": "Indicates if the reference should be returned in full", + "description": "Indicates if the reference should be returned in full.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -23591,7 +24514,7 @@ }, { "name": "relationPath", - "description": "URI path of the epic-issue relationship", + "description": "URI path of the epic-issue relationship.", "args": [ ], @@ -23605,7 +24528,7 @@ }, { "name": "relativePosition", - "description": "The relative position of the epic in the epic tree", + "description": "The relative position of the epic in the epic tree.", "args": [ ], @@ -23619,7 +24542,7 @@ }, { "name": "startDate", - "description": "Start date of the epic", + "description": "Start date of the epic.", "args": [ ], @@ -23633,7 +24556,7 @@ }, { "name": "startDateFixed", - "description": "Fixed start date of the epic", + "description": "Fixed start date of the epic.", "args": [ ], @@ -23647,7 +24570,7 @@ }, { "name": "startDateFromMilestones", - "description": "Inherited start date of the epic from milestones", + "description": "Inherited start date of the epic from milestones.", "args": [ ], @@ -23661,7 +24584,7 @@ }, { "name": "startDateIsFixed", - "description": "Indicates if the start date has been manually set", + "description": "Indicates if the start date has been manually set.", "args": [ ], @@ -23675,7 +24598,7 @@ }, { "name": "state", - "description": "State of the epic", + "description": "State of the epic.", "args": [ ], @@ -23693,7 +24616,7 @@ }, { "name": "subscribed", - "description": "Indicates the currently logged in user is subscribed to the epic", + "description": "Indicates the currently logged in user is subscribed to the epic.", "args": [ ], @@ -23711,7 +24634,7 @@ }, { "name": "title", - "description": "Title of the epic", + "description": "Title of the epic.", "args": [ ], @@ -23725,7 +24648,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of when the epic was updated", + "description": "Timestamp of when the epic was updated.", "args": [ ], @@ -23739,7 +24662,7 @@ }, { "name": "upvotes", - "description": "Number of upvotes the epic has received", + "description": "Number of upvotes the epic has received.", "args": [ ], @@ -23757,7 +24680,7 @@ }, { "name": "userDiscussionsCount", - "description": "Number of user discussions in the epic", + "description": "Number of user discussions in the epic.", "args": [ ], @@ -23775,7 +24698,7 @@ }, { "name": "userNotesCount", - "description": "Number of user notes of the epic", + "description": "Number of user notes of the epic.", "args": [ ], @@ -23811,7 +24734,7 @@ }, { "name": "webPath", - "description": "Web path of the epic", + "description": "Web path of the epic.", "args": [ ], @@ -23829,7 +24752,7 @@ }, { "name": "webUrl", - "description": "Web URL of the epic", + "description": "Web URL of the epic.", "args": [ ], @@ -24196,6 +25119,134 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "EpicBoardCreateInput", + "description": "Autogenerated input type of EpicBoardCreate", + "fields": null, + "inputFields": [ + { + "name": "name", + "description": "The board name.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "hideBacklogList", + "description": "Whether or not backlog list is hidden.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "hideClosedList", + "description": "Whether or not closed list is hidden.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "groupPath", + "description": "Full path of the group with which the resource is associated.", + "type": { + "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": "EpicBoardCreatePayload", + "description": "Autogenerated return type of EpicBoardCreate", + "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": "epicBoard", + "description": "The created epic board.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "EpicBoard", + "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": "EpicBoardEdge", "description": "An edge in a connection.", @@ -24520,7 +25571,7 @@ { "kind": "SCALAR", "name": "EpicID", - "description": "Identifier of Epic", + "description": "Identifier of Epic.", "fields": null, "inputFields": null, "interfaces": null, @@ -24715,7 +25766,7 @@ }, { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -24759,7 +25810,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -25705,7 +26756,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -26640,7 +27691,7 @@ { "kind": "SCALAR", "name": "EpicTreeSortingID", - "description": "Identifier of EpicTreeSorting", + "description": "Identifier of EpicTreeSorting.", "fields": null, "inputFields": null, "interfaces": null, @@ -26739,6 +27790,24 @@ "defaultValue": null }, { + "name": "selectedFields", + "description": "List of selected requirements fields to be exported.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", "type": { @@ -27488,7 +28557,7 @@ { "kind": "SCALAR", "name": "GitlabErrorTrackingDetailedErrorID", - "description": "Identifier of Gitlab::ErrorTracking::DetailedError", + "description": "Identifier of Gitlab::ErrorTracking::DetailedError.", "fields": null, "inputFields": null, "interfaces": null, @@ -27496,13 +28565,101 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "GitlabSubscriptionActivateInput", + "description": "Autogenerated input type of GitlabSubscriptionActivate", + "fields": null, + "inputFields": [ + { + "name": "activationCode", + "description": "Activation code received after purchasing a GitLab subscription.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "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": "GitlabSubscriptionActivatePayload", + "description": "Autogenerated return type of GitlabSubscriptionActivate", + "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": "GrafanaIntegration", "description": null, "fields": [ { "name": "createdAt", - "description": "Timestamp of the issue's creation", + "description": "Timestamp of the issue's creation.", "args": [ ], @@ -27520,7 +28677,7 @@ }, { "name": "enabled", - "description": "Indicates whether Grafana integration is enabled", + "description": "Indicates whether Grafana integration is enabled.", "args": [ ], @@ -27538,7 +28695,7 @@ }, { "name": "grafanaUrl", - "description": "URL for the Grafana host for the Grafana integration", + "description": "URL for the Grafana host for the Grafana integration.", "args": [ ], @@ -27556,7 +28713,7 @@ }, { "name": "id", - "description": "Internal ID of the Grafana integration", + "description": "Internal ID of the Grafana integration.", "args": [ ], @@ -27574,7 +28731,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of the issue's last activity", + "description": "Timestamp of the issue's last activity.", "args": [ ], @@ -27633,7 +28790,7 @@ }, { "name": "autoDevopsEnabled", - "description": "Indicates whether Auto DevOps is enabled for all projects within this group", + "description": "Indicates whether Auto DevOps is enabled for all projects within this group.", "args": [ ], @@ -27647,7 +28804,7 @@ }, { "name": "avatarUrl", - "description": "Avatar URL of the group", + "description": "Avatar URL of the group.", "args": [ ], @@ -27661,7 +28818,7 @@ }, { "name": "board", - "description": "A single board of the group", + "description": "A single board of the group.", "args": [ { "name": "id", @@ -27688,7 +28845,7 @@ }, { "name": "boards", - "description": "Boards of the group", + "description": "Boards of the group.", "args": [ { "name": "id", @@ -27881,7 +29038,7 @@ }, { "name": "containerRepositories", - "description": "Container repositories of the group", + "description": "Container repositories of the group.", "args": [ { "name": "name", @@ -27944,7 +29101,7 @@ }, { "name": "containerRepositoriesCount", - "description": "Number of container repositories in the group", + "description": "Number of container repositories in the group.", "args": [ ], @@ -27980,7 +29137,7 @@ }, { "name": "customEmoji", - "description": "Custom emoji within this namespace Available only when feature flag `custom_emoji` is enabled.", + "description": "Custom emoji within this namespace. Available only when feature flag `custom_emoji` is enabled.", "args": [ { "name": "after", @@ -28061,7 +29218,7 @@ }, { "name": "emailsDisabled", - "description": "Indicates if a group has email notifications disabled", + "description": "Indicates if a group has email notifications disabled.", "args": [ ], @@ -28583,7 +29740,7 @@ }, { "name": "groupMembers", - "description": "A membership of a user within this group", + "description": "A membership of a user within this group.", "args": [ { "name": "search", @@ -28714,7 +29871,7 @@ }, { "name": "issues", - "description": "Issues for projects in this group", + "description": "Issues for projects in this group.", "args": [ { "name": "iid", @@ -29146,11 +30303,11 @@ }, { "name": "label", - "description": "A label available on this group", + "description": "A label available on this group.", "args": [ { "name": "title", - "description": "Title of the label", + "description": "Title of the label.", "type": { "kind": "NON_NULL", "name": null, @@ -29173,7 +30330,7 @@ }, { "name": "labels", - "description": "Labels available on this group", + "description": "Labels available on this group.", "args": [ { "name": "after", @@ -29217,7 +30374,7 @@ }, { "name": "searchTerm", - "description": "A search term to find labels with", + "description": "A search term to find labels with.", "type": { "kind": "SCALAR", "name": "String", @@ -29250,7 +30407,7 @@ }, { "name": "mentionsDisabled", - "description": "Indicates if a group is disabled from getting mentioned", + "description": "Indicates if a group is disabled from getting mentioned.", "args": [ ], @@ -29264,7 +30421,7 @@ }, { "name": "mergeRequests", - "description": "Merge requests for projects in this group", + "description": "Merge requests for projects in this group.", "args": [ { "name": "iids", @@ -29469,7 +30626,7 @@ }, { "name": "milestones", - "description": "Milestones of the group", + "description": "Milestones of the group.", "args": [ { "name": "startDate", @@ -29652,7 +30809,7 @@ }, { "name": "parent", - "description": "Parent group", + "description": "Parent group.", "args": [ ], @@ -29684,7 +30841,7 @@ }, { "name": "projectCreationLevel", - "description": "The permission level required to create projects in the group", + "description": "The permission level required to create projects in the group.", "args": [ ], @@ -29827,7 +30984,7 @@ }, { "name": "requireTwoFactorAuthentication", - "description": "Indicates if all users in this group are required to set up two-factor authentication", + "description": "Indicates if all users in this group are required to set up two-factor authentication.", "args": [ ], @@ -29855,7 +31012,7 @@ }, { "name": "shareWithGroupLock", - "description": "Indicates if sharing a project with another group within this group is prevented", + "description": "Indicates if sharing a project with another group within this group is prevented.", "args": [ ], @@ -29897,7 +31054,7 @@ }, { "name": "subgroupCreationLevel", - "description": "The permission level required to create subgroups within the group", + "description": "The permission level required to create subgroups within the group.", "args": [ ], @@ -30050,7 +31207,7 @@ }, { "name": "twoFactorGracePeriod", - "description": "Time before two-factor authentication is enforced", + "description": "Time before two-factor authentication is enforced.", "args": [ ], @@ -30466,7 +31623,7 @@ }, { "name": "vulnerabilityScanners", - "description": "Vulnerability scanners reported on the project vulnerabilties of the group and its subgroups", + "description": "Vulnerability scanners reported on the project vulnerabilities of the group and its subgroups", "args": [ { "name": "after", @@ -30622,7 +31779,7 @@ }, { "name": "webUrl", - "description": "Web URL of the group", + "description": "Web URL of the group.", "args": [ ], @@ -30649,7 +31806,7 @@ { "kind": "SCALAR", "name": "GroupID", - "description": "Identifier of Group", + "description": "Identifier of Group.", "fields": null, "inputFields": null, "interfaces": null, @@ -30719,7 +31876,7 @@ }, { "name": "group", - "description": "Group that a User is a member of", + "description": "Group that a User is a member of.", "args": [ ], @@ -31483,6 +32640,34 @@ "defaultValue": null }, { + "name": "payloadExample", + "description": "The example of an alert payload.", + "type": { + "kind": "SCALAR", + "name": "JsonString", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "payloadAttributeMappings", + "description": "The custom mapping of GitLab alert attributes to fields from the payload_example.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "AlertManagementPayloadAlertFieldInput", + "ofType": null + } + } + }, + "defaultValue": null + }, + { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", "type": { @@ -31587,7 +32772,7 @@ { "kind": "SCALAR", "name": "IncidentManagementOncallParticipantID", - "description": "Identifier of IncidentManagement::OncallParticipant", + "description": "Identifier of IncidentManagement::OncallParticipant.", "fields": null, "inputFields": null, "interfaces": null, @@ -31717,6 +32902,87 @@ "deprecationReason": null }, { + "name": "shifts", + "description": "Blocks of time for which a participant is on-call within a given time frame. Time frame cannot exceed one month.", + "args": [ + { + "name": "startTime", + "description": "Start of timeframe to include shifts for.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "endTime", + "description": "End of timeframe to include shifts for. Cannot exceed one month after start.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "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": "IncidentManagementOncallShiftConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "startsAt", "description": "Start date of the on-call rotation.", "args": [ @@ -31853,7 +33119,7 @@ { "kind": "SCALAR", "name": "IncidentManagementOncallRotationID", - "description": "Identifier of IncidentManagement::OncallRotation", + "description": "Identifier of IncidentManagement::OncallRotation.", "fields": null, "inputFields": null, "interfaces": null, @@ -32112,6 +33378,173 @@ }, { "kind": "OBJECT", + "name": "IncidentManagementOncallShift", + "description": "A block of time for which a participant is on-call.", + "fields": [ + { + "name": "endsAt", + "description": "End time of the on-call shift.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "participant", + "description": "Participant assigned to the on-call shift.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "OncallParticipantType", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "startsAt", + "description": "Start time of the on-call shift.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "IncidentManagementOncallShiftConnection", + "description": "The connection type for IncidentManagementOncallShift.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "IncidentManagementOncallShiftEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "IncidentManagementOncallShift", + "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": "IncidentManagementOncallShiftEdge", + "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": "IncidentManagementOncallShift", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "InstanceSecurityDashboard", "description": null, "fields": [ @@ -32200,7 +33633,7 @@ }, { "name": "vulnerabilityScanners", - "description": "Vulnerability scanners reported on the vulnerabilties from projects selected in Instance Security Dashboard", + "description": "Vulnerability scanners reported on the vulnerabilities from projects selected in Instance Security Dashboard", "args": [ { "name": "after", @@ -32369,7 +33802,7 @@ "fields": [ { "name": "count", - "description": "Object count", + "description": "Object count.", "args": [ ], @@ -32387,7 +33820,7 @@ }, { "name": "identifier", - "description": "The type of objects being measured", + "description": "The type of objects being measured.", "args": [ ], @@ -32405,7 +33838,7 @@ }, { "name": "recordedAt", - "description": "The time the measurement was recorded", + "description": "The time the measurement was recorded.", "args": [ ], @@ -32811,7 +34244,7 @@ }, { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -32855,7 +34288,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -33773,7 +35206,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -33917,7 +35350,7 @@ { "kind": "SCALAR", "name": "IssueID", - "description": "Identifier of Issue", + "description": "Identifier of Issue.", "fields": null, "inputFields": null, "interfaces": null, @@ -36248,7 +37681,7 @@ { "kind": "SCALAR", "name": "IterationID", - "description": "Identifier of Iteration", + "description": "Identifier of Iteration.", "fields": null, "inputFields": null, "interfaces": null, @@ -37564,7 +38997,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -37650,7 +39083,7 @@ "inputFields": [ { "name": "projectPath", - "description": "The project full path the resource is associated with.", + "description": "Full path of the project with which the resource is associated.", "type": { "kind": "SCALAR", "name": "ID", @@ -37660,7 +39093,7 @@ }, { "name": "groupPath", - "description": "The group full path the resource is associated with.", + "description": "Full path of the group with which the resource is associated.", "type": { "kind": "SCALAR", "name": "ID", @@ -37832,7 +39265,7 @@ { "kind": "SCALAR", "name": "LabelID", - "description": "Identifier of Label", + "description": "Identifier of Label.", "fields": null, "inputFields": null, "interfaces": null, @@ -37842,7 +39275,7 @@ { "kind": "SCALAR", "name": "ListID", - "description": "Identifier of List", + "description": "Identifier of List.", "fields": null, "inputFields": null, "interfaces": null, @@ -38635,7 +40068,7 @@ }, { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -38679,7 +40112,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -40084,7 +41517,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -40641,7 +42074,7 @@ { "kind": "SCALAR", "name": "MergeRequestID", - "description": "Identifier of MergeRequest", + "description": "Identifier of MergeRequest.", "fields": null, "inputFields": null, "interfaces": null, @@ -40825,6 +42258,136 @@ }, { "kind": "INPUT_OBJECT", + "name": "MergeRequestReviewerRereviewInput", + "description": "Autogenerated input type of MergeRequestReviewerRereview", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "The project the merge request 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 merge request to mutate.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "userId", + "description": "The user ID for the user that has been requested for a new review.\n", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "UserID", + "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": "MergeRequestReviewerRereviewPayload", + "description": "Autogenerated return type of MergeRequestReviewerRereview", + "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": "mergeRequest", + "description": "The merge request after mutation.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "MergeRequest", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", "name": "MergeRequestSetAssigneesInput", "description": "Autogenerated input type of MergeRequestSetAssignees", "fields": null, @@ -41776,7 +43339,7 @@ }, { "name": "merged", - "description": null, + "description": "Merge Request has been merged", "isDeprecated": false, "deprecationReason": null } @@ -42401,7 +43964,7 @@ { "kind": "SCALAR", "name": "MetricsDashboardAnnotationID", - "description": "Identifier of Metrics::Dashboard::Annotation", + "description": "Identifier of Metrics::Dashboard::Annotation.", "fields": null, "inputFields": null, "interfaces": null, @@ -42772,7 +44335,7 @@ { "kind": "SCALAR", "name": "MilestoneID", - "description": "Identifier of Milestone", + "description": "Identifier of Milestone.", "fields": null, "inputFields": null, "interfaces": null, @@ -42782,20 +44345,20 @@ { "kind": "ENUM", "name": "MilestoneStateEnum", - "description": null, + "description": "Current state of milestone", "fields": null, "inputFields": null, "interfaces": null, "enumValues": [ { "name": "active", - "description": null, + "description": "Milestone is currently active", "isDeprecated": false, "deprecationReason": null }, { "name": "closed", - "description": null, + "description": "Milestone is closed", "isDeprecated": false, "deprecationReason": null } @@ -43790,6 +45353,33 @@ "deprecationReason": null }, { + "name": "dastProfileCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DastProfileCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DastProfileCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "dastScannerProfileCreate", "description": null, "args": [ @@ -44006,6 +45596,33 @@ "deprecationReason": null }, { + "name": "dastSiteValidationRevoke", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DastSiteValidationRevokeInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DastSiteValidationRevokePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "deleteAnnotation", "description": null, "args": [ @@ -44438,6 +46055,33 @@ "deprecationReason": null }, { + "name": "epicBoardCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "EpicBoardCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "EpicBoardCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "epicSetSubscription", "description": null, "args": [ @@ -44519,6 +46163,33 @@ "deprecationReason": null }, { + "name": "gitlabSubscriptionActivate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "GitlabSubscriptionActivateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "GitlabSubscriptionActivatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "httpIntegrationCreate", "description": null, "args": [ @@ -45059,6 +46730,33 @@ "deprecationReason": null }, { + "name": "mergeRequestReviewerRereview", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "MergeRequestReviewerRereviewInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "MergeRequestReviewerRereviewPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "mergeRequestSetAssignees", "description": null, "args": [ @@ -45302,6 +47000,33 @@ "deprecationReason": null }, { + "name": "oncallRotationDestroy", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "OncallRotationDestroyInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "OncallRotationDestroyPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "oncallScheduleCreate", "description": null, "args": [ @@ -47248,7 +48973,7 @@ { "kind": "SCALAR", "name": "NamespaceID", - "description": "Identifier of Namespace", + "description": "Identifier of Namespace.", "fields": null, "inputFields": null, "interfaces": null, @@ -47388,7 +49113,7 @@ "inputFields": [ { "name": "labelName", - "description": "Filter by label name", + "description": "Filter by label name.", "type": { "kind": "LIST", "name": null, @@ -47402,7 +49127,7 @@ }, { "name": "milestoneTitle", - "description": "Filter by milestone title", + "description": "Filter by milestone title.", "type": { "kind": "SCALAR", "name": "String", @@ -47412,7 +49137,7 @@ }, { "name": "assigneeUsername", - "description": "Filter by assignee username", + "description": "Filter by assignee username.", "type": { "kind": "LIST", "name": null, @@ -47426,7 +49151,7 @@ }, { "name": "authorUsername", - "description": "Filter by author username", + "description": "Filter by author username.", "type": { "kind": "SCALAR", "name": "String", @@ -47436,7 +49161,7 @@ }, { "name": "releaseTag", - "description": "Filter by release tag", + "description": "Filter by release tag.", "type": { "kind": "SCALAR", "name": "String", @@ -47446,7 +49171,7 @@ }, { "name": "myReactionEmoji", - "description": "Filter by reaction emoji", + "description": "Filter by reaction emoji.", "type": { "kind": "SCALAR", "name": "String", @@ -47601,7 +49326,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "NoteID", "ofType": null } }, @@ -47909,7 +49634,7 @@ { "kind": "SCALAR", "name": "NoteID", - "description": "Identifier of Note", + "description": "Identifier of Note.", "fields": null, "inputFields": null, "interfaces": null, @@ -48211,7 +49936,7 @@ { "kind": "SCALAR", "name": "NoteableID", - "description": "Identifier of Noteable", + "description": "Identifier of Noteable.", "fields": null, "inputFields": null, "interfaces": null, @@ -48628,6 +50353,136 @@ }, { "kind": "INPUT_OBJECT", + "name": "OncallRotationDestroyInput", + "description": "Autogenerated input type of OncallRotationDestroy", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "The project to remove the on-call schedule from.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "scheduleIid", + "description": "The IID of the on-call schedule to the on-call rotation belongs to.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "id", + "description": "The ID of the on-call rotation to remove.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "IncidentManagementOncallRotationID", + "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": "OncallRotationDestroyPayload", + "description": "Autogenerated return type of OncallRotationDestroy", + "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": "oncallRotation", + "description": "The on-call rotation.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "IncidentManagementOncallRotation", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", "name": "OncallRotationLengthInputType", "description": "The rotation length of the on-call rotation", "fields": null, @@ -49148,7 +51003,7 @@ "fields": [ { "name": "createdAt", - "description": "The created date.", + "description": "Date of creation.", "args": [ ], @@ -49166,25 +51021,7 @@ }, { "name": "id", - "description": "The ID of the package.", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "ID", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "name", - "description": "The name of the package.", + "description": "ID of the package.", "args": [ ], @@ -49193,25 +51030,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "String", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "packageType", - "description": "The type of the package.", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "ENUM", - "name": "PackageTypeEnum", + "name": "PackagesPackageID", "ofType": null } }, @@ -49219,284 +51038,22 @@ "deprecationReason": null }, { - "name": "pipelines", - "description": "Pipelines that built the package.", - "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": "PipelineConnection", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "project", - "description": "Project where the package is stored.", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "OBJECT", - "name": "Project", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "tags", - "description": "The package tags.", - "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": "PackageTagConnection", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "updatedAt", - "description": "The updated date.", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "Time", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "version", - "description": "The version of the package.", + "name": "metadata", + "description": "Package metadata.", "args": [ ], "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "versions", - "description": "The other versions of the package.", - "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": "PackageConnection", + "kind": "UNION", + "name": "PackageMetadata", "ofType": null }, "isDeprecated": false, "deprecationReason": null - } - ], - "inputFields": null, - "interfaces": [ - - ], - "enumValues": null, - "possibleTypes": null - }, - { - "kind": "OBJECT", - "name": "PackageComposerDetails", - "description": "Details of a Composer package", - "fields": [ - { - "name": "composerMetadatum", - "description": "The Composer metadatum.", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "OBJECT", - "name": "PackageComposerMetadatumType", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "createdAt", - "description": "The created date.", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "Time", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "id", - "description": "The ID of the package.", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "ID", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null }, { "name": "name", - "description": "The name of the package.", + "description": "Name of the package.", "args": [ ], @@ -49514,7 +51071,7 @@ }, { "name": "packageType", - "description": "The type of the package.", + "description": "Package type.", "args": [ ], @@ -49603,7 +51160,7 @@ }, { "name": "tags", - "description": "The package tags.", + "description": "Package tags.", "args": [ { "name": "after", @@ -49656,7 +51213,7 @@ }, { "name": "updatedAt", - "description": "The updated date.", + "description": "Date of most recent update.", "args": [ ], @@ -49674,7 +51231,7 @@ }, { "name": "version", - "description": "The version of the package.", + "description": "Version string.", "args": [ ], @@ -49733,7 +51290,7 @@ ], "type": { "kind": "OBJECT", - "name": "PackageConnection", + "name": "PackageWithoutVersionsConnection", "ofType": null }, "isDeprecated": false, @@ -49818,55 +51375,6 @@ }, { "kind": "OBJECT", - "name": "PackageComposerMetadatumType", - "description": "Composer metadatum", - "fields": [ - { - "name": "composerJson", - "description": "Data of the Composer JSON file.", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "OBJECT", - "name": "PackageComposerJsonType", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "targetSha", - "description": "Target SHA of the package.", - "args": [ - - ], - "type": { - "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": "PackageConnection", "description": "The connection type for Package.", "fields": [ @@ -50223,6 +51731,22 @@ "possibleTypes": null }, { + "kind": "UNION", + "name": "PackageMetadata", + "description": "Represents metadata associated with a Package", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": [ + { + "kind": "OBJECT", + "name": "ComposerMetadata", + "ofType": null + } + ] + }, + { "kind": "OBJECT", "name": "PackageSettings", "description": "Namespace-level Package Registry settings", @@ -50530,9 +52054,376 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "PackageWithoutVersions", + "description": "Represents a version of a package in the Package Registry", + "fields": [ + { + "name": "createdAt", + "description": "Date of creation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the package.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "PackagesPackageID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "metadata", + "description": "Package metadata.", + "args": [ + + ], + "type": { + "kind": "UNION", + "name": "PackageMetadata", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the package.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "packageType", + "description": "Package type.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "PackageTypeEnum", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pipelines", + "description": "Pipelines that built the package.", + "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": "PipelineConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "project", + "description": "Project where the package is stored.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "Project", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "tags", + "description": "Package tags.", + "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": "PackageTagConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "updatedAt", + "description": "Date of most recent update.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "version", + "description": "Version string.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "PackageWithoutVersionsConnection", + "description": "The connection type for PackageWithoutVersions.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PackageWithoutVersionsEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PackageWithoutVersions", + "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": "PackageWithoutVersionsEdge", + "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": "PackageWithoutVersions", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "SCALAR", "name": "PackagesPackageID", - "description": "Identifier of Packages::Package", + "description": "Identifier of Packages::Package.", "fields": null, "inputFields": null, "interfaces": null, @@ -50623,7 +52514,7 @@ "fields": [ { "name": "active", - "description": "Indicates if the pipeline is active", + "description": "Indicates if the pipeline is active.", "args": [ ], @@ -50641,7 +52532,7 @@ }, { "name": "beforeSha", - "description": "Base SHA of the source branch", + "description": "Base SHA of the source branch.", "args": [ ], @@ -50655,7 +52546,7 @@ }, { "name": "cancelable", - "description": "Specifies if a pipeline can be canceled", + "description": "Specifies if a pipeline can be canceled.", "args": [ ], @@ -50673,7 +52564,7 @@ }, { "name": "committedAt", - "description": "Timestamp of the pipeline's commit", + "description": "Timestamp of the pipeline's commit.", "args": [ ], @@ -50687,7 +52578,7 @@ }, { "name": "configSource", - "description": "Config source of the pipeline (UNKNOWN_SOURCE, REPOSITORY_SOURCE, AUTO_DEVOPS_SOURCE, WEBIDE_SOURCE, REMOTE_SOURCE, EXTERNAL_PROJECT_SOURCE, BRIDGE_SOURCE, PARAMETER_SOURCE)", + "description": "Configuration source of the pipeline (UNKNOWN_SOURCE, REPOSITORY_SOURCE, AUTO_DEVOPS_SOURCE, WEBIDE_SOURCE, REMOTE_SOURCE, EXTERNAL_PROJECT_SOURCE, BRIDGE_SOURCE, PARAMETER_SOURCE)", "args": [ ], @@ -50701,7 +52592,7 @@ }, { "name": "coverage", - "description": "Coverage percentage", + "description": "Coverage percentage.", "args": [ ], @@ -50715,7 +52606,7 @@ }, { "name": "createdAt", - "description": "Timestamp of the pipeline's creation", + "description": "Timestamp of the pipeline's creation.", "args": [ ], @@ -50733,7 +52624,7 @@ }, { "name": "detailedStatus", - "description": "Detailed status of the pipeline", + "description": "Detailed status of the pipeline.", "args": [ ], @@ -50751,7 +52642,7 @@ }, { "name": "downstream", - "description": "Pipelines this pipeline will trigger", + "description": "Pipelines this pipeline will trigger.", "args": [ { "name": "after", @@ -50804,7 +52695,7 @@ }, { "name": "duration", - "description": "Duration of the pipeline in seconds", + "description": "Duration of the pipeline in seconds.", "args": [ ], @@ -50818,7 +52709,7 @@ }, { "name": "finishedAt", - "description": "Timestamp of the pipeline's completion", + "description": "Timestamp of the pipeline's completion.", "args": [ ], @@ -50832,7 +52723,7 @@ }, { "name": "id", - "description": "ID of the pipeline", + "description": "ID of the pipeline.", "args": [ ], @@ -50850,7 +52741,7 @@ }, { "name": "iid", - "description": "Internal ID of the pipeline", + "description": "Internal ID of the pipeline.", "args": [ ], @@ -50868,7 +52759,7 @@ }, { "name": "jobs", - "description": "Jobs belonging to the pipeline", + "description": "Jobs belonging to the pipeline.", "args": [ { "name": "securityReportTypes", @@ -50939,7 +52830,7 @@ }, { "name": "path", - "description": "Relative path to the pipeline's page", + "description": "Relative path to the pipeline's page.", "args": [ ], @@ -50953,7 +52844,7 @@ }, { "name": "project", - "description": "Project the pipeline belongs to", + "description": "Project the pipeline belongs to.", "args": [ ], @@ -50967,7 +52858,7 @@ }, { "name": "retryable", - "description": "Specifies if a pipeline can be retried", + "description": "Specifies if a pipeline can be retried.", "args": [ ], @@ -50999,7 +52890,7 @@ }, { "name": "sha", - "description": "SHA of the pipeline's commit", + "description": "SHA of the pipeline's commit.", "args": [ ], @@ -51017,7 +52908,7 @@ }, { "name": "sourceJob", - "description": "Job where pipeline was triggered from", + "description": "Job where pipeline was triggered from.", "args": [ ], @@ -51031,7 +52922,7 @@ }, { "name": "stages", - "description": "Stages of the pipeline", + "description": "Stages of the pipeline.", "args": [ { "name": "after", @@ -51084,7 +52975,7 @@ }, { "name": "startedAt", - "description": "Timestamp when the pipeline was started", + "description": "Timestamp when the pipeline was started.", "args": [ ], @@ -51116,7 +53007,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of the pipeline's last activity", + "description": "Timestamp of the pipeline's last activity.", "args": [ ], @@ -51134,7 +53025,7 @@ }, { "name": "upstream", - "description": "Pipeline that triggered the pipeline", + "description": "Pipeline that triggered the pipeline.", "args": [ ], @@ -51148,7 +53039,7 @@ }, { "name": "user", - "description": "Pipeline user", + "description": "Pipeline user.", "args": [ ], @@ -51193,7 +53084,7 @@ "fields": [ { "name": "monthPipelinesLabels", - "description": "Labels for the monthly pipeline count", + "description": "Labels for the monthly pipeline count.", "args": [ ], @@ -51215,7 +53106,7 @@ }, { "name": "monthPipelinesSuccessful", - "description": "Total monthly successful pipeline count", + "description": "Total monthly successful pipeline count.", "args": [ ], @@ -51237,7 +53128,7 @@ }, { "name": "monthPipelinesTotals", - "description": "Total monthly pipeline count", + "description": "Total monthly pipeline count.", "args": [ ], @@ -51259,7 +53150,7 @@ }, { "name": "pipelineTimesLabels", - "description": "Pipeline times labels", + "description": "Pipeline times labels.", "args": [ ], @@ -51281,7 +53172,7 @@ }, { "name": "pipelineTimesValues", - "description": "Pipeline times", + "description": "Pipeline times.", "args": [ ], @@ -51303,7 +53194,7 @@ }, { "name": "weekPipelinesLabels", - "description": "Labels for the weekly pipeline count", + "description": "Labels for the weekly pipeline count.", "args": [ ], @@ -51325,7 +53216,7 @@ }, { "name": "weekPipelinesSuccessful", - "description": "Total weekly successful pipeline count", + "description": "Total weekly successful pipeline count.", "args": [ ], @@ -51347,7 +53238,7 @@ }, { "name": "weekPipelinesTotals", - "description": "Total weekly pipeline count", + "description": "Total weekly pipeline count.", "args": [ ], @@ -51369,7 +53260,7 @@ }, { "name": "yearPipelinesLabels", - "description": "Labels for the yearly pipeline count", + "description": "Labels for the yearly pipeline count.", "args": [ ], @@ -51391,7 +53282,7 @@ }, { "name": "yearPipelinesSuccessful", - "description": "Total yearly successful pipeline count", + "description": "Total yearly successful pipeline count.", "args": [ ], @@ -51413,7 +53304,7 @@ }, { "name": "yearPipelinesTotals", - "description": "Total yearly pipeline count", + "description": "Total yearly pipeline count.", "args": [ ], @@ -51595,7 +53486,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -52368,6 +54259,41 @@ "deprecationReason": null }, { + "name": "alertManagementPayloadFields", + "description": "Extract alert fields from payload for custom mapping", + "args": [ + { + "name": "payloadExample", + "description": "Sample payload for extracting alert fields for custom mappings.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "AlertManagementPayloadAlertField", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "allowMergeOnSkippedPipeline", "description": "If `only_allow_merge_if_pipeline_succeeds` is true, indicates if merge requests of the project can also be merged with skipped jobs", "args": [ @@ -52798,8 +54724,61 @@ "deprecationReason": null }, { + "name": "dastProfiles", + "description": "DAST Profiles associated with the project. Always returns no nodes if `dast_saved_scans` is disabled.", + "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": "DastProfileConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "dastScannerProfiles", - "description": "The DAST scanner profiles associated with the project", + "description": "The DAST scanner profiles associated with the project.", "args": [ { "name": "after", @@ -52852,7 +54831,7 @@ }, { "name": "dastSiteProfile", - "description": "DAST Site Profile associated with the project", + "description": "DAST Site Profile associated with the project.", "args": [ { "name": "id", @@ -52879,7 +54858,7 @@ }, { "name": "dastSiteProfiles", - "description": "DAST Site Profiles associated with the project", + "description": "DAST Site Profiles associated with the project.", "args": [ { "name": "after", @@ -52932,7 +54911,7 @@ }, { "name": "dastSiteValidations", - "description": "DAST Site Validations associated with the project. Will always return no nodes if `security_on_demand_scans_site_validation` is disabled", + "description": "DAST Site Validations associated with the project. Always returns no nodes if `security_on_demand_scans_site_validation` is disabled.", "args": [ { "name": "normalizedTargetUrls", @@ -55903,7 +57882,7 @@ }, { "name": "squashReadOnly", - "description": "Indicates if squash readonly is enabled", + "description": "Indicates if `squashReadOnly` is enabled", "args": [ ], @@ -55994,8 +57973,35 @@ "deprecationReason": null }, { + "name": "terraformState", + "description": "Find a single Terraform state by name.", + "args": [ + { + "name": "name", + "description": "Name of the Terraform state.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "TerraformState", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "terraformStates", - "description": "Terraform states associated with the project", + "description": "Terraform states associated with the project.", "args": [ { "name": "after", @@ -56334,7 +58340,7 @@ }, { "name": "vulnerabilityScanners", - "description": "Vulnerability scanners reported on the project vulnerabilties", + "description": "Vulnerability scanners reported on the project vulnerabilities", "args": [ { "name": "after", @@ -56708,7 +58714,7 @@ { "kind": "SCALAR", "name": "ProjectID", - "description": "Identifier of Project", + "description": "Identifier of Project.", "fields": null, "inputFields": null, "interfaces": null, @@ -58355,7 +60361,7 @@ { "kind": "SCALAR", "name": "PrometheusServiceID", - "description": "Identifier of PrometheusService", + "description": "Identifier of PrometheusService.", "fields": null, "inputFields": null, "interfaces": null, @@ -58975,8 +60981,8 @@ "deprecationReason": null }, { - "name": "packageComposerDetails", - "description": "Find a composer package", + "name": "package", + "description": "Find a package", "args": [ { "name": "id", @@ -58995,7 +61001,7 @@ ], "type": { "kind": "OBJECT", - "name": "PackageComposerDetails", + "name": "Package", "ofType": null }, "isDeprecated": false, @@ -60694,7 +62700,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -61124,7 +63130,7 @@ "fields": [ { "name": "collectedAt", - "description": "Timestamp when the evidence was collected", + "description": "Timestamp when the evidence was collected.", "args": [ ], @@ -61138,7 +63144,7 @@ }, { "name": "filepath", - "description": "URL from where the evidence can be downloaded", + "description": "URL from where the evidence can be downloaded.", "args": [ ], @@ -61152,7 +63158,7 @@ }, { "name": "id", - "description": "ID of the evidence", + "description": "ID of the evidence.", "args": [ ], @@ -61170,7 +63176,7 @@ }, { "name": "sha", - "description": "SHA1 ID of the evidence hash", + "description": "SHA1 ID of the evidence hash.", "args": [ ], @@ -61787,7 +63793,7 @@ }, { "name": "name", - "description": "The emoji name", + "description": "The emoji name.", "type": { "kind": "NON_NULL", "name": null, @@ -63288,7 +65294,7 @@ "fields": [ { "name": "downloadLocation", - "description": "Download location for the runner for the platform architecture", + "description": "Download location for the runner for the platform architecture.", "args": [ ], @@ -63306,7 +65312,7 @@ }, { "name": "name", - "description": "Name of the runner platform architecture", + "description": "Name of the runner platform architecture.", "args": [ ], @@ -63449,7 +65455,7 @@ "fields": [ { "name": "architectures", - "description": "Runner architectures supported for the platform", + "description": "Runner architectures supported for the platform.", "args": [ { "name": "after", @@ -63502,7 +65508,7 @@ }, { "name": "humanReadableName", - "description": "Human readable name of the runner platform", + "description": "Human readable name of the runner platform.", "args": [ ], @@ -63520,7 +65526,7 @@ }, { "name": "name", - "description": "Name slug of the runner platform", + "description": "Name slug of the runner platform.", "args": [ ], @@ -63663,7 +65669,7 @@ "fields": [ { "name": "installInstructions", - "description": "Instructions for installing the runner on the specified architecture", + "description": "Instructions for installing the runner on the specified architecture.", "args": [ ], @@ -63681,7 +65687,7 @@ }, { "name": "registerInstructions", - "description": "Instructions for registering the runner", + "description": "Instructions for registering the runner.", "args": [ ], @@ -63880,7 +65886,7 @@ "fields": [ { "name": "description", - "description": "Analyzer description that is displayed on the form", + "description": "Analyzer description that is displayed on the form.", "args": [ ], @@ -63894,7 +65900,7 @@ }, { "name": "enabled", - "description": "Indicates whether an analyzer is enabled", + "description": "Indicates whether an analyzer is enabled.", "args": [ ], @@ -63908,7 +65914,7 @@ }, { "name": "label", - "description": "Analyzer label used in the config UI", + "description": "Analyzer label used in the config UI.", "args": [ ], @@ -63922,7 +65928,7 @@ }, { "name": "name", - "description": "Name of the analyzer", + "description": "Name of the analyzer.", "args": [ ], @@ -63936,7 +65942,7 @@ }, { "name": "variables", - "description": "List of supported variables", + "description": "List of supported variables.", "args": [ { "name": "after", @@ -64115,7 +66121,7 @@ "inputFields": [ { "name": "name", - "description": "Name of analyzer", + "description": "Name of analyzer.", "type": { "kind": "NON_NULL", "name": null, @@ -64129,7 +66135,7 @@ }, { "name": "enabled", - "description": "State of the analyzer", + "description": "State of the analyzer.", "type": { "kind": "NON_NULL", "name": null, @@ -64143,7 +66149,7 @@ }, { "name": "variables", - "description": "List of variables for the analyzer", + "description": "List of variables for the analyzer.", "type": { "kind": "LIST", "name": null, @@ -64448,7 +66454,7 @@ "inputFields": [ { "name": "field", - "description": "CI keyword of entity", + "description": "CI keyword of entity.", "type": { "kind": "NON_NULL", "name": null, @@ -64462,7 +66468,7 @@ }, { "name": "defaultValue", - "description": "Default value that is used if value is empty", + "description": "Default value that is used if value is empty.", "type": { "kind": "NON_NULL", "name": null, @@ -64476,7 +66482,7 @@ }, { "name": "value", - "description": "Current value of the entity", + "description": "Current value of the entity.", "type": { "kind": "NON_NULL", "name": null, @@ -64501,7 +66507,7 @@ "inputFields": [ { "name": "global", - "description": "List of global entities related to SAST configuration", + "description": "List of global entities related to SAST configuration.", "type": { "kind": "LIST", "name": null, @@ -64519,7 +66525,7 @@ }, { "name": "pipeline", - "description": "List of pipeline entities related to SAST configuration", + "description": "List of pipeline entities related to SAST configuration.", "type": { "kind": "LIST", "name": null, @@ -64537,7 +66543,7 @@ }, { "name": "analyzers", - "description": "List of analyzers and related variables for the SAST configuration", + "description": "List of analyzers and related variables for the SAST configuration.", "type": { "kind": "LIST", "name": null, @@ -64900,7 +66906,7 @@ "fields": [ { "name": "apiFuzzing", - "description": "Aggregated counts for the api_fuzzing scan", + "description": "Aggregated counts for the `api_fuzzing` scan", "args": [ ], @@ -64914,7 +66920,7 @@ }, { "name": "containerScanning", - "description": "Aggregated counts for the container_scanning scan", + "description": "Aggregated counts for the `container_scanning` scan", "args": [ ], @@ -64928,7 +66934,7 @@ }, { "name": "coverageFuzzing", - "description": "Aggregated counts for the coverage_fuzzing scan", + "description": "Aggregated counts for the `coverage_fuzzing` scan", "args": [ ], @@ -64942,7 +66948,7 @@ }, { "name": "dast", - "description": "Aggregated counts for the dast scan", + "description": "Aggregated counts for the `dast` scan", "args": [ ], @@ -64956,7 +66962,7 @@ }, { "name": "dependencyScanning", - "description": "Aggregated counts for the dependency_scanning scan", + "description": "Aggregated counts for the `dependency_scanning` scan", "args": [ ], @@ -64970,7 +66976,7 @@ }, { "name": "sast", - "description": "Aggregated counts for the sast scan", + "description": "Aggregated counts for the `sast` scan", "args": [ ], @@ -64984,7 +66990,7 @@ }, { "name": "secretDetection", - "description": "Aggregated counts for the secret_detection scan", + "description": "Aggregated counts for the `secret_detection` scan", "args": [ ], @@ -65304,7 +67310,7 @@ "fields": [ { "name": "count", - "description": "Count of occurrences", + "description": "Count of occurrences.", "args": [ ], @@ -65322,7 +67328,7 @@ }, { "name": "culprit", - "description": "Culprit of the error", + "description": "Culprit of the error.", "args": [ ], @@ -65340,7 +67346,7 @@ }, { "name": "externalBaseUrl", - "description": "External Base URL of the Sentry Instance", + "description": "External Base URL of the Sentry Instance.", "args": [ ], @@ -65358,7 +67364,7 @@ }, { "name": "externalUrl", - "description": "External URL of the error", + "description": "External URL of the error.", "args": [ ], @@ -65376,7 +67382,7 @@ }, { "name": "firstReleaseLastCommit", - "description": "Commit the error was first seen", + "description": "Commit the error was first seen.", "args": [ ], @@ -65390,7 +67396,7 @@ }, { "name": "firstReleaseShortVersion", - "description": "Release short version the error was first seen", + "description": "Release short version the error was first seen.", "args": [ ], @@ -65404,7 +67410,7 @@ }, { "name": "firstReleaseVersion", - "description": "Release version the error was first seen", + "description": "Release version the error was first seen.", "args": [ ], @@ -65418,7 +67424,7 @@ }, { "name": "firstSeen", - "description": "Timestamp when the error was first seen", + "description": "Timestamp when the error was first seen.", "args": [ ], @@ -65436,7 +67442,7 @@ }, { "name": "frequency", - "description": "Last 24hr stats of the error", + "description": "Last 24hr stats of the error.", "args": [ ], @@ -65462,7 +67468,7 @@ }, { "name": "gitlabCommit", - "description": "GitLab commit SHA attributed to the Error based on the release version", + "description": "GitLab commit SHA attributed to the Error based on the release version.", "args": [ ], @@ -65476,7 +67482,7 @@ }, { "name": "gitlabCommitPath", - "description": "Path to the GitLab page for the GitLab commit attributed to the error", + "description": "Path to the GitLab page for the GitLab commit attributed to the error.", "args": [ ], @@ -65490,7 +67496,7 @@ }, { "name": "gitlabIssuePath", - "description": "URL of GitLab Issue", + "description": "URL of GitLab Issue.", "args": [ ], @@ -65504,7 +67510,7 @@ }, { "name": "id", - "description": "ID (global ID) of the error", + "description": "ID (global ID) of the error.", "args": [ ], @@ -65522,7 +67528,7 @@ }, { "name": "lastReleaseLastCommit", - "description": "Commit the error was last seen", + "description": "Commit the error was last seen.", "args": [ ], @@ -65536,7 +67542,7 @@ }, { "name": "lastReleaseShortVersion", - "description": "Release short version the error was last seen", + "description": "Release short version the error was last seen.", "args": [ ], @@ -65550,7 +67556,7 @@ }, { "name": "lastReleaseVersion", - "description": "Release version the error was last seen", + "description": "Release version the error was last seen.", "args": [ ], @@ -65564,7 +67570,7 @@ }, { "name": "lastSeen", - "description": "Timestamp when the error was last seen", + "description": "Timestamp when the error was last seen.", "args": [ ], @@ -65582,7 +67588,7 @@ }, { "name": "message", - "description": "Sentry metadata message of the error", + "description": "Sentry metadata message of the error.", "args": [ ], @@ -65596,7 +67602,7 @@ }, { "name": "sentryId", - "description": "ID (Sentry ID) of the error", + "description": "ID (Sentry ID) of the error.", "args": [ ], @@ -65614,7 +67620,7 @@ }, { "name": "sentryProjectId", - "description": "ID of the project (Sentry project)", + "description": "ID of the project (Sentry project).", "args": [ ], @@ -65632,7 +67638,7 @@ }, { "name": "sentryProjectName", - "description": "Name of the project affected by the error", + "description": "Name of the project affected by the error.", "args": [ ], @@ -65650,7 +67656,7 @@ }, { "name": "sentryProjectSlug", - "description": "Slug of the project affected by the error", + "description": "Slug of the project affected by the error.", "args": [ ], @@ -65668,7 +67674,7 @@ }, { "name": "shortId", - "description": "Short ID (Sentry ID) of the error", + "description": "Short ID (Sentry ID) of the error.", "args": [ ], @@ -65686,7 +67692,7 @@ }, { "name": "status", - "description": "Status of the error", + "description": "Status of the error.", "args": [ ], @@ -65704,7 +67710,7 @@ }, { "name": "tags", - "description": "Tags associated with the Sentry Error", + "description": "Tags associated with the Sentry Error.", "args": [ ], @@ -65722,7 +67728,7 @@ }, { "name": "title", - "description": "Title of the error", + "description": "Title of the error.", "args": [ ], @@ -65740,7 +67746,7 @@ }, { "name": "type", - "description": "Type of the error", + "description": "Type of the error.", "args": [ ], @@ -65758,7 +67764,7 @@ }, { "name": "userCount", - "description": "Count of users affected by the error", + "description": "Count of users affected by the error.", "args": [ ], @@ -65789,7 +67795,7 @@ "fields": [ { "name": "count", - "description": "Count of occurrences", + "description": "Count of occurrences.", "args": [ ], @@ -65807,7 +67813,7 @@ }, { "name": "culprit", - "description": "Culprit of the error", + "description": "Culprit of the error.", "args": [ ], @@ -65825,7 +67831,7 @@ }, { "name": "externalUrl", - "description": "External URL of the error", + "description": "External URL of the error.", "args": [ ], @@ -65843,7 +67849,7 @@ }, { "name": "firstSeen", - "description": "Timestamp when the error was first seen", + "description": "Timestamp when the error was first seen.", "args": [ ], @@ -65861,7 +67867,7 @@ }, { "name": "frequency", - "description": "Last 24hr stats of the error", + "description": "Last 24hr stats of the error.", "args": [ ], @@ -65887,7 +67893,7 @@ }, { "name": "id", - "description": "ID (global ID) of the error", + "description": "ID (global ID) of the error.", "args": [ ], @@ -65905,7 +67911,7 @@ }, { "name": "lastSeen", - "description": "Timestamp when the error was last seen", + "description": "Timestamp when the error was last seen.", "args": [ ], @@ -65923,7 +67929,7 @@ }, { "name": "message", - "description": "Sentry metadata message of the error", + "description": "Sentry metadata message of the error.", "args": [ ], @@ -65937,7 +67943,7 @@ }, { "name": "sentryId", - "description": "ID (Sentry ID) of the error", + "description": "ID (Sentry ID) of the error.", "args": [ ], @@ -65955,7 +67961,7 @@ }, { "name": "sentryProjectId", - "description": "ID of the project (Sentry project)", + "description": "ID of the project (Sentry project).", "args": [ ], @@ -65973,7 +67979,7 @@ }, { "name": "sentryProjectName", - "description": "Name of the project affected by the error", + "description": "Name of the project affected by the error.", "args": [ ], @@ -65991,7 +67997,7 @@ }, { "name": "sentryProjectSlug", - "description": "Slug of the project affected by the error", + "description": "Slug of the project affected by the error.", "args": [ ], @@ -66009,7 +68015,7 @@ }, { "name": "shortId", - "description": "Short ID (Sentry ID) of the error", + "description": "Short ID (Sentry ID) of the error.", "args": [ ], @@ -66027,7 +68033,7 @@ }, { "name": "status", - "description": "Status of the error", + "description": "Status of the error.", "args": [ ], @@ -66045,7 +68051,7 @@ }, { "name": "title", - "description": "Title of the error", + "description": "Title of the error.", "args": [ ], @@ -66063,7 +68069,7 @@ }, { "name": "type", - "description": "Type of the error", + "description": "Type of the error.", "args": [ ], @@ -66081,7 +68087,7 @@ }, { "name": "userCount", - "description": "Count of users affected by the error", + "description": "Count of users affected by the error.", "args": [ ], @@ -66112,7 +68118,7 @@ "fields": [ { "name": "detailedError", - "description": "Detailed version of a Sentry error on the project", + "description": "Detailed version of a Sentry error on the project.", "args": [ { "name": "id", @@ -66139,7 +68145,7 @@ }, { "name": "errorStackTrace", - "description": "Stack Trace of Sentry Error", + "description": "Stack Trace of Sentry Error.", "args": [ { "name": "id", @@ -66166,7 +68172,7 @@ }, { "name": "errors", - "description": "Collection of Sentry Errors", + "description": "Collection of Sentry Errors.", "args": [ { "name": "searchTerm", @@ -66239,7 +68245,7 @@ }, { "name": "externalUrl", - "description": "External URL for Sentry", + "description": "External URL for Sentry.", "args": [ ], @@ -66378,7 +68384,7 @@ "fields": [ { "name": "count", - "description": "Count of errors received since the previously recorded time", + "description": "Count of errors received since the previously recorded time.", "args": [ ], @@ -66396,7 +68402,7 @@ }, { "name": "time", - "description": "Time the error frequency stats were recorded", + "description": "Time the error frequency stats were recorded.", "args": [ ], @@ -66427,7 +68433,7 @@ "fields": [ { "name": "dateReceived", - "description": "Time the stack trace was received by Sentry", + "description": "Time the stack trace was received by Sentry.", "args": [ ], @@ -66445,7 +68451,7 @@ }, { "name": "issueId", - "description": "ID of the Sentry error", + "description": "ID of the Sentry error.", "args": [ ], @@ -66463,7 +68469,7 @@ }, { "name": "stackTraceEntries", - "description": "Stack trace entries for the Sentry error", + "description": "Stack trace entries for the Sentry error.", "args": [ ], @@ -66502,7 +68508,7 @@ "fields": [ { "name": "code", - "description": "Code number of the context", + "description": "Code number of the context.", "args": [ ], @@ -66520,7 +68526,7 @@ }, { "name": "line", - "description": "Line number of the context", + "description": "Line number of the context.", "args": [ ], @@ -66551,7 +68557,7 @@ "fields": [ { "name": "col", - "description": "Function in which the Sentry error occurred", + "description": "Function in which the Sentry error occurred.", "args": [ ], @@ -66565,7 +68571,7 @@ }, { "name": "fileName", - "description": "File in which the Sentry error occurred", + "description": "File in which the Sentry error occurred.", "args": [ ], @@ -66579,7 +68585,7 @@ }, { "name": "function", - "description": "Function in which the Sentry error occurred", + "description": "Function in which the Sentry error occurred.", "args": [ ], @@ -66593,7 +68599,7 @@ }, { "name": "line", - "description": "Function in which the Sentry error occurred", + "description": "Function in which the Sentry error occurred.", "args": [ ], @@ -66607,7 +68613,7 @@ }, { "name": "traceContext", - "description": "Context of the Sentry error", + "description": "Context of the Sentry error.", "args": [ ], @@ -66677,7 +68683,7 @@ "fields": [ { "name": "level", - "description": "Severity level of the Sentry Error", + "description": "Severity level of the Sentry Error.", "args": [ ], @@ -66691,7 +68697,7 @@ }, { "name": "logger", - "description": "Logger of the Sentry Error", + "description": "Logger of the Sentry Error.", "args": [ ], @@ -68012,7 +70018,7 @@ }, { "name": "loadAsync", - "description": "Shows whether the blob content is loaded async", + "description": "Shows whether the blob content is loaded asynchronously", "args": [ ], @@ -68219,7 +70225,7 @@ { "kind": "SCALAR", "name": "SnippetID", - "description": "Identifier of Snippet", + "description": "Identifier of Snippet.", "fields": null, "inputFields": null, "interfaces": null, @@ -68658,7 +70664,7 @@ "fields": [ { "name": "buttonTitle", - "description": "Title for the button, for example: Retry this job", + "description": "Title for the button, for example: Retry this job.", "args": [ ], @@ -68672,7 +70678,7 @@ }, { "name": "icon", - "description": "Icon used in the action button", + "description": "Icon used in the action button.", "args": [ ], @@ -68686,7 +70692,7 @@ }, { "name": "method", - "description": "Method for the action, for example: :post", + "description": "Method for the action, for example: :post.", "args": [ ], @@ -68700,7 +70706,7 @@ }, { "name": "path", - "description": "Path for the action", + "description": "Path for the action.", "args": [ ], @@ -68714,7 +70720,7 @@ }, { "name": "title", - "description": "Title for the action, for example: Retry", + "description": "Title for the action, for example: Retry.", "args": [ ], @@ -68823,7 +70829,7 @@ }, { "name": "sha", - "description": "Last commit sha for the entry", + "description": "Last commit SHA for the entry", "args": [ ], @@ -69192,7 +71198,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -69406,7 +71412,7 @@ { "kind": "SCALAR", "name": "TerraformStateID", - "description": "Identifier of Terraform::State", + "description": "Identifier of Terraform::State.", "fields": null, "inputFields": null, "interfaces": null, @@ -70617,11 +72623,11 @@ { "kind": "OBJECT", "name": "Todo", - "description": "Representing a todo entry", + "description": "Representing a to-do entry", "fields": [ { "name": "action", - "description": "Action of the todo", + "description": "Action of the to-do item", "args": [ ], @@ -70639,7 +72645,7 @@ }, { "name": "author", - "description": "The author of this todo", + "description": "The author of this to-do item", "args": [ ], @@ -70657,7 +72663,7 @@ }, { "name": "body", - "description": "Body of the todo", + "description": "Body of the to-do item", "args": [ ], @@ -70675,7 +72681,7 @@ }, { "name": "createdAt", - "description": "Timestamp this todo was created", + "description": "Timestamp this to-do item was created", "args": [ ], @@ -70693,7 +72699,7 @@ }, { "name": "group", - "description": "Group this todo is associated with", + "description": "Group this to-do item is associated with", "args": [ ], @@ -70707,7 +72713,7 @@ }, { "name": "id", - "description": "ID of the todo", + "description": "ID of the to-do item", "args": [ ], @@ -70725,7 +72731,7 @@ }, { "name": "project", - "description": "The project this todo is associated with", + "description": "The project this to-do item is associated with", "args": [ ], @@ -70739,7 +72745,7 @@ }, { "name": "state", - "description": "State of the todo", + "description": "State of the to-do item", "args": [ ], @@ -70757,7 +72763,7 @@ }, { "name": "targetType", - "description": "Target type of the todo", + "description": "Target type of the to-do item", "args": [ ], @@ -70983,7 +72989,7 @@ }, { "name": "todo", - "description": "The to-do created.", + "description": "The to-do item created.", "args": [ ], @@ -71051,7 +73057,7 @@ { "kind": "SCALAR", "name": "TodoID", - "description": "Identifier of Todo", + "description": "Identifier of Todo.", "fields": null, "inputFields": null, "interfaces": null, @@ -71066,7 +73072,7 @@ "inputFields": [ { "name": "id", - "description": "The global ID of the todo to mark as done.", + "description": "The global ID of the to-do item to mark as done.", "type": { "kind": "NON_NULL", "name": null, @@ -71140,7 +73146,7 @@ }, { "name": "todo", - "description": "The requested todo.", + "description": "The requested to-do item.", "args": [ ], @@ -71172,7 +73178,7 @@ "inputFields": [ { "name": "id", - "description": "The global ID of the todo to restore.", + "description": "The global ID of the to-do item to restore.", "type": { "kind": "NON_NULL", "name": null, @@ -71207,7 +73213,7 @@ "inputFields": [ { "name": "ids", - "description": "The global IDs of the todos to restore (a maximum of 50 is supported at once).", + "description": "The global IDs of the to-do items to restore (a maximum of 50 is supported at once).", "type": { "kind": "NON_NULL", "name": null, @@ -71289,7 +73295,7 @@ }, { "name": "todos", - "description": "Updated todos.", + "description": "Updated to-do items.", "args": [ ], @@ -71315,7 +73321,7 @@ }, { "name": "updatedIds", - "description": "The IDs of the updated todo items. Deprecated in 13.2: Use todos.", + "description": "The IDs of the updated to-do items. Deprecated in 13.2: Use to-do items.", "args": [ ], @@ -71337,7 +73343,7 @@ } }, "isDeprecated": true, - "deprecationReason": "Use todos. Deprecated in 13.2." + "deprecationReason": "Use to-do items. Deprecated in 13.2." } ], "inputFields": null, @@ -71394,7 +73400,7 @@ }, { "name": "todo", - "description": "The requested todo.", + "description": "The requested to-do item.", "args": [ ], @@ -71491,7 +73497,7 @@ { "kind": "SCALAR", "name": "TodoableID", - "description": "Identifier of Todoable", + "description": "Identifier of Todoable.", "fields": null, "inputFields": null, "interfaces": null, @@ -71566,7 +73572,7 @@ }, { "name": "todos", - "description": "Updated todos.", + "description": "Updated to-do items.", "args": [ ], @@ -71592,7 +73598,7 @@ }, { "name": "updatedIds", - "description": "Ids of the updated todos. Deprecated in 13.2: Use todos.", + "description": "IDs of the updated to-do items. Deprecated in 13.2: Use to-do items.", "args": [ ], @@ -71614,7 +73620,7 @@ } }, "isDeprecated": true, - "deprecationReason": "Use todos. Deprecated in 13.2." + "deprecationReason": "Use to-do items. Deprecated in 13.2." } ], "inputFields": null, @@ -71646,7 +73652,7 @@ }, { "name": "name", - "description": "The emoji name", + "description": "The emoji name.", "type": { "kind": "NON_NULL", "name": null, @@ -72035,7 +74041,7 @@ }, { "name": "sha", - "description": "Last commit sha for the entry", + "description": "Last commit SHA for the entry", "args": [ ], @@ -72392,7 +74398,7 @@ }, { "name": "todo", - "description": "The todo after mutation.", + "description": "The to-do item after mutation.", "args": [ ], @@ -72560,7 +74566,7 @@ }, { "name": "hideBacklogList", - "description": "Whether or not backlog list is hidden", + "description": "Whether or not backlog list is hidden.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -72570,7 +74576,7 @@ }, { "name": "hideClosedList", - "description": "Whether or not closed list is hidden", + "description": "Whether or not closed list is hidden.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -73010,7 +75016,7 @@ }, { "name": "enabled", - "description": "Indicates whether this container expiration policy is enabled", + "description": "Indicates whether this container expiration policy is enabled.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -73020,7 +75026,7 @@ }, { "name": "cadence", - "description": "This container expiration policy schedule", + "description": "This container expiration policy schedule.", "type": { "kind": "ENUM", "name": "ContainerExpirationPolicyCadenceEnum", @@ -73030,7 +75036,7 @@ }, { "name": "olderThan", - "description": "Tags older that this will expire", + "description": "Tags older that this will expire.", "type": { "kind": "ENUM", "name": "ContainerExpirationPolicyOlderThanEnum", @@ -73040,7 +75046,7 @@ }, { "name": "keepN", - "description": "Number of tags to retain", + "description": "Number of tags to retain.", "type": { "kind": "ENUM", "name": "ContainerExpirationPolicyKeepEnum", @@ -73050,7 +75056,7 @@ }, { "name": "nameRegex", - "description": "Tags with names matching this regex pattern will expire", + "description": "Tags with names matching this regex pattern will expire.", "type": { "kind": "SCALAR", "name": "UntrustedRegexp", @@ -73060,7 +75066,7 @@ }, { "name": "nameRegexKeep", - "description": "Tags with names matching this regex pattern will be preserved", + "description": "Tags with names matching this regex pattern will be preserved.", "type": { "kind": "SCALAR", "name": "UntrustedRegexp", @@ -74504,6 +76510,26 @@ "fields": null, "inputFields": [ { + "name": "captchaResponse", + "description": "A valid CAPTCHA response value obtained by using the provided captchaSiteKey with a CAPTCHA API to present a challenge to be solved on the client. Required to resubmit if the previous operation returned \"NeedsCaptchaResponse: true\".", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "spamLogId", + "description": "The spam log ID which must be passed along with a valid CAPTCHA response for the operation to be completed. Required to resubmit if the previous operation returned \"NeedsCaptchaResponse: true\".", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { "name": "id", "description": "The global ID of the snippet to update.", "type": { @@ -74586,6 +76612,20 @@ "description": "Autogenerated return type of UpdateSnippet", "fields": [ { + "name": "captchaSiteKey", + "description": "The CAPTCHA site key which must be used to render a challenge for the user to solve to obtain a valid captchaResponse value. Included only when an operation was not completed because \"NeedsCaptchaResponse\" is true.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", "args": [ @@ -74626,6 +76666,20 @@ "deprecationReason": null }, { + "name": "needsCaptchaResponse", + "description": "Indicates whether the operation was detected as possible spam and not completed. If CAPTCHA is enabled, the request must be resubmitted with a valid CAPTCHA response and spam_log_id included for the operation to be completed. Included only when an operation was not completed because \"NeedsCaptchaResponse\" is true.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "snippet", "description": "The snippet after mutation.", "args": [ @@ -74641,7 +76695,7 @@ }, { "name": "spam", - "description": "Indicates whether the operation returns a record detected as spam.", + "description": "Indicates whether the operation was detected as definite spam. There is no option to resubmit the request with a CAPTCHA response.", "args": [ ], @@ -74652,6 +76706,20 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "spamLogId", + "description": "The spam log ID which must be passed along with a valid CAPTCHA response for an operation to be completed. Included only when an operation was not completed because \"NeedsCaptchaResponse\" is true.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -75721,7 +77789,7 @@ }, { "name": "todos", - "description": "Todos of the user", + "description": "To-do items of the user", "args": [ { "name": "action", @@ -76079,7 +78147,7 @@ { "kind": "SCALAR", "name": "UserID", - "description": "Identifier of User", + "description": "Identifier of User.", "fields": null, "inputFields": null, "interfaces": null, @@ -76716,7 +78784,7 @@ { "kind": "SCALAR", "name": "VulnerabilitiesExternalIssueLinkID", - "description": "Identifier of Vulnerabilities::ExternalIssueLink", + "description": "Identifier of Vulnerabilities::ExternalIssueLink.", "fields": null, "inputFields": null, "interfaces": null, @@ -76771,6 +78839,32 @@ "deprecationReason": null }, { + "name": "details", + "description": "Details of the vulnerability", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "UNION", + "name": "VulnerabilityDetail", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "detectedAt", "description": "Timestamp of when the vulnerability was first detected", "args": [ @@ -77516,6 +79610,1259 @@ "possibleTypes": null }, { + "kind": "UNION", + "name": "VulnerabilityDetail", + "description": "Represents a vulnerability detail field. The fields with data will depend on the vulnerability detail type", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": [ + { + "kind": "OBJECT", + "name": "VulnerabilityDetailBase", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailBoolean", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailCode", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailCommit", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailDiff", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailFileLocation", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailInt", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailList", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailMarkdown", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailModuleLocation", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailTable", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailText", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailUrl", + "ofType": null + } + ] + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailBase", + "description": "Represents the vulnerability details base", + "fields": [ + { + "name": "description", + "description": "Description of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fieldName", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "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": "VulnerabilityDetailBoolean", + "description": "Represents the vulnerability details boolean value", + "fields": [ + { + "name": "description", + "description": "Description of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fieldName", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "value", + "description": "Value of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailCode", + "description": "Represents the vulnerability details code field", + "fields": [ + { + "name": "description", + "description": "Description of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fieldName", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "lang", + "description": "Language of the code.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "value", + "description": "Source code.", + "args": [ + + ], + "type": { + "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": "VulnerabilityDetailCommit", + "description": "Represents the vulnerability details commit field", + "fields": [ + { + "name": "description", + "description": "Description of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fieldName", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "value", + "description": "The commit SHA value.", + "args": [ + + ], + "type": { + "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": "VulnerabilityDetailDiff", + "description": "Represents the vulnerability details diff field", + "fields": [ + { + "name": "after", + "description": "Value of the field after the change.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "before", + "description": "Value of the field before the change.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "description", + "description": "Description of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fieldName", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "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": "VulnerabilityDetailFileLocation", + "description": "Represents the vulnerability details location within a file in the project", + "fields": [ + { + "name": "description", + "description": "Description of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fieldName", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fileName", + "description": "File name.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "lineEnd", + "description": "End line number of the file location.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "lineStart", + "description": "Start line number of the file location.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "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": "VulnerabilityDetailInt", + "description": "Represents the vulnerability details integer value", + "fields": [ + { + "name": "description", + "description": "Description of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fieldName", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "value", + "description": "Value of the field.", + "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": "VulnerabilityDetailList", + "description": "Represents the vulnerability details list value", + "fields": [ + { + "name": "description", + "description": "Description of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fieldName", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "items", + "description": "List of details.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "UNION", + "name": "VulnerabilityDetail", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "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": "VulnerabilityDetailMarkdown", + "description": "Represents the vulnerability details Markdown field", + "fields": [ + { + "name": "description", + "description": "Description of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fieldName", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "value", + "description": "Value of the Markdown field.", + "args": [ + + ], + "type": { + "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": "VulnerabilityDetailModuleLocation", + "description": "Represents the vulnerability details location within a file in the project", + "fields": [ + { + "name": "description", + "description": "Description of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fieldName", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "moduleName", + "description": "Module name.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "offset", + "description": "Offset of the module location.", + "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": "VulnerabilityDetailTable", + "description": "Represents the vulnerability details table value", + "fields": [ + { + "name": "description", + "description": "Description of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fieldName", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "headers", + "description": "Table headers.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "UNION", + "name": "VulnerabilityDetail", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "rows", + "description": "Table rows.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "UNION", + "name": "VulnerabilityDetail", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDetailText", + "description": "Represents the vulnerability details text field", + "fields": [ + { + "name": "description", + "description": "Description of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fieldName", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "value", + "description": "Value of the text field.", + "args": [ + + ], + "type": { + "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": "VulnerabilityDetailUrl", + "description": "Represents the vulnerability details URL field", + "fields": [ + { + "name": "description", + "description": "Description of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fieldName", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "href", + "description": "Href of the URL.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the field.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "text", + "description": "Text of the URL.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "INPUT_OBJECT", "name": "VulnerabilityDismissInput", "description": "Autogenerated input type of VulnerabilityDismiss", @@ -78194,7 +81541,7 @@ { "kind": "SCALAR", "name": "VulnerabilityID", - "description": "Identifier of Vulnerability", + "description": "Identifier of Vulnerability.", "fields": null, "inputFields": null, "interfaces": null, @@ -78574,6 +81921,20 @@ "description": "Represents the location of a vulnerability found by a Coverage Fuzzing scan", "fields": [ { + "name": "blobPath", + "description": "Blob path to the vulnerable file", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "endLine", "description": "Number of the last relevant line in the vulnerable file", "args": [ @@ -78726,6 +82087,20 @@ "description": "Represents the location of a vulnerability found by a dependency security scan", "fields": [ { + "name": "blobPath", + "description": "Blob path to the vulnerable file", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "dependency", "description": "Dependency containing the vulnerability", "args": [ @@ -78767,6 +82142,20 @@ "description": "Represents the location of a vulnerability found by a SAST scan", "fields": [ { + "name": "blobPath", + "description": "Blob path to the vulnerable file", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "endLine", "description": "Number of the last relevant line in the vulnerable file", "args": [ @@ -78850,6 +82239,20 @@ "description": "Represents the location of a vulnerability found by a secret detection scan", "fields": [ { + "name": "blobPath", + "description": "Blob path to the vulnerable file", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "endLine", "description": "Number of the last relevant line in the vulnerable file", "args": [ diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index c098de16ef6..1cf8371f35c 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -41,8 +41,8 @@ Represents the access level of a relationship between a User and object that it | Field | Type | Description | | ----- | ---- | ----------- | -| `integerValue` | Int | Integer representation of access level | -| `stringValue` | AccessLevelEnum | String representation of access level | +| `integerValue` | Int | Integer representation of access level. | +| `stringValue` | AccessLevelEnum | String representation of access level. | ### AddAwardEmojiPayload @@ -80,30 +80,30 @@ Describes an alert from the project's Alert Management. | Field | Type | Description | | ----- | ---- | ----------- | -| `assignees` | UserConnection | Assignees of the alert | -| `createdAt` | Time | Timestamp the alert was created | -| `description` | String | Description of the alert | -| `details` | JSON | Alert details | -| `detailsUrl` | String! | The URL of the alert detail page | +| `assignees` | UserConnection | Assignees of the alert. | +| `createdAt` | Time | Timestamp the alert was created. | +| `description` | String | Description of the alert. | +| `details` | JSON | Alert details. | +| `detailsUrl` | String! | The URL of the alert detail page. | | `discussions` | DiscussionConnection! | All discussions on this noteable | -| `endedAt` | Time | Timestamp the alert ended | -| `environment` | Environment | Environment for the alert | -| `eventCount` | Int | Number of events of this alert | -| `hosts` | String! => Array | List of hosts the alert came from | -| `iid` | ID! | Internal ID of the alert | -| `issueIid` | ID | Internal ID of the GitLab issue attached to the alert | -| `metricsDashboardUrl` | String | URL for metrics embed for the alert | -| `monitoringTool` | String | Monitoring tool the alert came from | +| `endedAt` | Time | Timestamp the alert ended. | +| `environment` | Environment | Environment for the alert. | +| `eventCount` | Int | Number of events of this alert. | +| `hosts` | String! => Array | List of hosts the alert came from. | +| `iid` | ID! | Internal ID of the alert. | +| `issueIid` | ID | Internal ID of the GitLab issue attached to the alert. | +| `metricsDashboardUrl` | String | URL for metrics embed for the alert. | +| `monitoringTool` | String | Monitoring tool the alert came from. | | `notes` | NoteConnection! | All notes on this noteable | -| `prometheusAlert` | PrometheusAlert | The alert condition for Prometheus | -| `runbook` | String | Runbook for the alert as defined in alert details | -| `service` | String | Service the alert came from | -| `severity` | AlertManagementSeverity | Severity of the alert | -| `startedAt` | Time | Timestamp the alert was raised | -| `status` | AlertManagementStatus | Status of the alert | -| `title` | String | Title of the alert | -| `todos` | TodoConnection | Todos of the current user for the alert | -| `updatedAt` | Time | Timestamp the alert was last updated | +| `prometheusAlert` | PrometheusAlert | The alert condition for Prometheus. | +| `runbook` | String | Runbook for the alert as defined in alert details. | +| `service` | String | Service the alert came from. | +| `severity` | AlertManagementSeverity | Severity of the alert. | +| `startedAt` | Time | Timestamp the alert was raised. | +| `status` | AlertManagementStatus | Status of the alert. | +| `title` | String | Title of the alert. | +| `todos` | TodoConnection | To-do items of the current user for the alert. | +| `updatedAt` | Time | Timestamp the alert was last updated. | ### AlertManagementAlertStatusCountsType @@ -112,9 +112,9 @@ Represents total number of alerts for the represented categories. | Field | Type | Description | | ----- | ---- | ----------- | | `acknowledged` | Int | Number of alerts with status ACKNOWLEDGED for the project | -| `all` | Int | Total number of alerts for the project | +| `all` | Int | Total number of alerts for the project. | | `ignored` | Int | Number of alerts with status IGNORED for the project | -| `open` | Int | Number of alerts with status TRIGGERED or ACKNOWLEDGED for the project | +| `open` | Int | Number of alerts with status TRIGGERED or ACKNOWLEDGED for the project. | | `resolved` | Int | Number of alerts with status RESOLVED for the project | | `triggered` | Int | Number of alerts with status TRIGGERED for the project | @@ -124,13 +124,23 @@ An endpoint and credentials used to accept alerts for a project. | Field | Type | Description | | ----- | ---- | ----------- | -| `active` | Boolean | Whether the endpoint is currently accepting alerts | -| `apiUrl` | String | URL at which Prometheus metrics can be queried to populate the metrics dashboard | -| `id` | ID! | ID of the integration | -| `name` | String | Name of the integration | -| `token` | String | Token used to authenticate alert notification requests | -| `type` | AlertManagementIntegrationType! | Type of integration | -| `url` | String | Endpoint which accepts alert notifications | +| `active` | Boolean | Whether the endpoint is currently accepting alerts. | +| `apiUrl` | String | URL at which Prometheus metrics can be queried to populate the metrics dashboard. | +| `id` | ID! | ID of the integration. | +| `name` | String | Name of the integration. | +| `token` | String | Token used to authenticate alert notification requests. | +| `type` | AlertManagementIntegrationType! | Type of integration. | +| `url` | String | Endpoint which accepts alert notifications. | + +### AlertManagementPayloadAlertField + +Parsed field from an alert used for custom mappings. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `label` | String | Human-readable label of the payload path. | +| `path` | String! => Array | Path to value inside payload JSON. | +| `type` | AlertManagementPayloadAlertFieldType | Type of the parsed value. | ### AlertManagementPrometheusIntegration @@ -138,13 +148,13 @@ An endpoint and credentials used to accept Prometheus alerts for a project. | Field | Type | Description | | ----- | ---- | ----------- | -| `active` | Boolean | Whether the endpoint is currently accepting alerts | -| `apiUrl` | String | URL at which Prometheus metrics can be queried to populate the metrics dashboard | -| `id` | ID! | ID of the integration | -| `name` | String | Name of the integration | -| `token` | String | Token used to authenticate alert notification requests | -| `type` | AlertManagementIntegrationType! | Type of integration | -| `url` | String | Endpoint which accepts alert notifications | +| `active` | Boolean | Whether the endpoint is currently accepting alerts. | +| `apiUrl` | String | URL at which Prometheus metrics can be queried to populate the metrics dashboard. | +| `id` | ID! | ID of the integration. | +| `name` | String | Name of the integration. | +| `token` | String | Token used to authenticate alert notification requests. | +| `type` | AlertManagementIntegrationType! | Type of integration. | +| `url` | String | Endpoint which accepts alert notifications. | ### AlertSetAssigneesPayload @@ -156,7 +166,7 @@ Autogenerated return type of AlertSetAssignees. | `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. | +| `todo` | Todo | The to-do item after mutation. | ### AlertTodoCreatePayload @@ -168,7 +178,7 @@ Autogenerated return type of AlertTodoCreate. | `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. | +| `todo` | Todo | The to-do item after mutation. | ### AwardEmoji @@ -176,12 +186,12 @@ An emoji awarded by a user. | Field | Type | Description | | ----- | ---- | ----------- | -| `description` | String! | The emoji description | -| `emoji` | String! | The emoji as an icon | -| `name` | String! | The emoji name | -| `unicode` | String! | The emoji in unicode | -| `unicodeVersion` | String! | The unicode version for this emoji | -| `user` | User! | The user who awarded the emoji | +| `description` | String! | The emoji description. | +| `emoji` | String! | The emoji as an icon. | +| `name` | String! | The emoji name. | +| `unicode` | String! | The emoji in Unicode. | +| `unicodeVersion` | String! | The Unicode version for this emoji. | +| `user` | User! | The user who awarded the emoji. | ### AwardEmojiAddPayload @@ -231,7 +241,7 @@ Autogenerated return type of AwardEmojiToggle. | `mode` | String | Blob mode in numeric format | | `name` | String! | Name of the entry | | `path` | String! | Path of the entry | -| `sha` | String! | Last commit sha for the entry | +| `sha` | String! | Last commit SHA for the entry | | `type` | EntryType! | Type of tree entry | | `webPath` | String | Web path of the blob | | `webUrl` | String | Web URL of the blob | @@ -244,14 +254,14 @@ Represents a project or group board. | ----- | ---- | ----------- | | `assignee` | User | The board assignee | | `epics` | BoardEpicConnection | Epics associated with board issues | -| `hideBacklogList` | Boolean | Whether or not backlog list is hidden | -| `hideClosedList` | Boolean | Whether or not closed list is hidden | -| `id` | ID! | ID (global ID) of the board | +| `hideBacklogList` | Boolean | Whether or not backlog list is hidden. | +| `hideClosedList` | Boolean | Whether or not closed list is hidden. | +| `id` | ID! | ID (global ID) of the board. | | `iteration` | Iteration | The board iteration. | | `labels` | LabelConnection | Labels of the board | -| `lists` | BoardListConnection | Lists of the board | +| `lists` | BoardListConnection | Lists of the board. | | `milestone` | Milestone | The board milestone | -| `name` | String | Name of the board | +| `name` | String | Name of the board. | | `webPath` | String! | Web path of the board. | | `webUrl` | String! | Web URL of the board. | | `weight` | Int | Weight of the board | @@ -262,51 +272,52 @@ Represents an epic on an issue board. | Field | Type | Description | | ----- | ---- | ----------- | -| `author` | User! | Author of the epic | -| `children` | EpicConnection | Children (sub-epics) of the epic | -| `closedAt` | Time | Timestamp of when the epic was closed | -| `confidential` | Boolean | Indicates if the epic is confidential | -| `createdAt` | Time | Timestamp of when the epic was created | -| `currentUserTodos` | TodoConnection! | Todos for the current user | -| `descendantCounts` | EpicDescendantCount | Number of open and closed descendant epics and issues | -| `descendantWeightSum` | EpicDescendantWeights | Total weight of open and closed issues in the epic and its descendants | -| `description` | String | Description of the epic | +| `author` | User! | Author of the epic. | +| `awardEmoji` | AwardEmojiConnection | A list of award emojis associated with the epic. | +| `children` | EpicConnection | Children (sub-epics) of the epic. | +| `closedAt` | Time | Timestamp of when the epic was closed. | +| `confidential` | Boolean | Indicates if the epic is confidential. | +| `createdAt` | Time | Timestamp of when the epic was created. | +| `currentUserTodos` | TodoConnection! | To-do items for the current user. | +| `descendantCounts` | EpicDescendantCount | Number of open and closed descendant epics and issues. | +| `descendantWeightSum` | EpicDescendantWeights | Total weight of open and closed issues in the epic and its descendants. | +| `description` | String | Description of the epic. | | `discussions` | DiscussionConnection! | All discussions on this noteable | -| `downvotes` | Int! | Number of downvotes the epic has received | -| `dueDate` | Time | Due date of the epic | -| `dueDateFixed` | Time | Fixed due date of the epic | -| `dueDateFromMilestones` | Time | Inherited due date of the epic from milestones | -| `dueDateIsFixed` | Boolean | Indicates if the due date has been manually set | -| `group` | Group! | Group to which the epic belongs | -| `hasChildren` | Boolean! | Indicates if the epic has children | -| `hasIssues` | Boolean! | Indicates if the epic has direct issues | -| `hasParent` | Boolean! | Indicates if the epic has a parent epic | -| `healthStatus` | EpicHealthStatus | Current health status of the epic | -| `id` | ID! | ID of the epic | -| `iid` | ID! | Internal ID of the epic | -| `issues` | EpicIssueConnection | A list of issues associated with the epic | -| `labels` | LabelConnection | Labels assigned to the epic | +| `downvotes` | Int! | Number of downvotes the epic has received. | +| `dueDate` | Time | Due date of the epic. | +| `dueDateFixed` | Time | Fixed due date of the epic. | +| `dueDateFromMilestones` | Time | Inherited due date of the epic from milestones. | +| `dueDateIsFixed` | Boolean | Indicates if the due date has been manually set. | +| `group` | Group! | Group to which the epic belongs. | +| `hasChildren` | Boolean! | Indicates if the epic has children. | +| `hasIssues` | Boolean! | Indicates if the epic has direct issues. | +| `hasParent` | Boolean! | Indicates if the epic has a parent epic. | +| `healthStatus` | EpicHealthStatus | Current health status of the epic. | +| `id` | ID! | ID of the epic. | +| `iid` | ID! | Internal ID of the epic. | +| `issues` | EpicIssueConnection | A list of issues associated with the epic. | +| `labels` | LabelConnection | Labels assigned to the epic. | | `notes` | NoteConnection! | All notes on this noteable | -| `parent` | Epic | Parent epic of the epic | -| `participants` | UserConnection | List of participants for the epic | -| `reference` | String! | Internal reference of the epic. Returned in shortened format by default | -| `relationPath` | String | URI path of the epic-issue relationship | -| `relativePosition` | Int | The relative position of the epic in the epic tree | -| `startDate` | Time | Start date of the epic | -| `startDateFixed` | Time | Fixed start date of the epic | -| `startDateFromMilestones` | Time | Inherited start date of the epic from milestones | -| `startDateIsFixed` | Boolean | Indicates if the start date has been manually set | -| `state` | EpicState! | State of the epic | -| `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the epic | -| `title` | String | Title of the epic | -| `updatedAt` | Time | Timestamp of when the epic was updated | -| `upvotes` | Int! | Number of upvotes the epic has received | -| `userDiscussionsCount` | Int! | Number of user discussions in the epic | -| `userNotesCount` | Int! | Number of user notes of the epic | +| `parent` | Epic | Parent epic of the epic. | +| `participants` | UserConnection | List of participants for the epic. | +| `reference` | String! | Internal reference of the epic. Returned in shortened format by default. | +| `relationPath` | String | URI path of the epic-issue relationship. | +| `relativePosition` | Int | The relative position of the epic in the epic tree. | +| `startDate` | Time | Start date of the epic. | +| `startDateFixed` | Time | Fixed start date of the epic. | +| `startDateFromMilestones` | Time | Inherited start date of the epic from milestones. | +| `startDateIsFixed` | Boolean | Indicates if the start date has been manually set. | +| `state` | EpicState! | State of the epic. | +| `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the epic. | +| `title` | String | Title of the epic. | +| `updatedAt` | Time | Timestamp of when the epic was updated. | +| `upvotes` | Int! | Number of upvotes the epic has received. | +| `userDiscussionsCount` | Int! | Number of user discussions in the epic. | +| `userNotesCount` | Int! | Number of user notes of the epic. | | `userPermissions` | EpicPermissions! | Permissions for the current user on the resource | | `userPreferences` | BoardEpicUserPreferences | User preferences for the epic on the issue board | -| `webPath` | String! | Web path of the epic | -| `webUrl` | String! | Web URL of the epic | +| `webPath` | String! | Web path of the epic. | +| `webUrl` | String! | Web URL of the epic. | ### BoardEpicUserPreferences @@ -323,19 +334,19 @@ Represents a list for an issue board. | 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 | -| `issues` | IssueConnection | Board issues | -| `issuesCount` | Int | Count of issues in the list | +| `collapsed` | Boolean | Indicates if list is collapsed for this user. | +| `id` | ID! | ID (global ID) of the list. | +| `issues` | IssueConnection | Board issues. | +| `issuesCount` | Int | Count of issues in the list. | | `iteration` | Iteration | Iteration of the list | -| `label` | Label | Label of the list | +| `label` | Label | Label of the list. | | `limitMetric` | ListLimitMetric | The current limit metric for the list | -| `listType` | String! | Type of the list | +| `listType` | String! | Type of the list. | | `maxIssueCount` | Int | Maximum number of issues in the list | | `maxIssueWeight` | Int | Maximum weight of issues in the list | | `milestone` | Milestone | Milestone of the list | -| `position` | Int | Position of list within the board | -| `title` | String! | Title of the list | +| `position` | Int | Position of list within the board. | +| `title` | String! | Title of the list. | | `totalWeight` | Int | Total weight of all issues in the list | ### BoardListCreatePayload @@ -362,8 +373,8 @@ Autogenerated return type of BoardListUpdateLimitMetrics. | Field | Type | Description | | ----- | ---- | ----------- | -| `commit` | Commit | Commit for the branch | -| `name` | String! | Name of the branch | +| `commit` | Commit | Commit for the branch. | +| `name` | String! | Name of the branch. | ### BurnupChartDailyTotals @@ -396,18 +407,18 @@ Autogenerated return type of CiCdSettingsUpdate. | Field | Type | Description | | ----- | ---- | ----------- | -| `errors` | String! => Array | Linting errors | -| `mergedYaml` | String | Merged CI config YAML | -| `stages` | CiConfigStageConnection | Stages of the pipeline | -| `status` | CiConfigStatus | Status of linting, can be either valid or invalid | +| `errors` | String! => Array | Linting errors. | +| `mergedYaml` | String | Merged CI configuration YAML. | +| `stages` | CiConfigStageConnection | Stages of the pipeline. | +| `status` | CiConfigStatus | Status of linting, can be either valid or invalid. | ### CiConfigGroup | Field | Type | Description | | ----- | ---- | ----------- | -| `jobs` | CiConfigJobConnection | Jobs in group | -| `name` | String | Name of the job group | -| `size` | Int | Size of the job group | +| `jobs` | CiConfigJobConnection | Jobs in group. | +| `name` | String | Name of the job group. | +| `size` | Int | Size of the job group. | ### CiConfigJob @@ -437,49 +448,49 @@ Autogenerated return type of CiCdSettingsUpdate. | Field | Type | Description | | ----- | ---- | ----------- | -| `name` | String | Name of the need | +| `name` | String | Name of the need. | ### CiConfigStage | Field | Type | Description | | ----- | ---- | ----------- | -| `groups` | CiConfigGroupConnection | Groups of jobs for the stage | -| `name` | String | Name of the stage | +| `groups` | CiConfigGroupConnection | Groups of jobs for the stage. | +| `name` | String | Name of the stage. | ### CiGroup | Field | Type | Description | | ----- | ---- | ----------- | -| `detailedStatus` | DetailedStatus | Detailed status of the group | -| `jobs` | CiJobConnection | Jobs in group | -| `name` | String | Name of the job group | -| `size` | Int | Size of the group | +| `detailedStatus` | DetailedStatus | Detailed status of the group. | +| `jobs` | CiJobConnection | Jobs in group. | +| `name` | String | Name of the job group. | +| `size` | Int | Size of the group. | ### CiJob | Field | Type | Description | | ----- | ---- | ----------- | -| `artifacts` | CiJobArtifactConnection | Artifacts generated by the job | -| `detailedStatus` | DetailedStatus | Detailed status of the job | -| `name` | String | Name of the job | -| `needs` | CiBuildNeedConnection | References to builds that must complete before the jobs run | -| `pipeline` | Pipeline | Pipeline the job belongs to | -| `scheduledAt` | Time | Schedule for the build | +| `artifacts` | CiJobArtifactConnection | Artifacts generated by the job. | +| `detailedStatus` | DetailedStatus | Detailed status of the job. | +| `name` | String | Name of the job. | +| `needs` | CiBuildNeedConnection | References to builds that must complete before the jobs run. | +| `pipeline` | Pipeline | Pipeline the job belongs to. | +| `scheduledAt` | Time | Schedule for the build. | ### CiJobArtifact | Field | Type | Description | | ----- | ---- | ----------- | -| `downloadPath` | String | URL for downloading the artifact's file | -| `fileType` | JobArtifactFileType | File type of the artifact | +| `downloadPath` | String | URL for downloading the artifact's file. | +| `fileType` | JobArtifactFileType | File type of the artifact. | ### CiStage | Field | Type | Description | | ----- | ---- | ----------- | -| `detailedStatus` | DetailedStatus | Detailed status of the stage | -| `groups` | CiGroupConnection | Group of jobs for the stage | -| `name` | String | Name of the stage | +| `detailedStatus` | DetailedStatus | Detailed status of the stage. | +| `groups` | CiGroupConnection | Group of jobs for the stage. | +| `name` | String | Name of the stage. | ### ClusterAgent @@ -554,22 +565,22 @@ Represents the code coverage summary for a project. | Field | Type | Description | | ----- | ---- | ----------- | -| `author` | User | Author of the commit | -| `authorGravatar` | String | Commit authors gravatar | -| `authorName` | String | Commit authors name | -| `authoredDate` | Time | Timestamp of when the commit was authored | -| `description` | String | Description of the commit message | +| `author` | User | Author of the commit. | +| `authorGravatar` | String | Commit authors gravatar. | +| `authorName` | String | Commit authors name. | +| `authoredDate` | Time | Timestamp of when the commit was authored. | +| `description` | String | Description of the commit message. | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | -| `id` | ID! | ID (global ID) of the commit | -| `message` | String | Raw commit message | -| `pipelines` | PipelineConnection | Pipelines of the commit ordered latest first | -| `sha` | String! | SHA1 ID of the commit | -| `shortId` | String! | Short SHA1 ID of the commit | -| `signatureHtml` | String | Rendered HTML of the commit signature | -| `title` | String | Title of the commit message | +| `id` | ID! | ID (global ID) of the commit. | +| `message` | String | Raw commit message. | +| `pipelines` | PipelineConnection | Pipelines of the commit ordered latest first. | +| `sha` | String! | SHA1 ID of the commit. | +| `shortId` | String! | Short SHA1 ID of the commit. | +| `signatureHtml` | String | Rendered HTML of the commit signature. | +| `title` | String | Title of the commit message. | | `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` | -| `webPath` | String! | Web path of the commit | -| `webUrl` | String! | Web URL of the commit | +| `webPath` | String! | Web path of the commit. | +| `webUrl` | String! | Web URL of the commit. | ### CommitCreatePayload @@ -591,6 +602,16 @@ Represents a ComplianceFramework associated with a Project. | `description` | String! | Description of the compliance framework | | `id` | ID! | Compliance framework ID | | `name` | String! | Name of the compliance framework | +| `pipelineConfigurationFullPath` | String | Full path of the compliance pipeline configuration stored in a project repository, such as `.gitlab/compliance/soc2/.gitlab-ci.yml`. | + +### ComposerMetadata + +Composer metadata. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `composerJson` | PackageComposerJsonType! | Data of the Composer JSON file. | +| `targetSha` | String! | Target SHA of the package. | ### ConfigureSastPayload @@ -609,15 +630,15 @@ A tag expiration policy designed to keep only the images that matter most. | 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 | -| `keepN` | ContainerExpirationPolicyKeepEnum | Number of tags to retain | -| `nameRegex` | UntrustedRegexp | Tags with names matching this regex pattern will expire | -| `nameRegexKeep` | UntrustedRegexp | Tags with names matching this regex pattern will be preserved | -| `nextRunAt` | Time | Next time that this container expiration policy will get executed | -| `olderThan` | ContainerExpirationPolicyOlderThanEnum | Tags older that this will expire | -| `updatedAt` | Time! | Timestamp of when the container expiration policy was updated | +| `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. | +| `keepN` | ContainerExpirationPolicyKeepEnum | Number of tags to retain. | +| `nameRegex` | UntrustedRegexp | Tags with names matching this regex pattern will expire. | +| `nameRegexKeep` | UntrustedRegexp | Tags with names matching this regex pattern will be preserved. | +| `nextRunAt` | Time | Next time that this container expiration policy will get executed. | +| `olderThan` | ContainerExpirationPolicyOlderThanEnum | Tags older that this will expire. | +| `updatedAt` | Time! | Timestamp of when the container expiration policy was updated. | ### ContainerRepository @@ -633,7 +654,7 @@ A container repository. | `location` | String! | URL of the container repository. | | `name` | String! | Name of the container repository. | | `path` | String! | Path of the container repository. | -| `project` | Project! | Project of the container registry | +| `project` | Project! | Project of the container registry. | | `status` | ContainerRepositoryStatus | Status of the container repository. | | `tagsCount` | Int! | Number of tags associated with this image. | | `updatedAt` | Time! | Timestamp when the container repository was updated. | @@ -652,9 +673,9 @@ Details of a container repository. | `location` | String! | URL of the container repository. | | `name` | String! | Name of the container repository. | | `path` | String! | Path of the container repository. | -| `project` | Project! | Project of the container registry | +| `project` | Project! | Project of the container registry. | | `status` | ContainerRepositoryStatus | Status of the container repository. | -| `tags` | ContainerRepositoryTagConnection | Tags of the container repository | +| `tags` | ContainerRepositoryTagConnection | Tags of the container repository. | | `tagsCount` | Int! | Number of tags associated with this image. | | `updatedAt` | Time! | Timestamp when the container repository was updated. | @@ -684,7 +705,7 @@ Autogenerated return type of CreateAlertIssue. | `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. | +| `todo` | Todo | The to-do item after mutation. | ### CreateAnnotationPayload @@ -832,10 +853,13 @@ Autogenerated return type of CreateSnippet. | Field | Type | Description | | ----- | ---- | ----------- | +| `captchaSiteKey` | String | The CAPTCHA site key which must be used to render a challenge for the user to solve to obtain a valid captchaResponse value. Included only when an operation was not completed because "NeedsCaptchaResponse" is true. | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `needsCaptchaResponse` | Boolean | Indicates whether the operation was detected as possible spam and not completed. If CAPTCHA is enabled, the request must be resubmitted with a valid CAPTCHA response and spam_log_id included for the operation to be completed. Included only when an operation was not completed because "NeedsCaptchaResponse" is true. | | `snippet` | Snippet | The snippet after mutation. | -| `spam` | Boolean | Indicates whether the operation returns a record detected as spam. | +| `spam` | Boolean | Indicates whether the operation was detected as definite spam. There is no option to resubmit the request with a CAPTCHA response. | +| `spamLogId` | Int | The spam log ID which must be passed along with a valid CAPTCHA response for an operation to be completed. Included only when an operation was not completed because "NeedsCaptchaResponse" is true. | ### CreateTestCasePayload @@ -853,10 +877,10 @@ A custom emoji uploaded by user. | Field | Type | Description | | ----- | ---- | ----------- | -| `external` | Boolean! | Whether the emoji is an external link | -| `id` | CustomEmojiID! | The ID of the emoji | -| `name` | String! | The name of the emoji | -| `url` | String! | The link to file of the emoji | +| `external` | Boolean! | Whether the emoji is an external link. | +| `id` | CustomEmojiID! | The ID of the emoji. | +| `name` | String! | The name of the emoji. | +| `url` | String! | The link to file of the emoji. | ### DastOnDemandScanCreatePayload @@ -868,6 +892,30 @@ Autogenerated return type of DastOnDemandScanCreate. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `pipelineUrl` | String | URL of the pipeline that was created. | +### DastProfile + +Represents a DAST Profile. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `dastScannerProfile` | DastScannerProfile | The associated scanner profile. | +| `dastSiteProfile` | DastSiteProfile | The associated site profile. | +| `description` | String | The description of the scan. | +| `editPath` | String | Relative web path to the edit page of a profile. | +| `id` | DastProfileID! | ID of the profile. | +| `name` | String | The name of the profile. | + +### DastProfileCreatePayload + +Autogenerated return type of DastProfileCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `dastProfile` | DastProfile | The created profile. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `pipelineUrl` | String! | The URL of the pipeline that was created. Requires `runAfterCreate` to be set to `true`. | + ### DastScannerProfile Represents a DAST scanner profile. @@ -998,6 +1046,15 @@ Autogenerated return type of DastSiteValidationCreate. | `id` | DastSiteValidationID | ID of the site validation. | | `status` | DastSiteProfileValidationStatusEnum | The current validation status. | +### DastSiteValidationRevokePayload + +Autogenerated return type of DastSiteValidationRevoke. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + ### DeleteAnnotationPayload Autogenerated return type of DeleteAnnotation. @@ -1022,9 +1079,9 @@ The response from the AdminSidekiqQueuesDeleteJobs mutation. | 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 | +| `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 @@ -1032,20 +1089,20 @@ A single design. | Field | Type | Description | | ----- | ---- | ----------- | -| `currentUserTodos` | TodoConnection! | Todos for the current user | -| `diffRefs` | DiffRefs! | The diff refs for this design | +| `currentUserTodos` | TodoConnection! | To-do items for the current user. | +| `diffRefs` | DiffRefs! | The diff refs for this design. | | `discussions` | DiscussionConnection! | All discussions on this noteable | -| `event` | DesignVersionEvent! | How this design was changed in the current version | -| `filename` | String! | The filename of the design | -| `fullPath` | String! | The full path to the design file | -| `id` | ID! | The ID of this design | -| `image` | String! | The URL of the full-sized image | +| `event` | DesignVersionEvent! | How this design was changed in the current version. | +| `filename` | String! | The filename of the design. | +| `fullPath` | String! | The full path to the design file. | +| `id` | ID! | The ID of this design. | +| `image` | String! | The URL of the full-sized image. | | `imageV432x230` | String | The URL of the design resized to fit within the bounds of 432x230. This will be `null` if the image has not been generated | -| `issue` | Issue! | The issue the design belongs to | +| `issue` | Issue! | The issue the design belongs to. | | `notes` | NoteConnection! | All notes on this noteable | -| `notesCount` | Int! | The total count of user-created notes for this design | -| `project` | Project! | The project the design belongs to | -| `versions` | DesignVersionConnection! | All versions related to this design ordered newest first | +| `notesCount` | Int! | The total count of user-created notes for this design. | +| `project` | Project! | The project the design belongs to. | +| `versions` | DesignVersionConnection! | All versions related to this design ordered newest first. | ### DesignAtVersion @@ -1053,18 +1110,18 @@ A design pinned to a specific version. The image field reflects the design as of | 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 | -| `fullPath` | String! | The full path to the design file | -| `id` | ID! | The ID of this design | -| `image` | String! | The URL of the full-sized image | +| `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. | +| `fullPath` | String! | The full path to the design file. | +| `id` | ID! | The ID of this design. | +| `image` | String! | The URL of the full-sized image. | | `imageV432x230` | String | The URL of the design resized to fit within the bounds of 432x230. This will be `null` if the image has not been generated | -| `issue` | Issue! | The issue the design belongs to | -| `notesCount` | Int! | The total count of user-created notes for this design | -| `project` | Project! | The project the design belongs to | -| `version` | DesignVersion! | The version this design-at-versions is pinned to | +| `issue` | Issue! | The issue the design belongs to. | +| `notesCount` | Int! | The total count of user-created notes for this design. | +| `project` | Project! | The project the design belongs to. | +| `version` | DesignVersion! | The version this design-at-versions is pinned to. | ### DesignCollection @@ -1072,21 +1129,21 @@ A collection of designs. | Field | Type | Description | | ----- | ---- | ----------- | -| `copyState` | DesignCollectionCopyState | Copy state of the design collection | -| `design` | Design | Find a specific design | -| `designAtVersion` | DesignAtVersion | Find a design as of a version | -| `designs` | DesignConnection! | All designs for the design collection | -| `issue` | Issue! | Issue associated with the design collection | -| `project` | Project! | Project associated with the design collection | -| `version` | DesignVersion | A specific version | -| `versions` | DesignVersionConnection! | All versions related to all designs, ordered newest first | +| `copyState` | DesignCollectionCopyState | Copy state of the design collection. | +| `design` | Design | Find a specific design. | +| `designAtVersion` | DesignAtVersion | Find a design as of a version. | +| `designs` | DesignConnection! | All designs for the design collection. | +| `issue` | Issue! | Issue associated with the design collection. | +| `project` | Project! | Project associated with the design collection. | +| `version` | DesignVersion | A specific version. | +| `versions` | DesignVersionConnection! | All versions related to all designs, ordered newest first. | ### DesignManagement | Field | Type | Description | | ----- | ---- | ----------- | -| `designAtVersion` | DesignAtVersion | Find a design as of a version | -| `version` | DesignVersion | Find a version | +| `designAtVersion` | DesignAtVersion | Find a design as of a version. | +| `version` | DesignVersion | Find a version. | ### DesignManagementDeletePayload @@ -1125,11 +1182,11 @@ A specific version in which designs were added, modified or deleted. | Field | Type | Description | | ----- | ---- | ----------- | -| `designAtVersion` | DesignAtVersion! | A particular design as of this version, provided it is visible at this version | -| `designs` | DesignConnection! | All designs that were changed in the version | -| `designsAtVersion` | DesignAtVersionConnection! | All designs that are visible at this version, as of this version | -| `id` | ID! | ID of the design version | -| `sha` | ID! | SHA of the design version | +| `designAtVersion` | DesignAtVersion! | A particular design as of this version, provided it is visible at this version. | +| `designs` | DesignConnection! | All designs that were changed in the version. | +| `designsAtVersion` | DesignAtVersionConnection! | All designs that are visible at this version, as of this version. | +| `id` | ID! | ID of the design version. | +| `sha` | ID! | SHA of the design version. | ### DestroyBoardListPayload @@ -1204,15 +1261,15 @@ Autogenerated return type of DestroySnippet. | Field | Type | Description | | ----- | ---- | ----------- | -| `action` | StatusAction | Action information for the status. This includes method, button title, icon, path, and title | -| `detailsPath` | String | Path of the details for the status | -| `favicon` | String | Favicon of the status | -| `group` | String | Group of the status | -| `hasDetails` | Boolean | Indicates if the status has further details | -| `icon` | String | Icon of the status | -| `label` | String | Label of the status | -| `text` | String | Text of the status | -| `tooltip` | String | Tooltip associated with the status | +| `action` | StatusAction | Action information for the status. This includes method, button title, icon, path, and title. | +| `detailsPath` | String | Path of the details for the status. | +| `favicon` | String | Favicon of the status. | +| `group` | String | Group of the status. | +| `hasDetails` | Boolean | Indicates if the status has further details. | +| `icon` | String | Icon of the status. | +| `label` | String | Label of the status. | +| `text` | String | Text of the status. | +| `tooltip` | String | Tooltip associated with the status. | ### DevopsAdoptionSegment @@ -1262,9 +1319,9 @@ Snapshot. | 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 | +| `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 @@ -1272,9 +1329,9 @@ Changes to a single file. | 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 | +| `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 @@ -1282,19 +1339,19 @@ Aggregated summary of changes. | 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 | +| `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 | Field | Type | Description | | ----- | ---- | ----------- | | `createdAt` | Time! | Timestamp of the discussion's creation | -| `id` | ID! | ID of this discussion | +| `id` | DiscussionID! | ID of this discussion | | `notes` | NoteConnection! | All notes in the discussion | -| `replyId` | ID! | ID used to reply to this discussion | +| `replyId` | DiscussionID! | ID used to reply to this discussion | | `resolvable` | Boolean! | Indicates if the object can be resolved | | `resolved` | Boolean! | Indicates if the object is resolved | | `resolvedAt` | Time | Timestamp of when the object was resolved | @@ -1326,12 +1383,12 @@ Describes where code is deployed for a project. | 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 | +| `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. | | `path` | String! | The path to the environment. | -| `state` | String! | State of the environment, for example: available/stopped | +| `state` | String! | State of the environment, for example: available/stopped. | ### EnvironmentsCanaryIngressUpdatePayload @@ -1348,50 +1405,51 @@ Represents an epic. | Field | Type | Description | | ----- | ---- | ----------- | -| `author` | User! | Author of the epic | -| `children` | EpicConnection | Children (sub-epics) of the epic | -| `closedAt` | Time | Timestamp of when the epic was closed | -| `confidential` | Boolean | Indicates if the epic is confidential | -| `createdAt` | Time | Timestamp of when the epic was created | -| `currentUserTodos` | TodoConnection! | Todos for the current user | -| `descendantCounts` | EpicDescendantCount | Number of open and closed descendant epics and issues | -| `descendantWeightSum` | EpicDescendantWeights | Total weight of open and closed issues in the epic and its descendants | -| `description` | String | Description of the epic | +| `author` | User! | Author of the epic. | +| `awardEmoji` | AwardEmojiConnection | A list of award emojis associated with the epic. | +| `children` | EpicConnection | Children (sub-epics) of the epic. | +| `closedAt` | Time | Timestamp of when the epic was closed. | +| `confidential` | Boolean | Indicates if the epic is confidential. | +| `createdAt` | Time | Timestamp of when the epic was created. | +| `currentUserTodos` | TodoConnection! | To-do items for the current user. | +| `descendantCounts` | EpicDescendantCount | Number of open and closed descendant epics and issues. | +| `descendantWeightSum` | EpicDescendantWeights | Total weight of open and closed issues in the epic and its descendants. | +| `description` | String | Description of the epic. | | `discussions` | DiscussionConnection! | All discussions on this noteable | -| `downvotes` | Int! | Number of downvotes the epic has received | -| `dueDate` | Time | Due date of the epic | -| `dueDateFixed` | Time | Fixed due date of the epic | -| `dueDateFromMilestones` | Time | Inherited due date of the epic from milestones | -| `dueDateIsFixed` | Boolean | Indicates if the due date has been manually set | -| `group` | Group! | Group to which the epic belongs | -| `hasChildren` | Boolean! | Indicates if the epic has children | -| `hasIssues` | Boolean! | Indicates if the epic has direct issues | -| `hasParent` | Boolean! | Indicates if the epic has a parent epic | -| `healthStatus` | EpicHealthStatus | Current health status of the epic | -| `id` | ID! | ID of the epic | -| `iid` | ID! | Internal ID of the epic | -| `issues` | EpicIssueConnection | A list of issues associated with the epic | -| `labels` | LabelConnection | Labels assigned to the epic | +| `downvotes` | Int! | Number of downvotes the epic has received. | +| `dueDate` | Time | Due date of the epic. | +| `dueDateFixed` | Time | Fixed due date of the epic. | +| `dueDateFromMilestones` | Time | Inherited due date of the epic from milestones. | +| `dueDateIsFixed` | Boolean | Indicates if the due date has been manually set. | +| `group` | Group! | Group to which the epic belongs. | +| `hasChildren` | Boolean! | Indicates if the epic has children. | +| `hasIssues` | Boolean! | Indicates if the epic has direct issues. | +| `hasParent` | Boolean! | Indicates if the epic has a parent epic. | +| `healthStatus` | EpicHealthStatus | Current health status of the epic. | +| `id` | ID! | ID of the epic. | +| `iid` | ID! | Internal ID of the epic. | +| `issues` | EpicIssueConnection | A list of issues associated with the epic. | +| `labels` | LabelConnection | Labels assigned to the epic. | | `notes` | NoteConnection! | All notes on this noteable | -| `parent` | Epic | Parent epic of the epic | -| `participants` | UserConnection | List of participants for the epic | -| `reference` | String! | Internal reference of the epic. Returned in shortened format by default | -| `relationPath` | String | URI path of the epic-issue relationship | -| `relativePosition` | Int | The relative position of the epic in the epic tree | -| `startDate` | Time | Start date of the epic | -| `startDateFixed` | Time | Fixed start date of the epic | -| `startDateFromMilestones` | Time | Inherited start date of the epic from milestones | -| `startDateIsFixed` | Boolean | Indicates if the start date has been manually set | -| `state` | EpicState! | State of the epic | -| `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the epic | -| `title` | String | Title of the epic | -| `updatedAt` | Time | Timestamp of when the epic was updated | -| `upvotes` | Int! | Number of upvotes the epic has received | -| `userDiscussionsCount` | Int! | Number of user discussions in the epic | -| `userNotesCount` | Int! | Number of user notes of the epic | +| `parent` | Epic | Parent epic of the epic. | +| `participants` | UserConnection | List of participants for the epic. | +| `reference` | String! | Internal reference of the epic. Returned in shortened format by default. | +| `relationPath` | String | URI path of the epic-issue relationship. | +| `relativePosition` | Int | The relative position of the epic in the epic tree. | +| `startDate` | Time | Start date of the epic. | +| `startDateFixed` | Time | Fixed start date of the epic. | +| `startDateFromMilestones` | Time | Inherited start date of the epic from milestones. | +| `startDateIsFixed` | Boolean | Indicates if the start date has been manually set. | +| `state` | EpicState! | State of the epic. | +| `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the epic. | +| `title` | String | Title of the epic. | +| `updatedAt` | Time | Timestamp of when the epic was updated. | +| `upvotes` | Int! | Number of upvotes the epic has received. | +| `userDiscussionsCount` | Int! | Number of user discussions in the epic. | +| `userNotesCount` | Int! | Number of user notes of the epic. | | `userPermissions` | EpicPermissions! | Permissions for the current user on the resource | -| `webPath` | String! | Web path of the epic | -| `webUrl` | String! | Web URL of the epic | +| `webPath` | String! | Web path of the epic. | +| `webUrl` | String! | Web URL of the epic. | ### EpicAddIssuePayload @@ -1414,6 +1472,16 @@ Represents an epic board. | `lists` | EpicListConnection | Epic board lists. | | `name` | String | Name of the board. | +### EpicBoardCreatePayload + +Autogenerated return type of EpicBoardCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `epicBoard` | EpicBoard | The created epic board. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + ### EpicDescendantCount Counts of descendent epics. @@ -1459,7 +1527,7 @@ Relationship between an epic and an issue. | `confidential` | Boolean! | Indicates the issue is confidential | | `createNoteEmail` | String | User specific email address for the issue | | `createdAt` | Time! | Timestamp of when the issue was created | -| `currentUserTodos` | TodoConnection! | Todos for the current user | +| `currentUserTodos` | TodoConnection! | To-do items for the current user. | | `description` | String | Description of the issue | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `designCollection` | DesignCollection | Collection of design images associated with this issue | @@ -1601,15 +1669,24 @@ Represents an external issue. | `url` | String | The user-facing URL for this Geo node | | `verificationMaxCapacity` | Int | The maximum concurrency of repository verification for this secondary node | +### GitlabSubscriptionActivatePayload + +Autogenerated return type of GitlabSubscriptionActivate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + ### GrafanaIntegration | 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 | -| `id` | ID! | Internal ID of the Grafana integration | -| `updatedAt` | Time! | Timestamp of the issue's last activity | +| `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. | +| `id` | ID! | Internal ID of the Grafana integration. | +| `updatedAt` | Time! | Timestamp of the issue's last activity. | ### Group @@ -1617,19 +1694,19 @@ Represents an external issue. | ----- | ---- | ----------- | | `actualRepositorySizeLimit` | Float | Size limit for repositories in the namespace in bytes | | `additionalPurchasedStorageSize` | Float | Additional storage purchased for the root namespace in bytes | -| `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 | -| `boards` | BoardConnection | Boards of the group | +| `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. | +| `boards` | BoardConnection | Boards of the group. | | `codeCoverageActivities` | CodeCoverageActivityConnection | Represents the code coverage activity for this group | | `complianceFrameworks` | ComplianceFrameworkConnection | Compliance frameworks available to projects in this namespace. Available only when feature flag `ff_custom_compliance_frameworks` is enabled. | -| `containerRepositories` | ContainerRepositoryConnection | Container repositories of the group | -| `containerRepositoriesCount` | Int! | Number of container repositories in the group | +| `containerRepositories` | ContainerRepositoryConnection | Container repositories of the group. | +| `containerRepositoriesCount` | Int! | Number of container repositories in the group. | | `containsLockedProjects` | Boolean! | Includes at least one project where the repository size exceeds the limit | -| `customEmoji` | CustomEmojiConnection | Custom emoji within this namespace Available only when feature flag `custom_emoji` is enabled. | +| `customEmoji` | CustomEmojiConnection | Custom emoji within this namespace. Available only when feature flag `custom_emoji` is enabled. | | `description` | String | Description of the namespace | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | -| `emailsDisabled` | Boolean | Indicates if a group has email notifications disabled | +| `emailsDisabled` | Boolean | Indicates if a group has email notifications disabled. | | `epic` | Epic | Find a single epic | | `epicBoard` | EpicBoard | Find a single epic board | | `epicBoards` | EpicBoardConnection | Find epic boards | @@ -1637,46 +1714,46 @@ Represents an external issue. | `epicsEnabled` | Boolean | Indicates if Epics are enabled for namespace | | `fullName` | String! | Full name of the namespace | | `fullPath` | ID! | Full path of the namespace | -| `groupMembers` | GroupMemberConnection | A membership of a user within this group | +| `groupMembers` | GroupMemberConnection | A membership of a user within this group. | | `groupTimelogsEnabled` | Boolean | Indicates if Group timelogs are enabled for namespace | | `id` | ID! | ID of the namespace | | `isTemporaryStorageIncreaseEnabled` | Boolean! | Status of the temporary storage increase | -| `issues` | IssueConnection | Issues for projects in this group | +| `issues` | IssueConnection | Issues for projects in this group. | | `iterations` | IterationConnection | Find iterations | -| `label` | Label | A label available on this group | -| `labels` | LabelConnection | Labels available on this group | +| `label` | Label | A label available on this group. | +| `labels` | LabelConnection | Labels available on this group. | | `lfsEnabled` | Boolean | Indicates if Large File Storage (LFS) is enabled for namespace | -| `mentionsDisabled` | Boolean | Indicates if a group is disabled from getting mentioned | -| `mergeRequests` | MergeRequestConnection | Merge requests for projects in this group | -| `milestones` | MilestoneConnection | Milestones of the group | +| `mentionsDisabled` | Boolean | Indicates if a group is disabled from getting mentioned. | +| `mergeRequests` | MergeRequestConnection | Merge requests for projects in this group. | +| `milestones` | MilestoneConnection | Milestones of the group. | | `name` | String! | Name of the namespace | | `packageSettings` | PackageSettings | The package settings for the namespace | -| `parent` | Group | Parent group | +| `parent` | Group | Parent group. | | `path` | String! | Path of the namespace | -| `projectCreationLevel` | String | The permission level required to create projects in the group | +| `projectCreationLevel` | String | The permission level required to create projects in the group. | | `projects` | ProjectConnection! | Projects within this namespace | | `repositorySizeExcessProjectCount` | Int! | Number of projects in the root namespace where the repository size exceeds the limit | | `requestAccessEnabled` | Boolean | Indicates if users can request access to namespace | -| `requireTwoFactorAuthentication` | Boolean | Indicates if all users in this group are required to set up two-factor authentication | +| `requireTwoFactorAuthentication` | Boolean | Indicates if all users in this group are required to set up two-factor authentication. | | `rootStorageStatistics` | RootStorageStatistics | Aggregated storage statistics of the namespace. Only available for root namespaces | -| `shareWithGroupLock` | Boolean | Indicates if sharing a project with another group within this group is prevented | +| `shareWithGroupLock` | Boolean | Indicates if sharing a project with another group within this group is prevented. | | `stats` | GroupStats | Group statistics | | `storageSizeLimit` | Float | Total storage limit of the root namespace in bytes | -| `subgroupCreationLevel` | String | The permission level required to create subgroups within the group | +| `subgroupCreationLevel` | String | The permission level required to create subgroups within the group. | | `temporaryStorageIncreaseEndsOn` | Time | Date until the temporary storage increase is active | | `timelogs` | TimelogConnection! | Time logged in issues by group members | | `totalRepositorySize` | Float | Total repository size of all projects in the root namespace in bytes | | `totalRepositorySizeExcess` | Float | Total excess repository size of all projects in the root namespace in bytes | -| `twoFactorGracePeriod` | Int | Time before two-factor authentication is enforced | +| `twoFactorGracePeriod` | Int | Time before two-factor authentication is enforced. | | `userPermissions` | GroupPermissions! | Permissions for the current user on the resource | | `visibility` | String | Visibility of the namespace | | `vulnerabilities` | VulnerabilityConnection | Vulnerabilities reported on the projects in the group and its subgroups | | `vulnerabilitiesCountByDay` | VulnerabilitiesCountByDayConnection | Number of vulnerabilities per day for the projects in the group and its subgroups | | `vulnerabilitiesCountByDayAndSeverity` **{warning-solid}** | VulnerabilitiesCountByDayAndSeverityConnection | **Deprecated:** Use `vulnerabilitiesCountByDay`. Deprecated in 13.3. | | `vulnerabilityGrades` | VulnerableProjectsByGrade! => Array | Represents vulnerable project counts for each grade | -| `vulnerabilityScanners` | VulnerabilityScannerConnection | Vulnerability scanners reported on the project vulnerabilties of the group and its subgroups | +| `vulnerabilityScanners` | VulnerabilityScannerConnection | Vulnerability scanners reported on the project vulnerabilities of the group and its subgroups | | `vulnerabilitySeveritiesCount` | VulnerabilitySeveritiesCount | Counts for each vulnerability severity in the group and its subgroups | -| `webUrl` | String! | Web URL of the group | +| `webUrl` | String! | Web URL of the group. | ### GroupMember @@ -1688,7 +1765,7 @@ Represents a Group Membership. | `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 | +| `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 | @@ -1768,6 +1845,7 @@ Describes an incident management on-call rotation. | `lengthUnit` | OncallRotationUnitEnum | Unit of the on-call rotation length. | | `name` | String! | Name of the on-call rotation. | | `participants` | OncallParticipantTypeConnection | Participants of the on-call rotation. | +| `shifts` | IncidentManagementOncallShiftConnection | Blocks of time for which a participant is on-call within a given time frame. Time frame cannot exceed one month. | | `startsAt` | Time | Start date of the on-call rotation. | ### IncidentManagementOncallSchedule @@ -1782,13 +1860,23 @@ Describes an incident management on-call schedule. | `rotations` | IncidentManagementOncallRotationConnection! | On-call rotations for the on-call schedule | | `timezone` | String! | Time zone of the on-call schedule | +### IncidentManagementOncallShift + +A block of time for which a participant is on-call.. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `endsAt` | Time | End time of the on-call shift. | +| `participant` | OncallParticipantType | Participant assigned to the on-call shift. | +| `startsAt` | Time | Start time of the on-call shift. | + ### InstanceSecurityDashboard | Field | Type | Description | | ----- | ---- | ----------- | | `projects` | ProjectConnection! | Projects selected in Instance Security Dashboard | | `vulnerabilityGrades` | VulnerableProjectsByGrade! => Array | Represents vulnerable project counts for each grade | -| `vulnerabilityScanners` | VulnerabilityScannerConnection | Vulnerability scanners reported on the vulnerabilties from projects selected in Instance Security Dashboard | +| `vulnerabilityScanners` | VulnerabilityScannerConnection | Vulnerability scanners reported on the vulnerabilities from projects selected in Instance Security Dashboard | | `vulnerabilitySeveritiesCount` | VulnerabilitySeveritiesCount | Counts for each vulnerability severity from projects selected in Instance Security Dashboard | ### InstanceStatisticsMeasurement @@ -1797,9 +1885,9 @@ Represents a recorded measurement (object count) for the Admins. | Field | Type | Description | | ----- | ---- | ----------- | -| `count` | Int! | Object count | -| `identifier` | MeasurementIdentifier! | The type of objects being measured | -| `recordedAt` | Time | The time the measurement was recorded | +| `count` | Int! | Object count. | +| `identifier` | MeasurementIdentifier! | The type of objects being measured. | +| `recordedAt` | Time | The time the measurement was recorded. | ### Issue @@ -1814,7 +1902,7 @@ Represents a recorded measurement (object count) for the Admins. | `confidential` | Boolean! | Indicates the issue is confidential | | `createNoteEmail` | String | User specific email address for the issue | | `createdAt` | Time! | Timestamp of when the issue was created | -| `currentUserTodos` | TodoConnection! | Todos for the current user | +| `currentUserTodos` | TodoConnection! | To-do items for the current user. | | `description` | String | Description of the issue | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `designCollection` | DesignCollection | Collection of design images associated with this issue | @@ -2125,7 +2213,7 @@ Autogenerated return type of MarkAsSpamSnippet. | `commitsWithoutMergeCommits` | CommitConnection | Merge request commits excluding merge commits | | `conflicts` | Boolean! | Indicates if the merge request has conflicts | | `createdAt` | Time! | Timestamp of when the merge request was created | -| `currentUserTodos` | TodoConnection! | Todos for the current user | +| `currentUserTodos` | TodoConnection! | To-do items for the current user. | | `defaultMergeCommitMessage` | String | Default merge commit message of the merge request | | `defaultMergeCommitMessageWithDescription` | String | Default merge commit message of the merge request with description | | `defaultSquashCommitMessage` | String | Default squash commit message of the merge request | @@ -2235,6 +2323,16 @@ 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 | +### MergeRequestReviewerRereviewPayload + +Autogenerated return type of MergeRequestReviewerRereview. + +| 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. | + ### MergeRequestSetAssigneesPayload Autogenerated return type of MergeRequestSetAssignees. @@ -2420,7 +2518,7 @@ Autogenerated return type of NamespaceIncreaseStorageTemporarily. | `confidential` | Boolean | Indicates if this note is confidential | | `createdAt` | Time! | Timestamp of the note creation | | `discussion` | Discussion | The discussion this note is a part of | -| `id` | ID! | ID of the note | +| `id` | NoteID! | ID of the note | | `position` | DiffPosition | The position of this note on a diff | | `project` | Project | Project associated with the note | | `resolvable` | Boolean! | Indicates if the object can be resolved | @@ -2465,6 +2563,16 @@ Autogenerated return type of OncallRotationCreate. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `oncallRotation` | IncidentManagementOncallRotation | The on-call rotation. | +### OncallRotationDestroyPayload + +Autogenerated return type of OncallRotationDestroy. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `oncallRotation` | IncidentManagementOncallRotation | The on-call rotation. | + ### OncallScheduleCreatePayload Autogenerated return type of OncallScheduleCreate. @@ -2501,34 +2609,17 @@ Represents a package in the Package Registry. | Field | Type | Description | | ----- | ---- | ----------- | -| `createdAt` | Time! | The created date. | -| `id` | ID! | The ID of the package. | -| `name` | String! | The name of the package. | -| `packageType` | PackageTypeEnum! | The type of the package. | -| `pipelines` | PipelineConnection | Pipelines that built the package. | -| `project` | Project! | Project where the package is stored. | -| `tags` | PackageTagConnection | The package tags. | -| `updatedAt` | Time! | The updated date. | -| `version` | String | The version of the package. | -| `versions` | PackageConnection | The other versions of the package. | - -### PackageComposerDetails - -Details of a Composer package. - -| Field | Type | Description | -| ----- | ---- | ----------- | -| `composerMetadatum` | PackageComposerMetadatumType! | The Composer metadatum. | -| `createdAt` | Time! | The created date. | -| `id` | ID! | The ID of the package. | -| `name` | String! | The name of the package. | -| `packageType` | PackageTypeEnum! | The type of the package. | +| `createdAt` | Time! | Date of creation. | +| `id` | PackagesPackageID! | ID of the package. | +| `metadata` | PackageMetadata | Package metadata. | +| `name` | String! | Name of the package. | +| `packageType` | PackageTypeEnum! | Package type. | | `pipelines` | PipelineConnection | Pipelines that built the package. | | `project` | Project! | Project where the package is stored. | -| `tags` | PackageTagConnection | The package tags. | -| `updatedAt` | Time! | The updated date. | -| `version` | String | The version of the package. | -| `versions` | PackageConnection | The other versions of the package. | +| `tags` | PackageTagConnection | Package tags. | +| `updatedAt` | Time! | Date of most recent update. | +| `version` | String | Version string. | +| `versions` | PackageWithoutVersionsConnection | The other versions of the package. | ### PackageComposerJsonType @@ -2541,15 +2632,6 @@ Represents a composer JSON file. | `type` | String | The type set in the Composer JSON file. | | `version` | String | The version set in the Composer JSON file. | -### PackageComposerMetadatumType - -Composer metadatum. - -| Field | Type | Description | -| ----- | ---- | ----------- | -| `composerJson` | PackageComposerJsonType! | Data of the Composer JSON file. | -| `targetSha` | String! | Target SHA of the package. | - ### PackageFileRegistry Represents the Geo sync and verification state of a package file. @@ -2585,6 +2667,23 @@ Represents a package tag. | `name` | String! | The name of the tag. | | `updatedAt` | Time! | The updated date. | +### PackageWithoutVersions + +Represents a version of a package in the Package Registry. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `createdAt` | Time! | Date of creation. | +| `id` | PackagesPackageID! | ID of the package. | +| `metadata` | PackageMetadata | Package metadata. | +| `name` | String! | Name of the package. | +| `packageType` | PackageTypeEnum! | Package type. | +| `pipelines` | PipelineConnection | Pipelines that built the package. | +| `project` | Project! | Project where the package is stored. | +| `tags` | PackageTagConnection | Package tags. | +| `updatedAt` | Time! | Date of most recent update. | +| `version` | String | Version string. | + ### PageInfo Information about pagination in a connection.. @@ -2600,49 +2699,49 @@ Information about pagination in a connection.. | Field | Type | Description | | ----- | ---- | ----------- | -| `active` | Boolean! | Indicates if the pipeline is active | -| `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 | -| `createdAt` | Time! | Timestamp of the pipeline's creation | -| `detailedStatus` | DetailedStatus! | Detailed status of the pipeline | -| `downstream` | PipelineConnection | Pipelines this pipeline will trigger | -| `duration` | Int | Duration of the pipeline in seconds | -| `finishedAt` | Time | Timestamp of the pipeline's completion | -| `id` | ID! | ID of the pipeline | -| `iid` | String! | Internal ID of the pipeline | -| `jobs` | CiJobConnection | Jobs belonging to the pipeline | -| `path` | String | Relative path to the pipeline's page | -| `project` | Project | Project the pipeline belongs to | -| `retryable` | Boolean! | Specifies if a pipeline can be retried | +| `active` | Boolean! | Indicates if the pipeline is active. | +| `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 | Configuration 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. | +| `createdAt` | Time! | Timestamp of the pipeline's creation. | +| `detailedStatus` | DetailedStatus! | Detailed status of the pipeline. | +| `downstream` | PipelineConnection | Pipelines this pipeline will trigger. | +| `duration` | Int | Duration of the pipeline in seconds. | +| `finishedAt` | Time | Timestamp of the pipeline's completion. | +| `id` | ID! | ID of the pipeline. | +| `iid` | String! | Internal ID of the pipeline. | +| `jobs` | CiJobConnection | Jobs belonging to the pipeline. | +| `path` | String | Relative path to the pipeline's page. | +| `project` | Project | Project the pipeline belongs to. | +| `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 | -| `sourceJob` | CiJob | Job where pipeline was triggered from | -| `stages` | CiStageConnection | Stages of the pipeline | -| `startedAt` | Time | Timestamp when the pipeline was started | +| `sha` | String! | SHA of the pipeline's commit. | +| `sourceJob` | CiJob | Job where pipeline was triggered from. | +| `stages` | CiStageConnection | Stages of the pipeline. | +| `startedAt` | Time | Timestamp when the pipeline was started. | | `status` | PipelineStatusEnum! | Status of the pipeline (CREATED, WAITING_FOR_RESOURCE, PREPARING, PENDING, RUNNING, FAILED, SUCCESS, CANCELED, SKIPPED, MANUAL, SCHEDULED) | -| `updatedAt` | Time! | Timestamp of the pipeline's last activity | -| `upstream` | Pipeline | Pipeline that triggered the pipeline | -| `user` | User | Pipeline user | +| `updatedAt` | Time! | Timestamp of the pipeline's last activity. | +| `upstream` | Pipeline | Pipeline that triggered the pipeline. | +| `user` | User | Pipeline user. | | `userPermissions` | PipelinePermissions! | Permissions for the current user on the resource | ### PipelineAnalytics | Field | Type | Description | | ----- | ---- | ----------- | -| `monthPipelinesLabels` | String! => Array | Labels for the monthly pipeline count | -| `monthPipelinesSuccessful` | Int! => Array | Total monthly successful pipeline count | -| `monthPipelinesTotals` | Int! => Array | Total monthly pipeline count | -| `pipelineTimesLabels` | String! => Array | Pipeline times labels | -| `pipelineTimesValues` | Int! => Array | Pipeline times | -| `weekPipelinesLabels` | String! => Array | Labels for the weekly pipeline count | -| `weekPipelinesSuccessful` | Int! => Array | Total weekly successful pipeline count | -| `weekPipelinesTotals` | Int! => Array | Total weekly pipeline count | -| `yearPipelinesLabels` | String! => Array | Labels for the yearly pipeline count | -| `yearPipelinesSuccessful` | Int! => Array | Total yearly successful pipeline count | -| `yearPipelinesTotals` | Int! => Array | Total yearly pipeline count | +| `monthPipelinesLabels` | String! => Array | Labels for the monthly pipeline count. | +| `monthPipelinesSuccessful` | Int! => Array | Total monthly successful pipeline count. | +| `monthPipelinesTotals` | Int! => Array | Total monthly pipeline count. | +| `pipelineTimesLabels` | String! => Array | Pipeline times labels. | +| `pipelineTimesValues` | Int! => Array | Pipeline times. | +| `weekPipelinesLabels` | String! => Array | Labels for the weekly pipeline count. | +| `weekPipelinesSuccessful` | Int! => Array | Total weekly successful pipeline count. | +| `weekPipelinesTotals` | Int! => Array | Total weekly pipeline count. | +| `yearPipelinesLabels` | String! => Array | Labels for the yearly pipeline count. | +| `yearPipelinesSuccessful` | Int! => Array | Total yearly successful pipeline count. | +| `yearPipelinesTotals` | Int! => Array | Total yearly pipeline count. | ### PipelineCancelPayload @@ -2689,6 +2788,7 @@ Autogenerated return type of PipelineRetry. | `alertManagementAlertStatusCounts` | AlertManagementAlertStatusCountsType | Counts of alerts by status for the project | | `alertManagementAlerts` | AlertManagementAlertConnection | Alert Management alerts of the project | | `alertManagementIntegrations` | AlertManagementIntegrationConnection | Integrations which can receive alerts for the project | +| `alertManagementPayloadFields` | AlertManagementPayloadAlertField! => Array | Extract alert fields from payload for custom mapping | | `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 | | `archived` | Boolean | Indicates the archived status of the project | | `autocloseReferencedIssues` | Boolean | Indicates if issues referenced by merge requests and commits within the default branch are closed automatically | @@ -2705,10 +2805,11 @@ Autogenerated return type of PipelineRetry. | `containerRepositories` | ContainerRepositoryConnection | Container repositories of the project | | `containerRepositoriesCount` | Int! | Number of container repositories in the project | | `createdAt` | Time | Timestamp of the project creation | -| `dastScannerProfiles` | DastScannerProfileConnection | The DAST scanner profiles associated with the project | -| `dastSiteProfile` | DastSiteProfile | DAST Site Profile associated with the project | -| `dastSiteProfiles` | DastSiteProfileConnection | DAST Site Profiles associated with the project | -| `dastSiteValidations` | DastSiteValidationConnection | DAST Site Validations associated with the project. Will always return no nodes if `security_on_demand_scans_site_validation` is disabled | +| `dastProfiles` | DastProfileConnection | DAST Profiles associated with the project. Always returns no nodes if `dast_saved_scans` is disabled. | +| `dastScannerProfiles` | DastScannerProfileConnection | The DAST scanner profiles associated with the project. | +| `dastSiteProfile` | DastSiteProfile | DAST Site Profile associated with the project. | +| `dastSiteProfiles` | DastSiteProfileConnection | DAST Site Profiles associated with the project. | +| `dastSiteValidations` | DastSiteValidationConnection | DAST Site Validations associated with the project. Always returns no nodes if `security_on_demand_scans_site_validation` is disabled. | | `description` | String | Short description of the project | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `environment` | Environment | A single environment of the project | @@ -2772,18 +2873,19 @@ Autogenerated return type of PipelineRetry. | `sharedRunnersEnabled` | Boolean | Indicates if shared runners are enabled for the project | | `snippets` | SnippetConnection | Snippets of the project | | `snippetsEnabled` | Boolean | Indicates if Snippets are enabled for the current user | -| `squashReadOnly` | Boolean! | Indicates if squash readonly is enabled | +| `squashReadOnly` | Boolean! | Indicates if `squashReadOnly` is enabled | | `sshUrlToRepo` | String | URL to connect to the project via SSH | | `starCount` | Int! | Number of times the project has been starred | | `statistics` | ProjectStatistics | Statistics of the project | | `suggestionCommitMessage` | String | The commit message used to apply merge request suggestions | | `tagList` | String | List of project topics (not Git tags) | -| `terraformStates` | TerraformStateConnection | Terraform states associated with the project | +| `terraformState` | TerraformState | Find a single Terraform state by name. | +| `terraformStates` | TerraformStateConnection | Terraform states associated with the project. | | `userPermissions` | ProjectPermissions! | Permissions for the current user on the resource | | `visibility` | String | Visibility of the project | | `vulnerabilities` | VulnerabilityConnection | Vulnerabilities reported on the project | | `vulnerabilitiesCountByDay` | VulnerabilitiesCountByDayConnection | Number of vulnerabilities per day for the project | -| `vulnerabilityScanners` | VulnerabilityScannerConnection | Vulnerability scanners reported on the project vulnerabilties | +| `vulnerabilityScanners` | VulnerabilityScannerConnection | Vulnerability scanners reported on the project vulnerabilities | | `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 | @@ -2994,10 +3096,10 @@ Evidence for a release. | 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 | +| `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 @@ -3149,23 +3251,23 @@ Autogenerated return type of RunDASTScan. | Field | Type | Description | | ----- | ---- | ----------- | -| `downloadLocation` | String! | Download location for the runner for the platform architecture | -| `name` | String! | Name of the runner platform architecture | +| `downloadLocation` | String! | Download location for the runner for the platform architecture. | +| `name` | String! | Name of the runner platform architecture. | ### RunnerPlatform | Field | Type | Description | | ----- | ---- | ----------- | -| `architectures` | RunnerArchitectureConnection | Runner architectures supported for the platform | -| `humanReadableName` | String! | Human readable name of the runner platform | -| `name` | String! | Name slug of the runner platform | +| `architectures` | RunnerArchitectureConnection | Runner architectures supported for the platform. | +| `humanReadableName` | String! | Human readable name of the runner platform. | +| `name` | String! | Name slug of the runner platform. | ### RunnerSetup | Field | Type | Description | | ----- | ---- | ----------- | -| `installInstructions` | String! | Instructions for installing the runner on the specified architecture | -| `registerInstructions` | String | Instructions for registering the runner | +| `installInstructions` | String! | Instructions for installing the runner on the specified architecture. | +| `registerInstructions` | String | Instructions for registering the runner. | ### SastCiConfiguration @@ -3183,11 +3285,11 @@ Represents an analyzer entity in SAST CI configuration. | 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 | -| `variables` | SastCiConfigurationEntityConnection | List of supported variables | +| `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. | +| `variables` | SastCiConfigurationEntityConnection | List of supported variables. | ### SastCiConfigurationEntity @@ -3228,13 +3330,13 @@ Represents summary of a security report. | Field | Type | Description | | ----- | ---- | ----------- | -| `apiFuzzing` | SecurityReportSummarySection | Aggregated counts for the api_fuzzing scan | -| `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 | -| `dependencyScanning` | SecurityReportSummarySection | Aggregated counts for the dependency_scanning scan | -| `sast` | SecurityReportSummarySection | Aggregated counts for the sast scan | -| `secretDetection` | SecurityReportSummarySection | Aggregated counts for the secret_detection scan | +| `apiFuzzing` | SecurityReportSummarySection | Aggregated counts for the `api_fuzzing` scan | +| `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 | +| `dependencyScanning` | SecurityReportSummarySection | Aggregated counts for the `dependency_scanning` scan | +| `sast` | SecurityReportSummarySection | Aggregated counts for the `sast` scan | +| `secretDetection` | SecurityReportSummarySection | Aggregated counts for the `secret_detection` scan | ### SecurityReportSummarySection @@ -3263,34 +3365,34 @@ A Sentry error. | Field | Type | Description | | ----- | ---- | ----------- | -| `count` | Int! | Count of occurrences | -| `culprit` | String! | Culprit of the error | -| `externalBaseUrl` | String! | External Base URL of the Sentry Instance | -| `externalUrl` | String! | External URL of the error | -| `firstReleaseLastCommit` | String | Commit the error was first seen | -| `firstReleaseShortVersion` | String | Release short version the error was first seen | -| `firstReleaseVersion` | String | Release version the error was first seen | -| `firstSeen` | Time! | Timestamp when the error was first seen | -| `frequency` | SentryErrorFrequency! => Array | Last 24hr stats of the error | -| `gitlabCommit` | String | GitLab commit SHA attributed to the Error based on the release version | -| `gitlabCommitPath` | String | Path to the GitLab page for the GitLab commit attributed to the error | -| `gitlabIssuePath` | String | URL of GitLab Issue | -| `id` | ID! | ID (global ID) of the error | -| `lastReleaseLastCommit` | String | Commit the error was last seen | -| `lastReleaseShortVersion` | String | Release short version the error was last seen | -| `lastReleaseVersion` | String | Release version the error was last seen | -| `lastSeen` | Time! | Timestamp when the error was last seen | -| `message` | String | Sentry metadata message of the error | -| `sentryId` | String! | ID (Sentry ID) of the error | -| `sentryProjectId` | ID! | ID of the project (Sentry project) | -| `sentryProjectName` | String! | Name of the project affected by the error | -| `sentryProjectSlug` | String! | Slug of the project affected by the error | -| `shortId` | String! | Short ID (Sentry ID) of the error | -| `status` | SentryErrorStatus! | Status of the error | -| `tags` | SentryErrorTags! | Tags associated with the Sentry Error | -| `title` | String! | Title of the error | -| `type` | String! | Type of the error | -| `userCount` | Int! | Count of users affected by the error | +| `count` | Int! | Count of occurrences. | +| `culprit` | String! | Culprit of the error. | +| `externalBaseUrl` | String! | External Base URL of the Sentry Instance. | +| `externalUrl` | String! | External URL of the error. | +| `firstReleaseLastCommit` | String | Commit the error was first seen. | +| `firstReleaseShortVersion` | String | Release short version the error was first seen. | +| `firstReleaseVersion` | String | Release version the error was first seen. | +| `firstSeen` | Time! | Timestamp when the error was first seen. | +| `frequency` | SentryErrorFrequency! => Array | Last 24hr stats of the error. | +| `gitlabCommit` | String | GitLab commit SHA attributed to the Error based on the release version. | +| `gitlabCommitPath` | String | Path to the GitLab page for the GitLab commit attributed to the error. | +| `gitlabIssuePath` | String | URL of GitLab Issue. | +| `id` | ID! | ID (global ID) of the error. | +| `lastReleaseLastCommit` | String | Commit the error was last seen. | +| `lastReleaseShortVersion` | String | Release short version the error was last seen. | +| `lastReleaseVersion` | String | Release version the error was last seen. | +| `lastSeen` | Time! | Timestamp when the error was last seen. | +| `message` | String | Sentry metadata message of the error. | +| `sentryId` | String! | ID (Sentry ID) of the error. | +| `sentryProjectId` | ID! | ID of the project (Sentry project). | +| `sentryProjectName` | String! | Name of the project affected by the error. | +| `sentryProjectSlug` | String! | Slug of the project affected by the error. | +| `shortId` | String! | Short ID (Sentry ID) of the error. | +| `status` | SentryErrorStatus! | Status of the error. | +| `tags` | SentryErrorTags! | Tags associated with the Sentry Error. | +| `title` | String! | Title of the error. | +| `type` | String! | Type of the error. | +| `userCount` | Int! | Count of users affected by the error. | ### SentryError @@ -3298,23 +3400,23 @@ A Sentry error. A simplified version of SentryDetailedError. | Field | Type | Description | | ----- | ---- | ----------- | -| `count` | Int! | Count of occurrences | -| `culprit` | String! | Culprit of the error | -| `externalUrl` | String! | External URL of the error | -| `firstSeen` | Time! | Timestamp when the error was first seen | -| `frequency` | SentryErrorFrequency! => Array | Last 24hr stats of the error | -| `id` | ID! | ID (global ID) of the error | -| `lastSeen` | Time! | Timestamp when the error was last seen | -| `message` | String | Sentry metadata message of the error | -| `sentryId` | String! | ID (Sentry ID) of the error | -| `sentryProjectId` | ID! | ID of the project (Sentry project) | -| `sentryProjectName` | String! | Name of the project affected by the error | -| `sentryProjectSlug` | String! | Slug of the project affected by the error | -| `shortId` | String! | Short ID (Sentry ID) of the error | -| `status` | SentryErrorStatus! | Status of the error | -| `title` | String! | Title of the error | -| `type` | String! | Type of the error | -| `userCount` | Int! | Count of users affected by the error | +| `count` | Int! | Count of occurrences. | +| `culprit` | String! | Culprit of the error. | +| `externalUrl` | String! | External URL of the error. | +| `firstSeen` | Time! | Timestamp when the error was first seen. | +| `frequency` | SentryErrorFrequency! => Array | Last 24hr stats of the error. | +| `id` | ID! | ID (global ID) of the error. | +| `lastSeen` | Time! | Timestamp when the error was last seen. | +| `message` | String | Sentry metadata message of the error. | +| `sentryId` | String! | ID (Sentry ID) of the error. | +| `sentryProjectId` | ID! | ID of the project (Sentry project). | +| `sentryProjectName` | String! | Name of the project affected by the error. | +| `sentryProjectSlug` | String! | Slug of the project affected by the error. | +| `shortId` | String! | Short ID (Sentry ID) of the error. | +| `status` | SentryErrorStatus! | Status of the error. | +| `title` | String! | Title of the error. | +| `type` | String! | Type of the error. | +| `userCount` | Int! | Count of users affected by the error. | ### SentryErrorCollection @@ -3322,17 +3424,17 @@ An object containing a collection of Sentry errors, and a detailed error. | 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 | +| `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 | Field | Type | Description | | ----- | ---- | ----------- | -| `count` | Int! | Count of errors received since the previously recorded time | -| `time` | Time! | Time the error frequency stats were recorded | +| `count` | Int! | Count of errors received since the previously recorded time. | +| `time` | Time! | Time the error frequency stats were recorded. | ### SentryErrorStackTrace @@ -3340,9 +3442,9 @@ An object containing a stack trace entry for a Sentry error. | 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 | +| `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 @@ -3350,8 +3452,8 @@ An object context for a Sentry error stack trace. | Field | Type | Description | | ----- | ---- | ----------- | -| `code` | String! | Code number of the context | -| `line` | Int! | Line number of the context | +| `code` | String! | Code number of the context. | +| `line` | Int! | Line number of the context. | ### SentryErrorStackTraceEntry @@ -3359,11 +3461,11 @@ An object containing a stack trace entry for a Sentry error. | 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 | +| `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 @@ -3371,8 +3473,8 @@ State of a Sentry error. | Field | Type | Description | | ----- | ---- | ----------- | -| `level` | String | Severity level of the Sentry Error | -| `logger` | String | Logger of the Sentry Error | +| `level` | String | Severity level of the Sentry Error. | +| `logger` | String | Logger of the Sentry Error. | ### Snippet @@ -3427,7 +3529,7 @@ Represents how the blob content should be displayed. | ----- | ---- | ----------- | | `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 | +| `loadAsync` | Boolean! | Shows whether the blob content is loaded asynchronously | | `loadingPartialName` | String! | Loading partial name | | `renderError` | String | Error rendering the blob content | | `tooLarge` | Boolean! | Shows whether the blob too large to be displayed | @@ -3463,11 +3565,11 @@ Represents the Geo sync and verification state of a snippet repository. | Field | Type | Description | | ----- | ---- | ----------- | -| `buttonTitle` | String | Title for the button, for example: Retry this job | -| `icon` | String | Icon used in the action button | -| `method` | String | Method for the action, for example: :post | -| `path` | String | Path for the action | -| `title` | String | Title for the action, for example: Retry | +| `buttonTitle` | String | Title for the button, for example: Retry this job. | +| `icon` | String | Icon used in the action button. | +| `method` | String | Method for the action, for example: :post. | +| `path` | String | Path for the action. | +| `title` | String | Title for the action, for example: Retry. | ### Submodule @@ -3477,7 +3579,7 @@ Represents the Geo sync and verification state of a snippet repository. | `id` | ID! | ID of the entry | | `name` | String! | Name of the entry | | `path` | String! | Path of the entry | -| `sha` | String! | Last commit sha for the entry | +| `sha` | String! | Last commit SHA for the entry | | `treeUrl` | String | Tree URL for the sub-module | | `type` | EntryType! | Type of tree entry | | `webUrl` | String | Web URL for the sub-module | @@ -3608,19 +3710,19 @@ Represents a historically accurate report about the timebox. ### Todo -Representing a todo entry. +Representing a to-do entry. | Field | Type | Description | | ----- | ---- | ----------- | -| `action` | TodoActionEnum! | Action of the 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 | -| `id` | ID! | ID of the todo | -| `project` | Project | The project this todo is associated with | -| `state` | TodoStateEnum! | State of the todo | -| `targetType` | TodoTargetEnum! | Target type of the todo | +| `action` | TodoActionEnum! | Action of the to-do item | +| `author` | User! | The author of this to-do item | +| `body` | String! | Body of the to-do item | +| `createdAt` | Time! | Timestamp this to-do item was created | +| `group` | Group | Group this to-do item is associated with | +| `id` | ID! | ID of the to-do item | +| `project` | Project | The project this to-do item is associated with | +| `state` | TodoStateEnum! | State of the to-do item | +| `targetType` | TodoTargetEnum! | Target type of the to-do item | ### TodoCreatePayload @@ -3630,7 +3732,7 @@ Autogenerated return type of TodoCreate. | ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -| `todo` | Todo | The to-do created. | +| `todo` | Todo | The to-do item created. | ### TodoMarkDonePayload @@ -3640,7 +3742,7 @@ Autogenerated return type of TodoMarkDone. | ----- | ---- | ----------- | | `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. | +| `todo` | Todo! | The requested to-do item. | ### TodoRestoreManyPayload @@ -3650,8 +3752,8 @@ Autogenerated return type of TodoRestoreMany. | ----- | ---- | ----------- | | `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}** | TodoID! => Array | **Deprecated:** Use todos. Deprecated in 13.2. | +| `todos` | Todo! => Array | Updated to-do items. | +| `updatedIds` **{warning-solid}** | TodoID! => Array | **Deprecated:** Use to-do items. Deprecated in 13.2. | ### TodoRestorePayload @@ -3661,7 +3763,7 @@ Autogenerated return type of TodoRestore. | ----- | ---- | ----------- | | `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. | +| `todo` | Todo! | The requested to-do item. | ### TodosMarkAllDonePayload @@ -3671,8 +3773,8 @@ Autogenerated return type of TodosMarkAllDone. | ----- | ---- | ----------- | | `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}** | TodoID! => Array | **Deprecated:** Use todos. Deprecated in 13.2. | +| `todos` | Todo! => Array | Updated to-do items. | +| `updatedIds` **{warning-solid}** | TodoID! => Array | **Deprecated:** Use to-do items. Deprecated in 13.2. | ### ToggleAwardEmojiPayload @@ -3704,7 +3806,7 @@ Represents a directory. | `id` | ID! | ID of the entry | | `name` | String! | Name of the entry | | `path` | String! | Path of the entry | -| `sha` | String! | Last commit sha for the entry | +| `sha` | String! | Last commit SHA for the entry | | `type` | EntryType! | Type of tree entry | | `webPath` | String | Web path for the tree entry (directory) | | `webUrl` | String | Web URL for the tree entry (directory) | @@ -3719,7 +3821,7 @@ Autogenerated return type of UpdateAlertStatus. | `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. | +| `todo` | Todo | The to-do item after mutation. | ### UpdateBoardEpicUserPreferencesPayload @@ -3857,10 +3959,13 @@ Autogenerated return type of UpdateSnippet. | Field | Type | Description | | ----- | ---- | ----------- | +| `captchaSiteKey` | String | The CAPTCHA site key which must be used to render a challenge for the user to solve to obtain a valid captchaResponse value. Included only when an operation was not completed because "NeedsCaptchaResponse" is true. | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `needsCaptchaResponse` | Boolean | Indicates whether the operation was detected as possible spam and not completed. If CAPTCHA is enabled, the request must be resubmitted with a valid CAPTCHA response and spam_log_id included for the operation to be completed. Included only when an operation was not completed because "NeedsCaptchaResponse" is true. | | `snippet` | Snippet | The snippet after mutation. | -| `spam` | Boolean | Indicates whether the operation returns a record detected as spam. | +| `spam` | Boolean | Indicates whether the operation was detected as definite spam. There is no option to resubmit the request with a CAPTCHA response. | +| `spamLogId` | Int | The spam log ID which must be passed along with a valid CAPTCHA response for an operation to be completed. Included only when an operation was not completed because "NeedsCaptchaResponse" is true. | ### User @@ -3882,7 +3987,7 @@ Autogenerated return type of UpdateSnippet. | `starredProjects` | ProjectConnection | Projects starred by the user | | `state` | UserState! | State of the user | | `status` | UserStatus | User status | -| `todos` | TodoConnection! | Todos of the user | +| `todos` | TodoConnection! | To-do items of the user | | `userPermissions` | UserPermissions! | Permissions for the current user on the resource | | `username` | String! | Username of the user. Unique within this instance of GitLab | | `webPath` | String! | Web path of the user | @@ -3937,6 +4042,7 @@ Represents a vulnerability. | `confirmedAt` | Time | Timestamp of when the vulnerability state was changed to confirmed | | `confirmedBy` | User | The user that confirmed the vulnerability. | | `description` | String | Description of the vulnerability | +| `details` | VulnerabilityDetail! => Array | Details of the vulnerability | | `detectedAt` | Time! | Timestamp of when the vulnerability was first detected | | `discussions` | DiscussionConnection! | All discussions on this noteable | | `dismissedAt` | Time | Timestamp of when the vulnerability state was changed to dismissed | @@ -3973,6 +4079,155 @@ Autogenerated return type of VulnerabilityConfirm. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `vulnerability` | Vulnerability | The vulnerability after state change. | +### VulnerabilityDetailBase + +Represents the vulnerability details base. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String! | Description of the field. | +| `fieldName` | String | Name of the field. | +| `name` | String! | Name of the field. | + +### VulnerabilityDetailBoolean + +Represents the vulnerability details boolean value. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String! | Description of the field. | +| `fieldName` | String | Name of the field. | +| `name` | String! | Name of the field. | +| `value` | Boolean! | Value of the field. | + +### VulnerabilityDetailCode + +Represents the vulnerability details code field. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String! | Description of the field. | +| `fieldName` | String | Name of the field. | +| `lang` | String | Language of the code. | +| `name` | String! | Name of the field. | +| `value` | String! | Source code. | + +### VulnerabilityDetailCommit + +Represents the vulnerability details commit field. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String! | Description of the field. | +| `fieldName` | String | Name of the field. | +| `name` | String! | Name of the field. | +| `value` | String! | The commit SHA value. | + +### VulnerabilityDetailDiff + +Represents the vulnerability details diff field. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `after` | String! | Value of the field after the change. | +| `before` | String! | Value of the field before the change. | +| `description` | String! | Description of the field. | +| `fieldName` | String | Name of the field. | +| `name` | String! | Name of the field. | + +### VulnerabilityDetailFileLocation + +Represents the vulnerability details location within a file in the project. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String! | Description of the field. | +| `fieldName` | String | Name of the field. | +| `fileName` | String! | File name. | +| `lineEnd` | Int! | End line number of the file location. | +| `lineStart` | Int! | Start line number of the file location. | +| `name` | String! | Name of the field. | + +### VulnerabilityDetailInt + +Represents the vulnerability details integer value. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String! | Description of the field. | +| `fieldName` | String | Name of the field. | +| `name` | String! | Name of the field. | +| `value` | Int! | Value of the field. | + +### VulnerabilityDetailList + +Represents the vulnerability details list value. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String! | Description of the field. | +| `fieldName` | String | Name of the field. | +| `items` | VulnerabilityDetail! => Array | List of details. | +| `name` | String! | Name of the field. | + +### VulnerabilityDetailMarkdown + +Represents the vulnerability details Markdown field. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String! | Description of the field. | +| `fieldName` | String | Name of the field. | +| `name` | String! | Name of the field. | +| `value` | String! | Value of the Markdown field. | + +### VulnerabilityDetailModuleLocation + +Represents the vulnerability details location within a file in the project. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String! | Description of the field. | +| `fieldName` | String | Name of the field. | +| `moduleName` | String! | Module name. | +| `name` | String! | Name of the field. | +| `offset` | Int! | Offset of the module location. | + +### VulnerabilityDetailTable + +Represents the vulnerability details table value. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String! | Description of the field. | +| `fieldName` | String | Name of the field. | +| `headers` | VulnerabilityDetail! => Array | Table headers. | +| `name` | String! | Name of the field. | +| `rows` | VulnerabilityDetail! => Array | Table rows. | + +### VulnerabilityDetailText + +Represents the vulnerability details text field. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String! | Description of the field. | +| `fieldName` | String | Name of the field. | +| `name` | String! | Name of the field. | +| `value` | String! | Value of the text field. | + +### VulnerabilityDetailUrl + +Represents the vulnerability details URL field. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String! | Description of the field. | +| `fieldName` | String | Name of the field. | +| `href` | String! | Href of the URL. | +| `name` | String! | Name of the field. | +| `text` | String | Text of the URL. | + ### VulnerabilityDismissPayload Autogenerated return type of VulnerabilityDismiss. @@ -4049,6 +4304,7 @@ Represents the location of a vulnerability found by a Coverage Fuzzing scan. | Field | Type | Description | | ----- | ---- | ----------- | +| `blobPath` | String | Blob path to the vulnerable file | | `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 | @@ -4072,6 +4328,7 @@ Represents the location of a vulnerability found by a dependency security scan. | Field | Type | Description | | ----- | ---- | ----------- | +| `blobPath` | String | Blob path to the vulnerable file | | `dependency` | VulnerableDependency | Dependency containing the vulnerability | | `file` | String | Path to the vulnerable file | @@ -4081,6 +4338,7 @@ Represents the location of a vulnerability found by a SAST scan. | Field | Type | Description | | ----- | ---- | ----------- | +| `blobPath` | String | Blob path to the vulnerable file | | `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 | @@ -4093,6 +4351,7 @@ Represents the location of a vulnerability found by a secret detection scan. | Field | Type | Description | | ----- | ---- | ----------- | +| `blobPath` | String | Blob path to the vulnerable file | | `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 | @@ -4754,15 +5013,17 @@ State of a GitLab merge request. | `all` | | | `closed` | | | `locked` | | -| `merged` | | +| `merged` | Merge Request has been merged | | `opened` | | ### MilestoneStateEnum +Current state of milestone. + | Value | Description | | ----- | ----------- | -| `active` | | -| `closed` | | +| `active` | Milestone is currently active | +| `closed` | Milestone is closed | ### MoveType diff --git a/doc/api/graphql/removed_items.md b/doc/api/graphql/removed_items.md index f05b23495bb..2761c1a1c84 100644 --- a/doc/api/graphql/removed_items.md +++ b/doc/api/graphql/removed_items.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Product Planning +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + # GraphQL API removed items GraphQL is a versionless API, unlike the REST API. diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index 7698fa9ba5f..e3fcaa3db37 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -12,11 +12,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w Badges support placeholders that are replaced in real time in both the link and image URL. The allowed placeholders are: +<!-- vale gitlab.Spelling = NO --> + - **%{project_path}**: replaced by the project path. - **%{project_id}**: replaced by the project ID. - **%{default_branch}**: replaced by the project default branch. - **%{commit_sha}**: replaced by the last project's commit SHA. +<!-- vale gitlab.Spelling = YES --> + Because these endpoints aren't inside a project's context, the information used to replace the placeholders comes from the first group's project by creation date. If the group hasn't got any project the original URL with the placeholders is returned. diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index 722f3a76267..b892962e2b2 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -76,7 +76,7 @@ Example response: ] ``` -Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) see +Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) see different parameters, due to the ability to have multiple group boards. Example response: @@ -192,7 +192,7 @@ Example response: } ``` -Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) see +Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) see different parameters, due to the ability to have multiple group issue boards. Example response: diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index f169c1829be..c4044b2332b 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Group clusters API +# Group clusters API **(CORE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30213) in GitLab 12.1. diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index 57670eff1ea..ac367bf7e5a 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -94,7 +94,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "name=i NOTE: The maximum import file size can be set by the Administrator, default is `0` (unlimited). -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](settings.md#change-application-settings) or the [Admin UI](../user/admin_area/settings/account_and_limit_settings.md). +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](settings.md#change-application-settings) or the [Admin UI](../user/admin_area/settings/account_and_limit_settings.md). Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. ## Important notes diff --git a/doc/api/group_iterations.md b/doc/api/group_iterations.md index d96f0881088..715f40e8325 100644 --- a/doc/api/group_iterations.md +++ b/doc/api/group_iterations.md @@ -49,7 +49,8 @@ Example response: "created_at": "2020-01-27T05:07:12.573Z", "updated_at": "2020-01-27T05:07:12.573Z", "due_date": "2020-02-01", - "start_date": "2020-02-14" + "start_date": "2020-02-14", + "web_url": "http://gitlab.example.com/groups/my-group/-/iterations/13" } ] ``` diff --git a/doc/api/group_wikis.md b/doc/api/group_wikis.md index f8804d1eadc..6c5e2b77f93 100644 --- a/doc/api/group_wikis.md +++ b/doc/api/group_wikis.md @@ -1,6 +1,6 @@ --- stage: Create -group: Knowledge +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/#assignments" type: reference, api --- @@ -179,9 +179,9 @@ POST /groups/:id/wikis/attachments | `file` | string | yes | The attachment to be uploaded | | `branch` | string | no | The name of the branch. Defaults to the wiki repository default branch | -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 diff --git a/doc/api/groups.md b/doc/api/groups.md index eb255f8de00..0aba679655b 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -685,7 +685,7 @@ Additional response parameters: } ``` -Users on GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/) also see +Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see the `marked_for_deletion_on` attribute: ```json @@ -764,8 +764,8 @@ Parameters: | `request_access_enabled` | boolean | no | Allow users to request member access. | | `parent_id` | integer | no | The parent group ID for creating nested group. | | `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). Default to the global level default branch protection setting. | -| `shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | -| `extra_shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | +| `shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | +| `extra_shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | ### Options for `default_branch_protection` @@ -838,8 +838,8 @@ PUT /groups/:id | `request_access_enabled` | boolean | no | Allow users to request member access. | | `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). | | `file_template_project_id` | integer | no | **(PREMIUM)** The ID of a project to load custom file templates from. | -| `shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | -| `extra_shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | +| `shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | +| `extra_shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | | `prevent_forking_outside_group` | boolean | no | **(PREMIUM)** When enabled, users can **not** fork projects from this group to external namespaces | `shared_runners_setting` | string | no | See [Options for `shared_runners_setting`](#options-for-shared_runners_setting). Enable or disable shared runners for a group's subgroups and projects. | @@ -941,6 +941,19 @@ The `shared_runners_setting` attribute determines whether shared runners are ena | `disabled_with_override` | Disables shared runners for all projects and subgroups in this group, but allows subgroups to override this setting. | | `disabled_and_unoverridable` | Disables shared runners for all projects and subgroups in this group, and prevents subgroups from overriding this setting. | +### Upload a group avatar + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36681) in GitLab 12.9. + +To upload an avatar 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 file system and be preceded by +`@`. For example: + +```shell +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22" --form "avatar=@/tmp/example.png" +``` + ## Remove group Only available to group owners and administrators. @@ -948,7 +961,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 happens 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). +- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium](https://about.gitlab.com/pricing/) or higher tiers, marks a group for deletion. The deletion happens 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 @@ -997,7 +1010,7 @@ GET /groups?search=foobar ] ``` -## Hooks +## Hooks **(PREMIUM)** Also called Group Hooks and Webhooks. These are different from [System Hooks](system_hooks.md) that are system wide and [Project Hooks](projects.md#hooks) that are limited to one project. @@ -1044,6 +1057,7 @@ GET /groups/:id/hooks/:hook_id "wiki_page_events": true, "deployment_events": true, "releases_events": true, + "subgroup_events": true, "enable_ssl_verification": true, "created_at": "2012-10-12T17:04:47Z" } @@ -1073,6 +1087,7 @@ POST /groups/:id/hooks | `wiki_page_events` | boolean | no | Trigger hook on wiki events | | `deployment_events` | boolean | no | Trigger hook on deployment events | | `releases_events` | boolean | no | Trigger hook on release events | +| `subgroup_events` | boolean | no | Trigger hook on subgroup events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | | `token` | string | no | Secret token to validate received payloads; not returned in the response | @@ -1101,6 +1116,7 @@ PUT /groups/:id/hooks/:hook_id | `wiki_events` | boolean | no | Trigger hook on wiki events | | `deployment_events` | boolean | no | Trigger hook on deployment events | | `releases_events` | boolean | no | Trigger hook on release events | +| `subgroup_events` | boolean | no | Trigger hook on subgroup events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | | `token` | string | no | Secret token to validate received payloads; not returned in the response | @@ -1122,7 +1138,7 @@ DELETE /groups/:id/hooks/:hook_id Group audit events can be accessed via the [Group Audit Events API](audit_events.md#group-audit-events) -## Sync group with LDAP **(STARTER ONLY)** +## Sync group with LDAP **(PREMIUM SELF)** Syncs the group with its linked LDAP group. Only available to group owners and administrators. @@ -1142,7 +1158,7 @@ Please consult the [Group Members](members.md) documentation. List, add, and delete LDAP group links. -### List LDAP group links **(STARTER ONLY)** +### List LDAP group links **(PREMIUM SELF)** Lists LDAP group links. @@ -1154,7 +1170,7 @@ GET /groups/:id/ldap_group_links | --------- | -------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -### Add LDAP group link with CN or filter **(STARTER ONLY)** +### Add LDAP group link with CN or filter **(PREMIUM SELF)** Adds an LDAP group link using a CN or filter. Adding a group link by filter is only supported in the Premium tier and above. @@ -1173,7 +1189,7 @@ POST /groups/:id/ldap_group_links NOTE: To define the LDAP group link, provide either a `cn` or a `filter`, but not both. -### Delete LDAP group link **(STARTER ONLY)** +### Delete LDAP group link **(PREMIUM SELF)** Deletes an LDAP group link. Deprecated. Scheduled for removal in a future release. @@ -1198,7 +1214,7 @@ DELETE /groups/:id/ldap_group_links/:provider/:cn | `cn` | string | yes | The CN of an LDAP group | | `provider` | string | yes | LDAP provider for the LDAP group link | -### Delete LDAP group link with CN or filter **(STARTER ONLY)** +### Delete LDAP group link with CN or filter **(PREMIUM SELF)** Deletes an LDAP group link using a CN or filter. Deleting by filter is only supported in the Premium tier and above. @@ -1306,7 +1322,7 @@ GET /groups/:id/push_rule } ``` -Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) also see +Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see the `commit_committer_check` and `reject_unsigned_commits` parameters: ```json diff --git a/doc/api/instance_clusters.md b/doc/api/instance_clusters.md index d5c033563d6..164830f2f34 100644 --- a/doc/api/instance_clusters.md +++ b/doc/api/instance_clusters.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Instance clusters API +# Instance clusters API **(CORE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36001) in GitLab 13.2. diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index b94207f8e16..0d55b77df0e 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.md @@ -4,9 +4,9 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issue links API **(CORE)** +# Issue links API **(FREE)** -> The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4. +> The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.4. ## List issue relations diff --git a/doc/api/iterations.md b/doc/api/iterations.md index 1ee489e4cf1..ff6e8e2542f 100644 --- a/doc/api/iterations.md +++ b/doc/api/iterations.md @@ -51,7 +51,8 @@ Example response: "created_at": "2020-01-27T05:07:12.573Z", "updated_at": "2020-01-27T05:07:12.573Z", "due_date": "2020-02-01", - "start_date": "2020-02-14" + "start_date": "2020-02-14", + "web_url": "http://gitlab.example.com/groups/my-group/-/iterations/13" } ] ``` diff --git a/doc/api/license.md b/doc/api/license.md index 9aaf68d5b89..7aa00335933 100644 --- a/doc/api/license.md +++ b/doc/api/license.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# License **(CORE ONLY)** +# License **(FREE SELF)** To interact with license endpoints, you need to authenticate yourself as an administrator. diff --git a/doc/api/license_templates.md b/doc/api/license_templates.md deleted file mode 100644 index 7587721968b..00000000000 --- a/doc/api/license_templates.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'templates/licenses.md' ---- - -This document was moved to [another location](templates/licenses.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/members.md b/doc/api/members.md index 47b686d9275..bf2bf8c1220 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -284,6 +284,7 @@ Example response: "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", + "last_activity_on": "2021-01-27" }, { "id": 2, @@ -292,7 +293,8 @@ Example response: "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", - "email": "john@example.com" + "email": "john@example.com", + "last_activity_on": "2021-01-25" }, { "id": 3, @@ -300,7 +302,8 @@ Example response: "name": "Foo bar", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", - "web_url": "http://192.168.1.8:3000/root" + "web_url": "http://192.168.1.8:3000/root", + "last_activity_on": "2021-01-20" } ] ``` @@ -319,7 +322,7 @@ POST /projects/:id/members | `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer/string | yes | The user ID of the new member or multiple IDs separated by commas | | `access_level` | integer | yes | A valid access level | -| `expires_at` | string | no | A date string in the format YEAR-MONTH-DAY | +| `expires_at` | string | no | A date string in the format `YEAR-MONTH-DAY` | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "user_id=1&access_level=30" "https://gitlab.example.com/api/v4/groups/:id/members" @@ -357,7 +360,7 @@ PUT /projects/:id/members/:user_id | `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | | `access_level` | integer | yes | A valid access level | -| `expires_at` | string | no | A date string in the format YEAR-MONTH-DAY | +| `expires_at` | string | no | A date string in the format `YEAR-MONTH-DAY` | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/:user_id?access_level=40" diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index e3ebb61768e..5b8bad1d685 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Merge request approvals API **(STARTER)** +# Merge request approvals API **(PREMIUM)** Configuration for approvals on all Merge Requests (MR) in the project. Must be authenticated for all endpoints. @@ -13,7 +13,8 @@ Configuration for approvals on all Merge Requests (MR) in the project. Must be a ### Get Configuration -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in GitLab 10.6. +> - Moved to GitLab Premium in 13.9. You can request information about a project's approval configuration using the following endpoint: @@ -41,7 +42,8 @@ GET /projects/:id/approvals ### Change configuration -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in GitLab 10.6. +> - Moved to GitLab Premium in 13.9. If you are allowed to, you can change approval configuration using the following endpoint: @@ -75,7 +77,8 @@ POST /projects/:id/approvals ### Get project-level rules -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. +> - Moved to GitLab Premium in 13.9. > - `protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. You can request information about a project's approval rules using the following endpoint: @@ -273,7 +276,8 @@ GET /projects/:id/approval_rules/:approval_rule_id ### Create project-level rule -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. +> - Moved to GitLab Premium in 13.9. You can create project approval rules using the following endpoint: @@ -375,7 +379,8 @@ POST /projects/:id/approval_rules ### Update project-level rule -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. +> - Moved to GitLab Premium in 13.9. You can update project approval rules using the following endpoint: @@ -480,7 +485,8 @@ PUT /projects/:id/approval_rules/:approval_rule_id ### Delete project-level rule -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. +> - Moved to GitLab Premium in 13.9. You can delete project approval rules using the following endpoint: @@ -497,7 +503,8 @@ DELETE /projects/:id/approval_rules/:approval_rule_id ### Change allowed approvers -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in GitLab 10.6. +> - Moved to GitLab Premium in 13.9. NOTE: This API endpoint has been deprecated. Please use Approval Rule API instead. @@ -566,7 +573,8 @@ Configuration for approvals on a specific Merge Request. Must be authenticated f ### Get Configuration -> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.9. +> - Introduced in GitLab 8.9. +> - Moved to GitLab Premium in 13.9. You can request information about a merge request's approval status using the following endpoint: @@ -612,7 +620,8 @@ GET /projects/:id/merge_requests/:merge_request_iid/approvals ### Change approval configuration -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in GitLab 10.6. +> - Moved to GitLab Premium in 13.9. If you are allowed to, you can change `approvals_required` using the following endpoint: @@ -648,7 +657,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals ### Change allowed approvers for Merge Request -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in GitLab 10.6. +> - Moved to GitLab Premium in 13.9. NOTE: This API endpoint has been deprecated. Please use Approval Rule API instead. @@ -722,7 +732,8 @@ PUT /projects/:id/merge_requests/:merge_request_iid/approvers ### Get the approval state of merge requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13712) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13712) in GitLab 12.3. +> - Moved to GitLab Premium in 13.9. You can request information about a merge request's approval state by using the following endpoint: @@ -794,7 +805,8 @@ This includes additional information about the users who have already approved ### Get merge request level rules -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13712) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13712) in GitLab 12.3. +> - Moved to GitLab Premium in 13.9. You can request information about a merge request's approval rules using the following endpoint: @@ -871,7 +883,8 @@ GET /projects/:id/merge_requests/:merge_request_iid/approval_rules ### Create merge request level rule -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. +> - Moved to GitLab Premium in 13.9. You can create merge request approval rules using the following endpoint: @@ -955,7 +968,8 @@ will be used. ### Update merge request level rule -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. +> - Moved to GitLab Premium in 13.9. You can update merge request approval rules using the following endpoint: @@ -1040,7 +1054,8 @@ These are system generated rules. ### Delete merge request level rule -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. +> - Moved to GitLab Premium in 13.9. You can delete merge request approval rules using the following endpoint: @@ -1061,7 +1076,8 @@ These are system generated rules. ## Approve Merge Request -> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.9. +> - Introduced in GitLab 8.9. +> - Moved to GitLab Premium in 13.9. If you are allowed to, you can approve a merge request using the following endpoint: @@ -1077,7 +1093,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve | `id` | integer | yes | The ID of a project | | `merge_request_iid` | integer | yes | The IID of MR | | `sha` | string | no | The HEAD of the MR | -| `approval_password` **(STARTER)** | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/merge_request_approvals.md#require-authentication-when-approving-a-merge-request) is enabled in the project settings. | +| `approval_password` **(PREMIUM)** | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/merge_request_approvals.md#require-authentication-when-approving-a-merge-request) is enabled in the project settings. | The `sha` parameter works in the same way as when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must @@ -1124,7 +1140,8 @@ does not match, the response code will be `409`. ## Unapprove Merge Request ->Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 9.0. +> - Introduced in GitLab 9.0. +> - Moved to GitLab Premium in 13.9. If you did approve a merge request, you can unapprove it using the following endpoint: diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index c43ac96a42f..097a9e5937f 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -15,6 +15,7 @@ type: reference, api > - `reference` was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) in GitLab 12.10 in favour of `references`. > - `with_merge_status_recheck` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. > - `reviewer_username` and `reviewer_id` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. +> - `reviewer_ids` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51186) in GitLab 13.8. Every API call to merge requests must be authenticated. @@ -30,7 +31,7 @@ If you need the value of these fields from this endpoint, set the `with_merge_st `true` in the query. - `references.relative` is relative to the group or project that the merge request is being requested. When the merge request is fetched from its project, `relative` format would be the same as `short` format, and when requested across groups or projects, it is expected to be the same as `full` format. -- If `approvals_before_merge` **(STARTER)** is not provided, it inherits the value from the target project. If provided, the following conditions must hold for it to take effect: +- If `approvals_before_merge` is not provided, it inherits the value from the target project. If provided, the following conditions must hold for it to take effect: - The target project's `approvals_before_merge` must be greater than zero. A value of zero disables approvals for that project. @@ -91,8 +92,8 @@ Parameters: | `author_id` | integer | no | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | | `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | -| `approver_ids` **(STARTER)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | -| `approved_by_ids` **(STARTER)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | +| `approver_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | +| `approved_by_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `reviewer_id` | integer | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | | `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. | | `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | @@ -216,7 +217,7 @@ Parameters: ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see +Users on GitLab Premium or higher also see the `approvals_before_merge` parameter: ```json @@ -277,8 +278,8 @@ Parameters: | `author_id` | integer | no | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. | | `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.| | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | -| `approver_ids` **(STARTER)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | -| `approved_by_ids` **(STARTER)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | +| `approver_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | +| `approved_by_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `reviewer_id` | integer | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | | `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. | @@ -401,7 +402,7 @@ Parameters: ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see +Users on GitLab Premium or higher also see the `approvals_before_merge` parameter: ```json @@ -453,8 +454,8 @@ Parameters: | `author_id` | integer | no | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5)_. | | `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 12.10)_. | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5)_. | -| `approver_ids` **(STARTER)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | -| `approved_by_ids` **(STARTER)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | +| `approver_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | +| `approved_by_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `reviewer_id` | integer | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#enable-or-disable-merge-request-reviewers) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | | `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#enable-or-disable-merge-request-reviewers) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. | | `my_reaction_emoji` | string | no | Return merge requests 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)_. | @@ -574,7 +575,7 @@ Parameters: ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see +Users on GitLab Premium or higher also see the `approvals_before_merge` parameter: ```json @@ -745,7 +746,7 @@ Parameters: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see +Users on GitLab Premium also see the `approvals_before_merge` parameter: ```json @@ -884,6 +885,14 @@ Parameters: "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", "web_url": "https://gitlab.example.com/axel.block" }], + "reviewers": [{ + "name": "Miss Monserrate Beier", + "username": "axel.block", + "id": 12, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", + "web_url": "https://gitlab.example.com/axel.block" + }], "source_project_id": 4, "target_project_id": 4, "labels": [ ], @@ -1052,6 +1061,8 @@ POST /projects/:id/merge_requests | `title` | string | yes | Title of MR. | | `assignee_id` | integer | no | Assignee user ID. | | `assignee_ids` | integer array | no | The ID of the user(s) to assign the MR to. Set to `0` or provide an empty value to unassign all assignees. | +| `assignee_ids` | integer array | no | The ID of the user(s) to assign the MR to. If set to `0` or left empty, there will be no assignees added. | +| `reviewer_ids` | integer array | no | The ID of the user(s) added as a reviewer to the MR. If set to `0` or left empty, there will be no reviewers added. | | `description` | string | no | Description of MR. Limited to 1,048,576 characters. | | `target_project_id` | integer | no | The target project (numeric ID). | | `labels` | string | no | Labels for MR as a comma-separated list. | @@ -1200,6 +1211,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid | `title` | string | no | Title of MR. | | `assignee_id` | integer | no | The ID of the user to assign the merge request to. Set to `0` or provide an empty value to unassign all assignees. | | `assignee_ids` | integer array | no | The ID of the user(s) to assign the MR to. Set to `0` or provide an empty value to unassign all assignees. | +| `reviewer_ids` | integer array | no | The ID of the user(s) set as a reviewer to the MR. Set the value to `0` or provide an empty value to unset all reviewers. | | `milestone_id` | integer | no | The global ID of a milestone to assign the merge request to. Set to `0` or provide an empty value to unassign a milestone.| | `labels` | string | no | Comma-separated label names for a merge request. Set to an empty string to unassign all labels. | | `add_labels` | string | no | Comma-separated label names to add to a merge request. | @@ -1252,6 +1264,14 @@ Must include at least one non-required attribute from above. "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", "web_url": "https://gitlab.example.com/axel.block" }], + "reviewers": [{ + "name": "Miss Monserrate Beier", + "username": "axel.block", + "id": 12, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", + "web_url": "https://gitlab.example.com/axel.block" + }], "source_project_id": 2, "target_project_id": 3, "labels": [ @@ -1333,7 +1353,7 @@ Must include at least one non-required attribute from above. } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see +Users on GitLab Premium or higher also see the `approvals_before_merge` parameter: ```json @@ -1386,7 +1406,7 @@ Parameters: | `merge_request_iid` | integer | yes | The internal ID of the merge request. | | `merge_commit_message` | string | no | Custom merge commit message. | | `squash_commit_message` | string | no | Custom squash commit message. | -| `squash` | boolean | no | If `true` the commits the commits are squashed into a single commit on merge. | +| `squash` | boolean | no | If `true` the commits are squashed into a single commit on merge. | | `should_remove_source_branch` | boolean | no | If `true` removes the source branch. | | `merge_when_pipeline_succeeds` | boolean | no | If `true` the MR is merged when the pipeline succeeds. | | `sha` | string | no | If present, then this SHA must match the HEAD of the source branch, otherwise the merge fails. | @@ -1429,6 +1449,14 @@ Parameters: "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", "web_url": "https://gitlab.example.com/axel.block" }], + "reviewers": [{ + "name": "Miss Monserrate Beier", + "username": "axel.block", + "id": 12, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", + "web_url": "https://gitlab.example.com/axel.block" + }], "source_project_id": 2, "target_project_id": 3, "labels": [ @@ -1510,7 +1538,7 @@ Parameters: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see +Users on GitLab Premium also see the `approvals_before_merge` parameter: ```json @@ -1609,6 +1637,14 @@ Parameters: "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", "web_url": "https://gitlab.example.com/axel.block" }], + "reviewers": [{ + "name": "Miss Monserrate Beier", + "username": "axel.block", + "id": 12, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", + "web_url": "https://gitlab.example.com/axel.block" + }], "source_project_id": 2, "target_project_id": 3, "labels": [ @@ -1690,7 +1726,7 @@ Parameters: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see +Users on GitLab Premium or higher also see the `approvals_before_merge` parameter: ```json @@ -1902,6 +1938,14 @@ Example response: "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", "web_url": "https://gitlab.example.com/axel.block" }], + "reviewers": [{ + "name": "Miss Monserrate Beier", + "username": "axel.block", + "id": 12, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", + "web_url": "https://gitlab.example.com/axel.block" + }], "source_project_id": 2, "target_project_id": 3, "labels": [ @@ -1982,7 +2026,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see +Users on GitLab Premium also see the `approvals_before_merge` parameter: ```json @@ -2053,6 +2097,14 @@ Example response: "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", "web_url": "https://gitlab.example.com/axel.block" }], + "reviewers": [{ + "name": "Miss Monserrate Beier", + "username": "axel.block", + "id": 12, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", + "web_url": "https://gitlab.example.com/axel.block" + }], "source_project_id": 2, "target_project_id": 3, "labels": [ @@ -2133,7 +2185,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see +Users on GitLab Premium or higher also see the `approvals_before_merge` parameter: ```json @@ -2224,6 +2276,14 @@ Example response: "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", "web_url": "https://gitlab.example.com/axel.block" }], + "reviewers": [{ + "name": "Miss Monserrate Beier", + "username": "axel.block", + "id": 12, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", + "web_url": "https://gitlab.example.com/axel.block" + }], "source_project_id": 3, "target_project_id": 3, "labels": [], @@ -2513,7 +2573,7 @@ Example response: } ``` -## Approvals **(STARTER)** +## Approvals For approvals, please see [Merge Request Approvals](merge_request_approvals.md) diff --git a/doc/api/metrics_dashboard_annotations.md b/doc/api/metrics_dashboard_annotations.md index b92e26b03fb..896420ed0fb 100644 --- a/doc/api/metrics_dashboard_annotations.md +++ b/doc/api/metrics_dashboard_annotations.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Dashboard annotations API +# Dashboard annotations API **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29089) in GitLab 12.10 behind a disabled feature flag. diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index 79040333148..9178291181e 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# User-starred metrics dashboards API +# User-starred metrics dashboards API **(FREE)** The starred dashboard feature makes navigating to frequently-used dashboards easier by displaying favorited dashboards at the top of the select list. diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 4e5a418be7a..a89e91f82e5 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Namespaces API -Usernames and groupnames fall under a special category called namespaces. +Usernames and group names fall under a special category called namespaces. For users and groups supported API calls see the [users](users.md) and [groups](groups.md) documentation respectively. diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 74746f60d7e..a85c6475331 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -196,7 +196,7 @@ Example responses: } ``` -Users on GitLab [Ultimate or Gold](https://about.gitlab.com/pricing/) also see the `new_epic` +Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) also see the `new_epic` parameter: ```json diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index a80a97890ba..92d109cac5f 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -21,7 +21,7 @@ GitLab currently supports the following authorization flows: - **Authorization code with [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636):** Most secure. Without PKCE, you'd have to include client secrets on mobile clients, - and is recommended for both client and server aoos. + and is recommended for both client and server apps. - **Authorization code:** Secure and common flow. Recommended option for secure server-side apps. - **Implicit grant:** Originally designed for user-agent only apps, such as @@ -89,7 +89,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD `/oauth/authorize` page with the following query parameters: ```plaintext - https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=YOUR_UNIQUE_STATE_HASH&scope=REQUESTED_SCOPES&code_challenge=CODE_CHALLENGE&code_challenge_method=S256 + https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE&scope=REQUESTED_SCOPES&code_challenge=CODE_CHALLENGE&code_challenge_method=S256 ``` This page asks the user to approve the request from the app to access their @@ -100,7 +100,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD The redirect includes the authorization `code`, for example: ```plaintext - https://example.com/oauth/redirect?code=1234567890&state=YOUR_UNIQUE_STATE_HASH + https://example.com/oauth/redirect?code=1234567890&state=STATE ``` 1. With the authorization `code` returned from the previous request (denoted as @@ -139,29 +139,31 @@ detailed flow description. The authorization code flow is essentially the same as [authorization code flow with PKCE](#authorization-code-with-proof-key-for-code-exchange-pkce), +Before starting the flow, generate the `STATE`. It is a value that can't be predicted +used by the client to maintain state between the request and callback. It should also +be used as a CSRF token. + 1. Request authorization code. To do that, you should redirect the user to the - `/oauth/authorize` endpoint with the following GET parameters: + `/oauth/authorize` page with the following query parameters: ```plaintext https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE&scope=REQUESTED_SCOPES ``` - This will ask the user to approve the applications access to their account - based on the scopes specified in `REQUESTED_SCOPES` and then redirect back to - the `REDIRECT_URI` you provided. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes) - is a space separated list of scopes you want to have access to (e.g. `scope=read_user+profile` - would request `read_user` and `profile` scopes). The redirect will - include the GET `code` parameter, for example: + This page asks the user to approve the request from the app to access their + account based on the scopes specified in `REQUESTED_SCOPES`. The user is then + redirected back to the specified `REDIRECT_URI`. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes) + is a space separated list of scopes associated with the user. + For example,`scope=read_user+profile` requests the `read_user` and `profile` scopes. + The redirect includes the authorization `code`, for example: ```plaintext https://example.com/oauth/redirect?code=1234567890&state=STATE ``` - You should then use `code` to request an access token. - -1. After you have the authorization code you can request an `access_token` using the - code. You can do that by using any HTTP client. In the following example, - we are using Ruby's `rest-client`: +1. With the authorization `code` returned from the previous request (shown as + `RETURNED_CODE` in the following example), you can request an `access_token`, with + any HTTP client. The following example uses Ruby's `rest-client`: ```ruby parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI' diff --git a/doc/api/packages.md b/doc/api/packages.md index a0d966fdd88..516f171e851 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -92,7 +92,7 @@ GET /groups/:id/packages | `include_versionless` | boolean | no | When set to true, versionless packages are included in the response. (_Introduced in GitLab 13.8_) ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/packages?exclude_subgroups=true" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/packages?exclude_subgroups=false" ``` > **Deprecation:** @@ -264,7 +264,7 @@ GET /projects/:id/packages/:package_id/package_files | `package_id` | integer | yes | ID of a package. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/4/package_files" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages/4/package_files" ``` Example response: diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index ca0ac3522c3..4949bf504fa 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -11,7 +11,7 @@ You can read more about [personal access tokens](../user/profile/personal_access ## List personal access tokens > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227264) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.6. Get a list of personal access tokens. @@ -71,7 +71,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ## Revoke a personal access token > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216004) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.6. Revoke a personal access token. diff --git a/doc/api/project_aliases.md b/doc/api/project_aliases.md index 270c88ca661..439f34ad93b 100644 --- a/doc/api/project_aliases.md +++ b/doc/api/project_aliases.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Project Aliases API **(PREMIUM ONLY)** +# Project Aliases API **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. diff --git a/doc/api/project_analytics.md b/doc/api/project_analytics.md index 97b15cc2c88..8f1ba912e57 100644 --- a/doc/api/project_analytics.md +++ b/doc/api/project_analytics.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, api --- -# Project Analytics API **(ULTIMATE ONLY)** +# Project Analytics API **(ULTIMATE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index 2ca22baf654..331d05e0d6d 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -13,11 +13,14 @@ type: reference, api Badges support placeholders that will be replaced in real time in both the link and image URL. The allowed placeholders are: +<!-- vale gitlab.Spelling = NO --> + - **%{project_path}**: will be replaced by the project path. - **%{project_id}**: will be replaced by the project ID. - **%{default_branch}**: will be replaced by the project default branch. - **%{commit_sha}**: will be replaced by the last project's commit SHA. +<!-- vale gitlab.Spelling = YES --> ## List all badges of a project Gets a list of a project's badges and its group badges. @@ -103,9 +106,10 @@ POST /projects/:id/badges | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link | | `image_url` | string | yes | URL of the badge image | +| `name` | string | no | Name of the badge | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/master&image_url=https://shields.io/my/badge1&position=0" "https://gitlab.example.com/api/v4/projects/:id/badges" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/master&image_url=https://shields.io/my/badge1&name=mybadge" "https://gitlab.example.com/api/v4/projects/:id/badges" ``` Example response: @@ -113,6 +117,7 @@ Example response: ```json { "id": 1, + "name": "mybadge", "link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master", "image_url": "https://shields.io/my/badge1", "rendered_link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master", @@ -135,6 +140,7 @@ PUT /projects/:id/badges/:badge_id | `badge_id` | integer | yes | The badge ID | | `link_url` | string | no | URL of the badge link | | `image_url` | string | no | URL of the badge image | +| `name` | string | no | Name of the badge | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/badges/:badge_id" @@ -145,6 +151,7 @@ Example response: ```json { "id": 1, + "name": "mybadge", "link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master", "image_url": "https://shields.io/my/badge", "rendered_link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master", diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index 3cc8cd07923..01bff56b9f6 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Project clusters API +# Project clusters API **(CORE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23922) in GitLab 11.7. diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index 0711cc8abd6..f737dd6d46c 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -12,7 +12,7 @@ type: reference, api See also: - [Project import/export documentation](../user/project/settings/import_export.md). -- [Project import/export administration Rake tasks](../administration/raketasks/project_import_export.md). **(CORE ONLY)** +- [Project import/export administration Rake tasks](../administration/raketasks/project_import_export.md). **(FREE SELF)** ## Schedule an export @@ -194,7 +194,7 @@ requests.post(url, headers=headers, data=data, files=files) NOTE: The maximum import file size can be set by the Administrator, default is `0` (unlimited).. -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](settings.md#change-application-settings) or the [Admin UI](../user/admin_area/settings/account_and_limit_settings.md). +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](settings.md#change-application-settings) or the [Admin UI](../user/admin_area/settings/account_and_limit_settings.md). Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. ## Import status diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 413d89950cd..8ef887675e9 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -17,7 +17,7 @@ GET /projects/:id/variables | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" @@ -48,7 +48,7 @@ GET /projects/:id/variables/:key | Attribute | Type | required | Description | |-----------|---------|----------|-----------------------| -| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | @@ -76,7 +76,7 @@ POST /projects/:id/variables | Attribute | Type | required | Description | |---------------------|---------|----------|-----------------------| -| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | | `value` | string | yes | The `value` of a variable | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | @@ -109,7 +109,7 @@ PUT /projects/:id/variables/:key | Attribute | Type | required | Description | |---------------------|---------|----------|-------------------------| -| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `value` | string | yes | The `value` of a variable | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | @@ -143,7 +143,7 @@ DELETE /projects/:id/variables/:key | Attribute | Type | required | Description | |-----------|---------|----------|-------------------------| -| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index 52c357ca32a..fd263314768 100644 --- a/doc/api/project_repository_storage_moves.md +++ b/doc/api/project_repository_storage_moves.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Project repository storage moves API **(CORE ONLY)** +# Project repository storage moves API **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31285) in GitLab 13.0. diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index d264e68e96a..c5adf361fb6 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -225,8 +225,8 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project's snippet -- `ref` (required) - The name of a branch, tag or commit e.g. master -- `file_path` (required) - The URL-encoded path to the file, e.g. snippet%2Erb +- `ref` (required) - The name of a branch, tag or commit, such as `master` +- `file_path` (required) - The URL-encoded path to the file, such as `snippet%2Erb` Example request: @@ -239,7 +239,7 @@ curl "https://gitlab.com/api/v4/projects/1/snippets/2/files/master/snippet%2Erb/ > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/29508) in GitLab 9.4. -Available only for admins. +Available only for users with Administrator [permissions](../user/permissions.md). ```plaintext GET /projects/:id/snippets/:snippet_id/user_agent_detail diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index d75047d6cb3..6c423f0b058 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -34,7 +34,7 @@ GET /projects/:id/templates/:type | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | | `id` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `type` | string | yes| The type `(dockerfiles|gitignores|gitlab_ci_ymls|licenses|issues|merge_requests)` of the template | +| `type` | string | yes | The type `(dockerfiles|gitignores|gitlab_ci_ymls|licenses|issues|merge_requests)` of the template | Example response (licenses): diff --git a/doc/api/projects.md b/doc/api/projects.md index f9a4b3ba55e..f58830f699c 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -298,7 +298,7 @@ When the user is authenticated and `simple` is not set this returns something li ``` NOTE: -For users of GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/), +For users of GitLab [Premium or higher](https://about.gitlab.com/pricing/), the `marked_for_deletion_at` attribute has been deprecated, and is removed in API v5 in favor of the `marked_for_deletion_on` attribute. @@ -1280,6 +1280,8 @@ POST /projects/:id/fork | `namespace_path` | string | **{dotted-circle}** No | The path of the namespace that the project is forked to. | | `namespace` | integer/string | **{dotted-circle}** No | _(Deprecated)_ The ID or path of the namespace that the project is forked to. | | `path` | string | **{dotted-circle}** No | The path assigned to the resultant project after forking. | +| `description` | string | **{dotted-circle}** No | The description assigned to the resultant project after forking. | +| `visibility` | string | **{dotted-circle}** No | The [visibility level](#project-visibility-level) assigned to the resultant project after forking. | ## List Forks of a project @@ -1875,7 +1877,7 @@ This endpoint: - Deletes a project including all associated resources (including issues and merge requests). - 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 + [Premium](https://about.gitlab.com/pricing/) or higher tiers, 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 @@ -2229,7 +2231,7 @@ GET /projects/:id/push_rule } ``` -Users of GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) +Users of GitLab [Premium or higher](https://about.gitlab.com/pricing/) can also see the `commit_committer_check` and `reject_unsigned_commits` parameters: diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 1dd15231dd8..9ff4e374311 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -62,7 +62,7 @@ Example response: ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab Premium or higher also see the `user_id` and `group_id` parameters: Example response: @@ -133,7 +133,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab Premium or higher also see the `user_id` and `group_id` parameters: Example response: @@ -182,9 +182,9 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, maintainer access level) | | `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, maintainer access level) | | `unprotect_access_level` | string | no | Access levels allowed to unprotect (defaults: `40`, maintainer access level) | -| `allowed_to_push` | array | no | **(STARTER)** Array of access levels allowed to push, with each described by a hash | -| `allowed_to_merge` | array | no | **(STARTER)** Array of access levels allowed to merge, with each described by a hash | -| `allowed_to_unprotect` | array | no | **(STARTER)** Array of access levels allowed to unprotect, with each described by a hash | +| `allowed_to_push` | array | no | **(PREMIUM)** Array of access levels allowed to push, with each described by a hash | +| `allowed_to_merge` | array | no | **(PREMIUM)** Array of access levels allowed to merge, with each described by a hash | +| `allowed_to_unprotect` | array | no | **(PREMIUM)** Array of access levels allowed to unprotect, with each described by a hash | | `code_owner_approval_required` | boolean | no | **(PREMIUM)** Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). (defaults: false) | Example response: @@ -215,7 +215,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab Premium or higher also see the `user_id` and `group_id` parameters: Example response: @@ -252,7 +252,7 @@ Example response: } ``` -### Example with user / group level access **(STARTER)** +### Example with user / group level access **(PREMIUM)** 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) and were [added to the API](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3516) in GitLab 10.3 EE. @@ -295,7 +295,9 @@ Example response: } ``` -### Example with allow to push and allow to merge access **(STARTER)** +### Example with allow to push and allow to merge access **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. Example request: @@ -375,7 +377,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git ## Require code owner approvals for a single branch -Update the "code owner approval required" option for the given protected branch protected branch. +Update the "code owner approval required" option for the given protected branch. ```plaintext PATCH /projects/:id/protected_branches/:name diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index a58d6246a63..be9512ed0e0 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -486,7 +486,7 @@ Example response: } ``` -### Group milestones **(PREMIUM ONLY)** +### Group milestones **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235391) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. @@ -495,7 +495,7 @@ array for [Create a release](#create-a-release) and [Update a release](#update-a API calls. Only milestones associated with the project's group may be specified, and adding milestones for ancestor groups raises an error. -## Collect release evidence **(PREMIUM ONLY)** +## Collect release evidence **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. diff --git a/doc/api/repositories.md b/doc/api/repositories.md index efdf010e072..6bbd4c56e40 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Repositories API +# Repositories API **(CORE)** ## List repository tree @@ -18,14 +18,15 @@ This command provides essentially the same functionality as the `git ls-tree` co GET /projects/:id/repository/tree ``` -Parameters: +Supported attributes: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `path` (optional) - The path inside repository. Used to get content of subdirectories -- `ref` (optional) - The name of a repository branch or tag or if not given the default branch -- `recursive` (optional) - Boolean value used to get a recursive tree (false by default) -- `per_page` (optional) - Number of results to show per page. If not specified, defaults to `20`. - Read more on [pagination](README.md#pagination). +| Attribute | Type | Required | Description | +| :---------- | :------------- | :------- | :---------- | +| `id` | integer/string | no | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `path` | string | yes | The path inside repository. Used to get content of subdirectories. | +| `ref` | string | yes | The name of a repository branch or tag or if not given the default branch. | +| `recursive` | boolean | yes | Boolean value used to get a recursive tree (false by default). | +| `per_page` | integer | yes | Number of results to show per page. If not specified, defaults to `20`. [Learn more on pagination](README.md#pagination). | ```json [ @@ -91,10 +92,12 @@ without authentication if the repository is publicly accessible. GET /projects/:id/repository/blobs/:sha ``` -Parameters: +Supported attributes: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `sha` (required) - The blob SHA +| 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. | +| `sha` | string | yes | The blob SHA. | ## Raw blob content @@ -105,10 +108,12 @@ without authentication if the repository is publicly accessible. GET /projects/:id/repository/blobs/:sha/raw ``` -Parameters: +Supported attributes: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `sha` (required) - The blob SHA +| Attribute | Type | Required | Description | +| :-------- | :------- | :------- | :---------- | +| `id` | datatype | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `sha` | datatype | yes | The blob SHA. | ## Get file archive @@ -128,10 +133,14 @@ GET /projects/:id/repository/archive[.format] `bz2`, `tar`, and `zip`. For example, specifying `archive.zip` would send an archive in ZIP format. -Parameters: +Supported attributes: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `sha` (optional) - The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. For example: +| 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. | +| `sha` | string | no | The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. | + +Example request: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha>" @@ -146,21 +155,22 @@ publicly accessible. Note that diffs could have an empty diff string if [diff li GET /projects/:id/repository/compare ``` -Parameters: +Supported attributes: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `from` (required) - the commit SHA or branch name -- `to` (required) - the commit SHA or branch name -- `straight` (optional) - comparison method, `true` for direct comparison between `from` and `to` (`from`..`to`), `false` to compare using merge base (`from`...`to`)'. Default is `false`. +| 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. | +| `from` | string | yes | The commit SHA or branch name. | +| `to` | string | yes | The commit SHA or branch name. | +| `straight` | boolean | no | Comparison method, `true` for direct comparison between `from` and `to` (`from`..`to`), `false` to compare using merge base (`from`...`to`)'. Default is `false`. | ```plaintext GET /projects/:id/repository/compare?from=master&to=feature ``` -Response: +Example response: ```json - { "commit": { "id": "12d65c8dd2b2676fa3ac47d955accc085a37a9c1", @@ -203,15 +213,17 @@ GET /projects/:id/repository/contributors ``` WARNING: -The `additions` and `deletions` attributes are deprecated [as of GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39653) because they [always return `0`](https://gitlab.com/gitlab-org/gitlab/-/issues/233119). +The `additions` and `deletions` attributes are deprecated [as of GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39653), because they [always return `0`](https://gitlab.com/gitlab-org/gitlab/-/issues/233119). -Parameters: +Supported attributes: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `order_by` (optional) - Return contributors ordered by `name`, `email`, or `commits` (orders by commit date) fields. Default is `commits` -- `sort` (optional) - Return contributors sorted in `asc` or `desc` order. Default is `asc` +| 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 contributors ordered by `name`, `email`, or `commits` (orders by commit date) fields. Default is `commits`. | +| `sort` | string | no | Return contributors sorted in `asc` or `desc` order. Default is `asc`. | -Response: +Example response: ```json [{ @@ -237,10 +249,12 @@ Get the common ancestor for 2 or more refs (commit SHAs, branch names or tags). GET /projects/:id/repository/merge_base ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `refs` | array | yes | The refs to find the common ancestor of, multiple refs can be passed | +| Attribute | Type | Required | Description | +| --------- | -------------- | -------- | ------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `refs` | array | yes | The refs to find the common ancestor of, multiple refs can be passed | + +Example request: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/merge_base?refs[]=304d257dcb821665ab5110318fc58a007bd104ed&refs[]=0031876facac3f2b2702a0e53a26e89939a42209" @@ -264,3 +278,252 @@ Example response: "committed_date": "2014-02-27T08:03:18.000Z" } ``` + +## Generate changelog data + +> - [Introduced](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/351) in GitLab 13.9. +> - It's [deployed behind a feature flag](../user/feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not yet recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-generating-changelog-data). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +Generate changelog data based on commits in a repository. + +Given a version (using semantic versioning) and a range of commits, +GitLab generates a changelog for all commits that use a particular +[Git trailer](https://git-scm.com/docs/git-interpret-trailers). + +The output of this process is a new section in a changelog file in the Git +repository of the given project. The output format is in Markdown, and can be +customized. + +```plaintext +POST /projects/:id/repository/changelog +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +| :-------- | :------- | :--------- | :---------- | +| `version` | string | yes | The version to generate the changelog for. The format must follow [semantic versioning](https://semver.org/). | +| `from` | string | yes | The start of the range of commits (as a SHA) to use for generating the changelog. This commit itself isn't included in the list. | +| `to` | string | yes | The end of the range of commits (as a SHA) to use for the changelog. This commit _is_ included in the list. | +| `date` | datetime | no | The date and time of the release, defaults to the current time. | +| `branch` | string | no | The branch to commit the changelog changes to, defaults to the project's default branch. | +| `trailer` | string | no | The Git trailer to use for including commits, defaults to `Changelog`. | +| `file` | string | no | The file to commit the changes to, defaults to `CHANGELOG.md`. | +| `message` | string | no | The commit message to produce when committing the changes, defaults to `Add changelog for version X` where X is the value of the `version` argument. | + +### How it works + +Changelogs are generated based on commit titles. Commits are only included if +they contain a specific Git trailer. GitLab uses the value of this trailer to +categorize the changes. + +GitLab uses Git trailers, because Git trailers are +supported by Git out of the box. We use commits as input, as this is the only +source of data every project uses. In addition, commits can be retrieved when +operating on a mirror. This is important for GitLab itself, because during a security +release we might need to include changes from both public projects and private +security mirrors. + +Changelogs are generated by taking the title of the commits to include and using +these as the changelog entries. You can enrich entries with additional data, +such as a link to the merge request or details about the commit author. You can +[customize the format of a changelog](#customize-the-changelog-output) section with a template. + +### Customize the changelog output + +The output is customized using a YAML configuration file stored in your +project's Git repository. This file must reside in +`.gitlab/changelog_config.yml`. + +You can set the following variables in this file: + +- `date_format`: the date format to use in the title of the newly added + changelog data. This uses regular `strftime` formatting. +- `template`: a custom template to use for generating the changelog data. +- `categories`: a hash that maps raw category names to the names to use in the + changelog. + +Using the default settings, generating a changelog results in a section along +the lines of the following: + +```markdown +## 1.0.0 (2021-01-05) + +### Features (4 changes) + +- [Feature 1](gitlab-org/gitlab@123abc) by @alice ([merge request](gitlab-org/gitlab!123)) +- [Feature 2](gitlab-org/gitlab@456abc) ([merge request](gitlab-org/gitlab!456)) +- [Feature 3](gitlab-org/gitlab@234abc) by @steve +- [Feature 4](gitlab-org/gitlab@456) +``` + +Each section starts with a title that contains the version and release date. +While the format of the date can be customized, the rest of the title can't be +changed. When adding a new section, GitLab parses these titles to determine +where in the file the new section should be placed. GitLab sorts sections +according to their versions, not their dates. + +Each section can have categories, each with their +corresponding changes. In the above example, "Features" is one such category. +You can customize the format of these sections. + +The section names are derived from the values of the Git trailer used to include +or exclude commits. + +For example, if the trailer to use is called `Changelog`, +and its value is `feature`, then the commit is grouped in the `feature` +category. The names of these raw values might differ from what you want to +show in a changelog, you can remap them. Let's say we use the `Changelog` +trailer and developers use the following values: `feature`, `bug`, and +`performance`. + +You can remap these using the following YAML configuration file: + +```yaml +--- +categories: + feature: Features + bug: Bug fixes + performance: Performance improvements +``` + +When generating the changelog data, the category titles are then `### Features`, +`### Bug fixes`, and `### Performance improvements`. + +### Custom templates + +The category sections are generated using a template. The default template is as +follows: + +```plaintext +{% if categories %} +{% each categories %} +### {{ title }} ({% if single_change %}1 change{% else %}{{ count }} changes{% end %}) + +{% each entries %} +- [{{ title }}]({{ commit.reference }})\ +{% if author.contributor %} by {{ author.reference }}{% end %}\ +{% if merge_request %} ([merge request]({{ merge_request.reference }})){% end %} +{% end %} + +{% end %} +{% else %} +No changes. +{% end %} +``` + +The `{% ... %}` tags are for statements, and `{{ ... }}` is used for printing +data. Statements must be terminated using a `{% end %}` tag. Both the `if` and +`each` statements require a single argument. + +For example, if we have a variable `valid`, and we want to display "yes" +when this value is true, and display "nope" otherwise. We can do so as follows: + +```plaintext +{% if valid %} +yes +{% else %} +nope +{% end %} +``` + +The use of `else` is optional. A value is considered true when it's a non-empty +value or boolean `true`. Empty arrays and hashes are considered false. + +Looping is done using `each`, and variables inside a loop are scoped to it. +Referring to the current value in a loop is done using the variable tag `{{ it +}}`. Other variables read their value from the current loop value. Take +this template for example: + +```plaintext +{% each users %} +{{name}} +{% end %} +``` + +Assuming `users` is an array of objects, each with a `name` field, this would +then print the name of every user. + +Using variable tags, you can access nested objects. For example, `{{ +users.0.name }}` prints the name of the first user in the `users` variable. + +If a line ends in a backslash, the next newline is ignored. This allows you to +wrap code across multiple lines, without introducing unnecessary newlines in the +Markdown output. + +You can specify a custom template in your configuration like so: + +```yaml +--- +template: > + {% if categories %} + {% each categories %} + ### {{ title }} + + {% each entries %} + - [{{ title }}]({{ commit.reference }})\ + {% if author.contributor %} by {{ author.reference }}{% end %} + {% end %} + + {% end %} + {% else %} + No changes. + {% end %} +``` + +### Template data + +At the top level, the following variable is available: + +- `categories`: an array of objects, one for every changelog category. + +In a category, the following variables are available: + +- `title`: the title of the category (after it has been remapped). +- `count`: the number of entries in this category. +- `single_change`: a boolean that indicates if there is only one change (`true`), + or multiple changes (`false`). +- `entries`: the entries that belong to this category. + +In an entry, the following variables are available (here `foo.bar` means that +`bar` is a sub-field of `foo`): + +- `title`: the title of the changelog entry (this is the commit title). +- `commit.reference`: a reference to the commit, for example, + `gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7`. +- `commit.trailers`: an object containing all the Git trailers that were present + in the commit body. +- `author.reference`: a reference to the commit author (for example, `@alice`). +- `author.contributor`: a boolean set to `true` when the author is an external + contributor, otherwise this is set to `false`. +- `merge_request.reference`: a reference to the merge request that first + introduced the change (for example, `gitlab-org/gitlab!50063`). + +The `author` and `merge_request` objects might not be present if the data couldn't +be determined (for example, when a commit was created without a corresponding merge +request). + +### Enable or disable generating changelog data **(CORE ONLY)** + +This feature 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 for a project: + +```ruby +Feature.enable(:changelog_api, Project.find(id_of_the_project)) +``` + +To disable it for a project: + +```ruby +Feature.disable(:changelog_api, Project.find(id_of_the_project)) +``` diff --git a/doc/api/resource_access_tokens.md b/doc/api/resource_access_tokens.md new file mode 100644 index 00000000000..50f5ea73634 --- /dev/null +++ b/doc/api/resource_access_tokens.md @@ -0,0 +1,107 @@ +--- +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/#assignments +--- + +# Project access tokens API + +You can read more about [project access tokens](../user/project/settings/project_access_tokens.md). + +## List project access tokens + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238991) in GitLab 13.9. + +Get a list of project access tokens. + +```plaintext +GET projects/:id/access_tokens +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer/string | yes | The ID of the project | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens" +``` + +```json +[ + { + "user_id" : 141, + "scopes" : [ + "api" + ], + "name" : "token", + "expires_at" : "2021-01-31", + "id" : 42, + "active" : true, + "created_at" : "2021-01-20T22:11:48.151Z", + "revoked" : false + } +] +``` + +## Create a project access token + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238991) in GitLab 13.9. + +Create a project access token. + +```plaintext +POST projects/:id/access_tokens +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|---------------------| +| `name` | String | yes | The name of the project access token | +| `scopes` | Array\[String] | yes | [List of scopes](../user/project/settings/project_access_tokens.md#limiting-scopes-of-a-project-access-token) | +| `expires_at` | Date | no | The token expires at midnight UTC on that date | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +--header "Content-Type:application/json" \ +--data '{ "name":"test_token", "scopes":["api", "read_repository"], "expires_at":"2021-01-31" }' \ +"https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens" +``` + +```json +{ + "scopes" : [ + "api", + "read_repository" + ], + "active" : true, + "name" : "test", + "revoked" : false, + "created_at" : "2021-01-21T19:35:37.921Z", + "user_id" : 166, + "id" : 58, + "expires_at" : "2021-01-31" +} +``` + +## Revoke a project access token + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238991) in GitLab 13.9. + +Revoke a project access token. + +```plaintext +DELETE projects/:id/access_tokens/:token_id +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer/string | yes | The ID of the project | +| `token_id` | integer/string | yes | The ID of the project access token | + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/<token_id>" +``` + +### Responses + +- `204: No Content` if successfully revoked. +- `400 Bad Request` or `404 Not Found` if not revoked successfully. diff --git a/doc/api/runners.md b/doc/api/runners.md index 131418de725..1782e236c36 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -575,7 +575,7 @@ Example response: ```json { - "id": "12345", + "id": 12345, "token": "6337ff461c94fd3fa32ba3b1ff4125" } ``` diff --git a/doc/api/scim.md b/doc/api/scim.md index 6e67b6fbc2d..d00a0988d2b 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -5,9 +5,9 @@ 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/#assignments --- -# SCIM API (SYSTEM ONLY) **(SILVER ONLY)** +# SCIM API (SYSTEM ONLY) **(PREMIUM SAAS)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab Premium 11.10. The SCIM API implements the [RFC7644 protocol](https://tools.ietf.org/html/rfc7644). As this API is for **system** use for SCIM provider integration, it is subject to change without notice. diff --git a/doc/api/search.md b/doc/api/search.md index 584b2cbb837..6f27b5af0b8 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -31,7 +31,7 @@ GET /search Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, users. -If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs, notes, and commits. Find more about [the feature](../integration/elasticsearch.md). **(STARTER)** +If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs, notes, and commits. Find more about [the feature](../integration/elasticsearch.md). **(PREMIUM)** The response depends on the requested scope. @@ -266,7 +266,9 @@ Example response: ] ``` -### Scope: wiki_blobs **(STARTER)** +### Scope: wiki_blobs **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -295,7 +297,9 @@ Example response: NOTE: `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). -### Scope: commits **(STARTER)** +### Scope: commits **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -328,7 +332,9 @@ Example response: ] ``` -### Scope: blobs **(STARTER)** +### Scope: blobs **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -367,7 +373,9 @@ Example response: NOTE: `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). -### Scope: notes **(STARTER)** +### Scope: notes **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -444,7 +452,7 @@ GET /groups/:id/search Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users. -If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs, notes, and commits. Find more about [the feature](../integration/elasticsearch.md). **(STARTER)** +If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs, notes, and commits. Find more about [the feature](../integration/elasticsearch.md). **(PREMIUM)** The response depends on the requested scope. @@ -648,7 +656,9 @@ Example response: ] ``` -### Scope: wiki_blobs **(STARTER)** +### Scope: wiki_blobs **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -677,7 +687,9 @@ Example response: NOTE: `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). -### Scope: commits **(STARTER)** +### Scope: commits **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -710,7 +722,9 @@ Example response: ] ``` -### Scope: blobs **(STARTER)** +### Scope: blobs **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -749,7 +763,9 @@ Example response: NOTE: `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). -### Scope: notes **(STARTER)** +### Scope: notes **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -998,7 +1014,9 @@ Example response: ] ``` -### Scope: notes **(STARTER)** +### Scope: notes **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -1032,7 +1050,9 @@ Example response: ] ``` -### Scope: wiki_blobs **(STARTER)** +### Scope: wiki_blobs **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -1078,7 +1098,9 @@ Example response: NOTE: `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). -### Scope: commits **(STARTER)** +### Scope: commits **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -1111,7 +1133,9 @@ Example response: ] ``` -### Scope: blobs **(STARTER)** +### Scope: blobs **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. diff --git a/doc/api/services.md b/doc/api/services.md index d00ddb07a05..16431937c7a 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -748,7 +748,7 @@ Send IRC messages, on update, to a list of recipients through an Irker gateway. Set Irker (IRC gateway) service for a project. NOTE: -Irker does NOT have built-in authentication, which makes it vulnerable to spamming IRC channels if it is hosted outside of a firewall. Please make sure you run the daemon within a secured network to prevent abuse. For more details, read: <http://www.catb.org/~esr/irker/security.html>. +Irker does NOT have built-in authentication, which makes it vulnerable to spamming IRC channels if it is hosted outside of a firewall. Please make sure you run the daemon within a secured network to prevent abuse. For more details, read [Security analysis of `irker`](http://www.catb.org/~esr/irker/security.html). ```plaintext PUT /projects/:id/services/irker @@ -1358,7 +1358,7 @@ Get JetBrains TeamCity CI service settings for a project. GET /projects/:id/services/teamcity ``` -## Jenkins CI **(STARTER)** +## Jenkins CI A continuous integration and build server diff --git a/doc/api/settings.md b/doc/api/settings.md index 264021b3a2d..6c996caed7b 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Application settings API **(CORE ONLY)** +# Application settings API **(FREE SELF)** These API calls allow you to read and modify GitLab instance [application settings](#list-of-settings-that-can-be-accessed-via-api-calls) @@ -77,6 +77,7 @@ Example response: "asset_proxy_enabled": true, "asset_proxy_url": "https://assets.example.com", "asset_proxy_whitelist": ["example.com", "*.example.com", "your-instance.com"], + "asset_proxy_allowlist": ["example.com", "*.example.com", "your-instance.com"], "npm_package_requests_forwarding": true, "snippet_size_limit": 52428800, "issues_create_limit": 300, @@ -166,7 +167,7 @@ Example response: "local_markdown_version": 0, "asset_proxy_enabled": true, "asset_proxy_url": "https://assets.example.com", - "asset_proxy_whitelist": ["example.com", "*.example.com", "your-instance.com"], + "asset_proxy_allowlist": ["example.com", "*.example.com", "your-instance.com"], "geo_node_allowed_ips": "0.0.0.0/0, ::/0", "allow_local_requests_from_hooks_and_services": true, "allow_local_requests_from_web_hooks_and_services": true, @@ -190,7 +191,7 @@ these parameters: - `geo_status_timeout` - `deletion_adjourned_period` -Example responses: **(PREMIUM ONLY)** +Example responses: **(PREMIUM SELF)** ```json "file_template_project_id": 1, @@ -219,7 +220,8 @@ listed in the descriptions of the relevant settings. | `asset_proxy_enabled` | boolean | no | (**If enabled, requires:** `asset_proxy_url`) Enable proxying of assets. GitLab restart is required to apply changes. | | `asset_proxy_secret_key` | string | no | Shared secret with the asset proxy server. GitLab restart is required to apply changes. | | `asset_proxy_url` | string | no | URL of the asset proxy server. GitLab restart is required to apply changes. | -| `asset_proxy_whitelist` | string or array of strings | no | Assets that match these domain(s) are **not** proxied. Wildcards allowed. Your GitLab installation URL is automatically allowlisted. GitLab restart is required to apply changes. | +| `asset_proxy_whitelist` | string or array of strings | no | (Deprecated: Use `asset_proxy_allowlist` instead) Assets that match these domain(s) are **not** proxied. Wildcards allowed. Your GitLab installation URL is automatically allowlisted. GitLab restart is required to apply changes. | +| `asset_proxy_allowlist` | string or array of strings | no | Assets that match these domain(s) are **not** proxied. Wildcards allowed. Your GitLab installation URL is automatically allowlisted. GitLab restart is required to apply changes. | | `authorized_keys_enabled` | boolean | no | By default, we write to the `authorized_keys` file to support Git over SSH without additional configuration. GitLab can be optimized to authenticate SSH keys via the database file. Only disable this if you have configured your OpenSSH server to use the AuthorizedKeysCommand. | | `auto_devops_domain` | string | no | Specify a domain to use by default for every project's Auto Review Apps and Auto Deploy stages. | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for projects by default. It automatically builds, tests, and deploys applications based on a predefined CI/CD configuration. | @@ -235,7 +237,7 @@ listed in the descriptions of the relevant settings. | `default_project_visibility` | string | no | What visibility level new projects receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `default_projects_limit` | integer | no | Project limit per user. Default is `100000`. | | `default_snippet_visibility` | string | no | What visibility level new snippets receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | -| `deletion_adjourned_period` | integer | no | **(PREMIUM ONLY)** The number of days to wait before deleting a project or group that is marked for deletion. Value must be between 0 and 90. +| `deletion_adjourned_period` | integer | no | **(PREMIUM SELF)** The number of days to wait before deleting a project or group that is marked for deletion. Value must be between 0 and 90. | `diff_max_patch_bytes` | integer | no | Maximum diff patch size (Bytes). | | `disable_feed_token` | boolean | no | Disable display of RSS/Atom and calendar feed tokens ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231493) in GitLab 13.7) | | `disabled_oauth_sign_in_sources` | array of strings | no | Disabled OAuth sign-in sources. | @@ -300,16 +302,16 @@ 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`, `fogbugz`, `git`, `gitlab_project`, `gitea`, `manifest`, and `phabricator`. | -| `invisible_captcha_enabled` | boolean | no | Enable Invisible Captcha spam detection during signup. Disabled by default. | +| `invisible_captcha_enabled` | boolean | no | <!-- vale gitlab.Spelling = NO --> Enable Invisible Captcha <!-- vale gitlab.Spelling = YES --> spam detection during sign-up. Disabled by default. | | `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 | -| `maintenance_mode` | boolean | no | **(PREMIUM)** When instance is in maintenance mode, non-admin users can sign in with read-only access and make read-only API requests | +| `maintenance_mode` | boolean | no | **(PREMIUM)** When instance is in maintenance mode, non-administrative users can sign in with read-only access and make read-only API requests | | `max_artifacts_size` | integer | no | Maximum artifacts size in MB | | `max_attachment_size` | integer | no | Limit attachment size in MB | -| `max_import_size` | integer | no | Maximum import size in MB. 0 for unlimited. Default = 0 (unlimited) | +| `max_import_size` | integer | no | Maximum import size in MB. 0 for unlimited. Default = 0 (unlimited) [Modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. | | `max_pages_size` | integer | no | Maximum size of pages repositories in MB | -| `max_personal_access_token_lifetime` | integer | no | **(ULTIMATE ONLY)** Maximum allowable lifetime for personal access tokens in days | +| `max_personal_access_token_lifetime` | integer | no | **(ULTIMATE SELF)** Maximum allowable lifetime for personal access tokens in days | | `metrics_method_call_threshold` | integer | no | A method call is only tracked when it takes longer than the given amount of milliseconds. | | `mirror_available` | boolean | no | Allow repository mirroring to configured by project Maintainers. If disabled, only Admins can configure repository mirroring. | | `mirror_capacity_threshold` | integer | no | **(PREMIUM)** Minimum capacity to be available before scheduling more mirrors preemptively | diff --git a/doc/api/sidekiq_metrics.md b/doc/api/sidekiq_metrics.md index 2f018e67628..4791f066cd2 100644 --- a/doc/api/sidekiq_metrics.md +++ b/doc/api/sidekiq_metrics.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Sidekiq Metrics API **(CORE ONLY)** +# Sidekiq Metrics API **(FREE SELF)** > Introduced in GitLab 8.9. diff --git a/doc/api/snippet_repository_storage_moves.md b/doc/api/snippet_repository_storage_moves.md index f60b1dfb449..7eb9f9d9817 100644 --- a/doc/api/snippet_repository_storage_moves.md +++ b/doc/api/snippet_repository_storage_moves.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Snippet repository storage moves API **(CORE ONLY)** +# Snippet repository storage moves API **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49228) in GitLab 13.8. diff --git a/doc/api/suggestions.md b/doc/api/suggestions.md index 9f878cd029a..dd4340b0560 100644 --- a/doc/api/suggestions.md +++ b/doc/api/suggestions.md @@ -21,6 +21,7 @@ PUT /suggestions/:id/apply | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID of a suggestion | +| `commit_message` | string | no | A custom commit message to use instead of the default generated message or the project's default message | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/suggestions/5/apply" diff --git a/doc/api/tags.md b/doc/api/tags.md index 126bc010022..262f5eb0010 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -123,7 +123,7 @@ Parameters: | `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 | +| `release_description` | string | no | This parameter is [deprecated](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) for use in GitLab 11.7, and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/290311) in GitLab 14.0. Use the [Releases API](../api/releases/index.md) instead. | ```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" @@ -186,6 +186,11 @@ Parameters: ## Create a new release +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) +for use in GitLab 11.7, and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/290311) +in GitLab 14.0. Use the [Releases API](../api/releases/index.md) instead. + Add release notes to the existing Git tag. If there already exists a release for the given tag, status code `409` is returned. @@ -221,6 +226,11 @@ Response: ## Update a release +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) +for use in GitLab 11.7, and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/290311) +in GitLab 14.0. Use the [Releases API](../api/releases/index.md) instead. + Updates the release notes of a given release. ```plaintext diff --git a/doc/api/users.md b/doc/api/users.md index ecfd8e26626..70a7e2a815f 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -65,7 +65,7 @@ GET /users?active=true GET /users?blocked=true ``` -GitLab supports bot users such as the [alert bot](../operations/incident_management/alert_integrations.md) +GitLab supports bot users such as the [alert bot](../operations/incident_management/integrations.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). @@ -186,7 +186,7 @@ Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) ] ``` -Users on GitLab [Silver or higher](https://about.gitlab.com/pricing/) also see +Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see the `group_saml` provider option: ```json @@ -264,6 +264,7 @@ Parameters: "created_at": "2012-05-23T08:00:58Z", "bio": "", "bio_html": "", + "bot": false, "location": null, "public_email": "john@example.com", "skype": "", @@ -350,7 +351,7 @@ the `shared_runners_minutes_limit`, and `extra_shared_runners_minutes_limit` par } ``` -Users on GitLab.com [Silver, or higher](https://about.gitlab.com/pricing/) also +Users on GitLab.com [Premium or higher](https://about.gitlab.com/pricing/) also see the `group_saml` option: ```json @@ -1374,7 +1375,7 @@ Example Responses: ``` ```json -{ "message": "The user you are trying to approve is not pending an approval" } +{ "message": "The user you are trying to approve is not pending approval" } ``` ## Get an impersonation token of a user @@ -1481,7 +1482,7 @@ Parameters: | `user_id` | integer | yes | The ID of the user | | `impersonation_token_id` | integer | yes | The ID of the impersonation token | -## Create a personal access token **(CORE ONLY)** +## Create a personal access token **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17176) in GitLab 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/267553) in GitLab 13.8. diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index 00e70d34db6..c63a04228a5 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -71,7 +71,7 @@ Below are the changes made between V3 and V4. - Notes do not return deprecated field `upvote` and `downvote` [!9384](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9384) - Return HTTP status code `400` for all validation errors when creating or updating a member instead of sometimes `422` error. [!9523](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9523) - Remove `GET /groups/owned`. Use `GET /groups?owned=true` instead [!9505](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9505) -- Return 202 with JSON body on async removals on V4 API (`DELETE /projects/:id/repository/merged_branches` and `DELETE /projects/:id`) [!9449](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9449) +- Return 202 with JSON body on asynchronous removals on V4 API (`DELETE /projects/:id/repository/merged_branches` and `DELETE /projects/:id`) [!9449](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9449) - `GET /projects/:id/milestones?iid[]=x&iid[]=y` array filter has been renamed to `iids` [!9096](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9096) - Return basic information about pipeline in `GET /projects/:id/pipelines` [!8875](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8875) - Renamed all `build` references to `job` [!9463](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9463) diff --git a/doc/api/visual_review_discussions.md b/doc/api/visual_review_discussions.md index 67d9c523862..c3414a4e9ec 100644 --- a/doc/api/visual_review_discussions.md +++ b/doc/api/visual_review_discussions.md @@ -5,9 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, api --- -# Visual Review discussions API **(STARTER)** +# Visual Review discussions API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18710) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18710) in GitLab 12.5. +> - [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. Visual Review discussions are notes on Merge Requests sent as feedback from [Visual Reviews](../ci/review_apps/index.md#visual-reviews). diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index e4853920cab..f70662c7c61 100644 --- a/doc/api/vulnerability_exports.md +++ b/doc/api/vulnerability_exports.md @@ -37,7 +37,7 @@ POST /security/projects/:id/vulnerability_exports | `id` | integer or string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the project which the authenticated user is a member of | ```shell -curl --header POST "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/vulnerability_exports" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/projects/1/vulnerability_exports" ``` The created vulnerability export is automatically deleted after 1 hour. @@ -83,7 +83,7 @@ POST /security/groups/:id/vulnerability_exports | `id` | integer or string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the group which the authenticated user is a member of | ```shell -curl --header POST "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/groups/1/vulnerability_exports" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/groups/1/vulnerability_exports" ``` The created vulnerability export is automatically deleted after 1 hour. @@ -116,7 +116,7 @@ POST /security/vulnerability_exports ``` ```shell -curl --header POST "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/vulnerability_exports" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/vulnerability_exports" ``` The created vulnerability export is automatically deleted after one hour. diff --git a/doc/api/wikis.md b/doc/api/wikis.md index dfbedc9bfd1..43587da9473 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -1,6 +1,6 @@ --- stage: Create -group: Knowledge +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/#assignments" type: reference, api --- @@ -175,9 +175,9 @@ POST /projects/:id/wikis/attachments | `file` | string | yes | The attachment to be uploaded | | `branch` | string | no | The name of the branch. Defaults to the wiki repository default branch | -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 diff --git a/doc/architecture/blueprints/feature_flags_development/index.md b/doc/architecture/blueprints/feature_flags_development/index.md index 6be582bb8af..a5e46d25921 100644 --- a/doc/architecture/blueprints/feature_flags_development/index.md +++ b/doc/architecture/blueprints/feature_flags_development/index.md @@ -91,7 +91,7 @@ allow us to have: name: ci_disallow_to_create_merge_request_pipelines_in_target_project introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40724 rollout_issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/235119 -group: group::progressive delivery +group: group::release type: development default_enabled: false ``` @@ -105,7 +105,7 @@ These are reason why these changes are needed: - we have ambiguous usage of feature flag with different `default_enabled:` and different `actors` used - we lack a clear indication who owns what feature flag and where to find - relevant informations + relevant information - we do not emphasise the desire to create feature flag rollout issue to indicate that feature flag is in fact a ~"technical debt" - we don't know exactly what feature flags we have in our codebase diff --git a/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md b/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md index 6c27ecca284..28719926cdc 100644 --- a/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md +++ b/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md @@ -1,12 +1,12 @@ --- -stage: configure -group: configure +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 comments: false description: 'GitLab to Kubernetes communication' --- -# GitLab to Kubernetes communication +# GitLab to Kubernetes communication **(CORE)** The goal of this document is to define how GitLab can communicate with Kubernetes and in-cluster services through the GitLab Kubernetes Agent. diff --git a/doc/architecture/blueprints/image_resizing/index.md b/doc/architecture/blueprints/image_resizing/index.md index 9e5c45a715d..686a2f9c8f5 100644 --- a/doc/architecture/blueprints/image_resizing/index.md +++ b/doc/architecture/blueprints/image_resizing/index.md @@ -59,6 +59,8 @@ The MVC Avatar resizing implementation is integrated into Workhorse. With the ex Proposal: +<!-- vale gitlab.Spelling = NO --> + | Role | Who |------------------------------|-------------------------| | Author | Craig Gomes | @@ -67,10 +69,16 @@ Proposal: | Domain Expert | Matthias Kaeppler | | Domain Expert | Aleksei Lipniagov | +<!-- vale gitlab.Spelling = YES --> + DRIs: +<!-- vale gitlab.Spelling = NO --> + | Role | Who |------------------------------|------------------------| | Product | Josh Lambert | | Leadership | Craig Gomes | | Engineering | Matthias Kaeppler | + +<!-- vale gitlab.Spelling = YES --> diff --git a/doc/ci/README.md b/doc/ci/README.md index 740be7d1dbd..dcac628eab1 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -71,7 +71,7 @@ available through the UI. You can use them by creating a new file, choosing a template that suits your application, and adjusting it to your needs: - + While building your `.gitlab-ci.yml`, you can use the [CI/CD configuration visualization](pipeline_editor/index.md#visualize-ci-configuration) to facilitate your writing experience. @@ -105,7 +105,7 @@ 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. | +| [Custom path for `.gitlab-ci.yml`](pipelines/settings.md#custom-cicd-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. | @@ -134,7 +134,7 @@ Its feature set is listed on the table below according to DevOps stages. | [CI services](services/README.md) | Link Docker containers with your base image. | | [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. | +| [Interactive Web Terminals](interactive_web_terminal/index.md) **(FREE SELF)** | Open an interactive web terminal to debug the running jobs. | | [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. | |-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------| @@ -160,9 +160,7 @@ Its feature set is listed on the table below according to DevOps stages. Find example project code and tutorials for using GitLab CI/CD with a variety of app frameworks, languages, and platforms on the [CI Examples](examples/README.md) page. -GitLab also provides [example projects](https://gitlab.com/gitlab-examples) pre-configured to use GitLab CI/CD. - -## Administration **(CORE ONLY)** +## Administration **(FREE SELF)** As a GitLab administrator, you can change the default behavior of GitLab CI/CD for: @@ -206,7 +204,7 @@ been necessary. These are: #### 12.0 -- [Use refspec to clone/fetch Git repository](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4069). +- [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). diff --git a/doc/ci/autodeploy/index.md b/doc/ci/autodeploy/index.md deleted file mode 100644 index 8c7d9c1da64..00000000000 --- a/doc/ci/autodeploy/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../topics/autodevops/stages.md#auto-deploy' ---- - -This document was moved to [another location](../../topics/autodevops/stages.md#auto-deploy). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/autodeploy/quick_start_guide.md b/doc/ci/autodeploy/quick_start_guide.md deleted file mode 100644 index 8c7d9c1da64..00000000000 --- a/doc/ci/autodeploy/quick_start_guide.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../topics/autodevops/stages.md#auto-deploy' ---- - -This document was moved to [another location](../../topics/autodevops/stages.md#auto-deploy). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/build_artifacts/README.md b/doc/ci/build_artifacts/README.md deleted file mode 100644 index 4344a544798..00000000000 --- a/doc/ci/build_artifacts/README.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../user/project/pipelines/job_artifacts.md' ---- - -This document was moved to [pipelines/job_artifacts.md](../../user/project/pipelines/job_artifacts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/chatops/README.md b/doc/ci/chatops/README.md index 5d6af0b78db..4ec921b4447 100644 --- a/doc/ci/chatops/README.md +++ b/doc/ci/chatops/README.md @@ -5,10 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, concepts, howto --- -# GitLab ChatOps +# GitLab ChatOps **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to [GitLab Free](https://about.gitlab.com/pricing/) in 11.9. GitLab ChatOps provides a method to interact with CI/CD jobs through chat services like Slack. Many organizations' discussion, collaboration, and troubleshooting takes 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 a466214374b..b7418f08bf5 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -14,8 +14,9 @@ GitLab CI/CD can be used with Bitbucket Cloud by: To use GitLab CI/CD with a Bitbucket Cloud repository: -1. In GitLab create a **CI/CD for external repository**, select **Repo by URL** and - create the project. +1. <!-- vale gitlab.Spelling = NO --> In GitLab create a **CI/CD for external repository**, select + **Repo by URL** and create the project. + <!-- vale gitlab.Spelling = YES -->  diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 44534ddf793..cc6c629fb47 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -25,11 +25,15 @@ snippets disabled. These features To connect to an external repository: +<!-- vale gitlab.Spelling = NO --> + 1. From your GitLab dashboard, click **New project**. 1. Switch to the **CI/CD for external repository** tab. 1. Choose **GitHub** or **Repo by URL**. 1. The next steps are similar to the [import flow](../../user/project/import/index.md). +<!-- vale gitlab.Spelling = YES --> +  ## Pipelines for external pull requests diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md index 0be86527cb5..2ad12992aaf 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -47,11 +47,11 @@ Some credentials are required to be able to run `aws` commands: You might want to check if the AWS service you intend to use is [available in the chosen region](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/). - | Env. variable name | Value | - |:------------------------|:-----------------------| - | `AWS_ACCESS_KEY_ID` | Your Access key ID | - | `AWS_SECRET_ACCESS_KEY` | Your Secret access key | - | `AWS_DEFAULT_REGION` | Your region code | + | Environment variable name | Value | + |:-------------------------------|:-----------------------| + | `AWS_ACCESS_KEY_ID` | Your Access key ID | + | `AWS_SECRET_ACCESS_KEY` | Your Secret access key | + | `AWS_DEFAULT_REGION` | Your region code | 1. You can now use `aws` commands in the `.gitlab-ci.yml` file of this project: diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index a8ce46b9845..5089aa6c9a5 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -82,11 +82,8 @@ are certain use cases that you may need to work around. For more information: ## Needs Visualization > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215517) in GitLab 13.1 as a [Beta feature](https://about.gitlab.com/handbook/product/#beta). -> - It was deployed behind a feature flag, disabled by default. -> - 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-needs-visualization). +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52208) in GitLab 13.9. The needs visualization makes it easier to visualize the relationships between dependent jobs in a DAG. This graph displays all the jobs in a pipeline that need or are needed by other jobs. Jobs with no relationships are not displayed in this view. @@ -97,16 +94,3 @@ To see the needs visualization, click on the **Needs** tab when viewing a pipeli Clicking a node highlights all the job paths it depends on.  - -### Enable or disable Needs Visualization **(CORE ONLY)** - -The needs visualization 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: - -```ruby -# Instance-wide -Feature.disable(:dag_pipeline_tab) -# or by project -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 af88a006156..11020f0a090 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -126,7 +126,7 @@ not without its own challenges: instance of Docker engine so they don't conflict with each other. But this also means that jobs can be slower because there's no caching of layers. - 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) + 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 root file system, the job's working directory can be used as a mount point for @@ -801,7 +801,7 @@ NOTE: 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 +copies the file system on every run. This is a disk-intensive operation which can be avoided if a different driver is used, for example `overlay2`. ### Requirements diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index 7eb2a8286c7..b3df1642d6c 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -76,7 +76,7 @@ If you use a custom GitLab Runner behind an http(s) proxy, kaniko needs to be se up accordingly. This means: - Adding the proxy to `/kaniko/.docker/config.json` -- Passing the `http_proxy` environment variables as build args so the Dockerfile +- Passing the `http_proxy` environment variables as build arguments so the Dockerfile instructions can use the proxy when building the image. The previous example can be extended as follows: diff --git a/doc/ci/environments.md b/doc/ci/environments.md deleted file mode 100644 index 2ce0618c8e7..00000000000 --- a/doc/ci/environments.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'environments/index.md' ---- - -This document was moved to [another location](environments/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index 4dac076ffb7..9ae79ef40e8 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -141,7 +141,7 @@ reference a file in another project with a completely different set of permissio In this scenario, the `gitlab-ci.yml` is publicly accessible, but can only be edited by users with appropriate permissions in the other project. -For more information, see [Custom CI configuration path](../pipelines/settings.md#custom-ci-configuration-path). +For more information, see [Custom CI/CD configuration path](../pipelines/settings.md#custom-cicd-configuration-path). ## Troubleshooting diff --git a/doc/ci/environments/environments_dashboard.md b/doc/ci/environments/environments_dashboard.md index 84f8b1b1dbf..ef222ba5779 100644 --- a/doc/ci/environments/environments_dashboard.md +++ b/doc/ci/environments/environments_dashboard.md @@ -36,7 +36,7 @@ environments are not displayed. To add a project to the dashboard: -1. Click the **Add projects** button in the homescreen of the dashboard. +1. Click the **Add projects** button in the home screen of the dashboard. 1. Search and add one or more projects using the **Search your projects** field. 1. Click the **Add projects** button. @@ -53,4 +53,4 @@ You can add up to 150 projects for GitLab to display on this dashboard. GitLab.com users can add public projects to the Environments Dashboard for free. If your project is private, the group it belongs -to must have a [GitLab Silver](https://about.gitlab.com/pricing/) plan. +to must have a [GitLab Premium](https://about.gitlab.com/pricing/) plan. diff --git a/doc/ci/environments/incremental_rollouts.md b/doc/ci/environments/incremental_rollouts.md index 15eb4d2c526..39e3dd1ca75 100644 --- a/doc/ci/environments/incremental_rollouts.md +++ b/doc/ci/environments/incremental_rollouts.md @@ -117,6 +117,10 @@ available, [demonstrating configuration of timed rollouts](https://gitlab.com/gl ## Blue-Green Deployment +NOTE: +As of GitLab 13.7, teams can leverage an Ingress annotation and [set traffic weight](../../user/project/canary_deployments.md#how-to-change-the-traffic-weight-on-a-canary-ingress) +as an alternative approach to the blue-green deployment strategy documented here. + Also sometimes known as A/B deployment or red-black deployment, this technique is used to reduce downtime and risk during a deployment. When combined with incremental rollouts, you can minimize the impact of a deployment causing an issue. diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 7bf30ef1b95..58e12fdd733 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -1009,7 +1009,7 @@ fetch = +refs/environments/*:refs/remotes/origin/environments/* ### Scoping environments with specs > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2112) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.4. -> - [Scoping for environment variables was moved to Core](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30779) in GitLab 12.2. +> - [Scoping for environment variables was moved to Free](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30779) in GitLab 12.2. You can limit the environment scope of a variable by defining which environments it can be available for. diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md index 9fa0bb080ac..1f0687858c9 100644 --- a/doc/ci/examples/README.md +++ b/doc/ci/examples/README.md @@ -23,31 +23,35 @@ Examples are available in several forms. As a collection of: The following table lists examples with step-by-step tutorials that are contained in this section: | Use case | Resource | -|:------------------------------|:---------| +|-------------------------------|----------| | Browser performance testing | [Browser Performance Testing with the Sitespeed.io container](../../user/project/merge_requests/browser_performance_testing.md). | | Clojure | [Test a Clojure application with GitLab CI/CD](test-clojure-application.md). | | Deployment with Dpl | [Using `dpl` as deployment tool](deployment/README.md). | | GitLab Pages | See the [GitLab Pages](../../user/project/pages/index.md) documentation for a complete example of deploying a static site. | | End-to-end testing | [End-to-end testing with GitLab CI/CD and WebdriverIO](end_to_end_testing_webdriverio/index.md). | -| Game development | [DevOps and Game Dev with GitLab CI/CD](devops_and_game_dev_with_gitlab_ci_cd/index.md). | -| Java with Maven | [How to deploy Maven projects to Artifactory with GitLab CI/CD](artifactory_and_gitlab/index.md). | -| Java with Spring Boot | [Deploy a Spring Boot application to Cloud Foundry with GitLab CI/CD](deploy_spring_boot_to_cloud_foundry/index.md). | | Load performance testing | [Load Performance Testing with the k6 container](../../user/project/merge_requests/load_performance_testing.md). | | Multi project pipeline | [Build, test deploy using multi project pipeline](https://gitlab.com/gitlab-examples/upstream-project). | | NPM with semantic-release | [Publish NPM packages to the GitLab Package Registry using semantic-release](semantic-release.md). | | PHP with Laravel, Envoy | [Test and deploy Laravel applications with GitLab CI/CD and Envoy](laravel_with_gitlab_and_envoy/index.md). | | PHP with NPM, SCP | [Running Composer and NPM scripts with deployment via SCP in GitLab CI/CD](deployment/composer-npm-deploy.md). | -| PHP with PHPunit, atoum | [Testing PHP projects](php.md). | -| Parallel testing Ruby & JS | [GitLab CI/CD parallel jobs testing for Ruby & JavaScript projects](https://docs.knapsackpro.com/2019/how-to-run-parallel-jobs-for-rspec-tests-on-gitlab-ci-pipeline-and-speed-up-ruby-javascript-testing). | +| PHP with PHPunit, `atoum` | [Testing PHP projects](php.md). | | Python on Heroku | [Test and deploy a Python application with GitLab CI/CD](test-and-deploy-python-application-to-heroku.md). | | Ruby on Heroku | [Test and deploy a Ruby application with GitLab CI/CD](test-and-deploy-ruby-application-to-heroku.md). | -| Scala on Heroku | [Test and deploy a Scala application to Heroku](test-scala-application.md). | -| Secrets management with Vault | [Authenticating and Reading Secrets With Hashicorp Vault](authenticating-with-hashicorp-vault/index.md). | +| Secrets management with Vault | [Authenticating and Reading Secrets With HashiCorp Vault](authenticating-with-hashicorp-vault/index.md). | + +### Contributed examples -### How to contributing examples +You can help people that use your favorite programming language by submitting a link +to a guide for that language. These contributed guides are hosted externally or in +separate example projects: -Contributions are welcome! You can help your favorite programming -language users and GitLab by sending a merge request with a guide for that language. +| Use case | Resource | +|-------------------------------|----------| +| Game development | [DevOps and Game Development with GitLab CI/CD](https://gitlab.com/gitlab-examples/gitlab-game-demo/). | +| Java with Maven | [How to deploy Maven projects to Artifactory with GitLab CI/CD](https://gitlab.com/gitlab-examples/maven/simple-maven-example). | +| Java with Spring Boot | [Deploy a Spring Boot application to Cloud Foundry with GitLab CI/CD](https://gitlab.com/gitlab-examples/spring-gitlab-cf-deploy-demo). | +| Parallel testing Ruby & JS | [GitLab CI/CD parallel jobs testing for Ruby & JavaScript projects](https://docs.knapsackpro.com/2019/how-to-run-parallel-jobs-for-rspec-tests-on-gitlab-ci-pipeline-and-speed-up-ruby-javascript-testing). | +| Scala on Heroku | [Test and deploy a Scala application to Heroku](https://gitlab.com/gitlab-examples/scala-sbt). | ## CI/CD templates @@ -95,9 +99,9 @@ choose one of these templates: If a programming language or framework template is not in this list, you can contribute one. To create a template, submit a merge request -to <https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates>. +to [the templates list](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates). -### Adding templates to your GitLab installation **(PREMIUM ONLY)** +### Adding templates to your GitLab installation **(PREMIUM SELF)** You can add custom examples and templates to your self-managed GitLab instance. Your GitLab administrator can [designate an instance template repository](../../user/admin_area/settings/instance_template_repository.md) @@ -127,7 +131,7 @@ See also the following video overviews: For some customer experiences with GitLab CI/CD, see: -- [How Verizon Connect reduced datacenter deploys from 30 days to under 8 hours with GitLab](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/) +- [How Verizon Connect reduced data center deploys from 30 days to under 8 hours with GitLab](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/) - [How Wag! cut their release process from 40 minutes to just 6](https://about.gitlab.com/blog/2019/01/16/wag-labs-blog-post/) - [How Jaguar Land Rover embraced CI to speed up their software lifecycle](https://about.gitlab.com/blog/2018/07/23/chris-hill-devops-enterprise-summit-talk/) diff --git a/doc/ci/examples/artifactory_and_gitlab/index.md b/doc/ci/examples/artifactory_and_gitlab/index.md index c1df21297e3..a1a7de26cf2 100644 --- a/doc/ci/examples/artifactory_and_gitlab/index.md +++ b/doc/ci/examples/artifactory_and_gitlab/index.md @@ -1,289 +1,8 @@ --- -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/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/articles/artifactory_and_gitlab/index.html' -author: Fabio Busatto -author_gitlab: bikebilly -type: tutorial -date: 2017-08-15 +redirect_to: '../README.md#contributed-examples' --- -<!-- vale off --> +This document was moved to [another location](../README.md#contributed-examples). -# How to deploy Maven projects to Artifactory with GitLab CI/CD - -## Introduction - -In this article, we show how you can leverage the power of [GitLab CI/CD](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) -to build a [Maven](https://maven.apache.org/) project, deploy it to [Artifactory](https://jfrog.com/artifactory/), and then use it from another Maven application as a dependency. - -You'll create two different projects: - -- `simple-maven-dep`: the app built and deployed to Artifactory (see the [simple-maven-dep](https://gitlab.com/gitlab-examples/maven/simple-maven-dep) example project) -- `simple-maven-app`: the app using the previous one as a dependency (see the [simple-maven-app](https://gitlab.com/gitlab-examples/maven/simple-maven-app) example project) - -We assume that you already have a GitLab account on [GitLab.com](https://gitlab.com/), and that you know the basic usage of Git and [GitLab CI/CD](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/). -We also assume that an Artifactory instance is available and reachable from the internet, and that you have valid credentials to deploy on it. - -## Create the simple Maven dependency - -First, you need an application to work with: in this specific case we'll use a -simple one, but it could be any Maven application. This will be the dependency -you want to package and deploy to Artifactory, to be available to other -projects. - -### Prepare the dependency application - -For this article you'll use a Maven app that can be cloned from our example -project: - -1. Log in to your GitLab account -1. Create a new project by selecting **Import project from > Repo by URL** -1. Add the following URL: - - ```plaintext - https://gitlab.com/gitlab-examples/maven/simple-maven-dep.git - ``` - -1. Click **Create project** - -This application is nothing more than a basic class with a stub for a JUnit based test suite. -It exposes a method called `hello` that accepts a string as input, and prints a hello message on the screen. - -The project structure is really simple, and you should consider these two resources: - -- `pom.xml`: project object model (POM) configuration file -- `src/main/java/com/example/dep/Dep.java`: source of our application - -### Configure the Artifactory deployment - -The application is ready to use, but you need some additional steps to deploy it to Artifactory: - -1. Log in to Artifactory with your user's credentials. -1. From the main screen, click on the `libs-release-local` item in the **Set Me Up** panel. -1. Copy to clipboard the configuration snippet under the **Deploy** paragraph. -1. Change the `url` value to have it configurable by using variables. -1. Copy the snippet in the `pom.xml` file for your project, just after the - `dependencies` section. The snippet should look like this: - - ```xml - <distributionManagement> - <repository> - <id>central</id> - <name>83d43b5afeb5-releases</name> - <url>${env.MAVEN_REPO_URL}/libs-release-local</url> - </repository> - </distributionManagement> - ``` - -Another step you need to do before you can deploy the dependency to Artifactory -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 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: - -1. Create a folder called `.m2` in the root of your repository -1. Create a file called `settings.xml` in the `.m2` folder -1. Copy the following content into a `settings.xml` file: - - ```xml - <settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd" - xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> - <servers> - <server> - <id>central</id> - <username>${env.MAVEN_REPO_USER}</username> - <password>${env.MAVEN_REPO_PASS}</password> - </server> - </servers> - </settings> - ``` - - Username and password will be replaced by the correct values using variables. - -### Configure GitLab CI/CD for `simple-maven-dep` - -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 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): - -- **MAVEN_REPO_URL**: `http://artifactory.example.com:8081/artifactory` (your Artifactory URL) -- **MAVEN_REPO_USER**: `gitlab` (your Artifactory username) -- **MAVEN_REPO_PASS**: `AKCp2WXr3G61Xjz1PLmYa3arm3yfBozPxSta4taP3SeNu2HPXYa7FhNYosnndFNNgoEds8BCS` (your Artifactory Encrypted Password) - -Now it's time to define jobs in `.gitlab-ci.yml` and push it to the repository: - -```yaml -image: maven:latest - -variables: - MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode" - MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository" - -cache: - paths: - - .m2/repository/ - - target/ - -build: - stage: build - script: - - mvn $MAVEN_CLI_OPTS compile - -test: - stage: test - script: - - mvn $MAVEN_CLI_OPTS test - -deploy: - stage: deploy - script: - - mvn $MAVEN_CLI_OPTS deploy - only: - - master -``` - -The runner uses the latest [Maven Docker image](https://hub.docker.com/_/maven/), -which contains all of the tools and dependencies needed to manage the project -and 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. - -Caching the `.m2/repository folder` (where all the Maven files are stored), and the `target` folder (where our application will be created), is useful for speeding up the process -by running all Maven phases in a sequential order, therefore, executing `mvn test` will automatically run `mvn compile` if necessary. - -Both `build` and `test` jobs leverage the `mvn` command to compile the application and to test it as defined in the test suite that is part of the application. - -Deploy to Artifactory is done as defined by the variables we have just set up. -The deployment occurs only if we're pushing or merging to `master` branch, so that the development versions are tested but not published. - -Done! Now you have all the changes in the GitLab repository, and a pipeline has already been started for this commit. In the **Pipelines** tab you can see what's happening. -If the deployment has been successful, the deploy job log will output: - -```plaintext -[INFO] ------------------------------------------------------------------------ -[INFO] BUILD SUCCESS -[INFO] ------------------------------------------------------------------------ -[INFO] Total time: 1.983 s -``` - ->**Note**: -the `mvn` command downloads a lot of files from the internet, so you'll see a lot of extra activity in the log the first time you run it. - -Yay! You did it! Checking in Artifactory will confirm that you have a new artifact available in the `libs-release-local` repository. - -## Create the main Maven application - -Now that you have the dependency available on Artifactory, it's time to use it! -Let's see how we can have it as a dependency to our main application. - -### Prepare the main application - -We'll use again a Maven app that can be cloned from our example project: - -1. Create a new project by selecting **Import project from ➔ Repo by URL** -1. Add the following URL: - - ```plaintext - https://gitlab.com/gitlab-examples/maven/simple-maven-app.git - ``` - -1. Click **Create project** - -This one is a simple app as well. If you look at the `src/main/java/com/example/app/App.java` -file you can see that it imports the `com.example.dep.Dep` class and calls the `hello` method passing `GitLab` as a parameter. - -Since Maven doesn't know how to resolve the dependency, you need to modify the configuration: - -1. Go back to Artifactory -1. Browse the `libs-release-local` repository -1. Select the `simple-maven-dep-1.0.jar` file -1. Find the configuration snippet from the **Dependency Declaration** section of the main panel -1. Copy the snippet in the `dependencies` section of the `pom.xml` file. - The snippet should look like this: - - ```xml - <dependency> - <groupId>com.example.dep</groupId> - <artifactId>simple-maven-dep</artifactId> - <version>1.0</version> - </dependency> - ``` - -### Configure the Artifactory repository location - -At this point you defined the dependency for the application, but you still miss where you can find the required files. -You need to create a `.m2/settings.xml` file as you did for the dependency project, and let Maven know the location using environment variables. - -Here is how you can get the content of the file directly from Artifactory: - -1. From the main screen, click on the `libs-release-local` item in the **Set Me Up** panel -1. Click on **Generate Maven Settings** -1. Click on **Generate Settings** -1. Copy to clipboard the configuration file -1. Save the file as `.m2/settings.xml` in your repository - -Now you are ready to use the Artifactory repository to resolve dependencies and use `simple-maven-dep` in your main application! - -### Configure GitLab CI/CD for `simple-maven-app` - -You need a last step to have everything in place: configure the `.gitlab-ci.yml` file for this project, as you already did for `simple-maven-dep`. - -You want to leverage [GitLab CI/CD](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) to automatically build, test and run your awesome application, -and see if you can get the greeting as expected! - -All you need to do is to add the following `.gitlab-ci.yml` to the repository: - -```yaml -image: maven:latest - -stages: - - build - - test - - run - -variables: - MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode" - MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository" - -cache: - paths: - - .m2/repository/ - - target/ - -build: - stage: build - script: - - mvn $MAVEN_CLI_OPTS compile - -test: - stage: test - script: - - mvn $MAVEN_CLI_OPTS test - -run: - stage: run - script: - - mvn $MAVEN_CLI_OPTS package - - mvn $MAVEN_CLI_OPTS exec:java -Dexec.mainClass="com.example.app.App" -``` - -It is very similar to the configuration used for `simple-maven-dep`, but instead of the `deploy` job there is a `run` job. -Probably something that you don't want to use in real projects, but here it is useful to see the application executed automatically. - -And that's it! In the `run` job output log you will find a friendly hello to GitLab! - -## Conclusion - -In this article we covered the basic steps to use an Artifactory Maven repository to automatically publish and consume artifacts. - -A similar approach could be used to interact with any other Maven compatible Binary Repository Manager. -Obviously, you can improve these examples, optimizing the `.gitlab-ci.yml` file to better suit your needs, and adapting to your workflow. +<!-- This redirect file can be deleted after 2021-04-18. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md index fccc62a4ca0..fdebc1affc0 100644 --- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md +++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md @@ -5,13 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Authenticating and Reading Secrets With Hashicorp Vault +# Authenticating and Reading Secrets With HashiCorp Vault This tutorial demonstrates how to authenticate, configure, and read secrets with HashiCorp's Vault from GitLab CI/CD. NOTE: [GitLab Premium](https://about.gitlab.com/pricing/) supports read access to a -Hashicorp Vault, and enables you to +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). @@ -155,11 +155,11 @@ This example uses [bound_claims](https://www.vaultproject.io/api/auth/jwt#bound_ Combined with [protected branches](../../../user/project/protected_branches.md), you can restrict who is able to authenticate and read the secrets. -[token_explicit_max_ttl](https://www.vaultproject.io/api/auth/jwt#token_explicit_max_ttl) specifies that the token issued by Vault, upon successful authentication, has a hard lifetime limit of 60 seconds. +[`token_explicit_max_ttl`](https://www.vaultproject.io/api/auth/jwt#token_explicit_max_ttl) specifies that the token issued by Vault, upon successful authentication, has a hard lifetime limit of 60 seconds. -[user_claim](https://www.vaultproject.io/api/auth/jwt#user_claim) specifies the name for the Identity alias created by Vault upon a successful login. +[`user_claim`](https://www.vaultproject.io/api/auth/jwt#user_claim) specifies the name for the Identity alias created by Vault upon a successful login. -[bound_claims_type](https://www.vaultproject.io/api-docs/auth/jwt#bound_claims_type) configures the interpretation of the `bound_claims` values. If set to `glob`, the values are interpreted as globs, with `*` matching any number of characters. +[`bound_claims_type`](https://www.vaultproject.io/api-docs/auth/jwt#bound_claims_type) configures the interpretation of the `bound_claims` values. If set to `glob`, the values are interpreted as globs, with `*` matching any number of characters. For the full list of options, see Vault's [Create Role documentation](https://www.vaultproject.io/api/auth/jwt#create-role). diff --git a/doc/ci/examples/browser_performance.md b/doc/ci/examples/browser_performance.md deleted file mode 100644 index 131a539499d..00000000000 --- a/doc/ci/examples/browser_performance.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../user/project/merge_requests/browser_performance_testing.md#configuring-browser-performance-testing' ---- - -This document was moved to [another location](../../user/project/merge_requests/browser_performance_testing.md#configuring-browser-performance-testing). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/code_climate.md b/doc/ci/examples/code_climate.md deleted file mode 100644 index 2b7b2574ef7..00000000000 --- a/doc/ci/examples/code_climate.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'code_quality.md' ---- - -This document was moved to [another location](code_quality.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/code_quality.md b/doc/ci/examples/code_quality.md deleted file mode 100644 index 808ad6d8fef..00000000000 --- a/doc/ci/examples/code_quality.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../user/project/merge_requests/code_quality.md#example-configuration' ---- - -This document was moved to [another location](../../user/project/merge_requests/code_quality.md#example-configuration). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/container_scanning.md b/doc/ci/examples/container_scanning.md deleted file mode 100644 index eecf939d959..00000000000 --- a/doc/ci/examples/container_scanning.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../user/application_security/container_scanning/index.md' ---- - -This document was moved to [another location](../../user/application_security/container_scanning/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/dast.md b/doc/ci/examples/dast.md deleted file mode 100644 index 97c5cafae95..00000000000 --- a/doc/ci/examples/dast.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../user/application_security/dast/index.md' ---- - -This document was moved to [another location](../../user/application_security/dast/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md deleted file mode 100644 index dc4b7bd764a..00000000000 --- a/doc/ci/examples/dependency_scanning.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../user/application_security/dependency_scanning/index.md' ---- - -This document was moved to [another location](../../user/application_security/dependency_scanning/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/img/cloud_foundry_variables.png b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/img/cloud_foundry_variables.png Binary files differdeleted file mode 100644 index e76767741ce..00000000000 --- a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/img/cloud_foundry_variables.png +++ /dev/null diff --git a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/img/create_from_template.png b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/img/create_from_template.png Binary files differdeleted file mode 100644 index f3761632556..00000000000 --- a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/img/create_from_template.png +++ /dev/null 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 9c145677f6e..a1a7de26cf2 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 @@ -1,145 +1,8 @@ --- -stage: Release -group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -author: Dylan Griffith -author_gitlab: DylanGriffith -type: tutorial -date: 2018-06-07 -description: "Continuous Deployment of a Spring Boot application to Cloud Foundry with GitLab CI/CD" +redirect_to: '../README.md#contributed-examples' --- -<!-- vale off --> +This document was moved to [another location](../README.md#contributed-examples). -# Deploy a Spring Boot application to Cloud Foundry with GitLab CI/CD - -## Introduction - -This article demonstrates how to use the [Continuous Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#continuous-deployment) -method to deploy a [Spring Boot](https://projects.spring.io/spring-boot/) application to -[Cloud Foundry (CF)](https://www.cloudfoundry.org/) -with GitLab CI/CD. - -All the code for this project can be found in this [GitLab -repository](https://gitlab.com/gitlab-examples/spring-gitlab-cf-deploy-demo). - -In case you're interested in deploying Spring Boot applications to Kubernetes -using GitLab CI/CD, read through the blog post [Continuous Delivery of a Spring Boot application with GitLab CI and Kubernetes](https://about.gitlab.com/blog/2016/12/14/continuous-delivery-of-a-spring-boot-application-with-gitlab-ci-and-kubernetes/). - -## Requirements - -This tutorial assumes you are familiar with Java, GitLab, Cloud Foundry, and GitLab CI/CD. - -To follow along, you need: - -- An account on [Pivotal Web Services (PWS)](https://run.pivotal.io/) or any - other Cloud Foundry (CF) instance. -- An account on GitLab. - -NOTE: -If you're not deploying to PWS, you must replace the `api.run.pivotal.io` URL in all the below -commands with the [API URL](https://docs.cloudfoundry.org/running/cf-api-endpoint.html) -of your CF instance. - -## Create your project - -To create your Spring Boot application you can use the Spring template in -GitLab when creating a new project: - - - -## Configure the deployment to Cloud Foundry - -To deploy to Cloud Foundry you must add a `manifest.yml` file. This -is the configuration for the CF CLI you must use to deploy the application. -Create this in the root directory of your project with the following -content: - -```yaml ---- -applications: - - name: gitlab-hello-world - random-route: true - memory: 1G - path: target/demo-0.0.1-SNAPSHOT.jar -``` - -## Configure GitLab CI/CD to deploy your application - -Now you must add the GitLab CI/CD configuration file -([`.gitlab-ci.yml`](../../yaml/README.md)) -to your project's root. This is how GitLab figures out what commands must run whenever -code is pushed to your repository. Add the following `.gitlab-ci.yml` -file to the root directory of the repository. GitLab detects it -automatically and runs the defined steps once you push your code: - -```yaml -image: java:8 - -stages: - - build - - deploy - -before_script: - - chmod +x mvnw - -build: - stage: build - script: ./mvnw package - artifacts: - paths: - - target/demo-0.0.1-SNAPSHOT.jar - -production: - stage: deploy - script: - - curl --location "https://cli.run.pivotal.io/stable?release=linux64-binary&source=github" | tar zx - - ./cf login -u $CF_USERNAME -p $CF_PASSWORD -a api.run.pivotal.io - - ./cf push - only: - - master -``` - -This uses the `java:8` [Docker image](../../docker/using_docker_images.md) -to build your application, as it provides the up-to-date Java 8 JDK on [Docker Hub](https://hub.docker.com/). -You also added the [`only` clause](../../yaml/README.md#onlyexcept-basic) -to ensure your deployments only happen when you push to the master branch. - -Because the steps defined in `.gitlab-ci.yml` require credentials to sign in to -CF, you must add your CF credentials as -[environment variables](../../variables/README.md#predefined-environment-variables) -in GitLab CI/CD. To set the environment variables, navigate to your project's -**Settings > CI/CD**, and then expand **Variables**. Name the variables -`CF_USERNAME` and `CF_PASSWORD` and set them to the correct values. - - - -After set up, GitLab CI/CD deploys your app to CF at every push to your -repository's default branch. To review the build logs or watch your builds -running live, navigate to **CI/CD > Pipelines**. - -WARNING: -It's considered best practice for security to create a separate deploy user for -your application and add its credentials to GitLab instead of using a -developer's credentials. - -To start a manual deployment in GitLab go to **CI/CD > Pipelines** then click -**Run Pipeline**. After the app is finished deploying, it displays the -URL of your application in the logs for the `production` job: - -```shell -requested state: started -instances: 1/1 -usage: 1G x 1 instances -urls: gitlab-hello-world-undissembling-hotchpot.cfapps.io -last uploaded: Mon Nov 6 10:02:25 UTC 2017 -stack: cflinuxfs2 -buildpack: client-certificate-mapper=1.2.0_RELEASE container-security-provider=1.8.0_RELEASE java-buildpack=v4.5-offline-https://github.com/cloudfoundry/java-buildpack.git#ffeefb9 java-main java-opts jvmkill-agent=1.10.0_RELEASE open-jdk-like-jre=1.8.0_1... - - state since cpu memory disk details -#0 running 2017-11-06 09:03:22 PM 120.4% 291.9M of 1G 137.6M of 1G -``` - -You can then visit your deployed application (for this example, -`https://gitlab-hello-world-undissembling-hotchpot.cfapps.io/`) and you should -see the "Spring is here!" message. +<!-- This redirect file can be deleted after 2021-04-18. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/deployment/README.md b/doc/ci/examples/deployment/README.md index 958093364af..779ca98084f 100644 --- a/doc/ci/examples/deployment/README.md +++ b/doc/ci/examples/deployment/README.md @@ -38,15 +38,15 @@ apt-get install ruby-dev The Dpl provides support for vast number of services, including: Heroku, Cloud Foundry, AWS/S3, and more. To use it simply define provider and any additional parameters required by the provider. -For example if you want to use it to deploy your application to Heroku, you need to specify `heroku` as provider, specify `api-key` and `app`. -All possible parameters can be found here: <https://github.com/travis-ci/dpl#heroku-api>. +For example if you want to use it to deploy your application to Heroku, you need to specify `heroku` as provider, specify `api_key` and `app`. +All possible parameters can be found in the [Heroku API section](https://github.com/travis-ci/dpl#heroku-api). ```yaml staging: stage: deploy script: - gem install dpl - - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY + - dpl --provider=heroku --app=my-app-staging --api_key=$HEROKU_STAGING_API_KEY ``` In the above example we use Dpl to deploy `my-app-staging` to Heroku server with API key stored in `HEROKU_STAGING_API_KEY` secure variable. @@ -67,7 +67,7 @@ staging: - apt-get update -yq - apt-get install -y ruby-dev - gem install dpl - - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY + - dpl --provider=heroku --app=my-app-staging --api_key=$HEROKU_STAGING_API_KEY only: - master ``` @@ -90,7 +90,7 @@ staging: stage: deploy script: - gem install dpl - - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY + - dpl --provider=heroku --app=my-app-staging --api_key=$HEROKU_STAGING_API_KEY only: - master @@ -98,7 +98,7 @@ production: stage: deploy script: - gem install dpl - - dpl --provider=heroku --app=my-app-production --api-key=$HEROKU_PRODUCTION_API_KEY + - dpl --provider=heroku --app=my-app-production --api_key=$HEROKU_PRODUCTION_API_KEY only: - tags ``` diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/img/aws_config_window.png b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/img/aws_config_window.png Binary files differdeleted file mode 100644 index 09eef98202f..00000000000 --- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/img/aws_config_window.png +++ /dev/null diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/img/gitlab_config.png b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/img/gitlab_config.png Binary files differdeleted file mode 100644 index 71ffcdea289..00000000000 --- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/img/gitlab_config.png +++ /dev/null diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/img/test_pipeline_pass.png b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/img/test_pipeline_pass.png Binary files differdeleted file mode 100644 index a9452577a42..00000000000 --- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/img/test_pipeline_pass.png +++ /dev/null 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 298ffff568a..9408c26f06f 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 @@ -1,534 +1,8 @@ --- -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/#assignments -author: Ryan Hall -author_gitlab: blitzgren -type: tutorial -date: 2018-03-07 +redirect_to: '../README.md#contributed-examples' --- -<!-- vale off --> +This document was moved to [another location](../README.md#contributed-examples). -# DevOps and Game Dev with GitLab CI/CD - -With advances in WebGL and WebSockets, browsers are extremely viable as game development -platforms without the use of plugins like Adobe Flash. Furthermore, by using GitLab and [AWS](https://aws.amazon.com/), -single game developers, as well as game dev teams, can easily host browser-based games online. - -In this tutorial, we'll focus on DevOps, as well as testing and hosting games with Continuous -Integration/Deployment methods using [GitLab CI/CD](../../README.md). We assume you are familiar with GitLab, JavaScript, -and the basics of game development. - -## The game - -Our [demo game](http://gitlab-game-demo.s3-website-us-east-1.amazonaws.com/) consists of a simple spaceship traveling in space that shoots by clicking the mouse in a given direction. - -Creating a strong CI/CD pipeline at the beginning of developing another game, [Dark Nova](https://www.darknova.io), -was essential for the fast pace the team worked at. This tutorial will build upon my -[previous introductory article](https://ryanhallcs.wordpress.com/2017/03/15/devops-and-game-dev/) and go through the following steps: - -1. Using code from the previous article to start with a bare-bones [Phaser](https://phaser.io) game built by a gulp file -1. Adding and running unit tests -1. Creating a `Weapon` class that can be triggered to spawn a `Bullet` in a given direction -1. Adding a `Player` class that uses this weapon and moves around the screen -1. Adding the sprites we will use for the `Player` and `Weapon` -1. Testing and deploying with Continuous Integration and Continuous Deployment methods - -By the end, we'll have the core of a [playable game](http://gitlab-game-demo.s3-website-us-east-1.amazonaws.com/) -that's tested and deployed on every push to the `master` branch of the [codebase](https://gitlab.com/blitzgren/gitlab-game-demo). -This will also provide -boilerplate code for starting a browser-based game with the following components: - -- Written in [TypeScript](https://www.typescriptlang.org/) and [PhaserJs](https://phaser.io) -- Building, running, and testing with [Gulp](https://gulpjs.com) -- Unit tests with [Chai](https://www.chaijs.com) and [Mocha](https://mochajs.org/) -- CI/CD with GitLab -- Hosting the codebase on GitLab.com -- Hosting the game on AWS -- Deploying to AWS - -## Requirements and setup - -Please refer to my previous article [DevOps and Game Dev](https://ryanhallcs.wordpress.com/2017/03/15/devops-and-game-dev/) to learn the foundational -development tools, running a Hello World-like game, and building this game using GitLab -CI/CD from every new push to master. The `master` branch for this game's [repository](https://gitlab.com/blitzgren/gitlab-game-demo) -contains a completed version with all configurations. If you would like to follow along -with this article, you can clone and work from the `devops-article` branch: - -```shell -git clone git@gitlab.com:blitzgren/gitlab-game-demo.git -git checkout devops-article -``` - -Next, we'll create a small subset of tests that exemplify most of the states I expect -this `Weapon` class to go through. To get started, create a folder called `lib/tests` -and add the following code to a new file `weaponTests.ts`: - -```typescript -import { expect } from 'chai'; -import { Weapon, BulletFactory } from '../lib/weapon'; - -describe('Weapon', () => { - var subject: Weapon; - var shotsFired: number = 0; - // Mocked bullet factory - var bulletFactory: BulletFactory = <BulletFactory>{ - generate: function(px, py, vx, vy, rot) { - shotsFired++; - } - }; - var parent: any = { x: 0, y: 0 }; - - beforeEach(() => { - shotsFired = 0; - subject = new Weapon(bulletFactory, parent, 0.25, 1); - }); - - it('should shoot if not in cooldown', () => { - subject.trigger(true); - subject.update(0.1); - expect(shotsFired).to.equal(1); - }); - - it('should not shoot during cooldown', () => { - subject.trigger(true); - subject.update(0.1); - subject.update(0.1); - expect(shotsFired).to.equal(1); - }); - - it('should shoot after cooldown ends', () => { - subject.trigger(true); - subject.update(0.1); - subject.update(0.3); // longer than timeout - expect(shotsFired).to.equal(2); - }); - - it('should not shoot if not triggered', () => { - subject.update(0.1); - subject.update(0.1); - expect(shotsFired).to.equal(0); - }); -}); -``` - -To build and run these tests using gulp, let's also add the following gulp functions -to the existing `gulpfile.js` file: - -```typescript -gulp.task('build-test', function () { - return gulp.src('src/tests/**/*.ts', { read: false }) - .pipe(tap(function (file) { - // replace file contents with browserify's bundle stream - file.contents = browserify(file.path, { debug: true }) - .plugin(tsify, { project: "./tsconfig.test.json" }) - .bundle(); - })) - .pipe(buffer()) - .pipe(sourcemaps.init({loadMaps: true}) ) - .pipe(gulp.dest('built/tests')); -}); - -gulp.task('run-test', function() { - gulp.src(['./built/tests/**/*.ts']).pipe(mocha()); -}); -``` - -We will start implementing the first part of our game and get these `Weapon` tests to pass. -The `Weapon` class will expose a method to trigger the generation of a bullet at a given -direction and speed. Later we will implement a `Player` class that ties together the user input -to trigger the weapon. In the `src/lib` folder create a `weapon.ts` file. We'll add two classes -to it: `Weapon` and `BulletFactory` which will encapsulate Phaser's **sprite** and -**group** objects, and the logic specific to our game. - -```typescript -export class Weapon { - private isTriggered: boolean = false; - private currentTimer: number = 0; - - constructor(private bulletFactory: BulletFactory, private parent: Phaser.Sprite, private cooldown: number, private bulletSpeed: number) { - } - - public trigger(on: boolean): void { - this.isTriggered = on; - } - - public update(delta: number): void { - this.currentTimer -= delta; - - if (this.isTriggered && this.currentTimer <= 0) { - this.shoot(); - } - } - - private shoot(): void { - // Reset timer - this.currentTimer = this.cooldown; - - // Get velocity direction from player rotation - var parentRotation = this.parent.rotation + Math.PI / 2; - var velx = Math.cos(parentRotation); - var vely = Math.sin(parentRotation); - - // Apply a small forward offset so bullet shoots from head of ship instead of the middle - var posx = this.parent.x - velx * 10 - var posy = this.parent.y - vely * 10; - - this.bulletFactory.generate(posx, posy, -velx * this.bulletSpeed, -vely * this.bulletSpeed, this.parent.rotation); - } -} - -export class BulletFactory { - - constructor(private bullets: Phaser.Group, private poolSize: number) { - // Set all the defaults for this BulletFactory's bullet object - this.bullets.enableBody = true; - this.bullets.physicsBodyType = Phaser.Physics.ARCADE; - this.bullets.createMultiple(30, 'bullet'); - this.bullets.setAll('anchor.x', 0.5); - this.bullets.setAll('anchor.y', 0.5); - this.bullets.setAll('outOfBoundsKill', true); - this.bullets.setAll('checkWorldBounds', true); - } - - public generate(posx: number, posy: number, velx: number, vely: number, rot: number): Phaser.Sprite { - // Pull a bullet from Phaser's Group pool - var bullet = this.bullets.getFirstExists(false); - - // Set the few unique properties about this bullet: rotation, position, and velocity - if (bullet) { - bullet.reset(posx, posy); - bullet.rotation = rot; - bullet.body.velocity.x = velx; - bullet.body.velocity.y = vely; - } - - return bullet; - } -} -``` - -Lastly, we'll redo our entry point, `game.ts`, to tie together both `Player` and `Weapon` objects -as well as add them to the update loop. Here is what the updated `game.ts` file looks like: - -```typescript -import { Player } from "./player"; -import { Weapon, BulletFactory } from "./weapon"; - -window.onload = function() { - var game = new Phaser.Game(800, 600, Phaser.AUTO, 'gameCanvas', { preload: preload, create: create, update: update }); - var player: Player; - var weapon: Weapon; - - // Import all assets prior to loading the game - function preload () { - game.load.image('player', 'assets/player.png'); - game.load.image('bullet', 'assets/bullet.png'); - } - - // Create all entities in the game, after Phaser loads - function create () { - // Create and position the player - var playerSprite = game.add.sprite(400, 550, 'player'); - playerSprite.anchor.setTo(0.5); - player = new Player(game.input, playerSprite, 150); - - var bulletFactory = new BulletFactory(game.add.group(), 30); - weapon = new Weapon(bulletFactory, player.sprite, 0.25, 1000); - - player.loadWeapon(weapon); - } - - // This function is called once every tick, default is 60fps - function update() { - var deltaSeconds = game.time.elapsedMS / 1000; // convert to seconds - player.update(deltaSeconds); - weapon.update(deltaSeconds); - } -} -``` - -Run `gulp serve` and you can run around and shoot. Wonderful! Let's update our CI -pipeline to include running the tests along with the existing build job. - -## Continuous Integration - -To ensure our changes don't break the build and all tests still pass, we use -Continuous Integration (CI) to run these checks automatically for every push. -Read through this article to understand [Continuous Integration, Continuous Delivery, and Continuous Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/), -and how these methods are leveraged by GitLab. -From the [last tutorial](https://ryanhallcs.wordpress.com/2017/03/15/devops-and-game-dev/) we already have a `.gitlab-ci.yml` file set up for building our app from -every push. We need to set up a new CI job for testing, which GitLab CI/CD will run after the build job using our generated artifacts from gulp. - -Please read through the [documentation on CI/CD configuration](../../../ci/yaml/README.md) file to explore its contents and adjust it to your needs. - -### Build your game with GitLab CI/CD - -We need to update our build job to ensure tests get run as well. Add `gulp build-test` -to the end of the `script` array for the existing `build` job. After these commands run, -we know we will need to access everything in the `built` folder, given by GitLab CI/CD's `artifacts`. -We'll also cache `node_modules` to avoid having to do a full re-pull of those dependencies: -just pack them up in the cache. Here is the full `build` job: - -```yaml -build: - stage: build - script: - - npm i gulp -g - - npm i - - gulp - - gulp build-test - cache: - policy: push - paths: - - node_modules - artifacts: - paths: - - built -``` - -### Test your game with GitLab CI/CD - -For testing locally, we simply run `gulp run-tests`, which requires gulp to be installed -globally like in the `build` job. We pull `node_modules` from the cache, so the `npm i` -command won't have to do much. In preparation for deployment, we know we will still need -the `built` folder in the artifacts, which will be brought over as default behavior from -the previous job. Lastly, by convention, we let GitLab CI/CD know this needs to be run after -the `build` job by giving it a `test` [stage](../../../ci/yaml/README.md#stages). -Following the YAML structure, the `test` job should look like this: - -```yaml -test: - stage: test - script: - - npm i gulp -g - - npm i - - gulp run-test - cache: - policy: push - paths: - - node_modules/ - artifacts: - paths: - - built/ -``` - -We have added unit tests for a `Weapon` class that shoots on a specified interval. -The `Player` class implements `Weapon` along with the ability to move around and shoot. Also, -we've added test artifacts and a test stage to our GitLab CI/CD pipeline using `.gitlab-ci.yml`, -allowing us to run our tests by every push. -Our entire `.gitlab-ci.yml` file should now look like this: - -```yaml -image: node:10 - -build: - stage: build - script: - - npm i gulp -g - - npm i - - gulp - - gulp build-test - cache: - policy: push - paths: - - node_modules/ - artifacts: - paths: - - built/ - -test: - stage: test - script: - - npm i gulp -g - - npm i - - gulp run-test - cache: - policy: pull - paths: - - node_modules/ - artifacts: - paths: - - built/ -``` - -### Run your CI/CD pipeline - -That's it! Add all your new files, commit, and push. For a reference of what our repository should -look like at this point, please refer to the [final commit related to this article on my sample repository](https://gitlab.com/blitzgren/gitlab-game-demo/commit/8b36ef0ecebcf569aeb251be4ee13743337fcfe2). -By applying both build and test stages, GitLab will run them sequentially at every push to -our repository. If all goes well you'll end up with a green check mark on each job for the pipeline: - - - -You can confirm that the tests passed by clicking on the `test` job to enter the full build logs. -Scroll to the bottom and observe, in all its passing glory: - -```shell -$ gulp run-test -[18:37:24] Using gulpfile /builds/blitzgren/gitlab-game-demo/gulpfile.js -[18:37:24] Starting 'run-test'... -[18:37:24] Finished 'run-test' after 21 ms - - - Weapon - ✓ should shoot if not in cooldown - ✓ should not shoot during cooldown - ✓ should shoot after cooldown ends - ✓ should not shoot if not triggered - - - 4 passing (18ms) - -Uploading artifacts... -built/: found 17 matching files -Uploading artifacts to coordinator... ok id=17095874 responseStatus=201 Created token=aaaaaaaa Job succeeded -``` - -## Continuous Deployment - -We have our codebase built and tested on every push. To complete the full pipeline with Continuous Deployment, -let's set up [free web hosting with AWS S3](https://aws.amazon.com/free/) and a job through which our build artifacts get -deployed. GitLab also has a free static site hosting service we can use, [GitLab Pages](https://about.gitlab.com/stages-devops-lifecycle/pages/), -however Dark Nova specifically uses other AWS tools that necessitates using `AWS S3`. -Read through this article that describes [deploying to both S3 and GitLab Pages](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/) -and further delves into the principles of GitLab CI/CD than discussed in this article. - -### Set up S3 Bucket - -1. Log into your AWS account and go to [S3](https://console.aws.amazon.com/s3/home) -1. Click the **Create Bucket** link at the top -1. Enter a name of your choosing and click next -1. Keep the default **Properties** and click next -1. Click the **Manage group permissions** and allow **Read** for the **Everyone** group, click next -1. Create the bucket, and select it in your S3 bucket list -1. On the right side, click **Properties** and enable the **Static website hosting** category -1. Update the radio button to the **Use this bucket to host a website** selection. Fill in `index.html` and `error.html` respectively - -### Set up AWS Secrets - -We need to be able to deploy to AWS with our AWS account credentials, but we certainly -don't want to put secrets into source code. Luckily GitLab provides a solution for this -with [Variables](../../../ci/variables/README.md). This can get complicated -due to [IAM](https://aws.amazon.com/iam/) management. As a best practice, you shouldn't -use root security credentials. Proper IAM credential management is beyond the scope of this -article, but AWS will remind you that using root credentials is unadvised and against their -best practices, as they should. Feel free to follow best practices and use a custom IAM user's -credentials, which will be the same two credentials (Key ID and Secret). It's a good idea to -fully understand [IAM Best Practices in AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html). We need to add these credentials to GitLab: - -1. Log into your AWS account and go to the [Security Credentials page](https://console.aws.amazon.com/iam/home#/security_credential) -1. Click the **Access Keys** section and **Create New Access Key**. Create the key and keep the ID and secret around, you'll need them later - -  - -1. Go to your GitLab project, click **Settings > CI/CD** on the left sidebar -1. Expand the **Variables** section - -  - -1. Add a key named `AWS_KEY_ID` and copy the key ID from Step 2 into the **Value** field -1. Add a key named `AWS_KEY_SECRET` and copy the key secret from Step 2 into the **Value** field - -### 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 -account to deploy the artifacts. By convention, AWS CLI will look for `AWS_ACCESS_KEY_ID` -and `AWS_SECRET_ACCESS_KEY`. GitLab CI/CD 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, -we add directives to ensure deployment `only` happens on pushes to `master`. This way, every -single branch still runs through CI, and only merging (or committing directly) to master will -trigger the `deploy` job of our pipeline. Put these together to get the following: - -```yaml -deploy: - stage: deploy - variables: - AWS_ACCESS_KEY_ID: "$AWS_KEY_ID" - AWS_SECRET_ACCESS_KEY: "$AWS_KEY_SECRET" - script: - - apt-get update - - apt-get install -y python3-dev python3-pip - - easy_install3 -U pip - - pip3 install --upgrade awscli - - aws s3 sync ./built s3://gitlab-game-demo --region "us-east-1" --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers --cache-control "no-cache, no-store, must-revalidate" --delete - only: - - master -``` - -Be sure to update the region and S3 URL in that last script command to fit your setup. -Our final configuration file `.gitlab-ci.yml` looks like: - -```yaml -image: node:10 - -build: - stage: build - script: - - npm i gulp -g - - npm i - - gulp - - gulp build-test - cache: - policy: push - paths: - - node_modules/ - artifacts: - paths: - - built/ - -test: - stage: test - script: - - npm i gulp -g - - gulp run-test - cache: - policy: pull - paths: - - node_modules/ - artifacts: - paths: - - built/ - -deploy: - stage: deploy - variables: - AWS_ACCESS_KEY_ID: "$AWS_KEY_ID" - AWS_SECRET_ACCESS_KEY: "$AWS_KEY_SECRET" - script: - - apt-get update - - apt-get install -y python3-dev python3-pip - - easy_install3 -U pip - - pip3 install --upgrade awscli - - aws s3 sync ./built s3://gitlab-game-demo --region "us-east-1" --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers --cache-control "no-cache, no-store, must-revalidate" --delete - only: - - master -``` - -## Conclusion - -Within the [demo repository](https://gitlab.com/blitzgren/gitlab-game-demo) you can also find a handful of boilerplate code to get -[TypeScript](https://www.typescriptlang.org/), [Mocha](https://mochajs.org/), [Gulp](https://gulpjs.com/) and [Phaser](https://phaser.io) all playing -together nicely with GitLab CI/CD, which is the result of lessons learned while making [Dark Nova](https://www.darknova.io). -Using a combination of free and open source software, we have a full CI/CD pipeline, a game foundation, -and unit tests, all running and deployed at every push to master - with shockingly little code. -Errors can be easily debugged through GitLab build logs, and within minutes of a successful commit, -you can see the changes live on your game. - -Setting up Continuous Integration and Continuous Deployment from the start with Dark Nova enables -rapid but stable development. We can easily test changes in a separate [environment](../../environments/index.md), -or multiple environments if needed. Balancing and updating a multiplayer game can be ongoing -and tedious, but having faith in a stable deployment with GitLab CI/CD allows -a lot of breathing room in quickly getting changes to players. - -## Further settings - -Here are some ideas to further investigate that can speed up or improve your pipeline: - -- [Yarn](https://yarnpkg.com) instead of npm -- Set up a custom [Docker](../../../ci/docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) image that can pre-load dependencies and tools (like AWS CLI) -- Forward a [custom domain](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html) to your game's S3 static website -- Combine jobs if you find it unnecessary for a small project -- Avoid the queues and set up your own [custom GitLab CI/CD runner](https://about.gitlab.com/blog/2016/03/01/gitlab-runner-with-docker/) +<!-- This redirect file can be deleted after 2021-04-19. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/license_management.md b/doc/ci/examples/license_management.md deleted file mode 100644 index 46be93c9676..00000000000 --- a/doc/ci/examples/license_management.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../user/compliance/license_compliance/index.md' ---- - -This document was moved to [another location](../../user/compliance/license_compliance/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index 31f0cc76023..b61943f0c32 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -66,8 +66,7 @@ docker-php-ext-install pdo_mysql You might wonder what `docker-php-ext-install` is. In short, it is a script provided by the official PHP Docker image that you can use to easily install -extensions. For more information read the documentation at -<https://hub.docker.com/_/php>. +extensions. For more information read [the documentation](https://hub.docker.com/_/php). Now that we created the script that contains all prerequisites for our build environment, let's add it in `.gitlab-ci.yml`: @@ -179,8 +178,8 @@ phpenv config-add my_config.ini *__Important note:__ It seems `phpenv/phpenv` [is abandoned](https://github.com/phpenv/phpenv/issues/57). There is a fork - at [madumlao/phpenv](https://github.com/madumlao/phpenv) that tries to bring - the project back to life. [CHH/phpenv](https://github.com/CHH/phpenv) also + at [`madumlao/phpenv`](https://github.com/madumlao/phpenv) that tries to bring + the project back to life. [`CHH/phpenv`](https://github.com/CHH/phpenv) also seems like a good alternative. Picking any of the mentioned tools works with the basic phpenv commands. Guiding you to choose the right phpenv is out of the scope of this tutorial.* @@ -201,10 +200,10 @@ command once, only to set up the build environment. ## Extend your tests -### Using atoum +### Using `atoum` Instead of PHPUnit, you can use any other tool to run unit tests. For example -you can use [atoum](https://github.com/atoum/atoum): +you can use [`atoum`](https://github.com/atoum/atoum): ```yaml before_script: diff --git a/doc/ci/examples/sast.md b/doc/ci/examples/sast.md deleted file mode 100644 index ebb3c1f66c1..00000000000 --- a/doc/ci/examples/sast.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../user/application_security/sast/index.md' ---- - -This document was moved to [another location](../../user/application_security/sast/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/sast_docker.md b/doc/ci/examples/sast_docker.md deleted file mode 100644 index eecf939d959..00000000000 --- a/doc/ci/examples/sast_docker.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../user/application_security/container_scanning/index.md' ---- - -This document was moved to [another location](../../user/application_security/container_scanning/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/test-phoenix-application.md b/doc/ci/examples/test-phoenix-application.md deleted file mode 100644 index 52db5740c34..00000000000 --- a/doc/ci/examples/test-phoenix-application.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../../ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md' ---- - -The content of this page was incorporated in [this document](../../ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md). diff --git a/doc/ci/examples/test-scala-application.md b/doc/ci/examples/test-scala-application.md index 5c499d6a855..057b950289d 100644 --- a/doc/ci/examples/test-scala-application.md +++ b/doc/ci/examples/test-scala-application.md @@ -1,81 +1,8 @@ --- -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/#assignments -type: tutorial +redirect_to: 'README.md#contributed-examples' --- -# Test and deploy a Scala application to Heroku +This document was moved to [another location](README.md#contributed-examples). -This example demonstrates the integration of GitLab CI/CD with Scala -applications using SBT. You can view or fork the [example project](https://gitlab.com/gitlab-examples/scala-sbt) -and view the logs of its past [CI jobs](https://gitlab.com/gitlab-examples/scala-sbt/-/jobs?scope=finished). - -## Add `.gitlab-ci.yml` file to project - -The following `.gitlab-ci.yml` should be added in the root of your -repository to trigger CI: - -``` yaml -image: openjdk:8 - -stages: - - test - - deploy - -before_script: - - apt-get update -y - - apt-get install apt-transport-https -y - ## Install SBT - - echo "deb http://dl.bintray.com/sbt/debian /" | tee -a /etc/apt/sources.list.d/sbt.list - - apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 642AC823 - - apt-get update -y - - apt-get install sbt -y - - sbt sbtVersion - -test: - stage: test - script: - - sbt clean coverage test coverageReport - -deploy: - stage: deploy - script: - - apt-get update -yq - - apt-get install rubygems ruby-dev -y - - gem install dpl - - dpl --provider=heroku --app=gitlab-play-sample-app --api-key=$HEROKU_API_KEY -``` - -In the above configuration: - -- The `before_script` installs [SBT](https://www.scala-sbt.org/) and - displays the version that is being used. -- The `test` stage executes SBT to compile and test the project. - - [sbt-scoverage](https://github.com/scoverage/sbt-scoverage) is used as an SBT - plugin to measure test coverage. -- The `deploy` stage automatically deploys the project to Heroku using dpl. - -You can use other versions of Scala and SBT by defining them in -`build.sbt`. - -## Display test coverage in job - -Add the `Coverage was \[\d+.\d+\%\]` regular expression in the -**Settings > Pipelines > Coverage report** project setting to -retrieve the [test coverage](../pipelines/settings.md#test-coverage-report-badge) -rate from the build trace and have it displayed with your jobs. - -**Pipelines** must be enabled for this option to appear. - -## Heroku application - -A Heroku application is required. You can create one through the -[Dashboard](https://dashboard.heroku.com/). Substitute `gitlab-play-sample-app` -in the `.gitlab-ci.yml` file with your application's name. - -## Heroku API key - -You can look up your Heroku API key in your -[account](https://dashboard.heroku.com/account). Add a [protected variable](../variables/README.md#protect-a-custom-variable) with -this value in **Project ➔ Variables** with key `HEROKU_API_KEY`. +<!-- This redirect file can be deleted after 2021-04-18. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/jenkins/index.md b/doc/ci/jenkins/index.md deleted file mode 100644 index 3f720ef959e..00000000000 --- a/doc/ci/jenkins/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../migration/jenkins.md' ---- - -This document was moved to [another location](../migration/jenkins.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md index c985a5b00ef..a57ef513be4 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/index.md @@ -196,8 +196,8 @@ You can create [collapsible sections in job logs](#expand-and-collapse-job-log-s by manually outputting special codes that GitLab uses to determine what sections to collapse: -- Section start marker: `section_start:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` + `TEXT_OF_SECTION_HEADER` -- Section end marker: `section_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` +- Section start marker: `\e[0Ksection_start:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` + `TEXT_OF_SECTION_HEADER` +- Section end marker: `\e[0Ksection_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` You must add these codes to the script section of the CI configuration. For example, using `echo`: @@ -205,9 +205,9 @@ using `echo`: ```yaml job1: script: - - echo -e "section_start:`date +%s`:my_first_section\r\e[0KHeader of the 1st collapsible section" + - echo -e "\e[0Ksection_start:`date +%s`:my_first_section\r\e[0KHeader of the 1st collapsible section" - echo 'this line should be hidden when collapsed' - - echo -e "section_end:`date +%s`:my_first_section\r\e[0K" + - echo -e "\e[0Ksection_end:`date +%s`:my_first_section\r\e[0K" ``` In the example above: @@ -223,9 +223,9 @@ In the example above: Sample raw job log: ```plaintext -section_start:1560896352:my_first_section\r\e[0KHeader of the 1st collapsible section +\e[0Ksection_start:1560896352:my_first_section\r\e[0KHeader of the 1st collapsible section this line should be hidden when collapsed -section_end:1560896353:my_first_section\r\e[0K +\e[0Ksection_end:1560896353:my_first_section\r\e[0K ``` ### Pre-collapse sections @@ -236,7 +236,7 @@ You can make the job log automatically collapse collapsible sections by adding t Add `[collapsed=true]` after the section name and before the `\r`. The section end marker remains unchanged: -- Section start marker with `[collapsed=true]`: `section_start:UNIX_TIMESTAMP:SECTION_NAME[collapsed=true]\r\e[0K` + `TEXT_OF_SECTION_HEADER` +- Section start marker with `[collapsed=true]`: `\e[0Ksection_start:UNIX_TIMESTAMP:SECTION_NAME[collapsed=true]\r\e[0K` + `TEXT_OF_SECTION_HEADER` - Section end marker: `section_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` Add the updated section start text to the CI configuration. For example, @@ -245,7 +245,7 @@ using `echo`: ```yaml job1: script: - - echo -e "section_start:`date +%s`:my_first_section[collapsed=true]\r\e[0KHeader of the 1st collapsible section" + - echo -e "\e[0Ksection_start:`date +%s`:my_first_section[collapsed=true]\r\e[0KHeader of the 1st collapsible section" - echo 'this line should be hidden automatically after loading the job log' - - echo -e "section_end:`date +%s`:my_first_section\r\e[0K" + - echo -e "\e[0Ksection_end:`date +%s`:my_first_section\r\e[0K" ``` diff --git a/doc/ci/junit_test_reports.md b/doc/ci/junit_test_reports.md deleted file mode 100644 index 2ae17df0933..00000000000 --- a/doc/ci/junit_test_reports.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'unit_test_reports.md' ---- - -This document was moved to [unit_test_reports](unit_test_reports.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index 35b4a2de8f8..aff18b0889f 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/index.md @@ -114,6 +114,11 @@ For example, if your project contains a large number of tags that your CI jobs d you could add [`--no-tags`](https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---no-tags) to the extra flags to make your fetches faster and more compact. +Also in the case where you repository does _not_ contain a lot of +tags, `--no-tags` can [make a big difference in some +cases](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/746). +If your CI builds do not depend on Git tags it is worth trying. + See the [`GIT_FETCH_EXTRA_FLAGS` documentation](../runners/README.md#git-fetch-extra-flags) for more information. diff --git a/doc/ci/lint.md b/doc/ci/lint.md index ec3c128f076..969f1fbc47b 100644 --- a/doc/ci/lint.md +++ b/doc/ci/lint.md @@ -4,8 +4,10 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- <!-- markdownlint-disable MD044 --> +<!-- vale gitlab.Spelling = NO --> # Validate .gitlab-ci.yml syntax with the CI Lint tool <!-- markdownlint-enable MD044 --> +<!-- vale gitlab.Spelling = YES --> If you want to test the validity of your GitLab CI/CD configuration before committing the changes, you can use the CI Lint tool. This tool checks for syntax and logical diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index 999d15eac24..5c3cf6ec02e 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -166,9 +166,10 @@ Read the [documentation on Pipelines for Merged Results](pipelines_for_merged_re Read the [documentation on Merge Trains](pipelines_for_merged_results/merge_trains/index.md). -## Run pipelines in the parent project for merge requests from a forked project **(STARTER)** +## Run pipelines in the parent project for merge requests from a forked project **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217451) in GitLab 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217451) in GitLab 13.3. +> - [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. By default, external contributors working from forks can't create pipelines in the parent project. When a pipeline for merge requests is triggered by a merge request 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 e5b9ad030d0..edfedbc2527 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 @@ -84,9 +84,10 @@ 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) 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** -1. Check **Enable merged results pipelines.** (if not enabled) -1. Check **Enable merge trains.** +1. Visit your project's **Settings > General** and expand **Merge requests**. +1. In the **Merge method** section, verify that **Merge commit** is selected. + You cannot use **Merge commit with semi-linear history** or **Fast-forward merge** with merge trains. +1. In the **Merge options** section, select **Enable merged results pipelines.** (if not already selected) and **Enable merge trains.** 1. Click **Save changes** In GitLab 13.5 and earlier, there is only one checkbox, named @@ -209,7 +210,7 @@ Trains, create a new pipeline for merged results when this error occurs: See [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/35135) for more information. -### Merge Trains feature flag **(PREMIUM ONLY)** +### Merge Trains feature flag **(PREMIUM SELF)** In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/244831), you can [enable or disable merge trains in the project settings](#enable-merge-trains). diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index 5d217466f5c..73219bb8ed7 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -271,8 +271,8 @@ CircleCI provides [Contexts](https://circleci.com/docs/2.0/contexts/) to securel There are two GitLab issues open addressing CircleCI Orbs and how GitLab can achieve similar functionality. -- <https://gitlab.com/gitlab-com/Product/-/issues/1151> -- <https://gitlab.com/gitlab-org/gitlab/-/issues/195173> +- [issue #1151](https://gitlab.com/gitlab-com/Product/-/issues/1151) +- [issue #195173](https://gitlab.com/gitlab-org/gitlab/-/issues/195173) ## Build environments diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index 71d5e6eb859..8392bfa50fa 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -209,7 +209,7 @@ as well as encourage inner sourcing. In self-managed GitLab instances, you can build an [Instance Template Repository](../../user/admin_area/settings/instance_template_repository.md). Development teams across the whole organization can select templates from a dropdown menu. -A group administrator is able to set a group to use as the source for the +A group maintainer or a group owner is able to set a group to use as the source for the [custom project templates](../../user/admin_area/custom_project_templates.md), which can be used by all projects in the group. An instance administrator can set a group as the source for [instance project templates](../../user/group/custom_project_templates.md), diff --git a/doc/ci/multi_project_pipeline_graphs.md b/doc/ci/multi_project_pipeline_graphs.md deleted file mode 100644 index 66efa0a7c35..00000000000 --- a/doc/ci/multi_project_pipeline_graphs.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'multi_project_pipelines.md' ---- - -This document was moved to [another location](multi_project_pipelines.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index 006d6bda0e0..a84fb3fa06f 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -261,7 +261,7 @@ test: ### Mirroring status from triggered pipeline > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11238) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Core in 12.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8. You can mirror the pipeline status from the triggered pipeline to the source bridge job by using `strategy: depend`. For example: diff --git a/doc/ci/parent_child_pipelines.md b/doc/ci/parent_child_pipelines.md index d088d0d7e4d..58b7e303138 100644 --- a/doc/ci/parent_child_pipelines.md +++ b/doc/ci/parent_child_pipelines.md @@ -156,7 +156,11 @@ build a matrix of targets and architectures. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Create child pipelines using dynamically generated configurations](https://youtu.be/nMdfus2JWHM). -We also have an [example project using Dynamic Child Pipelines with Jsonnet](https://gitlab.com/gitlab-org/project-templates/jsonnet) which shows how to use a data templating language to generate your `.gitlab-ci.yml` at runtime. You could use a similar process for other templating languages like [Dhall](https://dhall-lang.org/) or [`ytt`](https://get-ytt.io/). +<!-- vale gitlab.Spelling = NO --> +We also have an example project using +[Dynamic Child Pipelines with Jsonnet](https://gitlab.com/gitlab-org/project-templates/jsonnet) +which shows how to use a data templating language to generate your `.gitlab-ci.yml` at runtime. You could use a similar process for other templating languages like [Dhall](https://dhall-lang.org/) or [`ytt`](https://get-ytt.io/). +<!-- vale gitlab.Spelling = NO --> The artifact path is parsed by GitLab, not the runner, so the path must match the syntax for the OS running GitLab. If GitLab is running on Linux but using a Windows diff --git a/doc/ci/permissions/README.md b/doc/ci/permissions/README.md deleted file mode 100644 index 897d7b6ce51..00000000000 --- a/doc/ci/permissions/README.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../user/permissions.md#gitlab-cicd-permissions' ---- - -This document was moved to [user/permissions.md](../../user/permissions.md#gitlab-cicd-permissions). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index 61b8e289509..4ddaa16d7c5 100644 --- a/doc/ci/pipeline_editor/index.md +++ b/doc/ci/pipeline_editor/index.md @@ -5,13 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Pipeline Editor **(CORE)** +# Pipeline Editor **(FREE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4540) in GitLab 13.8. > - It's [deployed behind a feature flag](../../user/feature_flags.md), enabled by default. > - It's enabled 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-pipeline-editor). **(CORE ONLY)** +> - It's recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-pipeline-editor). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -28,8 +28,8 @@ From the pipeline editor page you can: - [Commit](#commit-changes-to-ci-configuration) the changes to a specific branch. NOTE: -You must have already [created a CI/CD configuration file](../quick_start/README.md#create-a-gitlab-ciyml-file) -to use the editor. +You must already have [a `.gitlab-ci.yml` file](../quick_start/README.md#create-a-gitlab-ciyml-file) +on the default branch (usually "master") of your project to use the editor. ## Validate CI configuration @@ -62,8 +62,8 @@ reflected in the CI lint. It displays the same results as the existing [CI Lint > - It was [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/290117) in GitLab 13.8. > - It's enabled 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-cicd-configuration-visualization). **(CORE ONLY)** +> - It's recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cicd-configuration-visualization). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -81,7 +81,7 @@ Hovering on a job highlights its `needs` relationships: If the configuration does not have any `needs` relationships, then no lines are drawn because each job depends only on the previous stage being completed successfully. -### Enable or disable CI/CD configuration visualization **(CORE ONLY)** +### Enable or disable CI/CD configuration visualization **(FREE SELF)** CI/CD configuration visualization is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. @@ -113,9 +113,9 @@ checkbox appears. Select it to start a new merge request after you commit the ch  -## Enable or disable pipeline editor **(CORE ONLY)** +## Enable or disable pipeline editor **(FREE SELF)** -The pipeline editor is under development and not ready for production use. It is +The pipeline editor 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 disable it. diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md deleted file mode 100644 index 090dbd3d347..00000000000 --- a/doc/ci/pipelines.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'pipelines/index.md' ---- - -This document was moved to [another location](pipelines/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 7920a3bf7f3..d6b9282462d 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -132,10 +132,6 @@ Pipelines can be manually executed, with predefined or manually-specified [varia You might do this if the results of a pipeline (for example, a code build) are required outside the normal operation of the pipeline. -[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30101), -all global variables with descriptions defined in the `.gitlab-ci.yml` file are -displayed in the variable fields. - To execute a pipeline manually: 1. Navigate to your project's **CI/CD > Pipelines**. @@ -143,10 +139,33 @@ To execute a pipeline manually: 1. On the **Run Pipeline** page: 1. Select the branch to run the pipeline for in the **Create for** field. 1. Enter any [environment variables](../variables/README.md) required for the pipeline run. + You can set specific variables to have their [values prefilled in the form](#prefill-variables-in-manual-pipelines). 1. Click the **Create pipeline** button. The pipeline now executes the jobs as configured. +#### Prefill variables in manual pipelines + +> [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) GitLab 13.7. + +You can use the [`value` and `description`](../yaml/README.md#prefill-variables-in-manual-pipelines) +keywords to define [variables](../variables/README.md) that are prefilled when running +a pipeline manually. + +In pipelines triggered manually, the **Run pipelines** page displays all variables +with a `description` and `value` defined in the `.gitlab-ci.yml` file. The values +can then be modified if needed, which overrides the value for that single pipeline run. + +The description is displayed below the variable. It can be used to explain what +the variable is used for, what the acceptable values are, and so on: + +```yaml +variables: + DEPLOY_ENVIRONMENT: + value: "staging" # Deploy to staging by default + description: "The deployment target. Change this variable to 'canary' or 'production' if needed." +``` + ### Run a pipeline by using a URL query string > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24146) in GitLab 12.5. diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index 4c77a578aa4..12310d0c8a8 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -168,9 +168,11 @@ The collected SAST report uploads to GitLab as an artifact and is summarized in merge requests and the pipeline view. It's also used to provide data for security dashboards. -#### `artifacts:reports:secret_detection` **(ULTIMATE)** +#### `artifacts:reports:secret_detection` > - Introduced in GitLab 13.1. +> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) in GitLab + 13.3. > - Requires GitLab Runner 11.5 and above. The `secret-detection` report collects [detected secrets](../../user/application_security/secret_detection/index.md) diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index de78b8558c4..a2df228e3a2 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -161,7 +161,7 @@ Try to find which jobs don't need to run in all situations, and use pipeline con 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. + when they are superseded 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. diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md index cddfcb754ec..a8e310c1f0d 100644 --- a/doc/ci/pipelines/schedules.md +++ b/doc/ci/pipelines/schedules.md @@ -6,7 +6,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/schedules. type: reference, howto --- -# Pipeline schedules +# Pipeline schedules **(FREE)** > - Introduced in GitLab 9.1 as [Trigger Schedule](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10533). > - [Renamed to Pipeline Schedule](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10853) in GitLab 9.2. @@ -83,7 +83,7 @@ job: - make build ``` -### Advanced configuration +### Advanced configuration **(FREE SELF)** The pipelines are not executed exactly on schedule because schedules are handled by Sidekiq, which runs according to its interval. diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index 5a758bccd62..20916588962 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -63,12 +63,12 @@ if the job surpasses the threshold, it is marked as failed. Project defined timeout (either specific timeout set by user or the default 60 minutes timeout) may be [overridden for runners](../runners/README.md#set-maximum-job-timeout-for-a-runner). -## Maximum artifacts size **(CORE ONLY)** +## Maximum artifacts size **(FREE SELF)** 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). -## Custom CI configuration path +## Custom CI/CD configuration path > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12509) in GitLab 9.4. > - [Support for external `.gitlab-ci.yml` locations](https://gitlab.com/gitlab-org/gitlab/-/issues/14376) introduced in GitLab 12.6. @@ -80,7 +80,7 @@ To customize the path: 1. Go to the project's **Settings > CI / CD**. 1. Expand the **General pipelines** section. -1. Provide a value in the **Custom CI configuration path** field. +1. Provide a value in the **CI/CD configuration file** field. 1. Click **Save changes**. If the CI configuration is stored within the repository in a non-default @@ -131,8 +131,23 @@ averaged.  -A few examples of known coverage tools for a variety of languages can be found -in the pipelines settings page. +<!-- vale gitlab.Spelling = NO --> + +| Coverage Tool | Sample regular expression | +|------------------------------------------------|---------------------------| +| Simplecov (Ruby) | `\(\d+.\d+\%\) covered` | +| pytest-cov (Python) | `^TOTAL.+?(\d+\%)$` | +| Scoverage (Scala) | `Statement coverage[A-Za-z\.*]\s*:\s*([^%]+)` | +| `phpunit --coverage-text --colors=never` (PHP) | `^\s*Lines:\s*\d+.\d+\%` | +| gcovr (C/C++) | `^TOTAL.*\s+(\d+\%)$` | +| `tap --coverage-report=text-summary` (NodeJS) | `^Statements\s*:\s*([^%]+)` | +| `nyc npm test` (NodeJS) | `All files[^|]*\|[^|]*\s+([\d\.]+)` | +| excoveralls (Elixir) | `\[TOTAL\]\s+(\d+\.\d+)%` | +| `mix test --cover` (Elixir) | `\d+.\d+\%\s+\|\s+Total` | +| JaCoCo (Java/Kotlin) | `Total.*?([0-9]{1,3})%` | +| `go test -cover` (Go) | `coverage: \d+.\d+% of statements` | + +<!-- vale gitlab.Spelling = YES --> ### Code Coverage history @@ -143,7 +158,7 @@ To see the evolution of your project code coverage over time, you can view a graph or download a CSV file with this data. From your project: 1. Go to **{chart}** **Project Analytics > Repository** to see the historic data for each job listed in the dropdown above the graph. -1. If you want a CSV file of that data, click **Download raw data (.csv)** +1. If you want a CSV file of that data, click **Download raw data (`.csv`)**  @@ -198,7 +213,7 @@ If **Public pipelines** is disabled: - For **private** projects, only project members (reporter or higher) can view the pipelines or access the related features. -## Auto-cancel pending pipelines +## Auto-cancel redundant pipelines > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9362) in GitLab 9.1. @@ -206,7 +221,7 @@ You can set pending or running pipelines to cancel automatically when a new pipe 1. Go to **Settings > CI / CD**. 1. Expand **General Pipelines**. -1. Check the **Auto-cancel redundant, pending pipelines** checkbox. +1. Check the **Auto-cancel redundant pipelines** checkbox. 1. Click **Save changes**. Use the [`interruptible`](../yaml/README.md#interruptible) keyword to indicate if a diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 3512b77e4e2..063e05fddab 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -180,18 +180,19 @@ After you have the route mapping set up, it takes effect in the following locati - In the diff for a merge request, comparison, or commit. -  +  - In the blob file view. -  +  -## Visual Reviews **(STARTER)** +## Visual Reviews **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10761) in GitLab Starter 12.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10761) in GitLab 12.0. +> - [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. > - It's [deployed behind a feature flag](../../user/feature_flags.md), enabled by default. > - It's enabled on GitLab.com. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-visual-reviews). **(STARTER ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-visual-reviews). **(PREMIUM SELF)** With Visual Reviews, members of any team (Product, Design, Quality, and so on) can provide feedback comments through a form in your review apps. The comments are added to the merge request that triggered the review app. @@ -288,7 +289,7 @@ can supply the ID by either: - Dynamically adding the `data-merge-request-id` value during the build of the app. - Supplying it manually through the visual review form in the app. -### Enable or disable Visual Reviews **(STARTER ONLY)** +### Enable or disable Visual Reviews **(PREMIUM SELF)** Visual Reviews is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index d6ea4d83825..43fd0af6f39 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -37,10 +37,10 @@ multiple projects. If you are using a self-managed instance of GitLab: -- Your administrator can install and register shared runners by [following the documentation](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**.--> - <!-- These instructions are also available [in the documentation](https://docs.gitlab.com/runner/install/index.html).--> +- Your administrator can install and register shared runners by + going to your project's **Settings > CI / CD**, expanding the **Runners** section, + and clicking **Show runner installation instructions**. + These instructions are also available [in the documentation](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). diff --git a/doc/ci/services/docker-services.md b/doc/ci/services/docker-services.md deleted file mode 100644 index e4653cdc9e2..00000000000 --- a/doc/ci/services/docker-services.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'README.md' ---- - -This document was moved to [another location](README.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 2e7ec58f048..db8782ac476 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Triggering pipelines through the API **(CORE)** +# Triggering pipelines through the API **(FREE)** Triggers can be used to force a pipeline rerun of a specific `ref` (branch or tag) with an API call. diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index 9cda1f14b01..cddcf76236a 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.md @@ -222,6 +222,29 @@ This also applies if the pipeline has not been created yet, or if you are waitin 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 pipeline for this merge request did not complete. Push a new commit to fix the failure or check the troubleshooting documentation to see other possible actions." message + +This message is shown if the [merge request pipeline](merge_request_pipelines/index.md), +[merged results pipeline](merge_request_pipelines/pipelines_for_merged_results/index.md), +or [merge train pipeline](merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md) +has failed or been canceled. + +If a merge request pipeline or merged result pipeline was canceled or failed, you can: + +- Re-run the entire pipeline by clicking **Run pipeline** in the pipeline tab in the merge request. +- [Retry only the jobs that failed](pipelines/index.md#view-pipelines). If you re-run the entire pipeline, this is not necessary. +- Push a new commit to fix the failure. + +If the merge train pipeline has failed, you can: + +- Check the failure and determine if you can use the [`/merge` quick action](../user/project/quick_actions.md) to immediately add the merge request to the train again. +- Re-run the entire pipeline by clicking **Run pipeline** in the pipeline tab in the merge request, then add the merge request to the train again. +- Push a commit to fix the failure, then add the merge request to the train again. + +If the merge train pipeline was canceled before the merge request was merged, without a failure, you can: + +- Add it to the train again. + ## Pipeline warnings Pipeline configuration warnings are shown when you: @@ -239,6 +262,23 @@ To [prevent duplicate pipelines](yaml/README.md#prevent-duplicate-pipelines), us [`workflow: rules`](yaml/README.md#workflowrules) or rewrite your rules to control which pipelines can run. +### Console workaround if job using resource_group gets stuck + +```ruby +# find resource group by name +resource_group = Project.find_by_full_path('...').resource_groups.find_by(key: 'the-group-name') +busy_resources = resource_group.resources.where('build_id IS NOT NULL') + +# identify which builds are occupying the resource +# (I think it should be 1 as of today) +busy_resources.pluck(:build_id) + +# it's good to check why this build is holding the resource. +# Is it stuck? Has it been forcefully dropped by the system? +# free up busy resources +busy_resources.update_all(build_id: nil) +``` + ## How to get help If you are unable to resolve pipeline issues, you can get help from: diff --git a/doc/ci/unit_test_reports.md b/doc/ci/unit_test_reports.md index 1fec1f77bc3..e72d746c42b 100644 --- a/doc/ci/unit_test_reports.md +++ b/doc/ci/unit_test_reports.md @@ -67,8 +67,9 @@ execution time and the error output. ### Number of recent failures -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241759) in GitLab 13.7. +> - [Introduced in Merge Requests](https://gitlab.com/gitlab-org/gitlab/-/issues/241759) in GitLab 13.7. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268249) in GitLab 13.8. +> - [Introduced in Test Reports](https://gitlab.com/gitlab-org/gitlab/-/issues/235525) in GitLab 13.9. If a test failed in the project's default branch in the last 14 days, a message like `Failed {n} time(s) in {default_branch} in the last 14 days` is displayed for that test. @@ -290,6 +291,22 @@ javascript: - junit.xml ``` +### Flutter / Dart example + +This example `.gitlab-ci.yml` file uses the [JUnit Report](https://pub.dev/packages/junitreport) package to convert the `flutter test` output into JUnit report XML format: + +```yaml +test: + stage: test + script: + - flutter test --machine | tojunit -o report.xml + artifacts: + when: always + reports: + junit: + - report.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. @@ -310,7 +327,7 @@ You can also retrieve the reports via the [GitLab API](../api/pipelines.md#get-a > - [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)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enabling-the-junit-screenshots-feature). **(FREE SELF)** If JUnit report format XML files contain an `attachment` tag, GitLab parses the attachment. @@ -324,7 +341,7 @@ Upload your screenshots as [artifacts](pipelines/job_artifacts.md#artifactsrepor 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)** +### Enabling the JUnit screenshots feature **(FREE SELF)** This feature comes with the `:junit_pipeline_screenshots_view` feature flag disabled by default. diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 5fca8e8c2b7..db80ba508f3 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -70,7 +70,8 @@ When you need a specific custom environment variable, you can 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. -You can also [override variable values manually for a specific pipeline](../jobs/index.md#specifying-variables-when-running-manual-jobs). +You can also [override variable values manually for a specific pipeline](../jobs/index.md#specifying-variables-when-running-manual-jobs), +or have them [prefilled in manual pipelines](../pipelines/index.md#prefill-variables-in-manual-pipelines). There are two types of variables: **Variable** and **File**. You cannot set types in the `.gitlab-ci.yml` file, but you can set them in the UI and API. @@ -208,9 +209,10 @@ The value of the variable must: - Be in a single line. - Be at least 8 characters long. - Not be a predefined or custom environment variable. -- Consist only of characters from the Base64 alphabet (RFC4648). - [In GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/63043) - and newer, `@` and `:` are also valid values. +- Consist only of: + - Characters from the Base64 alphabet (RFC4648). + - The `@` and `:` characters ([In GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/63043) and later). + - The `.` character ([In GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29022) and later). You can't mask variables that don't meet these requirements. @@ -406,6 +408,10 @@ script: - 'eval $LS_CMD' # will execute 'ls -al $TMP_DIR' ``` +Use the [`value` and `description`](../yaml/README.md#prefill-variables-in-manual-pipelines) +keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) +when [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually): + ## Group-level environment variables > Introduced in GitLab 9.4. @@ -618,7 +624,7 @@ variables, an `Insufficient permissions to set pipeline variables` error occurs. The setting is `disabled` by default. -If you [store your CI configurations in a different repository](../../ci/pipelines/settings.md#custom-ci-configuration-path), +If you [store your CI configurations in a different repository](../../ci/pipelines/settings.md#custom-cicd-configuration-path), use this setting for strict control over all aspects of the environment the pipeline runs in. @@ -777,7 +783,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)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-parenthesis-support-for-variables). **(FREE SELF)** It is possible to use parentheses to group conditions. Parentheses have the highest precedence of all operators. Expressions enclosed in parentheses are evaluated first, @@ -793,7 +799,7 @@ Examples: - `($VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/) && $VARIABLE3` - `$CI_COMMIT_BRANCH == "my-branch" || (($VARIABLE1 == "thing" || $VARIABLE2 == "thing") && $VARIABLE3)` -##### Enable or disable parenthesis support for variables **(CORE ONLY)** +##### Enable or disable parenthesis support for variables **(FREE SELF)** The 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) @@ -1076,7 +1082,7 @@ if [[ -d "/builds/gitlab-examples/ci-debug-trace/.git" ]]; then ## Video walkthrough of a working example -The [Managing the Complex Configuration Data Management Monster Using GitLab](https://www.youtube.com/watch?v=v4ZOJ96hAck) video is a walkthrough of the [Complex Config Data Monorepo](https://gitlab.com/guided-explorations/config-data-top-scope/config-data-subscope/config-data-monorepo) working example project. It explains how multiple levels of group CI/CD variables can be combined with environment-scoped project variables for complex configuration of application builds or deployments. +The [Managing the Complex Configuration Data Management Monster Using GitLab](https://www.youtube.com/watch?v=v4ZOJ96hAck) video is a walkthrough of the [Complex Configuration Data Monorepo](https://gitlab.com/guided-explorations/config-data-top-scope/config-data-subscope/config-data-monorepo) working example project. It explains how multiple levels of group CI/CD variables can be combined with environment-scoped project variables for complex configuration of application builds or deployments. 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/yaml/README.md b/doc/ci/yaml/README.md index 19b8f0f1c89..750ecd91085 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -5,7 +5,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab CI/CD pipeline configuration reference +<!-- markdownlint-disable MD044 --> +<!-- vale gitlab.Spelling = NO --> +# Keyword reference for the .gitlab-ci.yml file +<!-- vale gitlab.Spelling = YES --> +<!-- markdownlint-enable MD044 --> This document lists the configuration options for your GitLab `.gitlab-ci.yml` file. @@ -26,7 +30,7 @@ The keywords available for jobs are: |:---------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`script`](#script) | Shell script that is executed by a runner. | | [`after_script`](#after_script) | Override a set of commands that are executed after job. | -| [`allow_failure`](#allow_failure) | Allow job to fail. A failed job does not cause the pipeline to fail. | +| [`allow_failure`](#allow_failure) | Allow job to fail. A failed job does not cause the pipeline to fail. | | [`artifacts`](#artifacts) | List of files and directories to attach to a job on success. Also available: `artifacts:paths`, `artifacts:exclude`, `artifacts:expose_as`, `artifacts:name`, `artifacts:untracked`, `artifacts:when`, `artifacts:expire_in`, and `artifacts:reports`. | | [`before_script`](#before_script) | Override a set of commands that are executed before job. | | [`cache`](#cache) | List of files that should be cached between subsequent runs. Also available: `cache:paths`, `cache:key`, `cache:untracked`, `cache:when`, and `cache:policy`. | @@ -44,7 +48,7 @@ The keywords available for jobs are: | [`release`](#release) | Instructs the runner to generate a [Release](../../user/project/releases/index.md) object. | | [`resource_group`](#resource_group) | Limit job concurrency. | | [`retry`](#retry) | When and how many times a job can be auto-retried in case of a failure. | -| [`rules`](#rules) | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. May not be used alongside `only`/`except`. | +| [`rules`](#rules) | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. | | [`services`](#services) | Use Docker services images. Also available: `services:name`, `services:alias`, `services:entrypoint`, and `services:command`. | | [`stage`](#stage) | Defines a job stage (default: `test`). | | [`tags`](#tags) | List of tags that are used to select a runner. | @@ -55,8 +59,8 @@ The keywords available for jobs are: ### Unavailable names for jobs -Each job must have a unique name, but there are a few **reserved `keywords` that -can't be used as job names**: +Each job must have a unique name, but there are a few reserved `keywords` that +can't be used as job names: - `image` - `services` @@ -70,7 +74,7 @@ can't be used as job names**: ### Reserved keywords -If you get a validation error when using specific values (for example, `true` or `false`), try to: +If you get a validation error when you use specific values (for example, `true` or `false`), try to: - Quote them. - Change them to a different form. For example, `/bin/true`. @@ -223,7 +227,7 @@ stages: If any job fails, the pipeline is marked as `failed` and jobs in later stages do not start. Jobs in the current stage are not stopped and continue to run. -If no `stages` are defined in `.gitlab-ci.yml`, then `build`, `test` and `deploy` +If no `stages` are defined in the `.gitlab-ci.yml` file, then `build`, `test` and `deploy` are the default pipeline stages. If a job does not specify a [`stage`](#stage), the job is assigned the `test` stage. @@ -339,10 +343,10 @@ include: > - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. > - Available for Starter, Premium, and Ultimate in GitLab 10.6 and later. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Core in 11.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Free in 11.4. Use the `include` keyword to include external YAML files in your CI/CD configuration. -You can break down one long `gitlab-ci.yml` into multiple files to increase readability, +You can break down one long `gitlab-ci.yml` file into multiple files to increase readability, or reduce duplication of the same configuration in multiple places. You can also store template files in a central repository and `include` them in projects. @@ -363,33 +367,27 @@ use the [`extends` keyword](#extends). | [`remote`](#includeremote) | Include a file from a remote URL. Must be publicly accessible. | | [`template`](#includetemplate) | Include templates that are provided by GitLab. | -`.gitlab-ci.yml` configuration included by all methods is evaluated at pipeline creation. +The `.gitlab-ci.yml` file configuration included by all methods is evaluated when the pipeline is created. The configuration is a snapshot in time and persisted in the database. Any changes to -referenced `.gitlab-ci.yml` configuration is not reflected in GitLab until the next pipeline is created. +the referenced `.gitlab-ci.yml` file configuration is not reflected in GitLab until the next pipeline is created. The files defined by `include` are: -- Deep merged with those in `.gitlab-ci.yml`. -- Always evaluated first and merged with the content of `.gitlab-ci.yml`, +- Deep merged with those in the `.gitlab-ci.yml` file. +- Always evaluated first and merged with the content of the `.gitlab-ci.yml` file, regardless of the position of the `include` keyword. NOTE: Use merging to customize and override included CI/CD configurations with local -definitions. Local definitions in `.gitlab-ci.yml` override included definitions. +configurations. Local configurations in the `.gitlab-ci.yml` file override included configurations. -#### Variables with `include` +#### Variables with `include` **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/284883) in GitLab 13.8. -> - 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-includepredefined-project-variables). **(CORE ONLY)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/294294) in GitLab 13.9. You can [use some predefined variables in `include` sections](../variables/where_variables_can_be_used.md#gitlab-ciyml-file) -in your `.gitlab-ci.yml`: +in your `.gitlab-ci.yml` file: ```yaml include: @@ -400,33 +398,13 @@ include: For an example of how you can include these predefined variables, and their impact on CI jobs, see the following [CI variable demo](https://youtu.be/4XR8gw3Pkos). -##### Enable or disable include:predefined-project-variables **(CORE ONLY)** - -Use of predefined project variables in `include` section of `.gitlab-ci.yml` 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(:variables_in_include_section_ci) -``` - -To disable it: - -```ruby -Feature.disable(:variables_in_include_section_ci) -``` - #### `include:local` -`include:local` includes a file from the same repository as `.gitlab-ci.yml`. +`include:local` includes a file that is in the same repository as the `.gitlab-ci.yml` file. It's referenced with full paths relative to the root directory (`/`). -You can only use files that are tracked by Git on the same branch -your configuration file is on. If you `include:local`, make -sure that both `.gitlab-ci.yml` and the local file are on the same branch. +If you use `include:local`, make sure that both the `.gitlab-ci.yml` file and the local file +are on the same branch. You can't include local files through Git submodules paths. @@ -440,14 +418,14 @@ include: - local: '/templates/.gitlab-ci-template.yml' ``` -Local includes can be used as a replacement for symbolic links that are not followed. - This can be defined as a short local include: ```yaml include: '.gitlab-ci-production.yml' ``` +Use local includes instead of symbolic links. + #### `include:file` > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903) in GitLab 11.7. @@ -501,24 +479,23 @@ include: #### `include:remote` -`include:remote` can be used to include a file from a different location, -using HTTP/HTTPS, referenced by the full URL. The remote file must be -publicly accessible by a GET request, because authentication schemas -in the remote URL are not supported. For example: +Use `include:remote` with a full URL to include a file from a different location. +The remote file must be publicly accessible by an HTTP/HTTPS `GET` request, because +authentication in the remote URL is not supported. For example: ```yaml include: - - remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml' + - remote: 'https://gitlab.com/example-project/-/raw/master/.gitlab-ci.yml' ``` -All [nested includes](#nested-includes) are executed without context as a public user, +All [nested includes](#nested-includes) execute without context as a public user, so you can only `include` public projects or templates. #### `include:template` > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53445) in GitLab 11.7. -`include:template` can be used to include `.gitlab-ci.yml` templates that are +Use `include:template` to include `.gitlab-ci.yml` templates that are [shipped with GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates). For example: @@ -677,7 +654,7 @@ job: #### `before_script` -`before_script` is used to define an array of commands that should run before each job, +Use `before_script` to define an array of commands that should run before each job, but after [artifacts](#artifacts) are restored. Scripts specified in `before_script` are concatenated with any scripts specified @@ -705,7 +682,7 @@ You can use [YAML anchors with `before_script`](#yaml-anchors-for-scripts). #### `after_script` -`after_script` is used to define an array of commands that run after each job, +Use `after_script` to define an array of commands that run after each job, including failed jobs. If a job times out or is cancelled, the `after_script` commands are not executed. @@ -756,7 +733,7 @@ You can use special syntax in [`script`](README.md#script) sections to: `stage` is defined per-job and relies on [`stages`](#stages), which is defined globally. Use `stage` to define which stage a job runs in, and jobs of the same -`stage` are executed in parallel (subject to [certain conditions](#using-your-own-runners)). For example: +`stage` are executed in parallel (subject to [certain conditions](#use-your-own-runners)). For example: ```yaml stages: @@ -789,7 +766,7 @@ job 5: script: make something useful at the end of pipeline ``` -#### Using your own runners +#### Use your own runners When you use your own runners, each runner runs only one job at a time by default. Jobs can run in parallel if they run on different runners. @@ -811,7 +788,7 @@ User-defined stages are executed after `.pre` and before `.post`. A pipeline is not created if all jobs are in `.pre` or `.post` stages. -The order of `.pre` and `.post` can't be changed, even if defined out of order in `.gitlab-ci.yml`. +The order of `.pre` and `.post` can't be changed, even if defined out of order in the `.gitlab-ci.yml` file. For example, the following are equivalent configuration: - Configured in order: @@ -846,11 +823,16 @@ For example, the following are equivalent configuration: > Introduced in GitLab 11.3. -`extends` defines entry names that a job that uses `extends` -inherits from. +Use `extends` to reuse configuration sections. It's an alternative to [YAML anchors](#anchors) +and is a little more flexible and readable. You can use `extends` to reuse configuration +from [included configuration files](#use-extends-and-include-together). -It's an alternative to using [YAML anchors](#anchors) and is a little -more flexible and readable: +In this example, the `rspec` job uses the configuration from the `.tests` template job. +GitLab: + +- Performs a reverse deep merge based on the keys. +- Merges the `.tests` content with the `rspec` job. +- Doesn't merge the values of the keys. ```yaml .tests: @@ -868,13 +850,7 @@ rspec: - $RSPEC ``` -In the example above, the `rspec` job inherits from the `.tests` template job. -GitLab performs a reverse deep merge based on the keys. GitLab: - -- Merges the `rspec` contents into `.tests` recursively. -- Doesn't merge the values of the keys. - -The result is this `rspec` job, where `script: rake test` is overwritten by `script: rake rspec`: +The result is this `rspec` job: ```yaml rspec: @@ -887,10 +863,8 @@ rspec: - $RSPEC ``` -If you do want to include the `rake test`, see [`before_script`](#before_script) or [`after_script`](#after_script). - `.tests` in this example is a [hidden job](#hide-jobs), but it's -possible to inherit from regular jobs as well. +possible to extend configuration from regular jobs as well. `extends` supports multi-level inheritance. You should avoid using more than three levels, but you can use as many as eleven. The following example has two levels of inheritance: @@ -979,51 +953,51 @@ rspec: Note that in the example above: -- `variables` sections have been merged but that `URL: "http://my-url.internal"` -has been overwritten by `URL: "http://docker-url.internal"`. -- `tags: ['production']` has been overwritten by `tags: ['docker']`. -- `script` has not been merged but rather `script: ['echo "Hello world!"']` has - been overwritten by `script: ['rake rspec']`. Arrays can be - merged using [YAML anchors](#anchors). +- The `variables` sections merge, but `URL: "http://docker-url.internal"` overwrites `URL: "http://my-url.internal"`. +- `tags: ['docker']` overwrites `tags: ['production']`. +- `script` does not merge, but `script: ['rake rspec']` overwrites + `script: ['echo "Hello world!"']`. You can use [YAML anchors](#anchors) to merge arrays. -#### Using `extends` and `include` together +#### Use `extends` and `include` together -`extends` works across configuration files combined with `include`. +To reuse configuration from different configuration files, +combine `extends` and [`include`](#include). -For example, if you have a local `included.yml` file: +In this example, a `script` is defined in the `included.yml` file. +Then, in the `.gitlab-ci.yml` file, you use `extends` to refer +to the contents of the `script`: -```yaml -.template: - script: - - echo Hello! -``` +- `included.yml`: -Then, in `.gitlab-ci.yml`: + ```yaml + .template: + script: + - echo Hello! + ``` -```yaml -include: included.yml +- `.gitlab-ci.yml`: -useTemplate: - image: alpine - extends: .template -``` + ```yaml + include: included.yml -This example runs a job called `useTemplate` that runs `echo Hello!` as defined in -the `.template` job, and uses the `alpine` Docker image as defined in the local job. + useTemplate: + image: alpine + extends: .template + ``` ### `rules` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3. -The `rules` keyword can be used to include or exclude jobs in pipelines. +Use the `rules` keyword to include or exclude jobs in pipelines. Rules are evaluated *in order* until the first match. When matched, the job is either included or excluded from the pipeline, depending on the configuration. If included, the job also has [certain attributes](#rules-attributes) added to it. -`rules` replaces [`only/except`](#onlyexcept-basic) and can't be used in conjunction with it. -If you attempt to use both keywords in the same job, the linter returns a +`rules` replaces [`only/except`](#onlyexcept-basic) and they can't be used together +in the same job. If you configure one job to use both keywords, the linter returns a `key may not be used with rules` error. #### Rules attributes @@ -1078,7 +1052,7 @@ The job is not added to the pipeline: `when: always`. - If a rule matches, and has `when: never` as the attribute. -For example, using `if` clauses to strictly limit when jobs run: +This example uses `if` to strictly limit when jobs run: ```yaml job: @@ -1090,8 +1064,6 @@ job: - if: '$CI_PIPELINE_SOURCE == "schedule"' ``` -In this example: - - If the pipeline is for a merge request, the first rule matches, and the job is added to the [merge request pipeline](../merge_request_pipelines/index.md) with attributes of: @@ -1165,7 +1137,7 @@ There are multiple ways to avoid duplicate pipelines: or push (branch) pipelines only. - Rewrite the rules to run the job only in very specific cases, - and avoid using a final `when:` rule: + and avoid a final `when:` rule: ```yaml job: @@ -1282,7 +1254,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable: |-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). | | `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/README.md) command. | -| `external` | When using CI services other than GitLab. | +| `external` | When you use CI services other than GitLab. | | `external_pull_request_event` | When an external pull request on GitHub is created or updated. See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). | | `merge_request_event` | For pipelines created when a merge request is created or updated. Required to enable [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). | | `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`. Use this pipeline source in the child pipeline configuration so that it can be triggered by the parent pipeline. | @@ -1400,7 +1372,7 @@ docker build: - $DOCKERFILES_DIR/* ``` -The `$` character can be used for both variables and paths. For example, if the +You can use The `$` character for both variables and paths. For example, if the `$DOCKERFILES_DIR` variable exists, its value is used. If it does not exist, the `$` is interpreted as being part of a path. @@ -1409,7 +1381,9 @@ The `$` character can be used for both variables and paths. For example, if the > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4. `exists` accepts an array of paths and matches if any of these paths exist -as files in the repository: +as files in the repository. + +In this example, `job` runs if a `Dockerfile` exists anywhere in the repository: ```yaml job: @@ -1419,7 +1393,9 @@ job: - Dockerfile ``` -You can also use glob patterns to match multiple files in any directory in the repository: +Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly link outside it. + +You can use glob patterns to match multiple files in any directory in the repository: ```yaml job: @@ -1429,15 +1405,17 @@ job: - spec/**.rb ``` -For performance reasons, using `exists` with patterns is limited to 10,000 -checks. After the 10,000th check, rules with patterned globs always match. +Glob patterns are interpreted with Ruby [`File.fnmatch`](https://docs.ruby-lang.org/en/2.7.0/File.html#method-c-fnmatch) +with the flags `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`. + +For performance reasons, GitLab matches a maximum of 10,000 `exists` patterns. After the 10,000th check, rules with patterned globs always match. #### `rules:allow_failure` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8. You can use [`allow_failure: true`](#allow_failure) in `rules:` to allow a job to fail, or a manual job to -wait for action, without stopping the pipeline itself. All jobs using `rules:` default to `allow_failure: false` +wait for action, without stopping the pipeline itself. All jobs that use `rules:` default to `allow_failure: false` if `allow_failure:` is not defined. The rule-level `rules:allow_failure` option overrides the job-level @@ -1462,7 +1440,7 @@ In this example, if the first rule matches, then the job has `when: manual` and > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/289803) on GitLab 13.8. > - 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-rulesvariables). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-rulesvariables). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -1487,7 +1465,7 @@ job: - echo "Run another script if $IS_A_FEATURE exists" ``` -##### Enable or disable rules:variables **(CORE ONLY)** +##### Enable or disable rules:variables **(FREE SELF)** rules:variables is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. @@ -1553,12 +1531,10 @@ rules that use both `||` and `&&` may evaluate with an unexpected order of opera ### `only`/`except` (basic) NOTE: -The [`rules`](#rules) syntax is an improved, more powerful solution for defining -when jobs should run or not. Consider using `rules` instead of `only/except` to get -the most out of your pipelines. +`only` and `except` are not being actively developed. To define when +to add jobs to pipelines, use [`rules`](#rules). -`only` and `except` are two keywords that set a job policy to limit when -jobs are created: +`only` and `except` are two keywords that determine when to add jobs to pipelines: 1. `only` defines the names of branches and tags the job runs for. 1. `except` defines the names of branches and tags the job does @@ -1578,7 +1554,7 @@ In addition, `only` and `except` can use special keywords: | `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). | | `branches` | When the Git reference for a pipeline is a branch. | | `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/README.md) command. | -| `external` | When using CI services other than GitLab. | +| `external` | When you use CI services other than GitLab. | | `external_pull_requests` | When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)). | | `merge_requests` | For pipelines created when a merge request is created or updated. Enables [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). | | `pipelines` | For [multi-project pipelines](../multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../multi_project_pipelines.md#triggering-multi-project-pipelines-through-api), or the [`trigger`](#trigger) keyword. | @@ -1630,7 +1606,7 @@ job: - schedules ``` -The repository path can be used to have jobs executed only for the parent +Use the repository path to have jobs executed only for the parent repository and not forks: ```yaml @@ -1648,17 +1624,13 @@ except `master` and those with names prefixed with `release/`. If a job does not have an `only` rule, `only: ['branches', 'tags']` is set by default. If it does not have an `except` rule, it's empty. -For example, +For example, `job1` and `job2` are essentially the same: ```yaml -job: +job1: script: echo 'test' -``` - -is translated to: -```yaml -job: +job2: script: echo 'test' only: ['branches', 'tags'] ``` @@ -1728,7 +1700,7 @@ the pipeline if the following is true: In the example below, the `test` job is `only` created when **all** of the following are true: -- The pipeline has been [scheduled](../pipelines/schedules.md) **or** runs for `master`. +- The pipeline is [scheduled](../pipelines/schedules.md) **or** runs for `master`. - The `variables` keyword matches. - The `kubernetes` service is active on the project. @@ -1805,7 +1777,7 @@ The `variables` keyword defines variable expressions. These expressions determine whether or not a job should be created. -Examples of using variable expressions: +Examples of variable expressions: ```yaml deploy: @@ -1844,15 +1816,14 @@ job1: > `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19232) in GitLab 11.4. -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. +Use the `changes` keyword with `only` to run a job, or with `except` to skip a job, +when a Git push event modifies a file. -Use the `only:changes` policy for pipelines triggered by the following -refs only: +Use `only:changes` with pipelines triggered by the following refs only: - `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)) +- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](#use-onlychanges-with-pipelines-for-merge-requests)) WARNING: In pipelines with [sources other than the three above](../variables/predefined_variables.md) @@ -1860,7 +1831,13 @@ In pipelines with [sources other than the three above](../variables/predefined_v You can configure jobs to use `only: changes` with other `only: refs` keywords. However, those jobs ignore the changes and always run. -A basic example of using `only: changes`: +In this example, when you push commits to an existing branch, the `docker build` job +runs only if any of these files change: + +- The `Dockerfile` file. +- Files in the `docker/scripts/` directory. +- Files and subdirectories in the `dockerfiles` directory. +- Files with `rb`, `py`, `sh` extensions in the `more_scripts` directory. ```yaml docker build: @@ -1875,21 +1852,13 @@ docker build: - more_scripts/*.{rb,py,sh} ``` -When you push commits to an existing branch, -the `docker build` job is created, but only if changes were made to any of the following: - -- The `Dockerfile` file. -- Any of the files in the `docker/scripts/` directory. -- Any of the files and subdirectories in the `dockerfiles` directory. -- Any of the files with `rb`, `py`, `sh` extensions in the `more_scripts` directory. - WARNING: If you use `only:changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds), -you should [also use `only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected. +you should [also use `only:merge_requests`](#use-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected. You can also use glob patterns to match multiple files in either the root directory of the repository, or in _any_ directory in the repository. However, they must be wrapped -in double quotes or GitLab can't parse them. For example: +in double quotes or GitLab can't parse them: ```yaml test: @@ -1918,10 +1887,10 @@ the `build` job is still skipped. The job does not run for any of the files. Read more about how to use this feature with: -- [New branches or tags *without* pipelines for merge requests](#using-onlychanges-without-pipelines-for-merge-requests). -- [Scheduled pipelines](#using-onlychanges-with-scheduled-pipelines). +- [New branches or tags *without* pipelines for merge requests](#use-onlychanges-without-pipelines-for-merge-requests). +- [Scheduled pipelines](#use-onlychanges-with-scheduled-pipelines). -##### Using `only:changes` with pipelines for merge requests +##### Use `only:changes` with pipelines for merge requests With [pipelines for merge requests](../merge_request_pipelines/index.md), it's possible to define a job to be created based on files modified @@ -1971,7 +1940,7 @@ it doesn't matter that an earlier pipeline failed because of a change that has n When you use this configuration, ensure that the most recent pipeline properly corrects any failures from previous pipelines. -##### Using `only:changes` without pipelines for merge requests +##### Use `only:changes` without pipelines for merge requests Without [pipelines for merge requests](../merge_request_pipelines/index.md), pipelines run on branches or tags that don't have an explicit association with a merge request. @@ -1979,14 +1948,13 @@ In this case, a previous SHA is used to calculate the diff, which is equivalent This can result in some unexpected behavior, including: - When pushing a new branch or a new tag to GitLab, the policy always evaluates to true. -- When pushing a new commit, the changed files are calculated using the previous commit +- When pushing a new commit, the changed files are calculated by using the previous commit as the base SHA. -##### Using `only:changes` with scheduled pipelines +##### Use `only:changes` with scheduled pipelines -`only:changes` always evaluates as "true" in [Scheduled pipelines](../pipelines/schedules.md). -All files are considered to have "changed" when a scheduled pipeline -runs. +`only:changes` always evaluates as true in [Scheduled pipelines](../pipelines/schedules.md). +All files are considered to have changed when a scheduled pipeline runs. ### `needs` @@ -2064,7 +2032,7 @@ This example creates four paths of execution: - Related to the above, stages must be explicitly defined for all jobs that have the keyword `needs:` or are referred to by one. -##### Changing the `needs:` job limit **(CORE ONLY)** +##### Changing the `needs:` job limit **(FREE SELF)** The maximum number of jobs that can be defined in `needs:` defaults to 50. @@ -2081,14 +2049,11 @@ To disable directed acyclic graphs (DAG), set the limit to `0`. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.6. -When using `needs`, artifact downloads are controlled with `artifacts: true` (default) or `artifacts: false`. +Use `artifacts: true` (default) or `artifacts: false` to control when artifacts are +downloaded in jobs that use `needs`. -In GitLab 12.6 and later, you can't combine the [`dependencies`](#dependencies) keyword -with `needs` to control artifact downloads in jobs. `dependencies` is still valid -in jobs that do not use `needs`. - -In the example below, the `rspec` job downloads the `build_job` artifacts, while the -`rubocop` job doesn't: +In this example, the `rspec` job downloads the `build_job` artifacts, but the +`rubocop` job does not: ```yaml build_job: @@ -2110,9 +2075,11 @@ rubocop: artifacts: false ``` -Additionally, in the three syntax examples below, the `rspec` job downloads the artifacts -from all three `build_jobs`. `artifacts` is true for `build_job_1` and -**defaults** to true for both `build_job_2` and `build_job_3`. +In this example, the `rspec` job downloads the artifacts from all three `build_jobs`. +`artifacts` is: + +- Set to true for `build_job_1`. +- Defaults to true for both `build_job_2` and `build_job_3`. ```yaml rspec: @@ -2123,6 +2090,9 @@ rspec: - build_job_3 ``` +In GitLab 12.6 and later, you can't combine the [`dependencies`](#dependencies) keyword +with `needs`. + #### Cross project artifact downloads with `needs` **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.7. @@ -2146,7 +2116,7 @@ build_job: `build_job` downloads the artifacts from the latest successful `build-1` job on the `master` branch in the `group/project-name` project. If the project is in the -same group or namespace, you can omit them from the `project:` key. For example, +same group or namespace, you can omit them from the `project:` keyword. For example, `project: group/project-name` or `project: project-name`. The user running the pipeline must have at least `reporter` access to the group or project, or the group/project must have public visibility. @@ -2280,10 +2250,11 @@ osx job: ### `allow_failure` 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 -default to false, *including* `when: manual` jobs. +suite. The default value is `false`, except for [manual](#whenmanual) jobs that use +the `when: manual` syntax. + +In jobs that use [`rules:`](#rules), all jobs default to `allow_failure: false`, +*including* `when: manual` jobs. When `allow_failure` is set to `true` and the job fails, the job shows an orange warning in the UI. However, the logical flow of the pipeline considers the job a @@ -2318,13 +2289,7 @@ job3: #### `allow_failure:exit_codes` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273157) in GitLab 13.8. -> - 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-allow_failureexit_codes). **(CORE ONLY)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292024) in GitLab 13.9. Use `allow_failure:exit_codes` to dynamically control if a job should be allowed to fail. You can list which exit codes are not considered failures. The job fails @@ -2348,31 +2313,12 @@ test_job_2: - 255 ``` -##### Enable or disable `allow_failure:exit_codes` **(CORE ONLY)** - -`allow_failure:exit_codes` 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 disable it. - -To disable it: - -```ruby -Feature.disable(:ci_allow_failure_with_exit_codes) -``` - -To enable it: - -```ruby -Feature.enable(:ci_allow_failure_with_exit_codes) -``` - ### `when` -`when` is used to implement jobs that are run in case of failure or despite the +Use `when` to implement jobs that run in case of failure or despite the failure. -`when` can be set to one of the following values: +The valid values of `when` are: 1. `on_success` (default) - Execute job only when all jobs in earlier stages succeed, or are considered successful because they have `allow_failure: true`. @@ -2510,8 +2456,8 @@ by authorized users. Use `when: delayed` to execute scripts after a waiting period, or if you want to avoid jobs immediately entering the `pending` state. -You can set the period with `start_in` key. The value of `start_in` key is an elapsed time in seconds, unless a unit is -provided. `start_in` key must be less than or equal to one week. Examples of valid values include: +You can set the period with `start_in` keyword. The value of `start_in` is an elapsed time in seconds, unless a unit is +provided. `start_in` must be less than or equal to one week. Examples of valid values include: - `'5'` - `5 seconds` @@ -2519,13 +2465,13 @@ provided. `start_in` key must be less than or equal to one week. Examples of val - `1 day` - `1 week` -When there is a delayed job in a stage, the pipeline doesn't progress until the delayed job has finished. -This keyword can also be used for inserting delays between different stages. +When a stage includes a delayed job, the pipeline doesn't progress until the delayed job finishes. +You can use this keyword to insert delays between different stages. -The timer of a delayed job starts immediately after the previous stage has completed. -Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passed. +The timer of a delayed job starts immediately after the previous stage completes. +Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passes. -The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage has completed: +The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage completes: ```yaml timed rollout 10%: @@ -2535,7 +2481,7 @@ timed rollout 10%: start_in: 30 minutes ``` -You can stop the active timer of a delayed job by clicking the **{time-out}** (**Unschedule**) button. +To stop the active timer of a delayed job, click the **{time-out}** (**Unschedule**) button. This job can no longer be scheduled to run automatically. You can, however, execute the job manually. To start a delayed job immediately, click the **Play** button. @@ -2561,8 +2507,8 @@ deployment to the `production` environment. #### `environment:name` -The `environment: name` keyword can use any of the defined CI variables, -including predefined, secure, or `.gitlab-ci.yml` [`variables`](#variables). +The `environment: name` keyword can use any of the defined CI/CD [variables](#variables), +including predefined, secure, or variables defined in the `.gitlab-ci.yml` file. You can't use variables defined in a `script` section. @@ -2595,8 +2541,8 @@ deploy to production: #### `environment:url` -The `url` keyword can use any of the defined CI variables, -including predefined, secure, or `.gitlab-ci.yml` [`variables`](#variables). +The `environment:url` keyword can use any of the defined CI/CD [variables](#variables), +including predefined, secure, or variables defined in the `.gitlab-ci.yml` file. You can't use variables defined in a `script` section. @@ -2632,7 +2578,7 @@ Read the `environment:action` section for an example. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22191) in GitLab 8.13. -The `action` keyword can be used to specify jobs that prepare, start, or stop environments. +Use the `action` keyword to specify jobs that prepare, start, or stop environments. | **Value** | **Description** | |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -2718,7 +2664,7 @@ For more information, see > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6. -The `kubernetes` block is used to configure deployments to a +Use the `kubernetes` keyword to configure deployments to a [Kubernetes cluster](../../user/project/clusters/index.md) that is associated with your project. For example: @@ -2774,11 +2720,11 @@ as Review Apps. You can see an example that uses Review Apps at ### `cache` -`cache` is used to specify a list of files and directories that should be -cached between jobs. You can only use paths that are in the local working copy. +Use the `cache` keyword to specify a list of files and directories to +cache between jobs. You can only use paths that are in the local working copy. -If `cache` is defined outside the scope of jobs, it means it's set -globally and all jobs use that definition. +If `cache` is defined outside the scope of jobs, it's set +globally and all jobs use that configuration. Caching is shared between pipelines and jobs. Caches are restored before [artifacts](#artifacts). @@ -2789,7 +2735,7 @@ Read how caching works and find out some good practices in the Use the `paths` directive to choose which files or directories to cache. Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly link outside it. -Wildcards can be used that follow the [glob](https://en.wikipedia.org/wiki/Glob_(programming)) +You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and: - In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later, @@ -2875,7 +2821,8 @@ to download cache that's tagged with `test`. If a cache with this tag is not found, you can use `CACHE_FALLBACK_KEY` to specify a cache to use when none exists. -For example: +In this example, if the `$CI_COMMIT_REF_SLUG` is not found, the job uses the key defined +by the `CACHE_FALLBACK_KEY` variable: ```yaml variables: @@ -2887,9 +2834,6 @@ cache: - binaries/ ``` -In this example, if the `$CI_COMMIT_REF_SLUG` is not found, the job uses the key defined -by the `CACHE_FALLBACK_KEY` variable. - ##### `cache:key:files` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5. @@ -2900,7 +2844,7 @@ runs. When you include `cache:key:files`, you must also list the project files that are used to generate the key, up to a maximum of two files. The cache `key` is a SHA checksum computed from the most recent commits (up to two, if two files are listed) -that changed the given files. If neither file was changed in any commits, +that changed the given files. If neither file is changed in any commits, the fallback key is `default`. ```yaml @@ -2927,7 +2871,7 @@ use the new cache, instead of rebuilding the dependencies. When you want to combine a prefix with the SHA computed for `cache:key:files`, use the `prefix` keyword 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 +If neither file is changed in any commits, the prefix is added to `default`, so the key in the example would be `test-default`. Like `cache:key`, `prefix` can use any of the [predefined variables](../variables/README.md), @@ -3039,8 +2983,8 @@ rspec: - bundle exec rspec ... ``` -The `pull` policy speeds up job execution and reduces load on the cache server. It -can be used when you have many jobs that use caches executing in parallel. +Use the `pull` policy when you have many jobs executing in parallel that use caches. This +policy speeds up job execution and reduces load on the cache server. If you have a job that unconditionally recreates the cache without referring to its previous contents, you can skip the download step. @@ -3048,7 +2992,7 @@ To do so, add `policy: push` to the job. ### `artifacts` -`artifacts` is used to specify a list of files and directories that are +Use the `artifacts` keyword to specify a list of files and directories that are attached to the job when it [succeeds, fails, or always](#artifactswhen). The artifacts are sent to GitLab after the job finishes. They are @@ -3063,7 +3007,7 @@ artifacts are restored after [caches](#cache). #### `artifacts:paths` Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly -link outside it. Wildcards can be used that follow the [glob](https://en.wikipedia.org/wiki/Glob_(programming)) +link outside it. You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and: - In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later, @@ -3122,6 +3066,32 @@ job: - path/*xyz/* ``` +#### `artifacts:public` + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49775) in GitLab 13.8 +> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. + +Use `artifacts:public` to determine whether the job artifacts should be +publicly available. + +The default for `artifacts:public` is `true` which means that the artifacts in +public pipelines are available for download by anonymous and guest users: + +```yaml +artifacts: + public: true +``` + +To deny read access for anonymous and guest users to artifacts in public +pipelines, set `artifacts:public` to `false`: + +```yaml +artifacts: + public: false +``` + #### `artifacts:exclude` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15122) in GitLab 13.1 @@ -3131,9 +3101,9 @@ job: archive. Similar to [`artifacts:paths`](#artifactspaths), `exclude` paths are relative -to the project directory. Wildcards can be used that follow the -[glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and -[`filepath.Match`](https://golang.org/pkg/path/filepath/#Match). +to the project directory. You can use Wildcards that use +[glob](https://en.wikipedia.org/wiki/Glob_(programming)) or +[`filepath.Match`](https://golang.org/pkg/path/filepath/#Match) patterns. For example, to store all files in `binaries/`, but not `*.o` files located in subdirectories of `binaries/`: @@ -3153,7 +3123,7 @@ Files matched by [`artifacts:untracked`](#artifactsuntracked) can be excluded us > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15018) in GitLab 12.5. -The `expose_as` keyword can be used to expose [job artifacts](../pipelines/job_artifacts.md) +Use the `expose_as` keyword to expose [job artifacts](../pipelines/job_artifacts.md) in the [merge request](../../user/project/merge_requests/index.md) UI. For example, to match a single file: @@ -3270,8 +3240,8 @@ job: #### `artifacts:untracked` -`artifacts:untracked` is used to add all Git untracked files as artifacts (along -to the paths defined in `artifacts:paths`). `artifacts:untracked` ignores configuration +Use `artifacts:untracked` to add all Git untracked files as artifacts (along +with the paths defined in `artifacts:paths`). `artifacts:untracked` ignores configuration in the repository's `.gitignore` file. Send all Git untracked files: @@ -3301,7 +3271,7 @@ artifacts: #### `artifacts:when` -`artifacts:when` is used to upload artifacts on job failure or despite the +Use `artifacts:when` to upload artifacts on job failure or despite the failure. `artifacts:when` can be set to one of the following values: @@ -3365,8 +3335,8 @@ in GitLab 13.4. In [GitLab 13.8 and later](https://gitlab.com/gitlab-org/gitlab/ #### `artifacts:reports` -The [`artifacts:reports` keyword](../pipelines/job_artifacts.md#artifactsreports) -is used for collecting test reports, code quality reports, and security reports from jobs. +Use [`artifacts:reports`](../pipelines/job_artifacts.md#artifactsreports) +to collect test reports, code quality reports, and security reports from jobs. It also exposes these reports in the GitLab UI (merge requests, pipeline views, and security dashboards). These are the available report types: @@ -3385,7 +3355,7 @@ These are the available report types: | [`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:sast`](../pipelines/job_artifacts.md#artifactsreportssast) | 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` @@ -3403,7 +3373,7 @@ An error occurs if you define jobs from the current or an upcoming stage. To prevent a job from downloading artifacts, define an empty array. When you use `dependencies`, the status of the previous job is not considered. -If a job fails or it's a manual job that was not run, no error occurs. +If a job fails or it's a manual job that isn't triggered, no error occurs. The following example defines two jobs with artifacts: `build:osx` and `build:linux`. When the `test:osx` is executed, the artifacts from `build:osx` @@ -3449,7 +3419,7 @@ deploy: > Introduced in GitLab 10.3. -If the artifacts of the job that is set as a dependency have been +If the artifacts of the job that is set as a dependency are [expired](#artifactsexpire_in) or [erased](../pipelines/job_artifacts.md#erasing-artifacts), then the dependent job fails. @@ -3478,7 +3448,7 @@ job1: The coverage is shown in the UI if at least one line in the job output matches the regular expression. If there is more than one matched line in the job output, the last line is used. -For the matched line, the first occurence of `\d+(\.\d+)?` is the code coverage. +For the matched line, the first occurrence of `\d+(\.\d+)?` is the code coverage. Leading zeros are removed. Coverage output from [child pipelines](../parent_child_pipelines.md) is not recorded @@ -3554,15 +3524,15 @@ Possible values for `when` are: - `script_failure`: Retry when the script failed. - `api_failure`: Retry on API failure. - `stuck_or_timeout_failure`: Retry when the job got stuck or timed out. -- `runner_system_failure`: Retry if there was a runner system failure (for example, job setup failed). -- `missing_dependency_failure`: Retry if a dependency was missing. -- `runner_unsupported`: Retry if the runner was unsupported. +- `runner_system_failure`: Retry if there is a runner system failure (for example, job setup failed). +- `missing_dependency_failure`: Retry if a dependency is missing. +- `runner_unsupported`: Retry if the runner is unsupported. - `stale_schedule`: Retry if a delayed job could not be executed. - `job_execution_timeout`: Retry if the script exceeded the maximum execution time set for the job. - `archived_failure`: Retry if the job is archived and can't be run. - `unmet_prerequisites`: Retry if the job failed to complete prerequisite tasks. - `scheduler_failure`: Retry if the scheduler failed to assign the job to a runner. -- `data_integrity_failure`: Retry if there was a structural integrity problem detected. +- `data_integrity_failure`: Retry if there is a structural integrity problem detected. You can specify the number of [retry attempts for certain stages of job execution](../runners/README.md#job-stages-attempts) using variables. @@ -3640,7 +3610,7 @@ but with different variable values for each instance of the job. There can be from 2 to 50 jobs. Jobs can only run in parallel if there are multiple runners, or a single runner is -[configured to run multiple jobs concurrently](#using-your-own-runners). +[configured to run multiple jobs concurrently](#use-your-own-runners). Every job gets the same `CI_NODE_TOTAL` [environment variable](../variables/README.md#predefined-environment-variables) value, and a unique `CI_NODE_INDEX` value. @@ -3699,10 +3669,10 @@ deploystacks: ### `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. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8. -Use `trigger` to define a downstream pipeline trigger. When GitLab starts a job created -with a `trigger` definition, a downstream pipeline is created. +Use `trigger` to define a downstream pipeline trigger. When GitLab starts a `trigger` job, +a downstream pipeline is created. Jobs with `trigger` can only use a [limited set of keywords](../multi_project_pipelines.md#limitations). For example, you can't run commands with [`script`](#script), [`before_script`](#before_script), @@ -3777,7 +3747,7 @@ upstream_bridge: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16094) in GitLab 12.7. To create a [child pipeline](../parent_child_pipelines.md), specify the path to the -YAML file containing the CI config of the child pipeline: +YAML file that contains the configuration of the child pipeline: ```yaml trigger_job: @@ -3871,10 +3841,10 @@ The trigger token is different than the [`trigger`](#trigger) keyword. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3. -`interruptible` is used to indicate that a running job should be canceled if made redundant by a newer pipeline run. +Use `interruptible` to indicate that a running job should be canceled if made redundant by a newer pipeline run. Defaults to `false` (uninterruptible). Jobs that have not started yet (pending) are considered interruptible and safe to be cancelled. -This value is used only if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-pending-pipelines) +This value is used only if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-redundant-pipelines) is enabled. When enabled, a pipeline is immediately canceled when a new pipeline starts on the same branch if either of the following is true: @@ -3924,11 +3894,11 @@ When an uninterruptible job is running, the pipeline cannot be canceled, regardl Sometimes running multiple jobs or pipelines at the same time in an environment can lead to errors during the deployment. -To avoid these errors, the `resource_group` attribute can be used to ensure that +To avoid these errors, use the `resource_group` attribute to make sure that the runner doesn't run certain jobs simultaneously. Resource groups behave similar to semaphores in other programming languages. -When the `resource_group` key is defined for a job in `.gitlab-ci.yml`, +When the `resource_group` keyword is defined for a job in the `.gitlab-ci.yml` file, job executions are mutually exclusive across different pipelines for the same project. If multiple jobs belonging to the same resource group are enqueued simultaneously, only one of the jobs is picked by the runner. The other jobs wait until the @@ -3960,7 +3930,7 @@ For more information, see [Deployments Safety](../environments/deployment_safety `release` indicates that the job creates a [Release](../../user/project/releases/index.md). -These methods are supported: +These keywords are supported: - [`tag_name`](#releasetag_name) - [`description`](#releasedescription) @@ -3983,7 +3953,7 @@ image: registry.gitlab.com/gitlab-org/release-cli:latest #### Script All jobs except [trigger](#trigger) jobs must have the `script` keyword. A `release` -job can use the output from script commands, but a placeholder script can be used if +job can use the output from script commands, but you can use a placeholder script if the script is not needed: ```yaml @@ -4055,7 +4025,7 @@ description. You can specify a file in `$CI_PROJECT_DIR` that contains the description. The file must be relative to the project directory (`$CI_PROJECT_DIR`), and if the file is a symbolic link it can't reside -outside of `$CI_PROJECT_DIR`. The `./path/to/file` and file name can't contain spaces. +outside of `$CI_PROJECT_DIR`. The `./path/to/file` and filename can't contain spaces. ```yaml job: @@ -4086,7 +4056,7 @@ released_at: '2021-03-15T08:00:00Z' Combining the individual examples given above for `release` results in the following code snippets. There are two options, depending on how you generate the -tags. These options cannot be used together, so choose one: +tags. You can't use these options together, so choose one: - To create a release when you push a Git tag, or when you add a Git tag in the UI by going to **Repository > Tags**: @@ -4226,8 +4196,8 @@ job: ### `pages` -`pages` is a special job that is used to upload static content to GitLab that -can be used to serve your website. It has a special syntax, so the two +`pages` is a special job that uploads static content to GitLab that +is then published as a website. It has a special syntax, so the two requirements below must be met: - Any static content must be placed under a `public/` directory. @@ -4264,7 +4234,8 @@ There are two types of variables. - [Custom variables](../variables/README.md#custom-environment-variables): You can define their values in the `.gitlab-ci.yml` file, in the GitLab UI, - or by using the API. + or by using the API. You can also input variables in the GitLab UI when + [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually). - [Predefined variables](../variables/predefined_variables.md): These values are set by the runner itself. One example is `CI_COMMIT_REF_NAME`, which is the branch or tag the project is built for. @@ -4297,13 +4268,27 @@ meaning it applies to all jobs. If you define a variable in a job, it's availabl to that job only. If a variable of the same name is defined globally and for a specific job, the -[job-specific variable is used](../variables/README.md#priority-of-environment-variables). +[job-specific variable overrides the global variable](../variables/README.md#priority-of-environment-variables). All YAML-defined variables are also set to any linked [Docker service containers](../docker/using_docker_images.md#what-is-a-service). You can use [YAML anchors for variables](#yaml-anchors-for-variables). +### Prefill variables in manual pipelines + +> [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) GitLab 13.7. + +You can use the `value` and `description` keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) +when [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually): + +```yaml +variables: + DEPLOY_ENVIRONMENT: + value: "staging" # Deploy to staging by default + description: "The deployment target. Change this variable to 'canary' or 'production' if needed." +``` + ### Configure runner behavior with variables You can use [CI/CD variables](../variables/README.md) to configure runner Git behavior: @@ -4323,13 +4308,14 @@ You can also use variables to configure how many times a runner It's possible to use special YAML features like anchors (`&`), aliases (`*`) and map merging (`<<`). Use these features to reduce the complexity -of `.gitlab-ci.yml`. +of the code in the `.gitlab-ci.yml` file. Read more about the various [YAML features](https://learnxinyminutes.com/docs/yaml/). In most cases, the [`extends` keyword](#extends) is more user friendly and should -be used over these special YAML features. YAML anchors may still -need to be used to merge arrays. +be used over these special YAML features. + +You can use YAML anchors to merge YAML arrays. ### Anchors @@ -4349,26 +4335,26 @@ The following example uses anchors and map merging. It creates two jobs, with their own custom `script` defined: ```yaml -.job_template: &job_definition # Hidden key that defines an anchor named 'job_definition' +.job_template: &job_configuration # Hidden yaml configuration that defines an anchor named 'job_configuration' image: ruby:2.6 services: - postgres - redis test1: - <<: *job_definition # Merge the contents of the 'job_definition' alias + <<: *job_configuration # Merge the contents of the 'job_configuration' alias script: - test1 project test2: - <<: *job_definition # Merge the contents of the 'job_definition' alias + <<: *job_configuration # Merge the contents of the 'job_configuration' alias script: - test2 project ``` -`&` sets up the name of the anchor (`job_definition`), `<<` means "merge the +`&` sets up the name of the anchor (`job_configuration`), `<<` means "merge the given hash into the current one", and `*` includes the named anchor -(`job_definition` again). The expanded version of the example above is: +(`job_configuration` again). The expanded version of the example above is: ```yaml .job_template: @@ -4399,31 +4385,31 @@ and `test:mysql` share the `script` defined in `.job_template`, but use differen `services`, defined in `.postgres_services` and `.mysql_services`: ```yaml -.job_template: &job_definition +.job_template: &job_configuration script: - test project tags: - dev .postgres_services: - services: &postgres_definition + services: &postgres_configuration - postgres - ruby .mysql_services: - services: &mysql_definition + services: &mysql_configuration - mysql - ruby test:postgres: - <<: *job_definition - services: *postgres_definition + <<: *job_configuration + services: *postgres_configuration tags: - postgres test:mysql: - <<: *job_definition - services: *mysql_definition + <<: *job_configuration + services: *mysql_configuration ``` The expanded version is: @@ -4465,7 +4451,7 @@ test:mysql: ``` You can see that the hidden jobs are conveniently used as templates, and -`tags: [dev]` has been overwritten by `tags: [postgres]`. +`tags: [postgres]` overwrites `tags: [dev]`. #### YAML anchors for scripts @@ -4475,28 +4461,37 @@ You can use [YAML anchors](#anchors) with [script](#script), [`before_script`](# and [`after_script`](#after_script) to use predefined commands in multiple jobs: ```yaml -.some-script: &some-script - - echo "Execute this script in `before_script` sections" - .some-script-before: &some-script-before - - echo "Execute this script in `script` sections" + - echo "Execute this script first" + +.some-script: &some-script + - echo "Execute this script second" + - echo "Execute this script too" .some-script-after: &some-script-after - - echo "Execute this script in `after_script` sections" + - echo "Execute this script last" -job_name: +job1: before_script: - *some-script-before script: - *some-script + - echo "Execute something, for this job only" after_script: - *some-script-after + +job2: + script: + - *some-script-before + - *some-script + - echo "Execute something else, for this job only" + - *some-script-after ``` #### YAML anchors for variables -[YAML anchors](#anchors) can be used with `variables`, to repeat assignment -of variables across multiple jobs. Use can also use YAML anchors when a job +Use [YAML anchors](#anchors) with `variables` to repeat assignment +of variables across multiple jobs. You can also use YAML anchors when a job requires a specific `variables` block that would otherwise override the global variables. In the example below, we override the `GIT_STRATEGY` variable without affecting diff --git a/doc/ci/yaml/gitlab_ci_yaml.md b/doc/ci/yaml/gitlab_ci_yaml.md index e4ede9cf699..765b982dbeb 100644 --- a/doc/ci/yaml/gitlab_ci_yaml.md +++ b/doc/ci/yaml/gitlab_ci_yaml.md @@ -5,7 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- <!-- markdownlint-disable MD044 --> +<!-- vale gitlab.Spelling = NO --> # The .gitlab-ci.yml file +<!-- vale gitlab.Spelling = YES --> <!-- markdownlint-enable MD044 --> To use GitLab CI/CD, you need: diff --git a/doc/customization/branded_login_page.md b/doc/customization/branded_login_page.md deleted file mode 100644 index cf593f360c8..00000000000 --- a/doc/customization/branded_login_page.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/admin_area/appearance.md#sign-in--sign-up-pages' ---- - -This document was moved to [another location](../user/admin_area/appearance.md#sign-in--sign-up-pages). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/branded_page_and_email_header.md b/doc/customization/branded_page_and_email_header.md deleted file mode 100644 index 21a69178b6d..00000000000 --- a/doc/customization/branded_page_and_email_header.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/admin_area/appearance.md#navigation-bar' ---- - -This document was moved to [another location](../user/admin_area/appearance.md#navigation-bar). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/favicon.md b/doc/customization/favicon.md deleted file mode 100644 index 3d6c2f62b25..00000000000 --- a/doc/customization/favicon.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/admin_area/appearance.md#favicon' ---- - -This document was moved to [another location](../user/admin_area/appearance.md#favicon). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/help_message.md b/doc/customization/help_message.md deleted file mode 100644 index 3f13e4efdbd..00000000000 --- a/doc/customization/help_message.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/admin_area/settings/help_page.md' ---- - -This document was moved to [another location](../user/admin_area/settings/help_page.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/index.md b/doc/customization/index.md deleted file mode 100644 index 3c88ad8106b..00000000000 --- a/doc/customization/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/admin_area/appearance.md' ---- - -This document was moved to [another location](../user/admin_area/appearance.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/issue_and_merge_request_template.md b/doc/customization/issue_and_merge_request_template.md deleted file mode 100644 index 0b4ca009080..00000000000 --- a/doc/customization/issue_and_merge_request_template.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/project/description_templates.md' ---- - -This document was moved to [description_templates](../user/project/description_templates.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/issue_closing.md b/doc/customization/issue_closing.md deleted file mode 100644 index c860f51dc2f..00000000000 --- a/doc/customization/issue_closing.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/project/issues/managing_issues.md#closing-issues-automatically' ---- - -This document was moved to [another location](../user/project/issues/managing_issues.md#closing-issues-automatically). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/libravatar.md b/doc/customization/libravatar.md deleted file mode 100644 index affb6211377..00000000000 --- a/doc/customization/libravatar.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../administration/libravatar.md' ---- - -This document was moved to [another location](../administration/libravatar.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/new_project_page.md b/doc/customization/new_project_page.md deleted file mode 100644 index 82549d62960..00000000000 --- a/doc/customization/new_project_page.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/admin_area/appearance.md#new-project-pages' ---- - -This document was moved to [another location](../user/admin_area/appearance.md#new-project-pages). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/system_header_and_footer_messages.md b/doc/customization/system_header_and_footer_messages.md deleted file mode 100644 index 03dccfb35c9..00000000000 --- a/doc/customization/system_header_and_footer_messages.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/admin_area/appearance.md#system-header-and-footer-messages' ---- - -This document was moved to [another location](../user/admin_area/appearance.md#system-header-and-footer-messages). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/welcome_message.md b/doc/customization/welcome_message.md deleted file mode 100644 index cf593f360c8..00000000000 --- a/doc/customization/welcome_message.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/admin_area/appearance.md#sign-in--sign-up-pages' ---- - -This document was moved to [another location](../user/admin_area/appearance.md#sign-in--sign-up-pages). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/README.md b/doc/development/README.md index 0d3c1b3cbe9..d73acdd9dbc 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -151,6 +151,7 @@ In these cases, use the following workflow: ## Backend guides +- [Directory structure](directory_structure.md) - [GitLab utilities](utilities.md) - [Issuable-like Rails models](issuable-like-models.md) - [Logging](logging.md) @@ -229,7 +230,7 @@ See [database guidelines](database/index.md). - [Security Scanners](integrations/secure.md) - [Secure Partner Integration](integrations/secure_partner_integration.md) - [How to run Jenkins in development environment](integrations/jenkins.md) -- [How to run local Codesandbox integration for Web IDE Live Preview](integrations/codesandbox.md) +- [How to run local `Codesandbox` integration for Web IDE Live Preview](integrations/codesandbox.md) ## Testing guides diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md index 7e2add2c91f..f3e23906ac6 100644 --- a/doc/development/adding_service_component.md +++ b/doc/development/adding_service_component.md @@ -65,7 +65,7 @@ Notify the [Distribution team](https://about.gitlab.com/handbook/engineering/dev New services to be bundled with GitLab need to be available in the following environments. -**Dev environment** +**Development environment** The first step of bundling a new service is to provide it in the development environment to engage in collaboration and feedback. diff --git a/doc/development/agent/gitops.md b/doc/development/agent/gitops.md index 8c8586326fa..f183ba86aa1 100644 --- a/doc/development/agent/gitops.md +++ b/doc/development/agent/gitops.md @@ -4,7 +4,7 @@ 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 --- -# GitOps with the Kubernetes Agent **(PREMIUM ONLY)** +# GitOps with the Kubernetes Agent **(PREMIUM SELF)** The [GitLab Kubernetes Agent](../../user/clusters/agent/index.md) supports the [pull-based version](https://www.gitops.tech/#pull-based-deployments) of diff --git a/doc/development/agent/identity.md b/doc/development/agent/identity.md index 884ce015a02..49d20d2fd87 100644 --- a/doc/development/agent/identity.md +++ b/doc/development/agent/identity.md @@ -4,7 +4,7 @@ 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 --- -# Kubernetes Agent identity and authentication **(PREMIUM ONLY)** +# Kubernetes Agent identity and authentication **(PREMIUM SELF)** This page uses the word `agent` to describe the concept of the GitLab Kubernetes Agent. The program that implements the concept is called `agentk`. diff --git a/doc/development/agent/index.md b/doc/development/agent/index.md index 95661c8ddbd..112162f8f90 100644 --- a/doc/development/agent/index.md +++ b/doc/development/agent/index.md @@ -4,7 +4,7 @@ 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 --- -# Kubernetes Agent development **(PREMIUM ONLY)** +# Kubernetes Agent development **(PREMIUM SELF)** This page contains developer-specific information about the GitLab Kubernetes Agent. [End-user documentation about the GitLab Kubernetes Agent](../../user/clusters/agent/index.md) diff --git a/doc/development/agent/local.md b/doc/development/agent/local.md index 47246a6a6d3..603364567bf 100644 --- a/doc/development/agent/local.md +++ b/doc/development/agent/local.md @@ -4,7 +4,7 @@ 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 --- -# Run the Kubernetes Agent locally **(PREMIUM ONLY)** +# Run the Kubernetes Agent locally **(PREMIUM SELF)** You can run `kas` and `agentk` locally to test the [Kubernetes Agent](index.md) yourself. diff --git a/doc/development/agent/repository_overview.md b/doc/development/agent/repository_overview.md new file mode 100644 index 00000000000..b9eea286a3e --- /dev/null +++ b/doc/development/agent/repository_overview.md @@ -0,0 +1,98 @@ +--- +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 +--- + +# Kubernetes Agent repository overview **(PREMIUM SELF)** + +This page describes the subfolders of the Kubernetes Agent repository. +[Development information](index.md) and +[end-user documentation](../../user/clusters/agent/index.md) are both available. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a video overview, see +[GitLab Kubernetes Agent repository overview](https://www.youtube.com/watch?v=j8CyaCWroUY). + +## `build` + +Various files for the build process. + +### `build/deployment` + +A [`kpt`](https://googlecontainertools.github.io/kpt/) package that bundles some +[Kustomize](https://kustomize.io/) layers and components. Can be used as-is, or +to create a custom package to install `agentk`. + +## `cmd` + +Commands are binaries that this repository produces. They are: + +- `kas` is the GitLab Kubernetes Agent Server binary. +- `agentk` is the GitLab Kubernetes Agent binary. + +Each of these directories contain application bootstrap code for: + +- Reading configuration. +- Applying defaults to it. +- Constructing the dependency graph of objects that constitute the program. +- Running it. + +### `cmd/agentk` + +- `agentk` initialization logic. +- Implementation of the agent modules API. + +### `cmd/kas` + +- `kas` initialization logic. +- Implementation of the server modules API. + +## `examples` + +Git submodules for the example projects. + +## `internal` + +The main code of both `gitlab-kas` and `agentk`, and various supporting building blocks. + +### `internal/api` + +Structs that represent some important pieces of data. + +### `internal/gitaly` + +Items to work with [Gitaly](../../administration/gitaly/index.md). + +### `internal/gitlab` + +GitLab REST client. + +### `internal/module` + +Modules that implement server and agent-side functionality. + +### `internal/tool` + +Various building blocks. `internal/tool/testing` contains mocks and helpers +for testing. Mocks are generated with [`gomock`](https://pkg.go.dev/github.com/golang/mock). + +## `it` + +Contains scaffolding for integration tests. Unused at the moment. + +## `pkg` + +Contains exported packages. + +### `pkg/agentcfg` + +Contains protobuf definitions of the `agentk` configuration file. Used to configure +the agent through a configuration repository. + +### `pkg/kascfg` + +Contains protobuf definitions of the `gitlab-kas` configuration file. Contains an +example of that configuration file along with the test for it. The test ensures +the configuration file example is in sync with the protobuf definitions of the +file and defaults, which are applied when the file is loaded. diff --git a/doc/development/agent/routing.md b/doc/development/agent/routing.md index 43cc78ccdfb..9a7d6422d47 100644 --- a/doc/development/agent/routing.md +++ b/doc/development/agent/routing.md @@ -4,7 +4,7 @@ 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 --- -# Routing `kas` requests in the Kubernetes Agent **(PREMIUM ONLY)** +# Routing `kas` requests in the Kubernetes Agent **(PREMIUM SELF)** This document describes how `kas` routes requests to concrete `agentk` instances. GitLab must talk to GitLab Kubernetes Agent Server (`kas`) to: @@ -134,90 +134,97 @@ of the `kas` receiving the request from the _external_ endpoint to retry and re- requests. This method ensures a single central component for each request can determine how a request is routed, rather than distributing the decision across several `kas` instances. -### API definitions +### Reverse gRPC tunnel + +This section explains how the `agentk` -> `kas` reverse gRPC tunnel is implemented. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a video overview of how some of the blocks map to code, see +[GitLab Kubernetes Agent reverse gRPC tunnel architecture and code overview +](https://www.youtube.com/watch?v=9pnQF76hyZc). + +#### High level schema + +In this example, `Server side of module A` exposes its API to get the `Pod` list +on the `Public API gRPC server`. When it receives a request, it must determine +the agent ID from it, then call the proxying code which forwards the request to +a suitable `agentk` that can handle it. + +The `Agent side of module A` exposes the same API on the `Internal gRPC server`. +When it receives the request, it needs to handle it (such as retrieving and returning +the `Pod` list). + +This schema describes how reverse tunneling is handled fully transparently +for modules, so you can add new features: + +```mermaid +graph TB + subgraph kas + server-internal-grpc-server[Internal gRPC server] + server-api-grpc-server[Public API gRPC server] + server-module-a[Server side of module A] + server-module-b[Server side of module B] + end + subgraph agentk + agent-internal-grpc-server[Internal gRPC server] + agent-module-a[Agent side of module A] + agent-module-b[Agent side of module B] + end + + agent-internal-grpc-server -- request --> agent-module-a + agent-internal-grpc-server -- request --> agent-module-b + + server-module-a-. expose API on .-> server-internal-grpc-server + server-module-b-. expose API on .-> server-api-grpc-server + + server-internal-grpc-server -- proxy request --> agent-internal-grpc-server + server-api-grpc-server -- proxy request --> agent-internal-grpc-server +``` + +#### Implementation schema + +`HandleTunnelConnection()` is called with the server-side interface of the reverse +tunnel. It registers the connection and blocks, waiting for a request to proxy +through the connection. + +`HandleIncomingConnection()` is called with the server-side interface of the incoming +connection. It registers the connection and blocks, waiting for a matching tunnel +to proxy the connection through. + +After it has two connections that match, `Connection registry` starts bi-directional +data streaming: -```proto -syntax = "proto3"; - -import "google/protobuf/timestamp.proto"; - -message KasAddress { - string ip = 1; - uint32 port = 2; -} - -message ConnectedAgentInfo { - // Agent id. - int64 id = 1; - // Identifies a particular agentk->kas connection. Randomly generated when agent connects. - int64 connection_id = 2; - string version = 3; - string commit = 4; - // Pod namespace. - string pod_namespace = 5; - // Pod name. - string pod_name = 6; - // When the connection was established. - google.protobuf.Timestamp connected_at = 7; - KasAddress kas_address = 8; - // What else do we need? -} - -message KasInstanceInfo { - string version = 1; - string commit = 2; - KasAddress address = 3; - // What else do we need? -} - -message ConnectedAgentsForProjectRequest { - int64 project_id = 1; -} - -message ConnectedAgentsForProjectResponse { - // There may 0 or more agents with the same id, depending on the number of running Pods. - repeated ConnectedAgentInfo agents = 1; -} - -message ConnectedAgentsByIdRequest { - int64 agent_id = 1; -} - -message ConnectedAgentsByIdResponse { - repeated ConnectedAgentInfo agents = 1; -} - -// API for use by GitLab. -service KasApi { - // Connected agents for a particular configuration project. - rpc ConnectedAgentsForProject (ConnectedAgentsForProjectRequest) returns (ConnectedAgentsForProjectResponse) { - } - // Connected agents for a particular agent id. - rpc ConnectedAgentsById (ConnectedAgentsByIdRequest) returns (ConnectedAgentsByIdResponse) { - } - // Depends on the need, but here is the call from the example above. - rpc GetPods (GetPodsRequest) returns (GetPodsResponse) { - } -} - -message Pod { - string namespace = 1; - string name = 2; -} - -message GetPodsRequest { - int64 agent_id = 1; - int64 connection_id = 2; -} - -message GetPodsResponse { - repeated Pod pods = 1; -} - -// Internal API for use by kas for kas -> kas calls. -service KasInternal { - // Depends on the need, but here is the call from the example above. - rpc GetPods (GetPodsRequest) returns (GetPodsResponse) { - } -} +```mermaid +graph TB + subgraph kas + server-tunnel-module[Server tunnel module] + connection-registry[Connection registry] + server-internal-grpc-server[Internal gRPC server] + server-api-grpc-server[Public API gRPC server] + server-module-a[Server side of module A] + server-module-b[Server side of module B] + end + subgraph agentk + agent-internal-grpc-server[Internal gRPC server] + agent-tunnel-module[Agent tunnel module] + agent-module-a[Agent side of module A] + agent-module-b[Agent side of module B] + end + + server-tunnel-module -- "HandleTunnelConnection()" --> connection-registry + server-internal-grpc-server -- "HandleIncomingConnection()" --> connection-registry + server-api-grpc-server -- "HandleIncomingConnection()" --> connection-registry + server-module-a-. expose API on .-> server-internal-grpc-server + server-module-b-. expose API on .-> server-api-grpc-server + + agent-tunnel-module -- "establish tunnel, receive request" --> server-tunnel-module + agent-tunnel-module -- make request --> agent-internal-grpc-server + agent-internal-grpc-server -- request --> agent-module-a + agent-internal-grpc-server -- request --> agent-module-b ``` + +### API definitions + +- [`agent_tracker/agent_tracker.proto`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/internal/module/agent_tracker/agent_tracker.proto) +- [`agent_tracker/rpc/rpc.proto`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/internal/module/agent_tracker/rpc/rpc.proto) +- [`reverse_tunnel/rpc/rpc.proto`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/internal/module/reverse_tunnel/rpc/rpc.proto) diff --git a/doc/development/agent/user_stories.md b/doc/development/agent/user_stories.md index 2929573ffd3..609be47a3cb 100644 --- a/doc/development/agent/user_stories.md +++ b/doc/development/agent/user_stories.md @@ -4,7 +4,7 @@ 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 --- -# Kubernetes Agent user stories **(PREMIUM ONLY)** +# Kubernetes Agent user stories **(PREMIUM SELF)** The [personas in action](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#user-personas) for the Kubernetes Agent are: diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index d73c3a8d6f6..c0317a7e73e 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -10,7 +10,9 @@ This document outlines the style guide for the GitLab [GraphQL API](../api/graph ## How GitLab implements GraphQL +<!-- vale gitlab.Spelling = NO --> We use the [GraphQL Ruby gem](https://graphql-ruby.org/) written by [Robert Mosolgo](https://github.com/rmosolgo/). +<!-- vale gitlab.Spelling = YES --> All GraphQL queries are directed to a single endpoint ([`app/controllers/graphql_controller.rb#execute`](https://gitlab.com/gitlab-org/gitlab/blob/master/app%2Fcontrollers%2Fgraphql_controller.rb)), @@ -21,6 +23,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 the GitLab [GraphQL API](../api/graphql/index.md) to share his domain specific knowledge with anyone who may work in this part of the codebase in the future. You can find the +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [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). @@ -42,6 +45,32 @@ can be shared. It's also possible to add a `private_token` to the query string, or add a `HTTP_PRIVATE_TOKEN` header. +## Limits + +Several limits apply to the GraphQL API and some of these can be overridden +by developers. + +### Max page size + +By default, [connections](#connection-types) can only return +at most a maximum number of records defined in +[`app/graphql/gitlab_schema.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/gitlab_schema.rb) +per page. + +Developers can [specify a custom max page size](#page-size-limit) when defining +a connection. + +### Max complexity + +Complexity is explained [on our client-facing API page](../api/graphql/index.md#max-query-complexity). + +Fields default to adding `1` to a query's complexity score, but developers can +[specify a custom complexity](#field-complexity) when defining a field. + +### Request timeout + +Requests time out at 30 seconds. + ## Global IDs The GitLab GraphQL API uses Global IDs (i.e: `"gid://gitlab/MyObject/123"`) @@ -281,6 +310,61 @@ Use the functionality the framework provides unless there is a compelling reason For example, instead of `latest_pipeline`, use `pipelines(last: 1)`. +#### Page size limit + +By default, the API returns at most a maximum number of records defined in +[`app/graphql/gitlab_schema.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/gitlab_schema.rb) +per page within a connection and this will also be the default number of records +returned per page if no limiting arguments (`first:` or `last:`) are provided by a client. + +The `max_page_size` argument can be used to specify a different page size limit +for a connection. + +WARNING: +It's better to change the frontend client, or product requirements, to not need large amounts of +records per page than it is to raise the `max_page_size`, as the default is set to ensure +the GraphQL API remains performant. + +For example: + +```ruby +field :tags, + Types::ContainerRepositoryTagType.connection_type, + null: true, + description: 'Tags of the container repository', + max_page_size: 20 +``` + +### Field complexity + +The GitLab GraphQL API uses a _complexity_ score to limit performing overly complex queries. +Complexity is described in [our client documentation](../api/graphql/index.md#max-query-complexity) on the topic. + +Complexity limits are defined in [`app/graphql/gitlab_schema.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/gitlab_schema.rb). + +By default, fields will add `1` to a query's complexity score. This can be overridden by +[providing a custom `complexity`](https://graphql-ruby.org/queries/complexity_and_depth.html) value for a field. + +Developers should specify higher complexity for fields that cause more _work_ to be performed +by the server in order to return data. Fields that represent data that can be returned +with little-to-no _work_, for example in most cases; `id` or `title`, can be given a complexity of `0`. + +### `calls_gitaly` + +Fields that have the potential to perform a [Gitaly](../administration/gitaly/index.md) call when resolving _must_ be marked as +such by passing `calls_gitaly: true` to `field` when defining it. + +For example: + +```ruby +field :blob, type: Types::Snippets::BlobType, + description: 'Snippet blob', + null: false, + calls_gitaly: true +``` + +This will increment the [`complexity` score](#field-complexity) of the field by `1`. + ### Exposing permissions for a type To expose permissions the current user has on a resource, you can call @@ -1599,7 +1683,7 @@ full stack: - An argument or scalar's [`prepare`](#validating-arguments) applies correctly. - Logic in a resolver or mutation's [`#ready?` method](#correct-use-of-resolverready) applies correctly. - An [argument's `default_value`](https://graphql-ruby.org/fields/arguments.html) applies correctly. -- Objects resolve performantly and there are no N+1 issues. +- Objects resolve successfully, and there are no N+1 issues. When adding a query, you can use the `a working graphql query` shared example to test if the query renders valid results. diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index b2c93f16770..dd43281da6d 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -28,7 +28,7 @@ See the [Documentation Style Guide RESTful API page](documentation/restful_api_s ## Methods and parameters description Every method must be described using the [Grape DSL](https://github.com/ruby-grape/grape#describing-methods) -(see <https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/environments.rb> +(see [`environments.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/environments.rb) for a good example): - `desc` for the method summary. You should pass it a block for additional diff --git a/doc/development/approval_rules.md b/doc/development/approval_rules.md index 542bce1cb97..eae221c6598 100644 --- a/doc/development/approval_rules.md +++ b/doc/development/approval_rules.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Approval Rules **(STARTER)** +# Approval Rules development guide This document explains the backend design and flow of all related functionality about [merge request approval rules](../user/project/merge_requests/merge_request_approvals.md). @@ -44,8 +44,8 @@ erDiagram ### `Project` and `MergeRequest` `Project` and `MergeRequest` models are defined in `ee/app/models/ee/project.rb` -and `ee/app/models/ee/merge_request.rb`. They extend the non-EE versions since -approval rules is an EE only feature. Associations and other related stuff to +and `ee/app/models/ee/merge_request.rb`. They extend the non-EE versions, because +approval rules are an EE-only feature. Associations and other related stuff to merge request approvals are defined here. ### `ApprovalState` @@ -265,8 +265,8 @@ graph LR ApprovalWrappedRule --> Approval ``` -This flow gets initiated by the frontend component. The data returned will -then be used to display information on the MR widget. +This flow gets initiated by the frontend component. The data returned is +used to display information on the MR widget. ### Approving a merge request @@ -282,5 +282,5 @@ is executed instead. ## TODO -1. Add information related to other rule types (e.g. `code_owner` and `report_approver`). +1. Add information related to other rule types, such as `code_owner` and `report_approver`. 1. Add information about side effects of approving/unapproving merge request. diff --git a/doc/development/architecture.md b/doc/development/architecture.md index f8ab97de848..3aab57d8e15 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -91,6 +91,8 @@ The simplest way to ensure this, is to add support for your feature or service t [the official GitLab Helm chart](https://docs.gitlab.com/charts/) or reach out to [the Distribution team](https://about.gitlab.com/handbook/engineering/development/enablement/distribution/#how-to-work-with-distribution). +Refer to the [process for adding new service components](adding_service_component.md) for more details. + ### Simplified component overview This is a simplified architecture diagram that can be used to @@ -934,7 +936,7 @@ ps aux | grep '^git' ``` GitLab has several components to operate. It requires a persistent database -(PostgreSQL) and Redis database, and uses Apache `httpd` or NGINX to proxypass +(PostgreSQL) and Redis database, and uses Apache `httpd` or NGINX to `proxypass` Puma. All these components should run as different system users to GitLab (for example, `postgres`, `redis`, and `www-data`, instead of `git`). diff --git a/doc/development/auto_devops.md b/doc/development/auto_devops.md index c457573b87a..6b54de55738 100644 --- a/doc/development/auto_devops.md +++ b/doc/development/auto_devops.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Auto DevOps development guide +# Auto DevOps development guide **(CORE)** This document provides a development guide for contributors to [Auto DevOps](../topics/autodevops/index.md). diff --git a/doc/development/changelog.md b/doc/development/changelog.md index 8fad32ed163..88a0cf8dff0 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -45,7 +45,7 @@ the `author` field. GitLab team members **should not**. **must** have a changelog entry, without `merge_request` value and with `type` set to `security`. - Any user-facing change **must** have a changelog entry. This includes both visual changes (regardless of how minor), and changes to the rendered DOM which impact how a screen reader may announce the content. -- Any client-facing change to our REST and GraphQL APIs **must** have a changelog entry. +- Any client-facing change to our REST and GraphQL APIs **must** have a changelog entry. This includes modifying complexity of GraphQL fields. - Performance improvements **should** have a changelog entry. - Changes that need to be documented in the Product Intelligence [Event Dictionary](https://about.gitlab.com/handbook/product/product-intelligence-guide/#event-dictionary) also require a changelog entry. diff --git a/doc/development/chaos_endpoints.md b/doc/development/chaos_endpoints.md index 9104c01c980..85c93f521ac 100644 --- a/doc/development/chaos_endpoints.md +++ b/doc/development/chaos_endpoints.md @@ -6,8 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Generating chaos in a test GitLab instance +<!-- vale gitlab.Spelling = NO --> + As [Werner Vogels](https://twitter.com/Werner), the CTO at Amazon Web Services, famously put it, **Everything fails, all the time**. +<!-- vale gitlab.Spelling = NO --> + As a developer, it's as important to consider the failure modes in which your software may operate as much as normal operation. Doing so can mean the difference between a minor hiccup leading to a scattering of `500` errors experienced by a tiny fraction of users, and a full site outage that affects all users for an extended period. To paraphrase [Tolstoy](https://en.wikipedia.org/wiki/Anna_Karenina_principle), _all happy servers are alike, but all failing servers are failing in their own way_. Luckily, there are ways we can attempt to simulate these failure modes, and the chaos endpoints are tools for assisting in this process. @@ -160,3 +164,58 @@ GET /-/chaos/kill?async=true curl "http://localhost:3000/-/chaos/kill" --header 'X-Chaos-Secret: secret' curl "http://localhost:3000/-/chaos/kill?token=secret" ``` + +## Run garbage collector + +This endpoint triggers a GC run on the worker handling the request and returns its worker ID +plus GC stats as JSON. This is mostly useful when running Puma in standalone mode, since +otherwise the worker handling the request will not be known upfront. + +Endpoint: + +```plaintext +POST /-/chaos/gc +``` + +Example request: + +```shell +curl --request POST "http://localhost:3000/-/chaos/gc" --header 'X-Chaos-Secret: secret' +curl --request POST "http://localhost:3000/-/chaos/gc?token=secret" +``` + +Example response: + +```json +{ + "worker_id": "puma_1", + "gc_stat": { + "count": 94, + "heap_allocated_pages": 9077, + "heap_sorted_length": 9077, + "heap_allocatable_pages": 0, + "heap_available_slots": 3699720, + "heap_live_slots": 2827510, + "heap_free_slots": 872210, + "heap_final_slots": 0, + "heap_marked_slots": 2827509, + "heap_eden_pages": 9077, + "heap_tomb_pages": 0, + "total_allocated_pages": 9077, + "total_freed_pages": 0, + "total_allocated_objects": 14229357, + "total_freed_objects": 11401847, + "malloc_increase_bytes": 8192, + "malloc_increase_bytes_limit": 30949538, + "minor_gc_count": 71, + "major_gc_count": 23, + "compact_count": 0, + "remembered_wb_unprotected_objects": 41685, + "remembered_wb_unprotected_objects_limit": 83370, + "old_objects": 2617806, + "old_objects_limit": 5235612, + "oldmalloc_increase_bytes": 8192, + "oldmalloc_increase_bytes_limit": 122713697 + } +} +``` diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index eede1d691a9..d79d681263d 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -143,3 +143,25 @@ Finally if the runner can only pick jobs that are tagged, all untagged jobs are 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. + +## The definition of "Job" in GitLab CI/CD + +"Job" in GitLab CI context refers a task to drive Continuous Integration, Delivery and Deployment. +Typically, a pipeline contains multiple stages, and a stage contains multiple jobs. + +In Active Record modeling, Job is defined as `CommitStatus` class. +On top of that, we have the following types of jobs: + +- `Ci::Build` ... The job to be executed by runners. +- `Ci::Bridge` ... The job to trigger a downstream pipeline. +- `GenericCommitStatus` ... The job to be executed in an external CI/CD system e.g. Jenkins. + +Please note that, when you use the "Job" terminology in codebase, readers would +assume that the class/object is any type of above. +If you specifically refer `Ci::Build` class, you should not name the object/class +as "job" as this could cause some confusions. In documentation, +we should use "Job" in general, instead of "Build". + +We have a few inconsistencies in our codebase that should be refactored. +For example, `CommitStatus` should be `Ci::Job` and `Ci::JobArtifact` should be `Ci::BuildArtifact`. +See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/16111) for the full refactoring plan. diff --git a/doc/development/code_intelligence/index.md b/doc/development/code_intelligence/index.md index c5673f6eee2..02f701645f4 100644 --- a/doc/development/code_intelligence/index.md +++ b/doc/development/code_intelligence/index.md @@ -45,7 +45,7 @@ sequenceDiagram GitLab Rails to authorize the upload. 1. GitLab Rails validates whether the artifact can be uploaded and sends - `ProcessLsif: true` header if the lsif artifact can be processed. + `ProcessLsif: true` header if the LSIF artifact can be processed. 1. Workhorse reads the LSIF document line by line and generates code intelligence data for each file in the project. The output is a zipped directory of JSON diff --git a/doc/development/code_review.md b/doc/development/code_review.md index fe395dc2304..d856541bd91 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -24,7 +24,7 @@ uncovered edge cases. The default approach is to choose a reviewer from your group or team for the first review. This is only a recommendation and the reviewer may be from a different team. However, it is recommended to pick someone who is a [domain expert](#domain-experts). -If your merge request touches more than one domain (for example, Dynamic Analysis and GraphQL), ask for reviews from an expert from each domain. +If your merge request touches more than one domain (for example, Dynamic Analysis and GraphQL), ask for reviews from an expert from each domain. You can read more about the importance of involving reviewer(s) in the section on the responsibility of the author below. @@ -107,11 +107,11 @@ with [domain expertise](#domain-experts). be **approved by a [frontend foundations member](https://about.gitlab.com/direction/create/ecosystem/frontend-ux-foundations/)**. - If the license used by the new library hasn't been approved for use in GitLab, the license must be **approved by a [legal department member](https://about.gitlab.com/handbook/legal/)**. - More information about license compatiblity can be found in our + More information about license compatibility can be found in our [GitLab Licensing and Compatibility documentation](licensing.md). 1. If your merge request includes adding a new UI/UX paradigm (*1*), it must be **approved by a [UX lead](https://about.gitlab.com/company/team/)**. -1. If your merge request includes a new dependency or a filesystem change, it must be +1. If your merge request includes a new dependency or a file system change, it must be **approved by a [Distribution team member](https://about.gitlab.com/company/team/)**. See how to work with the [Distribution team](https://about.gitlab.com/handbook/engineering/development/enablement/distribution/#how-to-work-with-distribution) for more details. 1. If your merge request includes documentation changes, it must be **approved by a [Technical writer](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments)**, based on @@ -121,6 +121,8 @@ with [domain expertise](#domain-experts). 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. If your merge request includes Product Intelligence (telemetry or analytics) changes, it should be reviewed and approved by a [Product Intelligence engineer](https://gitlab.com/gitlab-org/growth/product_intelligence/engineers). +1. If your merge request includes an addition of, or changes to a [Feature spec](testing_guide/testing_levels.md#frontend-feature-tests), it must be **approved by a [Quality maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_maintainers_qa) or [Quality reviewer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_reviewers_qa)**. +1. If your merge request introduces a new service to GitLab (Puma, Sidekiq, Gitaly are examples), it must be **approved by a [product manager](https://about.gitlab.com/company/team/)**. See the [process for adding a service component to GitLab](adding_service_component.md) for details. - (*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 @@ -177,8 +179,11 @@ warrant a comment could be: Avoid: -- Adding comments (referenced above, or TODO items) directly to the source code unless the reviewer requires you to do so. If the comments are added due to an actionable task, -a link to an issue must be included. +- Adding TODO comments (referenced above) directly to the source code unless the reviewer requires + you to do so. If TODO comments are added due to an actionable task, + [include a link to the relevant issue](code_comments.md). +- Adding comments which only explain what the code is doing. If non-TODO comments are added, they should + [_explain why, not what_](https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/). - Assigning merge requests with failed tests to maintainers. If the tests are failing and you have to assign, ensure you leave a comment with an explanation. - Excessively mentioning maintainers through email or Slack (if the maintainer is reachable through Slack). If you can't assign a merge request, `@` mentioning a maintainer in a comment is acceptable and in all other cases assigning the merge request is sufficient. @@ -340,7 +345,7 @@ experience, refactors the existing code). Then: convey your intent. - For non-mandatory suggestions, decorate with (non-blocking) so the author knows they can optionally resolve within the merge request or follow-up at a later stage. - - There's a [Chrome/Firefox addon](https://gitlab.com/conventionalcomments/conventional-comments-button) which you can use to apply [Conventional Comment](https://conventionalcomments.org/) prefixes. + - There's a [Chrome/Firefox add-on](https://gitlab.com/conventionalcomments/conventional-comments-button) which you can use to apply [Conventional Comment](https://conventionalcomments.org/) prefixes. - After a round of line notes, it can be helpful to post a summary note such as "Looks good to me", or "Just a couple things to address." - Assign the merge request to the author if changes are required following your @@ -565,7 +570,7 @@ A good example of collaboration on an MR touching multiple parts of the codebase ### Credits -Largely based on the [thoughtbot code review guide](https://github.com/thoughtbot/guides/tree/master/code-review). +Largely based on the [`thoughtbot` code review guide](https://github.com/thoughtbot/guides/tree/master/code-review). --- diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 7859af4e88b..5c8068fdee7 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -212,7 +212,7 @@ the contribution acceptance criteria below: 1. Changes do not degrade performance: - Avoid repeated polling of endpoints that require a significant amount of overhead. - Check for N+1 queries via the SQL log or [`QueryRecorder`](../merge_request_performance_guidelines.md). - - Avoid repeated access of the filesystem. + - Avoid repeated access of the file system. - Use [polling with ETag caching](../polling.md) if needed to support real-time features. 1. If the merge request adds any new libraries (gems, JavaScript libraries, etc.), they should conform to our [Licensing guidelines](../licensing.md). See those diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index c316d50c88c..2a2cfebe964 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -15,52 +15,83 @@ settings automatically by default. If your editor/IDE does not automatically sup we suggest investigating to see if a plugin exists. For instance here is the [plugin for vim](https://github.com/editorconfig/editorconfig-vim). -## Pre-push static analysis +## Pre-push static analysis with Lefthook -We strongly recommend installing [Lefthook](https://github.com/Arkweid/lefthook) to automatically check -for static analysis offenses before pushing your changes. +[Lefthook](https://github.com/Arkweid/lefthook) is a Git hooks manager that allows +custom logic to be executed prior to Git committing or pushing. GitLab comes with +Lefthook configuration (`lefthook.yml`), but it must be installed. -To install `lefthook`, run the following in your GitLab source directory: +We have a `lefthook.yml` checked in but it is ignored until Lefthook is installed. -```shell -# 1. Make sure to uninstall Overcommit first -overcommit --uninstall +### Uninstall Overcommit + +We were using Overcommit prior to Lefthook, so you may want to uninstall it first with `overcommit --uninstall`. + +### Install Lefthook + +1. Install the `lefthook` Ruby gem: + + ```shell + bundle install + ``` + +1. Install Lefthook managed Git hooks: + + ```shell + bundle exec lefthook install + ``` + +1. Test Lefthook is working by running the Lefthook `prepare-commit-msg` Git hook: + + ```shell + bundle exec lefthook run prepare-commit-msg + ``` + +This should return a fully qualified path command with no other output. + +### Lefthook configuration -# If using rbenv, at this point you may need to do: rbenv rehash +The current Lefthook configuration can be found in [`lefthook.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lefthook.yml). -# 2. Install lefthook... +Before you push your changes, Lefthook automatically runs the following checks: -## With Homebrew (macOS) -brew install Arkweid/lefthook/lefthook +- Danger: Runs a subset of checks that `danger-review` runs on your merge requests. +- ES lint: Run `yarn eslint` checks (with the [`.eslintrc.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.eslintrc.yml) configuration) on the modified `*.{js,vue}` files. Tags: `frontend`, `style`. +- HAML lint: Run `bundle exec haml-lint` checks (with the [`.haml-lint.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.haml-lint.yml) configuration) on the modified `*.html.haml` files. Tags: `view`, `haml`, `style`. +- Markdown lint: Run `yarn markdownlint` checks on the modified `*.md` files. Tags: `documentation`, `style`. +- SCSS lint: Run `bundle exec scss-lint` checks (with the [`.scss-lint.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.scss-lint.yml) configuration) on the modified `*.scss{,.css}` files. Tags: `stylesheet`, `css`, `style`. +- RuboCop: Run `bundle exec rubocop` checks (with the [`.rubocop.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.rubocop.yml) configuration) on the modified `*.rb` files. Tags: `backend`, `style`. +- Vale: Run `vale` checks (with the [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.vale.ini) configuration) on the modified `*.md` files. Tags: `documentation`, `style`. -## Or with Go -go get github.com/Arkweid/lefthook +In addition to the default configuration, you can define a [local configuration](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#local-config). -## Or with Rubygems -gem install lefthook +### Disable Lefthook temporarily -### You may need to run the following if you're using rbenv -rbenv rehash +To disable Lefthook temporarily, you can set the `LEFTHOOK` environment variable to `0`. For instance: -# 3. Install the Git hooks -lefthook install -f +```shell +LEFTHOOK=0 git push ... ``` -Before you push your changes, Lefthook then automatically run Danger checks, and other checks -for changed files. This saves you time as you don't have to wait for the same errors to be detected -by CI/CD. +### Run Lefthook hooks manually + +To run the `pre-push` Git hook, run: + +```shell +bundle exec lefthook run pre-push +``` -Lefthook relies on a pre-push hook to prevent commits that violate its ruleset. -To override this behavior, pass the environment variable `LEFTHOOK=0`. That is, -`LEFTHOOK=0 git push`. +For more information, check out [Lefthook documentation](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#run-githook-group-directly). -You can also: +### Skip Lefthook checks per tag -- Define [local configuration](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#local-config). -- Skip [checks per tag on the fly](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#skip-some-tags-on-the-fly). - For example, `LEFTHOOK_EXCLUDE=frontend git push origin`. -- Run [hooks manually](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#run-githook-group-directly). - For example, `lefthook run pre-push`. +To skip some checks based on tags when pushing, you can set the `LEFTHOOK_EXCLUDE` environment variable. For instance: + +```shell +LEFTHOOK_EXCLUDE=frontend,documentation git push ... +``` + +For more information, check out [Lefthook documentation](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#skip-some-tags-on-the-fly). ## Ruby, Rails, RSpec @@ -111,7 +142,7 @@ This ensures that our list isn't mistakenly removed by another auto generation o the `.rubocop_todo.yml`. This also allows us greater visibility into the exceptions which are currently being resolved. -One way to generate the initial list is to run the todo auto generation, +One way to generate the initial list is to run the `todo` auto generation, with `exclude limit` set to a high number. ```shell @@ -149,8 +180,12 @@ See the dedicated [Shell scripting standards and style guidelines](../shell_scri ## Markdown +<!-- vale gitlab.Spelling = NO --> + We're following [Ciro Santilli's Markdown Style Guide](https://cirosantilli.com/markdown-style-guide/). +<!-- vale gitlab.Spelling = YES --> + ## Documentation See the dedicated [Documentation Style Guide](../documentation/styleguide/index.md). diff --git a/doc/development/cycle_analytics.md b/doc/development/cycle_analytics.md deleted file mode 100644 index 1619f3dcb10..00000000000 --- a/doc/development/cycle_analytics.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'value_stream_analytics.md' ---- - -This document was moved to [another location](value_stream_analytics.md) - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/dangerbot.md b/doc/development/dangerbot.md index 59b31437161..413c0a31eec 100644 --- a/doc/development/dangerbot.md +++ b/doc/development/dangerbot.md @@ -105,9 +105,9 @@ minimize the number of lines of code in `danger/`. A non-trivial `Dangerfile` should mostly call plugin code with arguments derived from the methods provided by Danger. The plugin code itself should have unit tests. -At present, we do this by putting the code in a module in `lib/gitlab/danger/...`, +At present, we do this by putting the code in a module in `tooling/danger/...`, and including it in the matching `danger/plugins/...` file. Specs can then be -added in `spec/lib/gitlab/danger/...`. +added in `spec/tooling/danger/...`. To determine if your `Dangerfile` works, push the branch that contains it to GitLab. This can be quite frustrating, as it significantly increases the cycle diff --git a/doc/development/database/database_reviewer_guidelines.md b/doc/development/database/database_reviewer_guidelines.md index 26083183d6d..a242a3d5fd0 100644 --- a/doc/development/database/database_reviewer_guidelines.md +++ b/doc/development/database/database_reviewer_guidelines.md @@ -50,17 +50,17 @@ European/US and APAC friendly hours. You can join the office hours call and brin that require a more in-depth discussion between the database reviewers and maintainers: - [Database Office Hours Agenda](https://docs.google.com/document/d/1wgfmVL30F8SdMg-9yY6Y8djPSxWNvKmhR5XmsvYX1EI/edit). -- [Youtube playlist with past recordings](https://www.youtube.com/playlist?list=PL05JrBw4t0Kp-kqXeiF7fF7cFYaKtdqXM). +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [YouTube playlist with past recordings](https://www.youtube.com/playlist?list=PL05JrBw4t0Kp-kqXeiF7fF7cFYaKtdqXM). You should also join the [#database-labs](../understanding_explain_plans.md#database-lab) -Slack channel and get familiar with how to use Joe, the slackbot that provides developers +Slack channel and get familiar with how to use Joe, the Slackbot that provides developers with their own clone of the production database. Understanding and efficiently using `EXPLAIN` plans is at the core of the database review process. The following guides provide a quick introduction and links to follow on more advanced topics: - Guide on [understanding EXPLAIN plans](../understanding_explain_plans.md). -- [Explaining the unexplainable series in depesz](https://www.depesz.com/tag/unexplainable/). +- [Explaining the unexplainable series in `depesz`](https://www.depesz.com/tag/unexplainable/). Finally, you can find various guides in the [Database guides](index.md) page that cover more specific topics and use cases. The most frequently required during database reviewing are the following: 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 33a0fd2ebb7..f338520c6ca 100644 --- a/doc/development/database/strings_and_the_text_data_type.md +++ b/doc/development/database/strings_and_the_text_data_type.md @@ -34,6 +34,12 @@ but only for updating the declaration of the columns. We can then validate it at `VALIDATE CONSTRAINT`, which requires only a `SHARE UPDATE EXCLUSIVE LOCK` (only conflicts with other validations and index creation while it allows reads and writes). +### Exceptions + +Text columns used by `attr_encrypted` are not required to have a limit, because the length of the +text after encryption may be longer than the text itself. Instead, you can use an Active Record +length validation on the attribute. + ## Create a new table with text columns When adding a new table, the limits for all text columns should be added in the same migration as diff --git a/doc/development/database/table_partitioning.md b/doc/development/database/table_partitioning.md index 358b9bb42b0..207d5a733ce 100644 --- a/doc/development/database/table_partitioning.md +++ b/doc/development/database/table_partitioning.md @@ -60,7 +60,7 @@ was the first table to be partitioned in the application database (scheduled for deployment with the GitLab 13.5 release). This table tracks audit entries of security events that happen in the application. In almost all cases, users want to see audit activity that -occurs in a certain timeframe. As a result, date-range partitioning +occurs in a certain time frame. As a result, date-range partitioning was a natural fit for how the data would be accessed. To look at this in more detail, imagine a simplified `audit_events` schema: diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md index f4558189000..dc64b59018b 100644 --- a/doc/development/database_debugging.md +++ b/doc/development/database_debugging.md @@ -69,16 +69,14 @@ bundle exec rails db -e development Use these instructions for exploring the GitLab database while developing with the GDK: 1. Install or open [Visual Studio Code](https://code.visualstudio.com/download). -1. Install the [PostgreSQL VSCode Extension](https://marketplace.visualstudio.com/items?itemName=ckolkman.vscode-postgres) by Chris Kolkman. +1. Install the [PostgreSQL VSCode Extension](https://marketplace.visualstudio.com/items?itemName=ckolkman.vscode-postgres). 1. In Visual Studio Code click on the PostgreSQL Explorer button in the left toolbar. 1. In the top bar of the new window, click on the `+` to **Add Database Connection**, and follow the prompts to fill in the details: 1. **Hostname**: the path to the PostgreSQL folder in your GDK directory (for example `/dev/gitlab-development-kit/postgresql`). 1. **PostgreSQL user to authenticate as**: usually your local username, unless otherwise specified during PostgreSQL installation. 1. **Password of the PostgreSQL user**: the password you set when installing PostgreSQL. 1. **Port number to connect to**: `5432` (default). - 1. <!-- vale gitlab.Spelling = NO --> - **Use an ssl connection?** - <!-- vale gitlab.Spelling = YES --> This depends on your installation. Options are: + 1. **Use an SSL connection?** 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/database_review.md b/doc/development/database_review.md index da2c93cc1fd..cc4acba100b 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -147,7 +147,7 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac - Provide the link to the plan at: [explain.depesz.com](https://explain.depesz.com). Paste both the plan and the query used in the form. - When providing query plans, make sure it hits enough data: - You can use a GitLab production replica to test your queries on a large scale, - through the `#database-lab` Slack channel or through [chatops](understanding_explain_plans.md#chatops). + through the `#database-lab` Slack channel or through [ChatOps](understanding_explain_plans.md#chatops). - Usually, the `gitlab-org` namespace (`namespace_id = 9970`) and the `gitlab-org/gitlab-foss` (`project_id = 13083`) or the `gitlab-org/gitlab` (`project_id = 278964`) projects provide enough data to serve as a good example. @@ -220,13 +220,13 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac - Check for any obviously complex queries and queries the author specifically points out for review (if any) - If not present yet, ask the author to provide SQL queries and query plans - (for example, by using [chatops](understanding_explain_plans.md#chatops) or direct + (for example, by using [ChatOps](understanding_explain_plans.md#chatops) or direct database access) - For given queries, review parameters regarding data distribution - [Check query plans](understanding_explain_plans.md) and suggest improvements to queries (changing the query, schema or adding indexes and similar) - General guideline is for queries to come in below [100ms execution time](query_performance.md#timing-guidelines-for-queries) - - Avoid N+1 problems and minimalize the [query count](merge_request_performance_guidelines.md#query-counts). + - Avoid N+1 problems and minimize the [query count](merge_request_performance_guidelines.md#query-counts). ### Timing guidelines for migrations diff --git a/doc/development/diffs.md b/doc/development/diffs.md index fba8eda0408..52ba89a4d6e 100644 --- a/doc/development/diffs.md +++ b/doc/development/diffs.md @@ -14,12 +14,20 @@ We rely on different sources to present diffs. These include: ## Deep Dive +<!-- vale gitlab.Spelling = NO --> + In January 2019, Oswaldo Ferreira hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) on GitLab Diffs and Commenting on Diffs -functionality to share his domain specific knowledge 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=K6G3gMcFyek), -and the slides on [Google Slides](https://docs.google.com/presentation/d/1bGutFH2AT3bxOPZuLMGl1ANWHqFnrxwQwjiwAZkF-TU/edit) -and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/b5ad2f336e0afcfe0f99db0af0ccc71a/). +functionality to share domain-specific knowledge with anyone who may work in this part of the +codebase in the future: + +<!-- vale gitlab.Spelling = YES --> + +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> + [Recording on YouTube](https://www.youtube.com/watch?v=K6G3gMcFyek) +- Slides on [Google Slides](https://docs.google.com/presentation/d/1bGutFH2AT3bxOPZuLMGl1ANWHqFnrxwQwjiwAZkF-TU/edit) +- [PDF slides](https://gitlab.com/gitlab-org/create-stage/uploads/b5ad2f336e0afcfe0f99db0af0ccc71a/) + Everything covered in this deep dive was accurate as of GitLab 11.7, and while specific details may have changed since then, it should still serve as a good introduction. @@ -125,7 +133,7 @@ Gitaly only returns `Diff.Collapsed` (RPC) when surpassing collection limits. #### Not expandable patches (too large) The patch not be rendered if it's larger than `ApplicationSettings#diff_max_patch_bytes`. -Users see a `This source diff could not be displayed because it is too large` message. +Users see a `Changes are too large to be shown.` message and a button to view only that file in that commit. ```ruby Commit::DIFF_SAFE_LINES = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 @@ -180,8 +188,8 @@ has been introduced. One of the key challenges to deal with when working on merge ref diffs are merge conflicts. If the target and source branch contains a merge conflict, the branches -cannot be automatically merged. The [recording on -YouTube](https://www.youtube.com/watch?v=GFXIFA4ZuZw&feature=youtu.be&ab_channel=GitLabUnfiltered) +cannot be automatically merged. The +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [recording on YouTube](https://www.youtube.com/watch?v=GFXIFA4ZuZw&feature=youtu.be&ab_channel=GitLabUnfiltered) is a quick introduction to the problem and the motivation behind the [epic](https://gitlab.com/groups/gitlab-org/-/epics/854). In 13.5 a solution for both-modified merge diff --git a/doc/development/directory_structure.md b/doc/development/directory_structure.md new file mode 100644 index 00000000000..c2329feb941 --- /dev/null +++ b/doc/development/directory_structure.md @@ -0,0 +1,36 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Backend directory structure + +## Use namespaces to define bounded contexts + +A healthy application is divided into macro and sub components that represent the contexts at play, +whether they are related to business domain or infrastructure code. + +As GitLab code has so many features and components it's hard to see what contexts are involved. +We should expect any class to be defined inside a module/namespace that represents the contexts where it operates. + +When we namespace classes inside their domain: + +- Similar terminology becomes unambiguous as the domain clarifies the meaning: + For example, `MergeRequests::Diff` and `Notes::Diff`. +- Top-level namespaces could be associated to one or more groups identified as domain experts. +- We can better identify the interactions and coupling between components. + For example, several classes inside `MergeRequests::` domain interact more with `Ci::` + domain and less with `ImportExport::`. + +```ruby +# bad +class MyClass +end + +# good +module MyDomain + class MyClass + end +end +``` diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md index 9228609aae9..eb20e721e46 100644 --- a/doc/development/distributed_tracing.md +++ b/doc/development/distributed_tracing.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Distributed Tracing - development guidelines +# Distributed Tracing - development guidelines **(FREE)** GitLab is instrumented for distributed tracing. Distributed Tracing in GitLab is currently considered **experimental**, as it has not yet been tested at scale on GitLab.com. diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md deleted file mode 100644 index 1595a841ade..00000000000 --- a/doc/development/doc_styleguide.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'documentation/styleguide.md' ---- - -This document was moved to [another location](documentation/styleguide.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md deleted file mode 100644 index 78e5510ffca..00000000000 --- a/doc/development/documentation/feature-change-workflow.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'workflow.md' ---- - -This document was moved to [another location](workflow.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 7547ec59fb2..6aa1aed0236 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -30,7 +30,7 @@ See how to document them below, according to the state of the flag: - [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). -The [`**(CORE ONLY)**`](styleguide/index.md#product-tier-badges) badge or equivalent for +The [`**(FREE SELF)**`](styleguide/index.md#product-tier-badges) badge or equivalent for the feature's tier should be added to the line and heading that refers to enabling/disabling feature flags as Admin access is required to do so, therefore, it indicates that it cannot be done by regular users of GitLab.com. @@ -61,7 +61,7 @@ be enabled for a single project, and is not ready for production use: > - 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 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)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#anchor-to-section). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -70,7 +70,7 @@ This feature might not be available to you. Check the **version history** note a <!-- Add this at the end of the file --> -### Enable or disable <Feature Name> **(CORE ONLY)** +### Enable or disable <Feature Name> **(FREE SELF)** <Feature Name> is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default**. @@ -91,7 +91,7 @@ Feature.disable(:<feature flag>) ```` Adjust the blurb according to the state of the feature you're documenting. -Replace `<Feature name>`, `**(CORE ONLY)**`, `<feature flag>`, and +Replace `<Feature name>`, `**(FREE SELF)**`, `<feature flag>`, and `<replace with path to>`, and `#anchor-to-section` accordingly. ### Features that became enabled by default @@ -120,7 +120,7 @@ use: > - [Became enabled by default](link-to-issue) on GitLab 12.1. > - It's enabled on GitLab.com. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -129,7 +129,7 @@ This feature might not be available to you. Check the **version history** note a <!-- Add this at the end of the file --> -### Enable or disable <Feature Name> **(CORE ONLY)** +### Enable or disable <Feature Name> **(FREE SELF)** <Feature Name> is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. @@ -150,7 +150,7 @@ 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 `<Feature name>`, `**(FREE SELF)**`, `<feature flag>`, `<replace with path to>`, and `#anchor-to-section` accordingly. ### Features directly enabled by default @@ -176,7 +176,7 @@ cannot be enabled for a single project, and is ready for production use: > - 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 recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -185,7 +185,7 @@ This feature might not be available to you. Check the **version history** note a <!-- Add this at the end of the file --> -### Enable or disable <Feature Name> **(CORE ONLY)** +### Enable or disable <Feature Name> **(FREE SELF)** <Feature Name> is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. @@ -206,7 +206,7 @@ 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 `<Feature name>`, `**(FREE SELF)**`, `<feature flag>`, `<replace with path to>`, and `#anchor-to-section` accordingly. ### Features enabled by project @@ -249,7 +249,7 @@ be enabled by project, and is ready for production use: > - It's enabled on GitLab.com. > - It can be enabled or disabled 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)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -258,7 +258,7 @@ This feature might not be available to you. Check the **version history** note a <!-- Add this at the end of the file --> -### Enable or disable <Feature Name> **(CORE ONLY)** +### Enable or disable <Feature Name> **(FREE SELF)** <Feature Name> is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. @@ -285,7 +285,7 @@ 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 `<Feature name>`, `**(FREE SELF)**`, `<feature flag>`, `<replace with path to>`, and `#anchor-to-section` accordingly. ### Features with flag removed diff --git a/doc/development/documentation/improvement-workflow.md b/doc/development/documentation/improvement-workflow.md deleted file mode 100644 index 78e5510ffca..00000000000 --- a/doc/development/documentation/improvement-workflow.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'workflow.md' ---- - -This document was moved to [another location](workflow.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 55f5d43b175..2d865ec3a7e 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -12,7 +12,7 @@ The GitLab documentation is [intended as the single source of truth (SSOT)](http In addition to this page, the following resources can help you craft and contribute to documentation: - [Style Guide](styleguide/index.md) - What belongs in the docs, language guidelines, Markdown standards to follow, links, and more. -- [Structure and template](structure.md) - Learn the typical parts of a doc page and how to write each one. +- [Topic type template](structure.md) - Learn about the different types of topics. - [Documentation process](workflow.md). - [Markdown Guide](../../user/markdown.md) - A reference for all Markdown syntax supported by GitLab. - [Site architecture](site_architecture/index.md) - How <https://docs.gitlab.com> is built. @@ -514,7 +514,7 @@ 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 information: [`pngquant`](https://pngquant.org/) +1. Install `pngquant`, see the tool website for more information: [`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. diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index c8c48e71b48..e05f6760ff1 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -165,7 +165,7 @@ curl --request POST \ ### Post data using form-data -Instead of using JSON or urlencode you can use multipart/form-data which +Instead of using JSON or URL-encoding data, you can use `multipart/form-data` which properly handles data encoding: ```shell diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index fcf4662502f..f66b0543ad1 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -283,8 +283,8 @@ and the following syntax rules. - As convention, always wrap URLs in single quotes `'url'`. - Always use relative paths against the home of CE and EE. Examples: - For `https://docs.gitlab.com/ee/README.html`, the relative URL is `README.html`. - - For `https://docs.gitlab.com/ee/user/project/cycle_analytics.html`, the relative - URL is `user/project/cycle_analytics.html`. + - For `https://docs.gitlab.com/ee/user/analytics/value_stream_analytics.md`, the relative + URL is `user/analytics/value_stream_analytics.html`. - For `README.html` files, add the complete path `path/to/README.html`. - For `index.html` files, use the clean (canonical) URL: `path/to/`. - For EE-only docs, use the same relative path, but add the attribute `ee_only: true` below @@ -328,7 +328,7 @@ There are three main considerations on the logic built for the nav: - `https://docs.gitlab.com/*` - [EE-only](#ee-only-docs): documentation only available in `/ee/`, not on `/ce/`, e.g.: - `https://docs.gitlab.com/ee/user/group/epics/` - - `https://docs.gitlab.com/ee/user/project/security_dashboard.html` + - `https://docs.gitlab.com/ee/user/application_security/security_dashboard/index.html` - [Default URL](#default-url): between CE and EE docs, the default is `ee`, therefore, all docs should link to `/ee/` unless if on `/ce/` linking internally to `ce`. diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index be25a083948..92fd17f9d3e 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -114,7 +114,7 @@ located in the [Dockerfiles directory](https://gitlab.com/gitlab-org/gitlab-docs If you need to rebuild the Docker images immediately (must have maintainer level permissions): WARNING: -If you change the dockerfile configuration and rebuild the images, you can break the master +If you change the Dockerfile configuration and rebuild the images, you can break the master pipeline in the main `gitlab` repository as well as in `gitlab-docs`. Create an image with a different name first and test it to ensure you do not break the pipelines. diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index fd0c29f0fc1..65949d5b5f5 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -5,167 +5,165 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: What to include in GitLab documentation pages. --- -# Documentation structure and template +# Documentation topic types -Use these standards to contribute content to the GitLab documentation. +At GitLab, we have not traditionally used topic types. However, we are starting to +move in this direction, and we now use four topic types: -Before getting started, familiarize yourself with [Documentation guidelines for GitLab](index.md) -and the [Documentation Style Guide](styleguide/index.md). +- [Concept](#concept) +- [Task](#task) +- [Reference](#reference) +- [Troubleshooting](#troubleshooting) -## Components of a documentation page +Each page contains multiple topic types. For example, +a page with the title `Pipelines`, which is generated from a file called `index.md`, +can include a concept and multiple task and reference topics. -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. +GitLab also uses high-level landing pages. -In general, each topic should include the following content, in this sequence: +## Landing pages -- *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. +Landing pages are topics that group other topics and help a user to navigate a section. -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. +Users who are using the in-product help do not have a left nav, +and need these topics to navigate the documentation. -## Template for new docs +These topics can also help other users find the most important topics +in a section. -Follow the [folder structure and filename guidelines](styleguide/index.md#folder-structure-overview) -and create a new topic by using this template: +Landing page topics should be in this format: ```markdown -<!--Follow the Style Guide when working on this document. -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. 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 -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/#assignments ---- +# Title (a noun, like "CI/CD or "Analytics") -# 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--> +Brief introduction to the concept or product area. +Include the reason why someone would use this thing. + +- Bulleted list of important related topics. +- These links are needed because users of in-product help do not have left navigation. +``` -<!--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). +## Concept -Write a description of the feature or use case. This introduction should answer -these questions: +A concept topic introduces a single feature or concept. -- 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 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? +A concept should answer the questions: -You can reuse this content, or part of it, for the front matter's `description` -at the top of this file. +- What is this? +- Why would I use it? -## Use cases +Think of everything someone might want to know if they’ve never heard of this topic before. -Describe common use cases, typically in bulleted form. Include real-life examples -for each. +Don’t tell them **how** to do this thing. Tell them **what it is**. -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. +If you start describing another topic, start a new concept and link to it. + +Concept topics should be in this format: + +```markdown +# Title (a noun, like "Widgets") -Examples of use cases on feature pages: +A paragraph that explains what this thing is. -- 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/index.md) -- EE-only: [Jenkins integration](../../integration/jenkins.md) +Another paragraph that explains what this thing is. -## Prerequisites +Remember, if you start to describe about another concept, stop yourself. +Each concept topic should be about one concept only. +``` -State any prerequisites for using the feature. These might include: +## Task -- 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). +A task topic gives instructions for how to complete a procedure. -Link each one to an appropriate place for more information. +Task topics should be in this format: -## Tasks +```markdown +# Title (starts with an active verb, like "Create a widget" or "Delete a widget") -Each topic should help users accomplish a specific task. +Do this task when you want to... -The heading should: +Prerequisites (optional): -- 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. +- Thing 1 +- Thing 2 +- Thing 3 -Bigger tasks can have subsections that explain specific phases of the process. +To do this task: -Include example code or configurations when needed. Use Markdown to wrap code -blocks with [syntax highlighting](../../user/markdown.md#colored-code-and-syntax-highlighting). +1. Location then action. (Go to this menu, then select this item.) +1. Another step. +1. Another step. -Example topic: +Task result (optional). Next steps (optional). +``` -## Create a teddy bear +Here is an example. -Create a teddy bear when you need something to hug. (Include the reason why you -might do the task.) +```markdown +# Create an issue -To create a teddy bear: +Create an issue when you want to track bugs or future work. -1. Go to **Settings > CI/CD**. -1. Expand **This** and click **This**. -1. Do another step. +Prerequisites: -The teddy bear is now in the kitchen, in the cupboard above the sink. _(This is the result.)_ +- A minimum of Contributor access to a project in GitLab. -You can retrieve the teddy bear and put it on the couch with the other animals. _(These are next steps.)_ +To create an issue: -Screenshots are not necessary. They are difficult to keep up-to-date and can -clutter the page. +1. Go to **Issues > List**. +1. In the top right, click **New issue**. +1. Complete the fields. (If you have a reference topic that lists each field, link to it here.) +1. Click **Submit issue**. -<!-- ## Troubleshooting +The issue is created. You can view it by going to **Issues > List**. +``` -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. +## Reference -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. --> +A reference topic provides information in an easily-scannable format, +like a table or list. It's similar to a dictionary or encyclopedia entry. ---- +```markdown +# Title (a noun, like "Pipeline settings" or "Administrator options") -Notes: +Introductory sentence. -- (1): Apply the [tier badges](styleguide/index.md#product-badges) accordingly. -- (2): Apply the correct format for the - [GitLab version that introduces the feature](styleguide/index.md#gitlab-versions-and-tiers). +| Setting | Description | +|---------|-------------| +| **Name** | Descriptive sentence about the setting. | ``` -## Help and feedback section +## Troubleshooting + +Troubleshooting topics can be one of two categories: + +- **Troubleshooting task.** This topic is written the same as a [standard task topic](#task). + For example, "Run debug tools" or "Verify syntax." +- **Troubleshooting reference.** This topic has a specific format. + +Troubleshooting reference topics should be in this format: + +```markdown +# Title (the error message or a description of it) + +You might get an error that states <error message>. + +This issue occurs when... + +The workaround is... +``` + +## Other information on a topic + +Topics include other information. + +For example: + +- Each topic must have a [tier badge](styleguide/index.md#product-tier-badges). +- New topics must have information about the + [GitLab version where the feature was introduced](styleguide/index.md#where-to-put-version-text). + +### Help and feedback section 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 @@ -180,7 +178,7 @@ 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. -### Disqus +#### Disqus We also have integrated the docs site with Disqus (introduced by [!151](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151)), @@ -206,7 +204,7 @@ 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 +### Guidelines for good practices > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36576/) in GitLab 13.2 as GitLab Development documentation. diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index a12c2740083..ade0b89a92c 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -3,3 +3,6 @@ redirect_to: 'styleguide/index.md' --- This document was moved to [another location](styleguide/index.md). + +<!-- This redirect file can be deleted after <2022-02-13>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index bba94c7de7e..baee01b8245 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -7,34 +7,25 @@ description: 'Writing styles, markup, formatting, and other standards for GitLab # Documentation Style Guide -This document defines the standards for GitLab documentation. +This document defines the standards for GitLab documentation, including grammar, formatting, word use, and more. -For broader information about the documentation, see the [Documentation guidelines](../index.md). +For style questions, mention `@tw-style` in an issue or merge request. If you have access to the GitLab Slack workspace, +use the `#docs-processes` channel. -For guidelines specific to text in the GitLab interface, see the Pajamas [Content](https://design.gitlab.com/content/error-messages/) section. +In addition to this page, the following resources can help you craft and contribute to documentation: -For information on how to validate styles locally or by using GitLab CI/CD, see [Testing](../testing.md). - -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: - - - [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/). - - [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`. +- [Doc contribution guidelines](../index.md) +- [Doc style and consistency testing](../testing.md) +- [UI text guidelines](https://design.gitlab.com/content/error-messages/) +- [GitLab Handbook style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) +- [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) +- [Google Developer Documentation Style Guide](https://developers.google.com/style) +- [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) ## 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 +The GitLab documentation is the SSOT for all +information related to GitLab implementation, usage, and troubleshooting. It evolves continuously, in keeping with new products and features, and with improvements for clarity, accuracy, and completeness. @@ -44,7 +35,7 @@ about GitLab products. It also informs decisions about the kinds of content we include in our documentation. -### All information +### The documentation includes all information Include problem-solving actions that may address rare cases or be considered _risky_, but provide proper context through fully-detailed @@ -54,10 +45,13 @@ If you think you have found an exception to this rule, contact the Technical Writing team. GitLab adds 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. +unlikely a user is to encounter a situation. -### All media types +GitLab Support maintains their own +[troubleshooting content](../../../administration/index.md#support-team-docs) +in the GitLab documentation. + +### The documentation includes all media types Include any media types/sources if the content is relevant to readers. You can freely include or link presentations, diagrams, and videos. No matter who @@ -71,48 +65,33 @@ include it. 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 +### Topic 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/): - -- Tutorials -- How-to guides -- Explanation -- Reference (for example, a glossary) +different types. For example: -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 becomes outdated. Therefore, we have a -[single template](../structure.md) for documentation. +- Concepts +- Tasks +- Reference +- Troubleshooting -GitLab documentation does not distinguish specific document types. 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. +At GitLab, we have not traditionally used topic types. However, we are starting to +move in this direction, so we can address these issues: -### Link instead of summarize +- **Content is hard to find.** Our docs are comprehensive and include a large amount of + useful information. Topic types create repeatable patterns that make our content easier + to scan and parse. +- **Content is often written from the contributor's point of view.** Our docs + are written by contributors. Topic types (tasks specifically) help put + information into a format that is geared toward helping others, rather than + documenting how a feature was implemented. -There is a temptation to summarize the information on another page, which -causes 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. +GitLab uses these [topic type templates](../structure.md). -### Organize by topic, not by type +### Link instead of repeating text -We organize content by topic, not by type, so it can be located in the -single-source-of-truth (SSOT) section for the subject matter. Top-level audience-type -folders, like `administration`, are exceptions. - -For example, do not create groupings of similar media types. For example: - -- Glossaries. -- 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. +Rather than repeating information from another topic, link to the single source +of truth and explain why it is important. ### Docs-first methodology @@ -127,14 +106,9 @@ of GitLab more efficient. should be to create a merge request (MR) to add this information to the documentation. You can then share the MR to communicate this information. -New information about the future usage or troubleshooting -of GitLab should not be written directly in a forum or other messaging system. -Instead, add it to a documentation merge request, then reference it. 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 [documentation template](../structure.md#template-for-new-docs), if present. +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. The more we reflexively add information to the documentation, the more the documentation helps others efficiently accomplish tasks and solve problems. @@ -217,8 +191,11 @@ included in backticks. For example: ## Structure -Because we want documentation to be a SSOT, we should [organize by topic, not by -type](#organize-by-topic-not-by-type). +We include concept and task topic types in the same larger topic. + +In general, we have one topic that's a [landing page](../structure.md#landing-pages). +Below that topic in the left nav are individual topics. Each of these include a concept +and multiple related tasks, reference, and troubleshooting topics. ### Folder structure overview @@ -299,7 +276,7 @@ place for it. ### Avoid duplication Do not include the same information in multiple places. -[Link to a single source of truth instead.](#link-instead-of-summarize) +[Link to a single source of truth instead.](#link-instead-of-repeating-text) ### References across documents @@ -389,7 +366,7 @@ by default. 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).) + GitLab Free 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, @@ -942,7 +919,7 @@ NOTE: [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39717) in GitLab 13.4, [product badges](#product-tier-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`. +`## This is an example **(FREE)**`, 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. When you change @@ -966,8 +943,8 @@ this option. ## Links -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) +Links are important in GitLab documentation. Use links instead of +summarizing to help preserve a [single source of truth](#documentation-is-the-single-source-of-truth-ssot) in GitLab documentation. We include guidance for links in these categories: @@ -1020,7 +997,8 @@ To link to internal documentation: - Use relative links to Markdown files in the same repository. - Do not use absolute URLs or URLs from `docs.gitlab.com`. - Use `../` to navigate to higher-level directories. -- Don't prepend `./` to links to files or directories. +- Don't prepend `./` to links to files or directories. To link to a file in the + same directory or one of its sub-directories, use the syntax `path/to/file.md`. - Don't link relative to root. For example, `/ee/user/gitlab_com/index.md`. Don't: @@ -1045,6 +1023,7 @@ To link to internal documentation: - `../../merge_requests/index.md` - `../../issues/tags.md` - `../../issues/tags.md#stages` + - `issues/tags.md` NOTE: Using the Markdown extension is necessary for the [`/help`](../index.md#gitlab-help) @@ -1671,8 +1650,8 @@ the blockquote to use a bulleted list: If a feature is moved to another tier: ```markdown -> - [Moved](<link-to-issue>) from GitLab Premium to GitLab Starter in 11.8. -> - [Moved](<link-to-issue>) from GitLab Starter to GitLab Core in 12.0. +> - [Moved](<link-to-issue>) from GitLab Ultimate to GitLab Premium in 11.8. +> - [Moved](<link-to-issue>) from GitLab Premium to GitLab Free in 12.0. ``` If a feature is deprecated, include a link to a replacement (when available): @@ -1779,7 +1758,7 @@ To add a tier badge to a heading, add the relevant [tier badge](#available-produ after the heading text. For example: ```markdown -# Heading title `**(CORE)**` +# Heading title **(FREE)** ``` #### Product tier badges on other content @@ -1787,30 +1766,26 @@ after the heading text. For example: In paragraphs, list names, and table cells, an information icon displays when you add a tier badge. More verbose information displays when a user points to the icon: -- `**(STARTER)**` displays as **(STARTER)** -- `**(STARTER ONLY)**` displays as **(STARTER ONLY)** -- `**(SILVER ONLY)**` displays as **(SILVER ONLY)** +- `**(FREE)**` displays as **(FREE)** +- `**(FREE SELF)**` displays as **(FREE SELF)** +- `**(FREE SAAS)**` displays as **(FREE SAAS)** -The `**(STARTER)**` generates 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 isn't displayed. +The `**(FREE)**` generates a `span` element to trigger the +badges and tooltips (`<span class="badge-trigger free">`). #### Available product tier badges -| Tier in which feature is available | Tier badge | -|:-----------------------------------------------------------------------|:----------------------| -| GitLab Core and GitLab.com Free, and their higher tiers | `**(CORE)**` | -| GitLab Starter and GitLab.com Bronze, and their higher tiers | `**(STARTER)**` | -| GitLab Premium and GitLab.com Silver, and their higher tiers | `**(PREMIUM)**` | -| GitLab Ultimate and GitLab.com Gold | `**(ULTIMATE)**` | -| _Only_ GitLab Core and higher tiers (no GitLab.com-based tiers) | `**(CORE ONLY)**` | -| _Only_ GitLab Starter and higher tiers (no GitLab.com-based tiers) | `**(STARTER ONLY)**` | -| _Only_ GitLab Premium and higher tiers (no GitLab.com-based tiers) | `**(PREMIUM ONLY)**` | -| _Only_ GitLab Ultimate (no GitLab.com-based tiers) | `**(ULTIMATE ONLY)**` | -| _Only_ GitLab.com Free and higher tiers (no self-managed instances) | `**(FREE ONLY)**` | -| _Only_ GitLab.com Bronze and higher tiers (no self-managed instances) | `**(BRONZE ONLY)**` | -| _Only_ GitLab.com Silver and higher tiers (no self-managed instances) | `**(SILVER ONLY)**` | -| _Only_ GitLab.com Gold (no self-managed instances) | `**(GOLD ONLY)**` | +| Tier in which feature is available | Tier badge | +|:--------------------------------------------------------------------------|:----------------------| +| GitLab Free self-managed and SaaS, and higher tiers | `**(FREE)**` | +| GitLab Premium self-managed and SaaS, and their higher tiers | `**(PREMIUM)**` | +| GitLab Ultimate self-managed and SaaS | `**(ULTIMATE)**` | +| _Only_ GitLab Free self-managed and higher tiers (no SaaS-based tiers) | `**(FREE SELF)**` | +| _Only_ GitLab Premium self-managed and higher tiers (no SaaS-based tiers) | `**(PREMIUM SELF)**` | +| _Only_ GitLab Ultimate self-managed (no SaaS-based tiers) | `**(ULTIMATE SELF)**` | +| _Only_ GitLab Free SaaS and higher tiers (no self-managed instances) | `**(FREE SAAS)**` | +| _Only_ GitLab Premium SaaS and higher tiers (no self-managed instances) | `**(PREMIUM SAAS)**` | +| _Only_ GitLab Ultimate SaaS (no self-managed instances) | `**(ULTIMATE SAAS)**` | Topics that mention the `gitlab.rb` file are referring to self-managed instances of GitLab. To prevent confusion, include the relevant `TIER ONLY` @@ -1899,21 +1874,6 @@ In this case: - Use the [GitLab Restart](#gitlab-restart) section to explain any required restart or reconfigure of GitLab. -### Troubleshooting - -For troubleshooting sections, provide as much context as possible so -users can identify their problem and resolve it on their own. You -can facilitate this by making sure the troubleshooting content addresses: - -1. The problem the user needs to solve. -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). Create 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 diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 561727648f0..f3d6e0a5c71 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -93,8 +93,8 @@ To execute documentation link tests locally: ### UI link tests -The `ui-docs-links lint` job uses `haml-lint` to test that all links to docs from -UI elements (`app/views` files, for example) are linking to valid docs and anchors. +The `ui-docs-links lint` job uses `haml-lint` to test that all documentation links from +UI elements (`app/views` files, for example) are linking to valid pages and anchors. To run the `ui-docs-links` test locally: @@ -156,12 +156,12 @@ markdownlint configuration is found in the following projects: - [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.markdownlint.json) - [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/.markdownlint.json) -This configuration is also used within build pipelines. +This configuration is also used in build pipelines. You can use markdownlint: - [On the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--). -- [Within a code editor](#configure-editors). +- [In a code editor](#configure-editors). - [In a `pre-push` hook](#configure-pre-push-hooks). ### Vale @@ -172,10 +172,10 @@ English language. Vale's configuration is stored in the directory of projects. Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/) that extend any of -several types of checks, which we store in the `.linting/vale/styles/gitlab` directory within the +several types of checks, which we store in the `.linting/vale/styles/gitlab` directory in the documentation directory of projects. -Vale configuration is found in the following projects: +You can find Vale configuration in the following projects: - [`gitlab`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab) - [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/master/docs/.vale/gitlab) @@ -183,13 +183,13 @@ Vale configuration is found in the following projects: - [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc/.vale/gitlab) - [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/master/doc/.vale/gitlab) -This configuration is also used within build pipelines, where +This configuration is also used in build pipelines, where [error-level rules](#vale-result-types) are enforced. You can use Vale: - [On the command line](https://errata-ai.gitbook.io/vale/getting-started/usage). -- [Within a code editor](#configure-editors). +- [In a code editor](#configure-editors). - [In a Git hook](#configure-pre-push-hooks). Vale only reports errors in the Git hook (the same configuration as the CI/CD pipelines), and does not report suggestions or warnings. @@ -243,32 +243,40 @@ To match the versions of `markdownlint-cli` and `vale` used in the GitLab projec [versions used](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L447) when building the `image:docs-lint-markdown` Docker image containing these tools for CI/CD. -| Tool | Version | Command | Additional information | -|--------------------|----------|-------------------------------------------|------------------------| -| `markdownlint-cli` | Latest | `yarn global add markdownlint-cli` | n/a | -| `markdownlint-cli` | Specfic | `yarn global add markdownlint-cli@0.23.2` | The `@` indicates a specific version, and this example updates the tool to version `0.23.2`. | -| Vale | Latest | `brew update && brew upgrade vale` | This command is for macOS only. | -| Vale | Specific | n/a | Not possible using `brew`, but can be [directly downloaded](https://github.com/errata-ai/vale/releases). | +| Tool | Version | Command | Additional information | +|--------------------|-----------|-------------------------------------------|------------------------| +| `markdownlint-cli` | Latest | `yarn global add markdownlint-cli` | n/a | +| `markdownlint-cli` | Specific | `yarn global add markdownlint-cli@0.23.2` | The `@` indicates a specific version, and this example updates the tool to version `0.23.2`. | +| Vale | Latest | `brew update && brew upgrade vale` | This command is for macOS only. | +| Vale | Specific | n/a | Not possible using `brew`, but can be [directly downloaded](https://github.com/errata-ai/vale/releases). | ### Configure editors Using linters in your editor is more convenient than having to run the commands from the command line. -To configure markdownlint within your editor, install one of the following as appropriate: +To configure markdownlint in your editor, install one of the following as appropriate: -- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) -- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) -- [Atom](https://atom.io/packages/linter-node-markdownlint) -- [Vim](https://github.com/dense-analysis/ale) +- Sublime Text [`SublimeLinter-contrib-markdownlint` package](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint). +- Visual Studio Code [`DavidAnson.vscode-markdownlint` extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint). +- Atom [`linter-node-markdownlint` package](https://atom.io/packages/linter-node-markdownlint). +- Vim [ALE plugin](https://github.com/dense-analysis/ale). -To configure Vale within your editor, install one of the following as appropriate: +To configure Vale in 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 [`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. You can configure the plugin to +- Sublime Text [`SublimeLinter-contrib-vale` package](https://packagecontrol.io/packages/SublimeLinter-contrib-vale). +- Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). + You can configure the plugin to [display only a subset of alerts](#show-subset-of-vale-alerts). -- [Vim](https://github.com/dense-analysis/ale). + + In the extension's settings: + + - Select the **Use CLI** checkbox. + - In the **Config** setting, enter an absolute path to [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) in one of the cloned GitLab repositories on your computer. + - In the **Path** setting, enter the absolute path to the Vale binary. In most + cases, `vale` should work. To find the location, run `which vale` in a terminal. + +- Vim [ALE plugin](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). @@ -286,7 +294,7 @@ Configuration for `lefthook` is available in the [`lefthook.yml`](https://gitlab file for the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project. To set up `lefthook` for documentation linting, see -[Pre-push static analysis](../contributing/style_guides.md#pre-push-static-analysis). +[Pre-push static analysis](../contributing/style_guides.md#pre-push-static-analysis-with-lefthook). ### Show subset of Vale alerts diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 5be601187ca..81014b7624c 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -92,12 +92,36 @@ class User < ActiveRecord::Base # ... lots of code here ... end -User.prepend_if_ee('EE::User') +User.prepend_ee_mod ``` Do not use methods such as `prepend`, `extend`, and `include`. Instead, use -`prepend_if_ee`, `extend_if_ee`, or `include_if_ee`. These methods take a -_String_ containing the full module name as the argument, not the module itself. +`prepend_ee_mod`, `extend_ee_mod`, or `include_ee_mod`. These methods will try to +find the relevant EE module by the name of the receiver module, for example; + +```ruby +module Vulnerabilities + class Finding + #... + end +end + +Vulnerabilities::Finding.prepend_ee_mod +``` + +will prepend the module named `::EE::Vulnerabilities::Finding`. + +If the extending module does not follow this naming convention, you can also provide the module name +by using `prepend_if_ee`, `extend_if_ee`, or `include_if_ee`. These methods take a +_String_ containing the full module name as the argument, not the module itself, like so; + +```ruby +class User + #... +end + +User.prepend_if_ee('::EE::UserExtension') +``` Since the module would require an `EE` namespace, the file should also be put in an `ee/` sub-directory. For example, we want to extend the user model @@ -142,9 +166,9 @@ still having access the class's implementation with `super`. There are a few gotchas with it: - you should always [`extend ::Gitlab::Utils::Override`](utilities.md#override) and use `override` to - guard the "overrider" method to ensure that if the method gets renamed in + guard the `overrider` method to ensure that if the method gets renamed in CE, the EE override isn't silently forgotten. -- when the "overrider" would add a line in the middle of the CE +- when the `overrider` would add a line in the middle of the CE implementation, you should refactor the CE method and split it in smaller methods. Or create a "hook" method that is empty in CE, and with the EE-specific implementation in EE. @@ -947,7 +971,7 @@ information on managing page-specific JavaScript within EE. #### Child Component only used in EE -To separate Vue template differences we should [async import the components](https://vuejs.org/v2/guide/components-dynamic-async.html#Async-Components). +To separate Vue template differences we should [import the components asynchronously](https://vuejs.org/v2/guide/components-dynamic-async.html#Async-Components). Doing this allows for us to load the correct component in EE while in CE we can load a empty component that renders nothing. This code **should** @@ -1044,7 +1068,7 @@ export default { **For EE components that need different results for the same computed values, we can pass in props to the CE wrapper as seen in the example.** - **EE Child components** - - Since we are using the async loading to check which component to load, we'd still use the component's name, check [this example](#child-component-only-used-in-ee). + - Since we are using the asynchronous loading to check which component to load, we'd still use the component's name, check [this example](#child-component-only-used-in-ee). - **EE extra HTML** - For the templates that have extra HTML in EE we should move it into a new component and use the `ee_else_ce` dynamic import diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index 8bf8a5fccb8..10fa331e1dd 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Elasticsearch knowledge **(STARTER ONLY)** +# Elasticsearch knowledge **(PREMIUM SELF)** This area is to maintain a compendium of useful information when working with Elasticsearch. @@ -13,9 +13,9 @@ the [Elasticsearch integration documentation](../integration/elasticsearch.md#en ## Deep Dive -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 the GitLab [Elasticsearch integration](../integration/elasticsearch.md) to share his domain specific knowledge 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=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 June 2019, Mario de la Ossa hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) on the GitLab [Elasticsearch integration](../integration/elasticsearch.md) to share his domain specific knowledge with anyone who may work in this part of the codebase in the future. You can find the <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [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-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. +In August 2020, a second Deep Dive was hosted, focusing on [GitLab-specific architecture for multi-indices support](#zero-downtime-reindexing-with-multiple-indices). The <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [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 @@ -210,7 +210,7 @@ class MigrationName < Elastic::Migration end ``` -Applied migrations are stored in `gitlab-#{RAILS_ENV}-migrations` index. All unexecuted migrations +Applied migrations are stored in `gitlab-#{RAILS_ENV}-migrations` index. All migrations not executed are applied by the [`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/workers/elastic/migration_worker.rb) cron worker sequentially. @@ -337,7 +337,7 @@ cluster.routing.allocation.disk.watermark.low: 15gb cluster.routing.allocation.disk.watermark.high: 10gb ``` -Restart Elasticsearch, and the `read_only_allow_delete` will clear on it's own. +Restart Elasticsearch, and the `read_only_allow_delete` will clear on its own. _from "Disk-based Shard Allocation | Elasticsearch Reference" [5.6](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/disk-allocator.html#disk-allocator) and [6.x](https://www.elastic.co/guide/en/elasticsearch/reference/6.7/disk-allocator.html)_ @@ -351,7 +351,7 @@ simply reindex everything from scratch. If your Elasticsearch index is incredibly large it may be too time consuming or cause too much downtime to reindex from scratch. There aren't any built in -mechanisms for automatically finding discrepencies and resyncing an +mechanisms for automatically finding discrepancies and resyncing an Elasticsearch index if it gets out of sync but one tool that may be useful is looking at the logs for all the updates that occurred in a time range you believe may have been missed. This information is very low level and only diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index a1899ab5f18..5d77c0ca0e9 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -12,7 +12,7 @@ Experiments are run as an A/B test and are behind a feature flag to turn the tes ## Experiment tracking issue -Each experiment should have an [Experiment tracking](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=growth%20experiment&search=%22Experiment+tracking%22) issue to track the experiment from roll-out through to cleanup/removal. Immediately after an experiment is deployed, the due date of the issue should be set (this depends on the experiment but can be up to a few weeks in the future). +Each experiment should have an [Experiment tracking](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=growth%20experiment&search=%22Experiment+tracking%22) issue to track the experiment from roll-out through to cleanup/removal. The tracking issue is similar to a feature flag rollout issue, and is also used to track the status of an experiment. Immediately after an experiment is deployed, the due date of the issue should be set (this depends on the experiment but can be up to a few weeks in the future). After the deadline, the issue needs to be resolved and either: - It was successful and the experiment becomes the new default. @@ -36,7 +36,17 @@ and link to the issue that resolves the experiment. If the experiment is successful and becomes part of the product, any follow up issues should be addressed. -## How to create an A/B test +## Experiments using `gitlab-experiment` + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300383) in GitLab 13.7. +> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - It's enabled on GitLab.com. +> - It is not yet intended for use in GitLab self-managed instances. + +[GitLab Experiment](https://gitlab.com/gitlab-org/gitlab-experiment/) is a gem included +in GitLab that can be used for running experiments. + +## How to create an A/B test using `experimentation.rb` ### Implement the experiment @@ -358,7 +368,7 @@ Use a comma to list more than one experiment to be forced: document.cookie = "force_experiment=<EXPERIMENT_KEY>,<ANOTHER_EXPERIMENT_KEY>; path=/"; ``` -Clear the experiments by unsetting the `force_experiment` cookie: +To clear the experiments, unset the `force_experiment` cookie: ```javascript document.cookie = "force_experiment=; path=/"; diff --git a/doc/development/export_csv.md b/doc/development/export_csv.md index 99b6062736d..0bf12149779 100644 --- a/doc/development/export_csv.md +++ b/doc/development/export_csv.md @@ -14,7 +14,7 @@ This document lists the different implementations of CSV export in GitLab codeba | Downloading | - Query and write data in batches to a temporary file.<br>- Loads the file into memory.<br>- Sends the file to the client. | - Report available immediately. | - Large amount of data might cause request timeout.<br>- Memory intensive.<br>- Request expires when user navigates to a different page. | [Export Chain of Custody Report](../user/compliance/compliance_dashboard/#chain-of-custody-report) | | As email attachment | - Asynchronously process the query with background job.<br>- Email uses the export as an attachment. | - Asynchronous processing. | - Requires users use a different app (email) to download the CSV.<br>- Email providers may limit attachment size. | - [Export Issues](../user/project/issues/csv_export.md)<br>- [Export Merge Requests](../user/project/merge_requests/csv_export.md) | | As downloadable link in email (*) | - Asynchronously process the query with background job.<br>- Email uses an export link. | - Asynchronous processing.<br>- Bypasses email provider attachment size limit. | - Requires users use a different app (email).<br>- Requires additional storage and cleanup. | [Export User Permissions](https://gitlab.com/gitlab-org/gitlab/-/issues/1772) | -| Polling (non-persistent state) | - Asynchronously processes the query with the background job.<br>- Frontend(FE) polls every few seconds to check if CSV file is ready. | - Asynchronous processing.<br>- Automatically downloads to local machine on completion.<br>- In-app solution. | - Non-persistable request - request expires when user navigates to a different page.<br>- API is processed for each polling request. | [Export Vulnerabilities](../user/application_security/security_dashboard/#export-vulnerabilities) | +| Polling (non-persistent state) | - Asynchronously processes the query with the background job.<br>- Frontend(FE) polls every few seconds to check if CSV file is ready. | - Asynchronous processing.<br>- Automatically downloads to local machine on completion.<br>- In-app solution. | - Non-persistable request - request expires when user navigates to a different page.<br>- API is processed for each polling request. | [Export Vulnerabilities](../user/application_security/vulnerability_report/#export-vulnerabilities) | | Polling (persistent state) (*) | - Asynchronously processes the query with background job.<br>- Backend (BE) maintains the export state<br>- FE polls every few seconds to check status.<br>- FE shows 'Download link' when export is ready.<br>- User can download or regenerate a new report. | - Asynchronous processing.<br>- No database calls made during the polling requests (HTTP 304 status is returned until export status changes).<br>- Does not require user to stay on page until export is complete.<br>- In-app solution.<br>- Can be expanded into a generic CSV feature (such as dashboard / CSV API). | - Requires to maintain export states in DB.<br>- Does not automatically download the CSV export to local machine, requires users to click 'Download' button. | [Export Merge Commits Report](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43055) | NOTE: diff --git a/doc/development/fe_guide/accessibility.md b/doc/development/fe_guide/accessibility.md index 92730e8139f..5ad1a701fac 100644 --- a/doc/development/fe_guide/accessibility.md +++ b/doc/development/fe_guide/accessibility.md @@ -9,11 +9,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Resources [Chrome Accessibility Developer Tools](https://github.com/GoogleChrome/accessibility-developer-tools) -are useful for testing for potential accessibility problems in GitLab. +assist with testing for potential accessibility problems in GitLab. -The [axe](https://www.deque.com/axe/) browser extension (available for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/) and [Chrome](https://chrome.google.com/webstore/detail/axe-web-accessibility-tes/lhdoppojpmngadmnindnejefpokejbdd)) is -also a handy tool for running audits and getting feedback on markup, CSS and even potentially problematic color usages. +The [axe](https://www.deque.com/axe/) browser extension (available for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/) and [Chrome](https://chrome.google.com/webstore/detail/axe-web-accessibility-tes/lhdoppojpmngadmnindnejefpokejbdd)) provides running audits and feedback on markup, CSS, and even potentially problematic color usages. Accessibility best-practices and more in-depth information are available on -[the Audit Rules page](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules) for the Chrome Accessibility Developer Tools. The [Awesome Accessibility](https://github.com/brunopulis/awesome-a11y) list is also a -useful compilation of accessibility-related material. +[the Audit Rules page](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules) for the Chrome Accessibility Developer Tools. The [Awesome Accessibility](https://github.com/brunopulis/awesome-a11y) list is a compilation of accessibility-related material. diff --git a/doc/development/fe_guide/architecture.md b/doc/development/fe_guide/architecture.md index 964837dc5f7..c51f99ca9d2 100644 --- a/doc/development/fe_guide/architecture.md +++ b/doc/development/fe_guide/architecture.md @@ -6,9 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Architecture -When you are developing a new feature that requires architectural design, or if -you are changing the fundamental design of an existing feature, make sure it is -discussed with one of the Frontend Architecture Experts. +When developing a feature that requires architectural design, or changing the fundamental design of an existing feature, discuss it with a Frontend Architecture Expert. A Frontend Architect is an expert who makes high-level Frontend design decisions and decides on technical standards, including coding standards and frameworks. diff --git a/doc/development/fe_guide/axios.md b/doc/development/fe_guide/axios.md index cf5a4970c04..2d699b305ce 100644 --- a/doc/development/fe_guide/axios.md +++ b/doc/development/fe_guide/axios.md @@ -44,7 +44,7 @@ Advantages over [`spyOn()`](https://jasmine.github.io/api/edge/global.html#spyOn - no need to create response objects - does not allow call through (which we want to avoid) -- simple API to test error cases +- clear API to test error cases - provides `replyOnce()` to allow for different responses We have also decided against using [Axios interceptors](https://github.com/axios/axios#interceptors) because they are not suitable for mocking. diff --git a/doc/development/fe_guide/components.md b/doc/development/fe_guide/components.md deleted file mode 100644 index 6b6274a6480..00000000000 --- a/doc/development/fe_guide/components.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/components/status/' ---- diff --git a/doc/development/fe_guide/design_patterns.md b/doc/development/fe_guide/design_patterns.md index 784612682f8..d6b1f38b417 100644 --- a/doc/development/fe_guide/design_patterns.md +++ b/doc/development/fe_guide/design_patterns.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w When exactly one object is needed for a given task, prefer to define it as a `class` rather than as an object literal. Prefer also to explicitly restrict -instantiation, unless flexibility is important (e.g. for testing). +instantiation, unless flexibility is important (such as for testing). ```javascript // bad @@ -56,7 +56,7 @@ export default class MyThing { ## Manipulating the DOM in a JS Class When writing a class that needs to manipulate the DOM guarantee a container option is provided. -This is useful when we need that class to be instantiated more than once in the same page. +This can be used when we need that class to be instantiated more than once in the same page. Bad: diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md index d122459f51c..b85ed4da442 100644 --- a/doc/development/fe_guide/development_process.md +++ b/doc/development/fe_guide/development_process.md @@ -12,9 +12,9 @@ You can find more about the organization of the frontend team in the [handbook]( 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. +Copy the content over to your issue or merge request and if something doesn't apply, remove it from your current list. -This checklist is intended to help us during development of bigger features/refactorings, it's not a "use it always and every point always matches" list. +This checklist is intended to help us during development of bigger features/refactorings. It is not a "use it always and every point always matches" list. Please use your best judgment when to use it and please contribute new points through merge requests if something comes to your mind. @@ -77,7 +77,7 @@ With the purpose of being [respectful of others' time](https://about.gitlab.com/ - includes tests - includes a changelog entry (when necessary) - Before assigning to a maintainer, assign to a reviewer. -- If you assigned a merge request or pinged someone directly, be patient because we work in different timezones and asynchronously. Unless the merge request is urgent (like fixing a broken master), please don't DM or reassign the merge request before waiting for a 24-hour window. +- If you assigned a merge request or pinged someone directly, be patient because we work in different timezones and asynchronously. Unless the merge request is urgent (like fixing a broken default branch), please don't DM or reassign the merge request before waiting for a 24-hour window. - If you have a question regarding your merge request/issue, make it on the merge request/issue. When we DM each other, we no longer have a SSOT and [no one else is able to contribute](https://about.gitlab.com/handbook/values/#public-by-default). - When you have a big **Draft** merge request with many changes, you're advised to get the review started before adding/removing significant code. Make sure it is assigned well before the release cut-off, as the reviewer(s)/maintainer(s) would always prioritize reviewing finished MRs before the **Draft** ones. - Make sure to remove the `Draft:` title before the last round of review. diff --git a/doc/development/fe_guide/dropdowns.md b/doc/development/fe_guide/dropdowns.md deleted file mode 100644 index bd2dae13c5b..00000000000 --- a/doc/development/fe_guide/dropdowns.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/components/dropdown/' ---- diff --git a/doc/development/fe_guide/editor_lite.md b/doc/development/fe_guide/editor_lite.md index 47ef85d8737..f783a97fbd3 100644 --- a/doc/development/fe_guide/editor_lite.md +++ b/doc/development/fe_guide/editor_lite.md @@ -8,13 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Background -**Editor Lite** is a technological product driving [Web Editor](../../user/project/repository/web_editor.md), [Snippets](../../user/snippets.md), [CI Linter](../../ci/lint.md), etc. Editor Lite is the driving technology for any single-file editing experience across the product. +**Editor Lite** is a technological product driving features like [Web Editor](../../user/project/repository/web_editor.md), [Snippets](../../user/snippets.md), and [CI Linter](../../ci/lint.md). Editor Lite is the driving technology for any single-file editing experience across the product. Editor Lite is a thin wrapper around [the Monaco editor](https://microsoft.github.io/monaco-editor/index.html) that provides the necessary helpers and abstractions and extends Monaco using extensions. ## How to use Editor Lite -Editor Lite is framework-agnostic and can be used in any application, whether it's Rails or Vue. For the convenience of integration, we have [the dedicated `<editor-lite>` Vue component](#vue-component), but in general, the integration of Editor Lite is pretty straightforward: +Editor Lite is framework-agnostic and can be used in any application, whether it's Rails or Vue. For the convenience of integration, we have the dedicated `<editor-lite>` Vue component, but in general, the integration of Editor Lite is pretty straightforward: 1. Import Editor Lite: @@ -65,7 +65,7 @@ The editor follows the same public API as [provided by Monaco editor](https://mi 1. Editor's loading state. -Editor Lite comes with the loading state built-in, making spinners and loaders rarely needed in HTML. To benefit the built-in loading state, set the `data-editor-loading` property on the HTML element that is supposed to contain the editor. Editor Lite will show the loader automatically while it's bootstrapping. +Editor Lite comes with the loading state built-in, making spinners and loaders rarely needed in HTML. To benefit the built-in loading state, set the `data-editor-loading` property on the HTML element that is supposed to contain the editor. Editor Lite shows the loader automatically while it's bootstrapping.  1. Update syntax highlighting if the filename changes. @@ -89,7 +89,7 @@ form.addEventListener('submit', () => { 1. Performance -Even though Editor Lite itself is extremely slim, it still depends on Monaco editor. Monaco is not an easily tree-shakeable module. Hence, every time you add Editor Lite to a view, the JavaScript bundle's size significantly increases, affecting your view's loading performance. To avoid that, it is recommended to import the editor on demand on those views where it is not 100% certain that the editor will be used. Or if the editor is a secondary element of the view. Loading Editor Lite on demand is no different from loading any other module: +Even though Editor Lite itself is extremely slim, it still depends on Monaco editor. Monaco is not an easily tree-shakeable module. Hence, every time you add Editor Lite to a view, the JavaScript bundle's size significantly increases, affecting your view's loading performance. It is recommended to import the editor on demand on those views where it is not 100% certain that the editor is needed. Or if the editor is a secondary element of the view. Loading Editor Lite on demand is no different from loading any other module: ```javascript someActionFunction() { @@ -109,8 +109,8 @@ which would not depend on any particular group. Even though the Editor Lite's co [Create::Editor FE Team](https://about.gitlab.com/handbook/engineering/development/dev/create-editor/), the main functional elements — extensions — can be owned by any group. Editor Lite extensions' main idea is that the core of the editor remains very slim and stable. At the same time, whatever new functionality -is needed can be added as an extension to this core, without touching the core itself. It allows any group -to build and own any new editing functionality without being afraid of it being broken or overridden with +is needed can be added as an extension to this core, without touching the core itself. Any group is allowed +to build and own new editing functionality without being afraid of it being broken or overridden with the Editor Lite changes. Structurally, the complete implementation of Editor Lite could be presented as the following diagram: @@ -145,7 +145,7 @@ Important things to note here: ### Using an existing extension -Adding an extension to Editor Lite's instance is simple: +Adding an extension to Editor Lite's instance requires the following steps: ```javascript import EditorLite from '~/editor/editor_lite'; @@ -159,7 +159,7 @@ editor.use(MyExtension); ### Creating an extension -Let's create our first Editor Lite extension. As aforementioned, extensions are ES6 modules exporting the simple `Object` that is used to extend Editor Lite's functionality. As the most straightforward test, let's create an extension that extends Editor Lite with a new function that, when called, will output editor's content in `alert`. +Let's create our first Editor Lite extension. Extensions are ES6 modules exporting a basic `Object` that is used to extend Editor Lite's functionality. As a test, let's create an extension that extends Editor Lite with a new function that, when called, outputs editor's content in `alert`. `~/my_folder/my_fancy_extension.js:` @@ -225,7 +225,3 @@ Just pass the array of extensions to your `use` method: ```javascript editor.use([FileTemplateExtension, MyFancyExtension]); ``` - -## <a id="vue-component"></a>`<editor-lite>` Vue component - -TBD diff --git a/doc/development/fe_guide/emojis.md b/doc/development/fe_guide/emojis.md index 7151e2ffeee..2dedbc8f19d 100644 --- a/doc/development/fe_guide/emojis.md +++ b/doc/development/fe_guide/emojis.md @@ -25,7 +25,7 @@ when your platform does not support it. - `app/assets/images/emoji.png` - `app/assets/images/emoji@2x.png` 1. Ensure you see new individual images copied into `app/assets/images/emoji/` - 1. Ensure you can see the new emojis and their aliases in the GFM Autocomplete + 1. Ensure you can see the new emojis and their aliases in the GitLab Flavored Markdown (GFM) Autocomplete 1. Ensure you can see the new emojis and their aliases in the award emoji menu 1. You might need to add new emoji Unicode support checks and rules for platforms that do not support a certain emoji and we need to fallback to an image. diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md index 9612f604b56..772f1672293 100644 --- a/doc/development/fe_guide/frontend_faq.md +++ b/doc/development/fe_guide/frontend_faq.md @@ -21,7 +21,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## FAQ -### 1. How do I find the Rails route for a page? +### 1. How does one find the Rails route for a page? #### Check the 'page' data attribute @@ -36,7 +36,7 @@ Find here the [source code setting the attribute](https://gitlab.com/gitlab-org/ #### Rails routes -The `rake routes` command can be used to list all the routes available in the application, piping the output into `grep`, we can perform a search through the list of available routes. +The `rake routes` command can be used to list all the routes available in the application. Piping the output into `grep`, we can perform a search through the list of available routes. The output includes the request types available, route parameters and the relevant controller. ```shell @@ -46,13 +46,13 @@ bundle exec rake routes | grep "issues" ### 2. `modal_copy_button` vs `clipboard_button` The `clipboard_button` uses the `copy_to_clipboard.js` behavior, which is -initialized on page load, so if there are vue-based clipboard buttons that -don't exist at page load (such as ones in a `GlModal`), they do not have the +initialized on page load. Vue clipboard buttons that +don't exist at page load (such as ones in a `GlModal`) do not have click handlers associated with the clipboard package. -`modal_copy_button` was added that manages an instance of the +`modal_copy_button` manages an instance of the [`clipboard` plugin](https://www.npmjs.com/package/clipboard) specific to -the instance of that component, which means that clipboard events are +the instance of that component. This means that clipboard events are bound on mounting and destroyed when the button is, mitigating the above issue. It also has bindings to a particular container or modal ID available, to work with the focus trap created by our GlModal. @@ -60,7 +60,7 @@ available, to work with the focus trap created by our GlModal. ### 3. A `gitlab-ui` component not conforming to [Pajamas Design System](https://design.gitlab.com/) Some [Pajamas Design System](https://design.gitlab.com/) components implemented in -`gitlab-ui` do not conform with the design system specs because they lack some +`gitlab-ui` do not conform with the design system specs. This is because they lack some planned features or are not correctly styled yet. In the Pajamas website, a banner on top of the component examples indicates that: @@ -77,18 +77,17 @@ It makes codebase unified and more comfortable to maintain/refactor in the futur Ensure a [Product Designer](https://about.gitlab.com/company/team/?department=ux-department) reviews the use of the non-conforming component as part of the MR review. Make a -follow up issue and attach it to the component implementation epic found within the +follow up issue and attach it to the component implementation epic found in the [Components of Pajamas Design System epic](https://gitlab.com/groups/gitlab-org/-/epics/973). ### 4. My submit form button becomes disabled after submitting -If you are using a submit button inside a form and you attach an `onSubmit` event listener on the form element, [this piece of code](https://gitlab.com/gitlab-org/gitlab/blob/794c247a910e2759ce9b401356432a38a4535d49/app/assets/javascripts/main.js#L225) adds a `disabled` class selector to the submit button when the form is submitted. -To avoid this behavior, add the class `js-no-auto-disable` to the button. +A Submit button inside of a form attaches an `onSubmit` event listener on the form element. [This code](https://gitlab.com/gitlab-org/gitlab/blob/794c247a910e2759ce9b401356432a38a4535d49/app/assets/javascripts/main.js#L225) adds a `disabled` class selector to the submit button when the form is submitted. To avoid this behavior, add the class `js-no-auto-disable` to the button. -### 5. Should I use a full URL (i.e. `gon.gitlab_url`) or a full path (i.e. `gon.relative_url_root`) when referencing backend endpoints? +### 5. Should one use a full URL (for example `gon.gitlab_url`) or a full path (for example `gon.relative_url_root`) when referencing backend endpoints? -It's preferred to use a **full path** over a **full URL** because the URL uses the hostname configured with -GitLab which may not match the request. This causes [CORS issues like this Web IDE one](https://gitlab.com/gitlab-org/gitlab/-/issues/36810). +It's preferred to use a **full path** over a **full URL**. This is because the URL uses the hostname configured with +GitLab which may not match the request. This causes [cross-origin resource sharing issues like this Web IDE example](https://gitlab.com/gitlab-org/gitlab/-/issues/36810). Example: @@ -117,7 +116,7 @@ Example: ### 6. How should the Frontend reference Backend paths? -We prefer not to add extra coupling by hardcoding paths. If possible, +We prefer not to add extra coupling by hard-coding paths. If possible, add these paths as data attributes to the DOM element being referenced in the JavaScript. Example: @@ -153,7 +152,7 @@ export const fetchFoos = ({ state }) => { }; ``` -### 7. How can I test the production build locally? +### 7. How can one test the production build locally? Sometimes it's necessary to test locally what the frontend production build would produce, to do so the steps are: @@ -161,7 +160,7 @@ Sometimes it's necessary to test locally what the frontend production build woul 1. Open `gitlab.yaml` located in your `gitlab` installation folder, scroll down to the `webpack` section and change `dev_server` to `enabled: false`. 1. Run `yarn webpack-prod && gdk restart rails-web`. -The production build takes a few minutes to be completed; any code changes at this point are +The production build takes a few minutes to be completed. Any code changes at this point are displayed only after executing the item 3 above again. To return to the normal development mode: @@ -176,8 +175,8 @@ To return to the normal development mode: > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/28837) in GitLab 12.8. GitLab has enabled the Babel `preset-env` option -[`useBuiltIns: 'usage'`](https://babeljs.io/docs/en/babel-preset-env#usebuiltins-usage), -which adds the appropriate `core-js` polyfills once for each JavaScript feature +[`useBuiltIns: 'usage'`](https://babeljs.io/docs/en/babel-preset-env#usebuiltins-usage). +This adds the appropriate `core-js` polyfills once for each JavaScript feature we're using that our target browsers don't support. You don't need to add `core-js` polyfills manually. diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index cbaa648570c..a53d9fee029 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -18,34 +18,46 @@ info: "See the Technical Writers assigned to Development Guidelines: https://abo **GraphQL at GitLab**: -- [🎬 GitLab Unfiltered GraphQL playlist](https://www.youtube.com/watch?v=wHPKZBDMfxE&list=PL05JrBw4t0KpcjeHjaRMB7IGB2oDWyJzv) -- [🎬 GraphQL at GitLab: Deep Dive](../api_graphql_styleguide.md#deep-dive) (video) by Nick Thomas +<!-- vale gitlab.Spelling = NO --> + +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [GitLab Unfiltered GraphQL playlist](https://www.youtube.com/watch?v=wHPKZBDMfxE&list=PL05JrBw4t0KpcjeHjaRMB7IGB2oDWyJzv) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [GraphQL at GitLab: Deep Dive](../api_graphql_styleguide.md#deep-dive) (video) by Nick Thomas - An overview of the history of GraphQL at GitLab (not frontend-specific) -- [🎬 GitLab Feature Walkthrough with GraphQL and Vue Apollo](https://www.youtube.com/watch?v=6yYp2zB7FrM) (video) by Natalia Tepluhina +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [GitLab Feature Walkthrough with GraphQL and Vue Apollo](https://www.youtube.com/watch?v=6yYp2zB7FrM) (video) by Natalia Tepluhina - A real-life example of implementing a frontend feature in GitLab using GraphQL -- [🎬 History of client-side GraphQL at GitLab](https://www.youtube.com/watch?v=mCKRJxvMnf0) (video) Illya Klymov and Natalia Tepluhina -- [🎬 From Vuex to Apollo](https://www.youtube.com/watch?v=9knwu87IfU8) (video) by Natalia Tepluhina - - A useful overview of when Apollo might be a better choice than Vuex, and how one could go about the transition +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [History of client-side GraphQL at GitLab](https://www.youtube.com/watch?v=mCKRJxvMnf0) (video) Illya Klymov and Natalia Tepluhina +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [From Vuex to Apollo](https://www.youtube.com/watch?v=9knwu87IfU8) (video) by Natalia Tepluhina + - An overview of when Apollo might be a better choice than Vuex, and how one could go about the transition - [🛠 Vuex -> Apollo Migration: a proof-of-concept project](https://gitlab.com/ntepluhina/vuex-to-apollo/blob/master/README.md) - A collection of examples that show the possible approaches for state management with Vue+GraphQL+(Vuex or Apollo) apps +<!-- vale gitlab.Spelling = YES --> + ### Libraries We use [Apollo](https://www.apollographql.com/) (specifically [Apollo Client](https://www.apollographql.com/docs/react/)) and [Vue Apollo](https://github.com/vuejs/vue-apollo) when using GraphQL for frontend development. -If you are using GraphQL within a Vue application, the [Usage in Vue](#usage-in-vue) section +If you are using GraphQL in a Vue application, the [Usage in Vue](#usage-in-vue) section 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. +<!-- vale gitlab.Spelling = NO --> + 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. +<!-- vale gitlab.Spelling = YES --> + ### Tooling +<!-- vale gitlab.Spelling = NO --> + - [Apollo Client Devtools](https://github.com/apollographql/apollo-client-devtools) +<!-- vale gitlab.Spelling = YES --> + #### [Apollo GraphQL VS Code extension](https://marketplace.visualstudio.com/items?itemName=apollographql.vscode-apollo) If you use VS Code, the Apollo GraphQL extension supports autocompletion in `.graphql` files. To set up @@ -76,7 +88,7 @@ Our GraphQL API can be explored via GraphiQL at your instance's where needed. You can check all existing queries and mutations on the right side -of GraphiQL in its **Documentation explorer**. It's also possible to +of GraphiQL in its **Documentation explorer**. You can also write queries and mutations directly on the left tab and check their execution by clicking **Execute query** button on the top left: @@ -93,8 +105,8 @@ Default client accepts two parameters: `resolvers` and `config`. - `resolvers` parameter is created to accept an object of resolvers for [local state management](#local-state-with-apollo) queries and mutations - `config` parameter takes an object of configuration settings: - `cacheConfig` field accepts an optional object of settings to [customize Apollo cache](https://www.apollographql.com/docs/react/caching/cache-configuration/#configuring-the-cache) - - `baseUrl` allows us to pass a URL for GraphQL endpoint different from our main endpoint (i.e.`${gon.relative_url_root}/api/graphql`) - - `assumeImmutableResults` (set to `false` by default) - this setting, when set to `true`, will assume that every single operation on updating Apollo Cache is immutable. It also sets `freezeResults` to `true`, so any attempt on mutating Apollo Cache will throw a console warning in development environment. Please ensure you're following the immutability pattern on cache update operations before setting this option to `true`. + - `baseUrl` allows us to pass a URL for GraphQL endpoint different from our main endpoint (for example, `${gon.relative_url_root}/api/graphql`) + - `assumeImmutableResults` (set to `false` by default) - this setting, when set to `true`, assumes that every single operation on updating Apollo Cache is immutable. It also sets `freezeResults` to `true`, so any attempt on mutating Apollo Cache throws a console warning in development environment. Please ensure you're following the immutability pattern on cache update operations before setting this option to `true`. - `fetchPolicy` determines how you want your component to interact with the Apollo cache. Defaults to "cache-first". ## GraphQL Queries @@ -139,7 +151,7 @@ fragment DesignItem on Design { ``` More about fragments: -[GraphQL Docs](https://graphql.org/learn/queries/#fragments) +[GraphQL documentation](https://graphql.org/learn/queries/#fragments) ## Global IDs @@ -157,12 +169,17 @@ 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 +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). +<!-- vale gitlab.Spelling = NO --> + +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: +<!-- vale gitlab.Spelling = YES --> + - The updated cache is named `data`. - The original cache data is named `sourceData`. @@ -184,10 +201,10 @@ client.writeQuery({ ``` 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. +`draftState`. Besides, `immer` guarantees that a new state which includes the changes to `draftState` is generated. Finally, to verify whether the immutable cache update is working properly, we need to change -`assumeImmutableResults` to `true` in the default client configuration (see [Apollo Client](#apollo-client) for more information). +`assumeImmutableResults` to `true` in the default client configuration. See [Apollo Client](#apollo-client) for more information. If everything is working properly `assumeImmutableResults` should remain set to `true`. @@ -259,11 +276,11 @@ query User { } ``` -Along with creating local data, we can also extend existing GraphQL types with `@client` fields. This is extremely useful when we need to mock an API responses for fields not yet added to our GraphQL API. +Along with creating local data, we can also extend existing GraphQL types with `@client` fields. This is extremely helpful when we need to mock an API response for fields not yet added to our GraphQL API. #### Mocking API response with local Apollo cache -Using local Apollo Cache is handy when we have a need to mock some GraphQL API responses, queries or mutations locally (e.g. when they're still not added to our actual API). +Using local Apollo Cache is helpful when we have a need to mock some GraphQL API responses, queries, or mutations locally (such as when they're still not added to our actual API). For example, we have a [fragment](#fragments) on `DesignVersion` used in our queries: @@ -274,7 +291,7 @@ fragment VersionListItem on DesignVersion { } ``` -We need to fetch also version author and the 'created at' property to display them in the versions dropdown but these changes are still not implemented in our API. We can change the existing fragment to get a mocked response for these new fields: +We also need to fetch the version author and the `created at` property to display in the versions dropdown. But, these changes are still not implemented in our API. We can change the existing fragment to get a mocked response for these new fields: ```javascript fragment VersionListItem on DesignVersion { @@ -288,7 +305,7 @@ fragment VersionListItem on DesignVersion { } ``` -Now Apollo will try to find a _resolver_ for every field marked with `@client` directive. Let's create a resolver for `DesignVersion` type (why `DesignVersion`? because our fragment was created on this type). +Now Apollo tries to find a _resolver_ for every field marked with `@client` directive. Let's create a resolver for `DesignVersion` type (why `DesignVersion`? because our fragment was created on this type). ```javascript // resolvers.js @@ -319,13 +336,13 @@ import resolvers from './graphql/resolvers'; const defaultClient = createDefaultClient(resolvers); ``` -For each attempt to fetch a version, our client will fetch `id` and `sha` from the remote API endpoint and will assign our hardcoded values to the `author` and `createdAt` version properties. With this data, frontend developers are able to work on their UI without being blocked by backend. When the actual response is added to the API, our custom local resolver can be removed and the only change to the query/fragment is to remove the `@client` directive. +For each attempt to fetch a version, our client fetches `id` and `sha` from the remote API endpoint. It then assigns our hardcoded values to the `author` and `createdAt` version properties. With this data, frontend developers are able to work on their UI without being blocked by backend. When the response is added to the API, our custom local resolver can be removed. The only change to the query/fragment is to remove the `@client` directive. Read more about local state management with Apollo in the [Vue Apollo documentation](https://vue-apollo.netlify.app/guide/local-state.html#local-state). ### Using with Vuex -When Apollo Client is used within Vuex and fetched data is stored in the Vuex store, there is no need to keep Apollo Client cache enabled. Otherwise we would have data from the API stored in two places - Vuex store and Apollo Client cache. With Apollo's default settings, a subsequent fetch from the GraphQL API could result in fetching data from Apollo cache (in the case where we have the same query and variables). To prevent this behavior, we need to disable Apollo Client cache by passing a valid `fetchPolicy` option to its constructor: +When the Apollo Client is used in Vuex and fetched data is stored in the Vuex store, the Apollo Client cache does not need to be enabled. Otherwise we would have data from the API stored in two places - Vuex store and Apollo Client cache. With Apollo's default settings, a subsequent fetch from the GraphQL API could result in fetching data from Apollo cache (in the case where we have the same query and variables). To prevent this behavior, we need to disable Apollo Client cache by passing a valid `fetchPolicy` option to its constructor: ```javascript import fetchPolicies from '~/graphql_shared/fetch_policy_constants'; @@ -338,11 +355,61 @@ export const gqClient = createGqClient( ); ``` -### Feature flags in queries +### Working on GraphQL-based features when frontend and backend are not in sync + +Any feature that requires GraphQL queries/mutations to be created or updated should be carefully +planned. Frontend and backend counterparts should agree on a schema that satisfies both client-side and +server-side requirements. This enables both departments to start implementing their parts without +blocking each other. + +Ideally, the backend implementation should be done prior to the frontend so that the client can +immediately start querying the API with minimal back and forth between departments. However, we +recognize that priorities don't always align. For the sake of iteration and +delivering work we're committed to, it might be necessary for the frontend to be implemented ahead +of the backend. + +#### Implementing frontend queries and mutations ahead of the backend -Sometimes it may be useful to have an entity in the GraphQL query behind a feature flag. -For example, when working on a feature where the backend has already been merged but the frontend -hasn't you might want to put the GraphQL entity behind a feature flag to allow for smaller +In such case, the frontend will define GraphQL schemas or fields that do not correspond to any +backend resolver yet. This is fine as long as the implementation is properly feature-flagged so it +does not translate to public-facing errors in the product. However, we do validate client-side +queries/mutations against the backend GraphQL schema with the `graphql-verify` CI job. +You must confirm your changes pass the validation if they are to be merged before the +backend actually supports them. Below are a few suggestions to go about this. + +##### Using the `@client` directive + +The preferred approach is to use the `@client` directive on any new query, mutation, or field that +isn't yet supported by the backend. Any entity with the directive is skipped by the +`graphql-verify` validation job. + +Additionally Apollo will attempt to resolve them client-side, which can be used in conjunction with +[Mocking API response with local Apollo cache](#mocking-api-response-with-local-apollo-cache). This +provides a convenient way of testing your feature with fake data defined client-side. +When opening a merge request for your changes, it can be a good idea to provide local resolvers as a +patch that reviewers can apply in their GDK to easily smoke-test your work. + +Make sure to track the removal of the directive in a follow-up issue, or as part of the backend +implementation plan. + +##### Adding an exception to the list of known failures + +GraphQL queries/mutations validation can be completely turned off for specific files by adding their +paths to the +[`config/known_invalid_graphql_queries.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/known_invalid_graphql_queries.yml) +file, much like you would disable ESLint for some files via an `.eslintignore` file. +Bear in mind that any file listed in here will not be validated at all. So if you're only adding +fields to an existing query, use the `@client` directive approach so that the rest of the query +is still validated. + +Again, make sure that those overrides are as short-lived as possible by tracking their removal in +the appropriate issue. + +#### Feature flags in queries + +Sometimes it may be helpful to have an entity in the GraphQL query behind a feature flag. +One example is working on a feature where the backend has already been merged but the frontend +has not. In this case, you may consider putting the GraphQL entity behind a feature flag to allow smaller merge requests to be created and merged. To do this we can use the `@include` directive to exclude an entity if the `if` statement passes. @@ -355,7 +422,7 @@ query getAuthorData($authorNameEnabled: Boolean = false) { ``` Then in the Vue (or JavaScript) call to the query we can pass in our feature flag. This feature -flag will need to be already setup correctly. See the [feature flag documentation](../feature_flags/development.md) +flag needs to be already set up correctly. See the [feature flag documentation](../feature_flags/development.md) for the correct way to do this. ```javascript @@ -469,7 +536,7 @@ Note that we are using the [`pageInfo.fragment.graphql`](https://gitlab.com/gitl #### Using `fetchMore` method in components -This approach makes sense to use with user-handled pagination (e.g. when the scrolls to fetch more data or explicitly clicks a "Next Page"-button). +This approach makes sense to use with user-handled pagination. For example, when the scrolling to fetch more data or explicitly clicking a **Next Page** button. When we need to fetch all the data initially, it is recommended to use [a (non-smart) query, instead](#using-a-recursive-query-in-components). When making an initial fetch, we usually want to start a pagination from the beginning. @@ -479,7 +546,7 @@ In this case, we can either: - Pass `null` explicitly to `after`. After data is fetched, we can use the `update`-hook as an opportunity [to customize -the data that is set in the Vue component property](https://apollo.vuejs.org/api/smart-query.html#options), getting a hold of the `pageInfo` object among other data. +the data that is set in the Vue component property](https://apollo.vuejs.org/api/smart-query.html#options). This allows us to get a hold of the `pageInfo` object among other data. In the `result`-hook, we can inspect the `pageInfo` object to see if we need to fetch the next page. Note that we also keep a `requestCount` to ensure that the application @@ -561,8 +628,8 @@ fetchNextPage(endCursor) { When it is necessary to fetch all paginated data initially an Apollo query can do the trick for us. If we need to fetch the next page based on user interactions, it is recommend to use a [`smartQuery`](https://apollo.vuejs.org/api/smart-query.html) along with the [`fetchMore`-hook](#using-fetchmore-method-in-components). -When the query resolves we can update the component data and inspect the `pageInfo` object -to see if we need to fetch the next page, i.e. call the method recursively. +When the query resolves we can update the component data and inspect the `pageInfo` object. This allows us +to see if we need to fetch the next page, calling the method recursively. Note that we also keep a `requestCount` to ensure that the application does not keep requesting the next page, indefinitely. @@ -634,7 +701,7 @@ or [`.writeQuery()`](https://www.apollographql.com/docs/react/v2/api/apollo-clie This can be tedious and counter-intuitive. To make it easier to deal with cached paginated queries, Apollo provides the `@connection` directive. -The directive accepts a `key` parameter that will be used as a static key when caching the data. +The directive accepts a `key` parameter that is used as a static key when caching the data. You'd then be able to retrieve the data without providing any pagination-specific variables. Here's an example of a query using the `@connection` directive: @@ -661,7 +728,7 @@ query DastSiteProfiles($fullPath: ID!, $after: String, $before: String, $first: } ``` -In this example, Apollo will store the data with the stable `dastSiteProfiles` cache key. +In this example, Apollo stores the data with the stable `dastSiteProfiles` cache key. To retrieve that data from the cache, you'd then only need to provide the `$fullPath` variable, omitting pagination-specific variables like `after` or `before`: @@ -679,9 +746,9 @@ Read more about the `@connection` directive in [Apollo's documentation](https:// ### Managing performance -The Apollo client will batch queries by default. This means that if you have 3 queries defined, -Apollo will group them into one request, send the single request off to the server and only -respond once all 3 queries have completed. +The Apollo client batches queries by default. Given 3 deferred queries, +Apollo groups them into one request, sends the single request to the server, and +responds after all 3 queries have completed. If you need to have queries sent as individual requests, additional context can be provided to tell Apollo to do this. @@ -703,9 +770,13 @@ export default { #### Mocking response as component data -With [Vue test utils](https://vue-test-utils.vuejs.org/) it is easy to quickly test components that +<!-- vale gitlab.Spelling = NO --> + +With [Vue Test Utils](https://vue-test-utils.vuejs.org/) one can quickly test components that fetch GraphQL queries. The simplest way is to use `shallowMount` and then set -the data on the component +the data on the component: + +<!-- vale gitlab.Spelling = YES --> ```javascript it('tests apollo component', () => { @@ -719,7 +790,7 @@ it('tests apollo component', () => { #### Testing loading state -If we need to test how our component renders when results from the GraphQL API are still loading, we can mock a loading state into respective Apollo queries/mutations: +To test how a component renders when results from the GraphQL API are still loading, mock a loading state into respective Apollo queries/mutations: ```javascript function createComponent({ @@ -817,9 +888,9 @@ it('calls mutation on submitting form ', () => { To test the logic of Apollo cache updates, we might want to mock an Apollo Client in our unit tests. We use [`mock-apollo-client`](https://www.npmjs.com/package/mock-apollo-client) library to mock Apollo client and [`createMockApollo` helper](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/frontend/__helpers__/mock_apollo_helper.js) we created on top of it. -To separate tests with mocked client from 'usual' unit tests, it's recommended to create an additional factory and pass the created `mockApollo` as an option to the `createComponent`-factory. This way we only create Apollo Client instance when it's necessary. +To separate tests with mocked client from 'usual' unit tests, create an additional factory and pass the created `mockApollo` as an option to the `createComponent`-factory. This way we only create Apollo Client instance when it's necessary. -We need to inject `VueApollo` to the Vue local instance and, likewise, it is recommended to call `localVue.use()` within `createMockApolloProvider()` to only load it when it is necessary. +We need to inject `VueApollo` to the Vue local instance and, likewise, it is recommended to call `localVue.use()` in `createMockApolloProvider()` to only load it when it is necessary. ```javascript import VueApollo from 'vue-apollo'; @@ -861,7 +932,7 @@ describe('Some component', () => { }); ``` -Within `createMockApolloProvider`-factory, we need to define an array of _handlers_ for every query or mutation: +In the `createMockApolloProvider`-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'; @@ -1251,9 +1322,9 @@ describe('My Index test with `createMockApollo`', () => { ## Handling errors -The GitLab GraphQL mutations currently have two distinct error modes: [Top-level](#top-level-errors) and [errors-as-data](#errors-as-data). +The GitLab GraphQL mutations have two distinct error modes: [Top-level](#top-level-errors) and [errors-as-data](#errors-as-data). -When utilising a GraphQL mutation, we must consider handling **both of these error modes** to ensure that the user receives the appropriate feedback when an error occurs. +When utilising a GraphQL mutation, consider handling **both of these error modes** to ensure that the user receives the appropriate feedback when an error occurs. ### Top-level errors @@ -1261,13 +1332,13 @@ These errors are located at the "top level" of a GraphQL response. These are non #### Handling top-level errors -Apollo is aware of top-level errors, so we are able to leverage Apollo's various error-handling mechanisms to handle these errors (e.g. handling Promise rejections after invoking the [`mutate`](https://www.apollographql.com/docs/react/api/core/ApolloClient/#ApolloClient.mutate) method, or handling the `error` event emitted from the [`ApolloMutation`](https://apollo.vuejs.org/api/apollo-mutation.html#events) component). +Apollo is aware of top-level errors, so we are able to leverage Apollo's various error-handling mechanisms to handle these errors. For example, handling Promise rejections after invoking the [`mutate`](https://www.apollographql.com/docs/react/api/core/ApolloClient/#ApolloClient.mutate) method, or handling the `error` event emitted from the [`ApolloMutation`](https://apollo.vuejs.org/api/apollo-mutation.html#events) component. Because these errors are not intended for users, error messages for top-level errors should be defined client-side. ### Errors-as-data -These errors are nested within the `data` object of a GraphQL response. These are recoverable errors that, ideally, can be presented directly to the user. +These errors are nested in the `data` object of a GraphQL response. These are recoverable errors that, ideally, can be presented directly to the user. #### Handling errors-as-data @@ -1283,7 +1354,7 @@ mutation createNoteMutation($input: String!) { } ``` -Now, when we commit this mutation and errors occur, the response will include `errors` for us to handle: +Now, when we commit this mutation and errors occur, the response includes `errors` for us to handle: ```javascript { @@ -1316,7 +1387,7 @@ When [using Vuex](#using-with-vuex), disable the cache when: - The data is being cached elsewhere - The use case does not need caching -if the data is being cached elsewhere, or if there is simply no need for it for the given use case. +if the data is being cached elsewhere, or if there is no need for it for the given use case. ```javascript import createDefaultClient from '~/lib/graphql'; @@ -1416,7 +1487,7 @@ for your application. To add GraphQL startup calls, we use `add_page_startup_graphql_call` helper where the first parameter is a path to the query, the second one is an object containing query variables. Path to the query is relative to `app/graphql/queries` folder: for example, if we need a -`app/graphql/queries/repository/files.query.graphql` query, the path will be +`app/graphql/queries/repository/files.query.graphql` query, the path is `repository/files`. ```yaml diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index af587a31bbb..821334e3008 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.md @@ -26,12 +26,16 @@ To use a sprite Icon in HAML or Rails we use a specific helper function: sprite_icon(icon_name, size: nil, css_class: '') ``` +<!-- vale gitlab.Spelling = NO --> + - **icon_name**: Use the icon_name for the SVG sprite in the list of ([GitLab SVGs](https://gitlab-org.gitlab.io/gitlab-svgs)). - **size (optional)**: Use one of the following sizes : 16, 24, 32, 48, 72 (this is translated into a `s16` class) - **css_class (optional)**: If you want to add additional CSS classes. +<!-- vale gitlab.Spelling = YES --> + **Example** ```haml @@ -100,7 +104,7 @@ by the examples that follow: - `container` (optional): wraps the loading icon in a container, which centers the loading icon using the `text-center` CSS property. - `color` (optional): either `orange` (default), `light`, or `dark`. - `size` (optional): either `sm` (default), `md`, `lg`, or `xl`. -- `css_class` (optional): defaults to an empty string, but can be useful for utility classes to fine-tune alignment or spacing. +- `css_class` (optional): defaults to an empty string, but can be used for utility classes to fine-tune alignment or spacing. **Example 1:** @@ -164,8 +168,8 @@ export default { ## SVG Illustrations -Please use from now on for any SVG based illustrations simple `img` tags to show an illustration by simply using either `image_tag` or `image_path` helpers. -Please use the class `svg-content` around it to ensure nice rendering. +From now on, use `img` tags to display any SVG based illustrations with either `image_tag` or `image_path` helpers. +Using the class `svg-content` around it ensures nice rendering. ### Usage in HAML/Rails diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 84c1623f8c0..f590473c3c3 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -11,7 +11,7 @@ across the GitLab frontend team. ## Overview -GitLab is built on top of [Ruby on Rails](https://rubyonrails.org) using [Haml](https://haml.info/) and also a JavaScript based Frontend with [Vue.js](https://vuejs.org). +GitLab is built on top of [Ruby on Rails](https://rubyonrails.org). It uses [Haml](https://haml.info/) and a JavaScript0based frontend with [Vue.js](https://vuejs.org). Be wary of [the limitations that come with using Hamlit](https://github.com/k0kubun/hamlit/blob/master/REFERENCE.md#limitations). We also use [SCSS](https://sass-lang.com) and plain JavaScript with modern ECMAScript standards supported through [Babel](https://babeljs.io/) and ES module support through [webpack](https://webpack.js.org/). @@ -21,7 +21,7 @@ Working with our frontend assets requires Node (v10.13.0 or greater) and Yarn ### Browser Support -For our currently-supported browsers, see our [requirements](../../install/requirements.md#supported-web-browsers). +For supported browsers, see our [requirements](../../install/requirements.md#supported-web-browsers). Use [BrowserStack](https://www.browserstack.com/) to test with our supported browsers. Sign in to BrowserStack with the credentials saved in the **Engineering** vault of the GitLab @@ -121,3 +121,7 @@ Our accessibility standards and resources. Frontend internationalization support is described in [this document](../i18n/). The [externalization part of the guide](../i18n/externalization.md) explains the helpers/methods available. + +## [Troubleshooting](troubleshooting.md) + +Running into a Frontend development problem? Check out [this guide](troubleshooting.md) to help resolve your issue. diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index aac2258f3a3..2a1c3daa6b8 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -202,15 +202,15 @@ help identify marks and measures coming from the different apps on the same page ## Best Practices -### Realtime Components +### Real-time Components -When writing code for realtime features we have to keep a couple of things in mind: +When writing code for real-time features we have to keep a couple of things in mind: 1. Do not overload the server with requests. -1. It should feel realtime. +1. It should feel real-time. -Thus, we must strike a balance between sending requests and the feeling of realtime. -Use the following rules when creating realtime solutions. +Thus, we must strike a balance between sending requests and the feeling of real-time. +Use the following rules when creating real-time solutions. 1. The server tells you how much to poll by sending `Poll-Interval` in the header. Use that as your polling interval. This enables system administrators to change the @@ -221,7 +221,7 @@ Use the following rules when creating realtime solutions. 1. Poll on active tabs only. Please use [Visibility](https://github.com/ai/visibilityjs). 1. Use regular polling intervals, do not use backoff polling, or jitter, as the interval is controlled by the server. -1. The backend code is likely to be using etags. You do not and should not check for status +1. The backend code is likely to be using ETags. You do not and should not check for status `304 Not Modified`. The browser transforms it for you. ### Lazy Loading Images @@ -230,12 +230,12 @@ To improve the time to first render we are using lazy loading for images. This w the actual image source on the `data-src` attribute. After the HTML is rendered and JavaScript is loaded, the value of `data-src` is moved to `src` automatically if the image is in the current viewport. -- Prepare images in HTML for lazy loading by renaming the `src` attribute to `data-src` AND adding the class `lazy`. +- Prepare images in HTML for lazy loading by renaming the `src` attribute to `data-src` and adding the class `lazy`. - If you are using the Rails `image_tag` helper, all images are lazy-loaded by default unless `lazy: false` is provided. -If you are asynchronously adding content which contains lazy images then you need to call the function +When asynchronously adding content which contains lazy images, call the function `gl.lazyLoader.searchLazyImages()` which searches for lazy images and loads them if needed. -But in general it should be handled automatically through a `MutationObserver` in the lazy loading function. +In general, it should be handled automatically through a `MutationObserver` in the lazy loading function. ### Animations @@ -243,7 +243,7 @@ Only animate `opacity` & `transform` properties. Other properties (such as `top` Layout to be recalculated, which is much more expensive. For details on this, see "Styles that Affect Layout" in [High Performance Animations](https://www.html5rocks.com/en/tutorials/speed/high-performance-animations/). -If you _do_ need to change layout (for example, a sidebar that pushes main content over), prefer [FLIP](https://aerotwist.com/blog/flip-your-animations/) to change expensive +If you _do_ need to change layout (for example, a sidebar that pushes main content over), prefer [FLIP](https://aerotwist.com/blog/flip-your-animations/). FLIP allows you to change expensive properties once, and handle the actual animation with transforms. ## Reducing Asset Footprint @@ -251,7 +251,7 @@ properties once, and handle the actual animation with transforms. ### Universal code Code that is contained in `main.js` and `commons/index.js` is loaded and -run on _all_ pages. **DO NOT ADD** anything to these files unless it is truly +run on _all_ pages. **Do not add** anything to these files unless it is truly needed _everywhere_. These bundles include ubiquitous libraries like `vue`, `axios`, and `jQuery`, as well as code for the main navigation and sidebar. Where possible we should aim to remove modules from these bundles to reduce our @@ -277,9 +277,9 @@ manually generated webpack bundles. However under this new system you should not ever need to manually add an entry point to the `webpack.config.js` file. NOTE: -If you are unsure what controller and action corresponds to a given page, you -can find this out by inspecting `document.body.dataset.page` in your -browser's developer console while on any page in GitLab. +When unsure what controller and action corresponds to a page, +inspect `document.body.dataset.page` in your +browser's developer console from any page in GitLab. #### Important Considerations @@ -294,7 +294,7 @@ browser's developer console while on any page in GitLab. All GitLab JavaScript files are added with the `defer` attribute. According to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-defer), this implies that "the script is meant to be executed after the document has - been parsed, but before firing `DOMContentLoaded`". Since the document is already + been parsed, but before firing `DOMContentLoaded`". Because the document is already parsed, `DOMContentLoaded` is not needed to bootstrap applications because all the DOM nodes are already at our disposal. @@ -333,7 +333,7 @@ browser's developer console while on any page in GitLab. action(); ``` - For example, see how we use this in [app/assets/javascripts/pages/projects/graphs/charts/index.js](https://gitlab.com/gitlab-org/gitlab/-/commit/5e90885d6afd4497002df55bf015b338efcfc3c5#02e81de37f5b1716a3ef3222fa7f7edf22c40969_9_8): + For example, see how we use this in [`app/assets/javascripts/pages/projects/graphs/charts/index.js`](https://gitlab.com/gitlab-org/gitlab/-/commit/5e90885d6afd4497002df55bf015b338efcfc3c5#02e81de37f5b1716a3ef3222fa7f7edf22c40969_9_8): ```javascript waitForCSSLoaded(() => { @@ -366,9 +366,9 @@ browser's developer console while on any page in GitLab. ### Code Splitting -For any code that does not need to be run immediately upon page load, (for example, -modals, dropdowns, and other behaviors that can be lazy-loaded), you can split -your module into asynchronous chunks with dynamic import statements. These +Code that does not need to be run immediately upon page load (for example, +modals, dropdowns, and other behaviors that can be lazy-loaded) should be split +into asynchronous chunks with dynamic import statements. These imports return a Promise which is resolved after the script has loaded: ```javascript @@ -377,16 +377,16 @@ import(/* webpackChunkName: 'emoji' */ '~/emoji') .catch(/* report error */) ``` -Please try to use `webpackChunkName` when generating these dynamic imports as +Use `webpackChunkName` when generating dynamic imports as it provides a deterministic filename for the chunk which can then be cached -the browser across GitLab versions. +in the browser across GitLab versions. More information is available in [webpack's code splitting documentation](https://webpack.js.org/guides/code-splitting/#dynamic-imports). ### Minimizing page size -A smaller page size means the page loads faster (especially important on mobile -and poor connections), the page is parsed more quickly by the browser, and less +A smaller page size means the page loads faster, especially on mobile +and poor connections. The page is parsed more quickly by the browser, and less data is used for users with capped data plans. General tips: diff --git a/doc/development/fe_guide/security.md b/doc/development/fe_guide/security.md index 627c5f4d12f..df4613d521d 100644 --- a/doc/development/fe_guide/security.md +++ b/doc/development/fe_guide/security.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Resources -[Mozilla’s HTTP Observatory CLI](https://github.com/mozilla/http-observatory-cli) and the +[Mozilla’s HTTP Observatory CLI](https://github.com/mozilla/http-observatory-cli) and [Qualys SSL Labs Server Test](https://www.ssllabs.com/ssltest/analyze.html) are good resources for finding potential problems and ensuring compliance with security best practices. @@ -76,7 +76,7 @@ such as with reCAPTCHA, which cannot be used without an `iframe`. In order to protect users from [XSS vulnerabilities](https://en.wikipedia.org/wiki/Cross-site_scripting), we intend to disable inline scripts in the future using Content Security Policy. -While inline scripts can be useful, they're also a security concern. If +While inline scripts can make something easier, they're also a security concern. If user-supplied content is unintentionally left un-sanitized, malicious users can inject scripts into the web app. diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md deleted file mode 100644 index 73a5bea189d..00000000000 --- a/doc/development/fe_guide/style_guide_js.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'style/javascript.md' ---- - -This document was moved to [another location](style/javascript.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/fe_guide/style_guide_scss.md b/doc/development/fe_guide/style_guide_scss.md deleted file mode 100644 index eaa6d33fb43..00000000000 --- a/doc/development/fe_guide/style_guide_scss.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'style/scss.md' ---- - -This document was moved to [another location](style/scss.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/fe_guide/testing.md b/doc/development/fe_guide/testing.md deleted file mode 100644 index 457d15235ae..00000000000 --- a/doc/development/fe_guide/testing.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../testing_guide/frontend_testing.md' ---- - -This document was moved to [another location](../testing_guide/frontend_testing.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/fe_guide/tooling.md b/doc/development/fe_guide/tooling.md index d33022b9355..7a2d8fccdbf 100644 --- a/doc/development/fe_guide/tooling.md +++ b/doc/development/fe_guide/tooling.md @@ -111,7 +111,7 @@ preferred editor (all major editors are supported) accordingly. We suggest setting up Prettier to run when each file is saved. For instructions about using Prettier in your preferred editor, see the [Prettier documentation](https://prettier.io/docs/en/editors.html). -Please take care that you only let Prettier format the same file types as the global Yarn script does (`.js`, `.vue`, `.graphql`, and `.scss`). In VSCode by example you can easily exclude file formats in your settings file: +Please take care that you only let Prettier format the same file types as the global Yarn script does (`.js`, `.vue`, `.graphql`, and `.scss`). For example, you can exclude file formats in your Visual Studio Code settings file: ```json "prettier.disableLanguages": [ @@ -128,13 +128,13 @@ The following yarn scripts are available to do global formatting: yarn prettier-staged-save ``` -Updates all currently staged files (based on `git diff`) with Prettier and saves the needed changes. +Updates all staged files (based on `git diff`) with Prettier and saves the needed changes. ```shell yarn prettier-staged ``` -Checks all currently staged files (based on `git diff`) with Prettier and log which files would need manual updating to the console. +Checks all staged files (based on `git diff`) with Prettier and log which files would need manual updating to the console. ```shell yarn prettier-all diff --git a/doc/development/fe_guide/troubleshooting.md b/doc/development/fe_guide/troubleshooting.md new file mode 100644 index 00000000000..abaf9cd68c7 --- /dev/null +++ b/doc/development/fe_guide/troubleshooting.md @@ -0,0 +1,41 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Troubleshooting + +Running into a problem? Maybe this will help ¯\＿(ツ)＿/¯. + +## Troubleshooting issues + +### This guide doesn't contain the issue I ran into + +If you run into a Frontend development issue that is not in this guide, please consider updating this guide with your issue and possible remedies. This way future adventurers can face these dragons with more success, being armed with your experience and knowledge. + +## Testing issues + +### ``Property or method `nodeType` is not defined`` but I'm not using `nodeType` anywhere + +This issue can happen in Vue component tests, when an expectation fails, but there is an error thrown when +Jest tries to pretty print the diff in the console. It's been noted that using `toEqual` with an array as a +property might also be a contributing factor. + +See [this video](https://youtu.be/-BkEhghP-kM) for an in-depth overview and investigation. + +**Remedy - Try cloning the object that has Vue watchers** + +```patch +- expect(wrapper.find(ChildComponent).props()).toEqual(...); ++ expect(cloneDeep(wrapper.find(ChildComponent).props())).toEqual(...) +``` + +**Remedy - Try using `toMatchObject` instead of `toEqual`** + +```patch +- expect(wrapper.find(ChildComponent).props()).toEqual(...); ++ expect(wrapper.find(ChildComponent).props()).toMatchObject(...); +``` + +Please note that `toMatchObject` actually changes the nature of the assertion and won't fail if some items are **missing** from the expectation. diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index b3fbb9556a9..79ccd966bca 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -22,7 +22,7 @@ All new features built with Vue.js must follow a [Flux architecture](https://fac The main goal we are trying to achieve is to have only one data flow and only one data entry. In order to achieve this goal we use [vuex](#vuex). -You can also read about this architecture in Vue docs about +You can also read about this architecture in Vue documentation about [state management](https://vuejs.org/v2/guide/state-management.html#Simple-State-Management-from-Scratch) and about [one way data flow](https://vuejs.org/v2/guide/components.html#One-Way-Data-Flow). @@ -70,7 +70,7 @@ The advantage of providing data from the DOM to the Vue instance through `props` function instead of querying the DOM inside the main Vue component is avoiding the need to create a fixture or an HTML element in the unit test, which makes the tests easier. -See the following example, also, please refer to our [Vue style guide](style/vue.md#basic-rules) for +See the following example. Also, please refer to our [Vue style guide](style/vue.md#basic-rules) for additional information on why we explicitly declare the data being passed into the Vue app; ```javascript @@ -101,8 +101,8 @@ across the codebase. #### Accessing the `gl` object -When we need to query the `gl` object for data that doesn't change during the application's life -cycle, we should do it in the same place where we query the DOM. By following this practice, we can +We query the `gl` object for data that doesn't change during the application's life +cycle in the same place we query the DOM. By following this practice, we can avoid the need to mock the `gl` object, which makes tests easier. It should be done while initializing our Vue instance, and the data should be provided as `props` to the main component: @@ -148,8 +148,8 @@ This approach has a few benefits: - Arbitrarily deeply nested components can opt-in and access the flag without intermediate components being aware of it (c.f. passing the flag down via props). -- Good testability, since the flag can be provided to `mount`/`shallowMount` - from `vue-test-utils` simply as a prop. +- Good testability, because the flag can be provided to `mount`/`shallowMount` + from `vue-test-utils` as a prop. ```javascript import { shallowMount } from '@vue/test-utils'; @@ -207,20 +207,20 @@ Based on the Vue guidance: such as `user: new User()`. - **Do not** add new JavaScript class implementations. - **Do** use [GraphQL](../api_graphql_styleguide.md), [Vuex](vuex.md) or a set of components if -cannot use simple primitives or objects. +cannot use primitives or objects. - **Do** maintain existing implementations using such approaches. - **Do** Migrate components to a pure object model when there are substantial changes to it. -- **Do** add business logic to helpers or utils, so you can test them separately from your component. +- **Do** add business logic to helpers or utilities, so you can test them separately from your component. #### Why There are additional reasons why having a JavaScript class presents maintainability issues on a huge codebase: -- Once a class is created, it is easy to extend it in a way that can infringe Vue reactivity and best practices. +- After a class is created, it can be extended in a way that can infringe Vue reactivity and best practices. - A class adds a layer of abstraction, which makes the component API and its inner workings less clear. -- It makes it harder to test. Since the class is instantiated by the component data function, it is +- It makes it harder to test. Because the class is instantiated by the component data function, it is harder to 'manage' component and class separately. -- Adding OOP to a functional codebase adds yet another way of writing code, reducing consistency and clarity. +- Adding Object Oriented Principles (OOP) to a functional codebase adds yet another way of writing code, reducing consistency and clarity. ## Style guide @@ -234,8 +234,8 @@ for guidelines and best practices for testing your Vue components. Each Vue component has a unique output. This output is always present in the render function. -Although we can test each method of a Vue component individually, our goal must be to test the output -of the render/template function, which represents the state at all times. +Although each method of a Vue component can be tested individually, our goal is to test the output +of the render function, which represents the state at all times. Here's an example of a well structured unit test for [this Vue component](#appendix---vue-component-subject-under-test): @@ -366,7 +366,7 @@ component under test, with the `computed` property, for example). Remember to us ### Events -We should test for events emitted in response to an action within our component, this is useful to +We should test for events emitted in response to an action in our component. This is used to verify the correct events are being fired with the correct arguments. For any DOM events we should use [`trigger`](https://vue-test-utils.vuejs.org/api/wrapper/#trigger) @@ -416,7 +416,7 @@ You should only apply to be a Vue.js expert when your own merge requests and you > This section is added temporarily to support the efforts to migrate the codebase from Vue 2.x to Vue 3.x -Currently, we recommend to minimize adding certain features to the codebase to prevent increasing +We recommend to minimize adding certain features to the codebase to prevent increasing the tech debt for the eventual migration: - filters; diff --git a/doc/development/fe_guide/vue3_migration.md b/doc/development/fe_guide/vue3_migration.md index 9d2f3b27968..90bf46d9ad9 100644 --- a/doc/development/fe_guide/vue3_migration.md +++ b/doc/development/fe_guide/vue3_migration.md @@ -26,7 +26,7 @@ Component's computed properties / methods or external helpers. **What to use instead** -Vue docs recommend using [mitt](https://github.com/developit/mitt) library. It's relatively small (200 bytes gzipped) and has a simple API: +Vue documentation recommends using the [mitt](https://github.com/developit/mitt) library. It's relatively small (200 bytes gzipped) and has a clear API: ```javascript import mitt from 'mitt' @@ -51,9 +51,9 @@ emitter.off('foo', onFoo) // unlisten **Event hub factory** -To make it easier for you to migrate existing event hubs to the new recommended approach, or simply -to create new ones, we have created a factory that you can use to instantiate a new mitt-based -event hub. +We have created a factory that you can use to instantiate a new mitt-based event hub. +This makes it easier to migrate existing event hubs to the new recommended approach, or +to create new ones. ```javascript import createEventHub from '~/helpers/event_hub_factory'; @@ -88,7 +88,7 @@ It is not recommended to replace stateful components with functional components **Why?** -In Vue 2.6 `slot` attribute was already deprecated in favor of `v-slot` directive but its usage is still allowed and sometimes we prefer using them because it simplifies unit tests (with old syntax, slots are rendered on `shallowMount`). However, in Vue 3 we can't use old syntax anymore. +In Vue 2.6 `slot` attribute was already deprecated in favor of `v-slot` directive. The `slot` attribute usage is still allowed and sometimes we prefer using it because it simplifies unit tests (with old syntax, slots are rendered on `shallowMount`). However, in Vue 3 we can't use old syntax anymore. **What to use instead** diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 1d83335291a..cc1d9ccab77 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -146,7 +146,7 @@ The only way to change state in a Vuex store is by committing a mutation. Most mutations are committed from an action using `commit`. If you don't have any asynchronous operations, you can call mutations from a component using the `mapMutations` helper. -See the Vuex docs for examples of [committing mutations from components](https://vuex.vuejs.org/guide/mutations.html#committing-mutations-in-components). +See the Vuex documentation for examples of [committing mutations from components](https://vuex.vuejs.org/guide/mutations.html#committing-mutations-in-components). #### Naming Pattern: `REQUEST` and `RECEIVE` namespaces @@ -271,7 +271,7 @@ import { mapGetters } from 'vuex'; ### `mutation_types.js` -From [vuex mutations docs](https://vuex.vuejs.org/guide/mutations.html): +From [Vuex mutations documentation](https://vuex.vuejs.org/guide/mutations.html): > It is a commonly seen pattern to use constants for mutation types in various Flux implementations. > This allows the code to take advantage of tooling like linters, and putting all constants in a > single file allows your collaborators to get an at-a-glance view of what mutations are possible @@ -429,7 +429,7 @@ export default { #### Testing Vuex concerns -Refer to [Vuex docs](https://vuex.vuejs.org/guide/testing.html) regarding testing Actions, Getters and Mutations. +Refer to [Vuex documentation](https://vuex.vuejs.org/guide/testing.html) regarding testing Actions, Getters and Mutations. #### Testing components that need a store diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md deleted file mode 100644 index 7456e8df8d9..00000000000 --- a/doc/development/feature_flags.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'feature_flags/index.md' ---- - -This document was moved to [another location](feature_flags/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index adcf3175c45..cda4f4c905c 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -11,12 +11,12 @@ info: "See the Technical Writers assigned to Development Guidelines: https://abo To be able to turn on/off features behind feature flags in any of the GitLab Inc. provided environments such as staging and production, you need to -have access to the [Chatops](../chatops_on_gitlabcom.md) bot. The Chatops bot +have access to the [ChatOps](../chatops_on_gitlabcom.md) bot. The ChatOps bot is currently running on the ops instance, which is different from <https://gitlab.com> or <https://dev.gitlab.org>. -Follow the Chatops document to [request access](../chatops_on_gitlabcom.md#requesting-access). +Follow the ChatOps document to [request access](../chatops_on_gitlabcom.md#requesting-access). -Once you are added to the project test if your access propagated, +After you are added to the project test if your access propagated, run: ```shell @@ -37,7 +37,7 @@ easier to measure the impact of both separately. The GitLab feature library (using [Flipper](https://github.com/jnunemaker/flipper), and covered in the [Feature Flags process](process.md) guide) supports rolling out changes to a percentage of -time to users. This in turn can be controlled using [GitLab Chatops](../../ci/chatops/README.md). +time to users. This in turn can be controlled using [GitLab ChatOps](../../ci/chatops/README.md). For an up to date list of feature flag commands please see [the source code](https://gitlab.com/gitlab-com/chatops/blob/master/lib/chatops/commands/feature.rb). @@ -48,7 +48,7 @@ If you get an error "Whoops! This action is not allowed. This incident will be reported." that means your Slack account is not allowed to change feature flags or you do not [have access](#access). -### Enabling a feature for preproduction testing +### Enabling a feature for pre-production testing As a first step in a feature rollout, you should enable the feature on <https://about.staging.gitlab.com> and <https://dev.gitlab.org>. @@ -62,7 +62,7 @@ a (very) rough estimate of how your feature will look/behave on GitLab.com. Both of these instances are connected to Sentry so make sure you check the projects there for any exceptions while testing your feature after enabling the feature flag. -For these preproduction environments, the commands should be run in a +For these pre-production environments, the commands should be run in a Slack channel for the stage the feature is relevant to. For example, use the `#s_monitor` channel for features developed by the Monitor stage, Health group. @@ -77,7 +77,7 @@ To enable a feature for 25% of all users, run the following in Slack: ### Enabling a feature for GitLab.com When a feature has successfully been -[enabled on a preproduction](#enabling-a-feature-for-preproduction-testing) +[enabled on a pre-production](#enabling-a-feature-for-pre-production-testing) environment and verified as safe and working, you can roll out the change to GitLab.com (production). @@ -226,11 +226,27 @@ you should fully roll out the feature by enabling the flag **globally** by runni This changes the feature flag state to be **enabled** always, which overrides the existing gates (e.g. `--group=gitlab-org`) in the above processes. +##### Disabling feature flags + +To disable a feature flag that has been globally enabled you can run: + +```shell +/chatops run feature set some_feature false +``` + +To disable a feature flag that has been enabled for a specific project you can run: + +```shell +/chatops run feature set --group=gitlab-org some_feature false +``` + +You cannot selectively disable feature flags for a specific project/group/user without applying a [specific method of implementing](development.md#selectively-disable-by-actor) the feature flags. + ### Feature flag change logging -#### Chatops level +#### ChatOps level -Any feature flag change that affects GitLab.com (production) via [Chatops](https://gitlab.com/gitlab-com/chatops) +Any feature flag change that affects GitLab.com (production) via [ChatOps](https://gitlab.com/gitlab-com/chatops) is automatically logged in an issue. The issue is created in the @@ -243,7 +259,7 @@ The issue is then also posted to the GitLab internal marker to make the change even more visible. Changes to the issue format can be submitted in the -[Chatops project](https://gitlab.com/gitlab-com/chatops). +[ChatOps project](https://gitlab.com/gitlab-com/chatops). #### Instance level diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md index dd732a08c72..0cdfa3e68d7 100644 --- a/doc/development/feature_flags/development.md +++ b/doc/development/feature_flags/development.md @@ -66,6 +66,13 @@ Feature.disabled?(:my_ops_flag, project, type: :ops) push_frontend_feature_flag(:my_ops_flag, project, type: :ops) ``` +### `experiment` type + +`experiment` feature flags are used for A/B testing on GitLab.com. + +An `experiment` feature flag should conform to the same standards as a `development` feature flag, +although the interface has some differences. More information can be found in the [experiment guide](../experiment_guide/index.md). + ## Feature flag definition and validation > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229161) in GitLab 13.3. @@ -321,6 +328,28 @@ Feature.enabled?(:feature_flag, group) Feature.enabled?(:feature_flag, user) ``` +#### Selectively disable by actor + +By default you cannot selectively disable a feature flag by actor. + +```shell +# This will not work how you would expect. +/chatops run feature set some_feature true +/chatops run feature set --project=gitlab-org/gitlab some_feature false +``` + +However, if you add two feature flags, you can write your conditional statement in such a way that the equivalent selective disable is possible. + +```ruby +Feature.enabled?(:a_feature, project) && Feature.disabled?(:a_feature_override, project) +``` + +```shell +# This will enable a feature flag globally, except for gitlab-org/gitlab +/chatops run feature set a_feature true +/chatops run feature set --project=gitlab-org/gitlab a_feature_override true +``` + ### Enable additional objects as actors To use feature gates based on actors, the model needs to respond to @@ -398,6 +427,9 @@ to ensure the feature works properly. When using the testing environment, all feature flags are enabled by default. +WARNING: +This does not apply to end-to-end (QA) tests, which [do not disable feature flags by default](#end-to-end-qa-tests). There is a different [process for using feature flags in end-to-end tests](../testing_guide/end_to_end/feature_flags.md). + To disable a feature flag in a test, use the `stub_feature_flags` helper. For example, to globally disable the `ci_live_trace` feature flag in a test: @@ -545,3 +577,17 @@ a mode that is used by `production` and `development`. You should use this mode only when you really want to tests aspects of Flipper with how it interacts with `ActiveRecord`. + +### End-to-end (QA) tests + +Toggling feature flags works differently in end-to-end (QA) tests. The end-to-end test framework does not have direct access to +Rails or the database, so it can't use Flipper. Instead, it uses [the public API](../../api/features.md#set-or-create-a-feature). Each end-to-end test can [enable or disable a feature flag during the test](../testing_guide/end_to_end/feature_flags.md). Alternatively, you can enable or disable a feature flag before one or more tests when you [run them from your GitLab repository's `qa` directory](https://gitlab.com/gitlab-org/gitlab/tree/master/qa#running-tests-with-a-feature-flag-enabled-or-disabled), or if you [run the tests via GitLab QA](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md#running-tests-with-a-feature-flag-enabled). + +[As noted above, feature flags are not enabled by default in end-to-end tests.](#feature-flags-in-tests) +This means that end-to-end tests will run with feature flags in the default state implemented in the source +code, or with the feature flag in its current state on the GitLab instance under test, unless the +test is written to enable/disable a feature flag explicitly. + +When a feature flag is changed on Staging or on GitLab.com, a Slack message will be posted to the `#qa-staging` or `#qa-production` channels to inform +the pipeline triage DRI so that they can more easily determine if any failures are related to a feature flag change. However, if you are working on a change you can +help to avoid unexpected failures by [confirming that the end-to-end tests pass with a feature flag enabled.](../testing_guide/end_to_end/feature_flags.md#confirming-that-end-to-end-tests-pass-with-a-feature-flag-enabled) diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index e93a5b3de1b..4890cc5da35 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -31,7 +31,8 @@ In all cases, those working on the changes should ask themselves: > Why do I need to add a feature flag? If I don't add one, what options do I have to control the impact on application reliability, and user experience? -For perspective on why we limit our use of feature flags please see the following [video](https://www.youtube.com/watch?v=DQaGqyolOd8). +For perspective on why we limit our use of feature flags please see +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Feature flags only when needed](https://www.youtube.com/watch?v=DQaGqyolOd8). In case you are uncertain if a feature flag is necessary, simply ask about this in an early merge request, and those reviewing the changes will likely provide you with an answer. diff --git a/doc/development/feature_flags/process.md b/doc/development/feature_flags/process.md index 7e6299c193c..65a6d01e0a2 100644 --- a/doc/development/feature_flags/process.md +++ b/doc/development/feature_flags/process.md @@ -155,7 +155,7 @@ It may seem like feature flags are configuration, which goes against our [conven principle. However, configuration is by definition something that is user-manageable. Feature flags are not intended to be user-editable. Instead, they are intended as a tool for Engineers and Site Reliability Engineers to use to de-risk their changes. Feature flags are the shim that gets us -to Continuous Delivery with our mono repo and without having to deploy the entire codebase on every change. +to Continuous Delivery with our monorepo and without having to deploy the entire codebase on every change. Feature flags are created to ensure that we can safely rollout our work on our terms. If we use Feature Flags as a configuration, we are doing it wrong and are indeed in violation of our principles. If something needs to be configured, we should intentionally make it configuration from the @@ -173,5 +173,5 @@ Some of the benefits of using development-type feature flags are: 1. Improved throughput: when a change is less risky because a flag exists, theoretical tests about scalability can potentially become unnecessary or less important. This allows an engineer to potentially test a feature on a small project, monitor the impact, and proceed. The alternative might - be to build complex benchmarks locally, or on staging, or on another GitLab deployment, which has an - outsized impact on the time it can take to build and release a feature. + be to build complex benchmarks locally, or on staging, or on another GitLab deployment, which has a + large impact on the time it can take to build and release a feature. diff --git a/doc/development/filtering_by_label.md b/doc/development/filtering_by_label.md index b10e2f6e082..2b9c7efc087 100644 --- a/doc/development/filtering_by_label.md +++ b/doc/development/filtering_by_label.md @@ -137,7 +137,7 @@ object, so the number of combinations would balloon further. ### Attempt B2: store label titles for each object -From the perspective of updating the labelable object, this is the worst +From the perspective of updating the object, this is the worst option. We have to bulk update the objects when: 1. The objects are moved from one project to another. @@ -159,7 +159,7 @@ However, at present, the disadvantages outweigh the advantages. ## Conclusion -We have yet to find a method that is demonstratably better than the current +We have yet to find a method that is demonstrably better than the current method, when considering: 1. Query performance. diff --git a/doc/development/foreign_keys.md b/doc/development/foreign_keys.md index 37764a12f97..abe191ace5e 100644 --- a/doc/development/foreign_keys.md +++ b/doc/development/foreign_keys.md @@ -75,7 +75,7 @@ your models _unless_ absolutely required and only when approved by database specialists. For example, if each row in a table has a corresponding file on a file system it may be tempting to add a `after_destroy` hook. This however introduces non database logic to a model, and means we can no longer rely on -foreign keys to remove the data as this would result in the filesystem data +foreign keys to remove the data as this would result in the file system data being left behind. In such a case you should use a service class instead that takes care of removing non database data. diff --git a/doc/development/frontend.md b/doc/development/frontend.md deleted file mode 100644 index 040004a6917..00000000000 --- a/doc/development/frontend.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'fe_guide/index.md' ---- - -This document was moved to [another location](fe_guide/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/gemfile.md b/doc/development/gemfile.md index c4a9ec4c454..1615c96309c 100644 --- a/doc/development/gemfile.md +++ b/doc/development/gemfile.md @@ -18,3 +18,16 @@ dependencies and build times. ## License compliance Refer to [licensing guidelines](licensing.md) for ensuring license compliance. + +## Upgrade Rails + +When upgrading the Rails gem and its dependencies, you also should update the following: + +- The [`Gemfile` in the `qa` directory](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/Gemfile). +- The [`Gemfile` in Gitaly Ruby](https://gitlab.com/gitlab-org/gitaly/-/blob/master/ruby/Gemfile), + to ensure that we ship only one version of these gems. + +You should also update NPM packages that follow the current version of Rails: + +- `@rails/ujs` +- `@rails/actioncable` diff --git a/doc/development/geo.md b/doc/development/geo.md index ed1837f9564..05fadcad08a 100644 --- a/doc/development/geo.md +++ b/doc/development/geo.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Geo (development) **(PREMIUM ONLY)** +# Geo (development) **(PREMIUM SELF)** Geo connects GitLab instances together. One GitLab instance is designated as a **primary** node and can be run with multiple @@ -305,7 +305,7 @@ events include: - Repositories Changed event - Repository Created event - Hashed Storage Migrated event -- Lfs Object Deleted event +- LFS Object Deleted event - Hashed Storage Attachments event - Job Artifact Deleted event - Upload Deleted event diff --git a/doc/development/geo/framework.md b/doc/development/geo/framework.md index 148953dc418..c2f267f0786 100644 --- a/doc/development/geo/framework.md +++ b/doc/development/geo/framework.md @@ -279,17 +279,32 @@ For example, to add support for files referenced by a `Widget` model with a unless table_exists?(:widget_registry) ActiveRecord::Base.transaction do create_table :widget_registry, id: :bigserial, force: :cascade do |t| - t.integer :widget_id, null: false + t.bigint :widget_id, null: false + t.datetime_with_timezone :created_at, null: false + t.datetime_with_timezone :last_synced_at + t.datetime_with_timezone :retry_at + t.datetime_with_timezone :verified_at + t.datetime_with_timezone :verification_started_at + t.datetime_with_timezone :verification_retry_at t.integer :state, default: 0, null: false, limit: 2 + t.integer :verification_state, default: 0, null: false, limit: 2 t.integer :retry_count, default: 0, limit: 2 - t.datetime_with_timezone :retry_at - t.datetime_with_timezone :last_synced_at - t.datetime_with_timezone :created_at, null: false + t.integer :verification_retry_count, default: 0, limit: 2 + t.boolean :checksum_mismatch + t.binary :verification_checksum + t.binary :verification_checksum_mismatched + t.string :verification_failure, limit: 255 t.text :last_sync_failure t.index :widget_id, name: :index_widget_registry_on_widget_id, unique: true t.index :retry_at t.index :state + # To optimize performance of WidgetRegistry.verification_failed_batch + t.index :verification_retry_at, name: :widget_registry_failed_verification, order: "NULLS FIRST", where: "((state = 2) AND (verification_state = 3))" + # To optimize performance of WidgetRegistry.needs_verification_count + t.index :verification_state, name: :widget_registry_needs_verification, where: "((state = 2) AND (verification_state = ANY (ARRAY[0, 3])))" + # To optimize performance of WidgetRegistry.verification_pending_batch + t.index :verified_at, name: :widget_registry_pending_verification, order: "NULLS FIRST", where: "((state = 2) AND (verification_state = 0))" end end end @@ -310,6 +325,10 @@ For example, to add support for files referenced by a `Widget` model with a class Geo::WidgetRegistry < Geo::BaseRegistry include Geo::ReplicableRegistry + # TODO: Include VerificationState in VerifiableRegistry + # https://gitlab.com/gitlab-org/gitlab/-/issues/298811 + include ::Gitlab::Geo::VerificationState + include ::Geo::VerifiableRegistry MODEL_CLASS = ::Widget MODEL_FOREIGN_KEY = :widget_id @@ -366,6 +385,7 @@ For example, to add support for files referenced by a `Widget` model with a end include_examples 'a Geo framework registry' + include_examples 'a Geo verifiable registry' describe '.find_registry_differences' do ... # To be implemented diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 5d062d7404e..98649f08dea 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -12,17 +12,18 @@ Workhorse and GitLab Shell. ## Deep Dive -In May 2019, Bob Van Landuyt hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) -on the [Gitaly project](https://gitlab.com/gitlab-org/gitaly) and how to contribute to it as a -Ruby developer, to share his domain specific knowledge with anyone who may work in this part of the +In May 2019, <!-- vale gitlab.Spelling = NO --> Bob Van Landuyt <!-- vale gitlab.Spelling = YES --> +hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) +on the [Gitaly project](https://gitlab.com/gitlab-org/gitaly). It included how to contribute to it as a +Ruby developer, and shared domain-specific knowledge 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=BmlEWFS8ORo), and the slides +You can find the <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [recording on YouTube](https://www.youtube.com/watch?v=BmlEWFS8ORo), and the slides on [Google Slides](https://docs.google.com/presentation/d/1VgRbiYih9ODhcPnL8dS0W98EwFYpJ7GXMPpX-1TM6YE/edit) and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/a4fdb1026278bda5c1c5bb574379cf80/Create_Deep_Dive__Gitaly_for_Create_Ruby_Devs.pdf). Everything covered in this deep dive was accurate as of GitLab 11.11, and while specific details may -have changed since then, it should still serve as a good introduction. +have changed, it should still serve as a good introduction. ## Beginner's guide @@ -43,7 +44,7 @@ needs direct access to the Git repository *must* be implemented in Gitaly, and exposed via an RPC. It's often easier to develop a new feature in Gitaly if you make the changes to -GitLab that will use the new feature in a separate merge request, to be merged +GitLab that intends to use the new feature in a separate merge request, to be merged immediately after the Gitaly one. This allows you to test your changes before they are merged. @@ -107,9 +108,9 @@ bundle exec rake gitlab:features:disable_rugged Most of this code exists in the `lib/gitlab/git/rugged_impl` directory. NOTE: -You should NOT need to add or modify code related to -Rugged unless explicitly discussed with the [Gitaly -Team](https://gitlab.com/groups/gl-gitaly/group_members). This code does +You should *not* need to add or modify code related to +Rugged unless explicitly discussed with the +[Gitaly Team](https://gitlab.com/groups/gl-gitaly/group_members). This code does NOT work on GitLab.com or other GitLab instances that do not use NFS. ## `TooManyInvocationsError` errors @@ -129,7 +130,7 @@ Isolate the source of the n+1 problem. This is normally a loop that results in G element in an array. If you are unable to isolate the problem, please contact a member of the [Gitaly Team](https://gitlab.com/groups/gl-gitaly/group_members) for assistance. -Once the source has been found, wrap it in an `allow_n_plus_1_calls` block, as follows: +After the source has been found, wrap it in an `allow_n_plus_1_calls` block, as follows: ```ruby # n+1: link to n+1 issue @@ -139,7 +140,7 @@ Gitlab::GitalyClient.allow_n_plus_1_calls do end ``` -Once the code is wrapped in this block, this code path is excluded from n+1 detection. +After the code is wrapped in this block, this code path is excluded from n+1 detection. ## Request counts @@ -164,13 +165,13 @@ end Normally, GitLab CE/EE tests use a local clone of Gitaly in `tmp/tests/gitaly` pinned at the version specified in `GITALY_SERVER_VERSION`. The `GITALY_SERVER_VERSION` file supports also -branches and SHA to use a custom commit in <https://gitlab.com/gitlab-org/gitaly>. +branches and SHA to use a custom commit in [the repository](https://gitlab.com/gitlab-org/gitaly). NOTE: With the introduction of auto-deploy for Gitaly, the format of `GITALY_SERVER_VERSION` was aligned with Omnibus syntax. It no longer supports `=revision`, it evaluates the file content as a Git -reference (branch or SHA). Only if it matches a semver does it prepend a `v`. +reference (branch or SHA). Only if it matches a semantic version does it prepend a `v`. If you want to run tests locally against a modified version of Gitaly you can replace `tmp/tests/gitaly` with a symlink. This is much faster @@ -195,7 +196,7 @@ Note that CI tests do not use your locally modified version of Gitaly. To use a custom Gitaly version in CI you need to update GITALY_SERVER_VERSION as described at the beginning of this section. -To use a different Gitaly repository, e.g., if your changes are present +To use a different Gitaly repository, such as if your changes are present on a fork, you can specify a `GITALY_REPO_URL` environment variable when running tests: @@ -218,7 +219,7 @@ as a [CI environment variable](../ci/variables/README.md#gitlab-cicd-environment If you are making changes to the RPC client, such as adding a new endpoint or adding a new parameter to an existing endpoint, follow the guide for -[Gitaly proto](https://gitlab.com/gitlab-org/gitaly/blob/master/proto/README.md). After pushing +[Gitaly protobuf specifications](https://gitlab.com/gitlab-org/gitaly/blob/master/proto/README.md). After pushing the branch with the changes (`new-feature-branch`, for example): 1. Change the `gitaly` line in the Rails' `Gemfile` to: @@ -328,15 +329,15 @@ the integration by using GDK: 1. Uncomment `prometheus_listen_addr` in the configuration file and run `gdk restart gitaly`. 1. Make sure that the flag is not enabled yet: - 1. Perform whatever action is required to trigger your changes (project creation, - submitting commit, observing history, etc.). + 1. Perform whatever action is required to trigger your changes, such as project creation, + submitting commit, or observing history. 1. Check that the list of current metrics has the new counter for the feature flag: ```shell curl --silent "http://localhost:9236/metrics" | grep go_find_all_tags ``` -1. Once you observe the metrics for the new feature flag and it increments, you +1. After you observe the metrics for the new feature flag and it increments, you can enable the new feature: 1. Navigate to GDK's root directory. 1. Start a Rails console: @@ -359,7 +360,7 @@ the integration by using GDK: ``` 1. Exit the Rails console and perform whatever action is required to trigger - your changes (project creation, submitting commit, observing history, etc.). + your changes, such as project creation, submitting commit, or observing history. 1. Verify the feature is on by observing the metrics for it: ```shell diff --git a/doc/development/go_guide/dependencies.md b/doc/development/go_guide/dependencies.md index 72b3f82d86f..c5af21d0772 100644 --- a/doc/development/go_guide/dependencies.md +++ b/doc/development/go_guide/dependencies.md @@ -178,4 +178,4 @@ authenticate requests made over HTTP. Go rejects HTTP-only entries in `GOPROXY` that have embedded credentials. In a future version, Go may add support for arbitrary authentication headers. -Follow [golang/go#26232](https://github.com/golang/go/issues/26232) for details. +Follow [`golang/go#26232`](https://github.com/golang/go/issues/26232) for details. diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index 68210c08a00..f352db918ed 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -63,10 +63,9 @@ of possible security breaches in our code: Remember to run [SAST](../../user/application_security/sast/index.md) and [Dependency Scanning](../../user/application_security/dependency_scanning/index.md) -**(ULTIMATE)** on your project (or at least the [gosec -analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/gosec)), -and to follow our [Security -requirements](../code_review.md#security-requirements). +**(ULTIMATE)** on your project (or at least the +[`gosec` analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/gosec)), +and to follow our [Security requirements](../code_review.md#security-requirements). Web servers can take advantages of middlewares like [Secure](https://github.com/unrolled/secure). @@ -92,9 +91,9 @@ projects: - Avoid global variables, even in packages. By doing so you introduce side effects if the package is included multiple times. - Use `goimports` before committing. - [goimports](https://godoc.org/golang.org/x/tools/cmd/goimports) + [`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports) is a tool that automatically formats Go source code using - [Gofmt](https://golang.org/cmd/gofmt/), in addition to formatting import lines, + [`Gofmt`](https://golang.org/cmd/gofmt/), in addition to formatting import lines, adding missing ones and removing unreferenced ones. Most editors/IDEs allow you to run commands before/after saving a file, you can set it @@ -162,8 +161,8 @@ be downloaded repeatedly, which can lead to intermittent problems due to rate limiting or network failures. In these circumstances, you should [cache the downloaded code between](../../ci/caching/index.md#caching-go-dependencies). -There was a [bug on modules -checksums](https://github.com/golang/go/issues/29278) in Go < v1.11.4, so make +There was a +[bug on modules checksums](https://github.com/golang/go/issues/29278) in Go versions earlier than v1.11.4, so make sure to use at least this version to avoid `checksum mismatch` errors. ### ORM @@ -171,7 +170,7 @@ sure to use at least this version to avoid `checksum mismatch` errors. We don't use object-relational mapping libraries (ORMs) at GitLab (except [ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html) in Ruby on Rails). Projects can be structured with services to avoid them. -[pgx](https://github.com/jackc/pgx) should be enough to interact with PostgreSQL +[`pgx`](https://github.com/jackc/pgx) should be enough to interact with PostgreSQL databases. ### Migrations @@ -193,7 +192,7 @@ external dependencies might be worth considering in case we decide to use a spec library or framework: - [Testify](https://github.com/stretchr/testify) -- [httpexpect](https://github.com/gavv/httpexpect) +- [`httpexpect`](https://github.com/gavv/httpexpect) ### Subtests @@ -329,8 +328,8 @@ A few things to keep in mind when adding context: ## CLIs Every Go program is launched from the command line. -[cli](https://github.com/urfave/cli) is a convenient package to create command -line apps. It should be used whether the project is a daemon or a simple cli +[`cli`](https://github.com/urfave/cli) is a convenient package to create command +line apps. It should be used whether the project is a daemon or a simple CLI tool. Flags can be mapped to [environment variables](https://github.com/urfave/cli#values-from-the-environment) directly, which documents and centralizes at the same time all the possible command line @@ -389,7 +388,7 @@ functionality: This gives us a thin abstraction over underlying implementations that is consistent across Workhorse, Gitaly, and, in future, other Go servers. For example, in the case of `gitlab.com/gitlab-org/labkit/tracing` we can switch -from using Opentracing directly to using Zipkin or Gokit's own tracing wrapper +from using `Opentracing` directly to using `Zipkin` or Gokit's own tracing wrapper without changes to the application code, while still keeping the same consistent configuration mechanism (i.e. the `GITLAB_TRACING` environment variable). @@ -489,9 +488,9 @@ The following are some style guidelines that are specific to the Secure Team. ### Code style and format Use `goimports -local gitlab.com/gitlab-org` before committing. -[goimports](https://godoc.org/golang.org/x/tools/cmd/goimports) +[`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports) is a tool that automatically formats Go source code using -[Gofmt](https://golang.org/cmd/gofmt/), in addition to formatting import lines, +[`Gofmt`](https://golang.org/cmd/gofmt/), in addition to formatting import lines, adding missing ones and removing unreferenced ones. By using the `-local gitlab.com/gitlab-org` option, `goimports` groups locally referenced packages separately from external ones. See diff --git a/doc/development/graphql_guide/batchloader.md b/doc/development/graphql_guide/batchloader.md index e965e678aba..1869c6e6f80 100644 --- a/doc/development/graphql_guide/batchloader.md +++ b/doc/development/graphql_guide/batchloader.md @@ -20,7 +20,7 @@ When implementing a new endpoint we should aim to minimise the number of SQL que Batch loading is useful when a series of queries for inputs `Qα, Qβ, ... Qω` can be combined to a single query for `Q[α, β, ... ω]`. An example of this is lookups by ID, where we can find two users by usernames as cheaply as one, but real-world examples can be more complex. -Batchloading is not suitable when the result sets have different sort-orders, grouping, aggregation or other non-composable features. +Batch loading is not suitable when the result sets have different sort-orders, grouping, aggregation or other non-composable features. There are two ways to use the batch-loader in your code. For simple ID lookups, use `::Gitlab::Graphql::Loaders::BatchModelLoader.new(model, id).find`. For more complex cases, you can use the batch API directly. diff --git a/doc/development/i18n/merging_translations.md b/doc/development/i18n/merging_translations.md index 582c1428bdd..e7d25942143 100644 --- a/doc/development/i18n/merging_translations.md +++ b/doc/development/i18n/merging_translations.md @@ -66,12 +66,14 @@ have been fixed on master. NOTE: These instructions work only for GitLab Team Members. -If for some reason the GitLab integration in CrowdIn does not exist, it can be -recreated by the following steps: - -1. Sign in to GitLab as `gitlab-crowdin-bot` (If you're a GitLab Team Member, find credentials in the GitLab shared [1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams) -1. Sign in to Crowdin with the GitLab integration -1. Navigate to Settings > Integrations > GitLab > Set Up Integration -1. Select `gitlab-org/gitlab` repository -1. On `Select Branches for Translation`, select `master` -1. Ensure the `Service Branch Name` is `master-i18n` +If for some reason the GitLab integration in CrowdIn doesn't exist, you can +recreate it with the following steps: + +1. Sign in to GitLab as `gitlab-crowdin-bot`. (If you're a GitLab Team Member, + find credentials in the GitLab shared + [1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams).) +1. Sign in to CrowdIn with the GitLab integration. +1. Go to **Settings > Integrations > GitLab > Set Up Integration**. +1. Select the `gitlab-org/gitlab` repository. +1. In `Select Branches for Translation`, select `master`. +1. Ensure the `Service Branch Name` is `master-i18n`. diff --git a/doc/development/i18n_guide.md b/doc/development/i18n_guide.md deleted file mode 100644 index ddc91f9308e..00000000000 --- a/doc/development/i18n_guide.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'i18n/index.md' ---- - -This document was moved to [another location](i18n/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/import_project.md b/doc/development/import_project.md index dfe6153ad45..a4917cc0c3d 100644 --- a/doc/development/import_project.md +++ b/doc/development/import_project.md @@ -170,7 +170,7 @@ The last option is to import a project using a Rails console: Gitlab::ImportExport::RepoRestorer.new(path_to_bundle: repo_path, shared: shared, - project: project).restore + importable: project).restore ``` We are storing all import failures in the `import_failures` data table. diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md index 94b56e10d9e..338ad76d414 100644 --- a/doc/development/instrumentation.md +++ b/doc/development/instrumentation.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Instrumenting Ruby code +# Instrumenting Ruby code **(FREE)** [GitLab Performance Monitoring](../administration/monitoring/performance/index.md) allows instrumenting of both methods and custom blocks of Ruby code. Method instrumentation is the primary form of diff --git a/doc/development/integrations/codesandbox.md b/doc/development/integrations/codesandbox.md index faa1ec0ee3f..3909991eed5 100644 --- a/doc/development/integrations/codesandbox.md +++ b/doc/development/integrations/codesandbox.md @@ -1,14 +1,20 @@ -# Set up local Codesandbox development environment +--- +stage: none +group: Development +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- -This guide walks through setting up a local [Codesandbox repository](https://github.com/codesandbox/codesandbox-client) and integrating it with a local GitLab instance. Codesandbox -is used to power the Web IDE's [Live Preview feature](../../user/project/web_ide/index.md#live-preview). Having a local Codesandbox setup is useful for debugging upstream issues or +# Set up local CodeSandbox development environment + +This guide walks through setting up a local [CodeSandbox repository](https://github.com/codesandbox/codesandbox-client) and integrating it with a local GitLab instance. CodeSandbox +is used to power the Web IDE's [Live Preview feature](../../user/project/web_ide/index.md#live-preview). Having a local CodeSandbox setup is useful for debugging upstream issues or creating upstream contributions like [this one](https://github.com/codesandbox/codesandbox-client/pull/5137). ## Initial setup -Before using Codesandbox with your local GitLab instance, you must: +Before using CodeSandbox with your local GitLab instance, you must: -1. Enable HTTPS on your GDK. Codesandbox uses Service Workers that require `https`. +1. Enable HTTPS on your GDK. CodeSandbox uses Service Workers that require `https`. Follow the GDK [NGINX configuration instructions](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/nginx.md) to enable HTTPS for GDK. 1. Clone the [`codesandbox-client` project](https://github.com/codesandbox/codesandbox-client) locally. If you plan on contributing upstream, you might want to fork and clone first. @@ -32,16 +38,16 @@ Before using Codesandbox with your local GitLab instance, you must: You can run `yarn build:clean` to clean up the build assets. -## Use local GitLab instance with local Codesandbox +## Use local GitLab instance with local CodeSandbox -GitLab integrates with two parts of Codesandbox: +GitLab integrates with two parts of CodeSandbox: - An NPM package called `smooshpack` (called `sandpack` in the `codesandbox-client` project). This exposes an entrypoint for us to kick off Codesandbox's bundler. -- A server that houses Codesandbox assets for bundling and previewing. This is hosted +- A server that houses CodeSandbox assets for bundling and previewing. This is hosted on a separate server for security. -Each time you want to run GitLab and Codesandbox together, you need to perform the +Each time you want to run GitLab and CodeSandbox together, you need to perform the steps in the following sections. ### Use local `smooshpack` for GitLab @@ -88,7 +94,7 @@ mkdir node_modules ln -s $PATH_TO_LOCAL_GITLAB/node_modules/core-js ./node_modules/core-js ``` -### Start building codesandbox app assets +### Start building CodeSandbox app assets In the `codesandbox-client` project directory: @@ -98,7 +104,7 @@ cd packages/app yarn start:sandpack-sandbox ``` -### Create HTTPS proxy for Codesandbox `sandpack` assets +### Create HTTPS proxy for CodeSandbox `sandpack` assets Because we need `https`, we need to create a proxy to the webpack server. We can use [`http-server`](https://www.npmjs.com/package/http-server), which can do this proxying @@ -111,7 +117,7 @@ npx http-server --proxy http://localhost:3000 -S -C $PATH_TO_CERT_PEM -K $PATH_T ### Update `bundler_url` setting in GitLab We need to update our `application_setting_implementation.rb` to point to the server that hosts the -Codesandbox `sandpack` assets. For instance, if these assets are hosted by a server at `https://sandpack.local:8044`: +CodeSandbox `sandpack` assets. For instance, if these assets are hosted by a server at `https://sandpack.local:8044`: ```patch diff --git a/app/models/application_setting_implementation.rb b/app/models/application_setting_implementation.rb @@ -133,7 +139,7 @@ index 6eed627b502..1824669e881 100644 NOTE: You can apply this patch by copying it to your clipboard and running `pbpaste | git apply`. -You'll might want to restart the GitLab Rails server after making this change: +You may want to restart the GitLab Rails server after making this change: ```shell gdk restart rails-web diff --git a/doc/development/integrations/jenkins.md b/doc/development/integrations/jenkins.md index a9a1026f1a8..16aba023fab 100644 --- a/doc/development/integrations/jenkins.md +++ b/doc/development/integrations/jenkins.md @@ -21,7 +21,7 @@ brew services start jenkins GitLab does not allow requests to localhost or the local network by default. When running Jenkins on your local machine, you need to enable local access. -1. Log into your GitLab instance as an admin. +1. Log into your GitLab instance as an administrator. 1. Go to **Admin Area > Settings > Network**. 1. Expand **Outbound requests** and check the following checkboxes: @@ -32,7 +32,7 @@ GitLab does not allow requests to localhost or the local network by default. Whe Jenkins uses the GitLab API and needs an access token. -1. Log in to your GitLab instance. +1. Sign in to your GitLab instance. 1. Click on your profile picture, then click **Settings**. 1. Click **Access Tokens**. 1. Create a new Access Token with the **API** scope enabled. Note the value of the token. diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index 48beb526774..bfe523ee390 100644 --- a/doc/development/integrations/jira_connect.md +++ b/doc/development/integrations/jira_connect.md @@ -19,10 +19,12 @@ The following are required to install and test the app: - [GDK with Gitpod](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/gitpod.md) documentation. - You **must not** use tunneling tools such as Serveo or `ngrok`. These are + You **must not** use tunneling tools such as + <!-- vale gitlab.Spelling = NO --> Serveo <!-- vale gitlab.Spelling = YES --> + or `ngrok`. These are security risks, and must not be run on developer laptops. - Jira requires all connections to the app host to be over SSL, so if you set up + Jira requires all connections to the app host to be over SSL. If you set up your own environment, remember to enable SSL and an appropriate certificate. ## Install the app in Jira diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md index fb9d894d203..1d5aced5869 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -260,6 +260,8 @@ When executing command lines, scanners should use the `debug` level to log the c For instance, the [bundler-audit](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit) scanner uses the `debug` level to log the command line `bundle audit check --quiet`, and what `bundle audit` writes to the standard output. +If the command line fails, then it should be logged with the `error` log level; +this makes it possible to debug the problem without having to change the log level to `debug` and rerun the scanning job. #### common logutil package diff --git a/doc/development/integrations/secure_partner_integration.md b/doc/development/integrations/secure_partner_integration.md index 80f632639ca..364e18ad015 100644 --- a/doc/development/integrations/secure_partner_integration.md +++ b/doc/development/integrations/secure_partner_integration.md @@ -19,7 +19,7 @@ integration as well as linking to more detailed resources for how to do so. ## Integration Tiers -The security offerings in GitLab are designed for GitLab Gold and GitLab Ultimate users, and the +The security offerings in GitLab are designed for GitLab Ultimate users, and the [DevSecOps](https://about.gitlab.com/handbook/use-cases/#4-devsecops-shift-left-security) use case. All the features are in those tiers. This includes the APIs and standard reporting framework needed to provide a consistent experience for users to easily bring their preferred @@ -75,7 +75,7 @@ and complete an integration with the Secure stage. 1. [Create an issue](https://gitlab.com/gitlab-com/alliances/alliances/-/issues/new?issuable_template=new_partner) using our new partner issue template to begin the discussion. 1. Get a test account to begin developing your integration. You can - request a [GitLab.com Gold Subscription Sandbox](https://about.gitlab.com/partners/integrate/#gitlabcom-gold-subscription-sandbox-request) + request a [GitLab.com Subscription Sandbox](https://about.gitlab.com/partners/integrate/#gitlabcom-subscription-sandbox-request) or an [EE Developer License](https://about.gitlab.com/partners/integrate/#requesting-ee-dev-license-for-rd). 1. Provide a [pipeline job](../../development/pipelines.md) template that users could integrate into their own GitLab pipelines. @@ -114,7 +114,7 @@ and complete an integration with the Secure stage. doing an [Unfiltered blog post](https://about.gitlab.com/handbook/marketing/blog/unfiltered/), doing a co-branded webinar, or producing a co-branded white paper. -We have a [video playlist](https://www.youtube.com/playlist?list=PL05JrBw4t0KpMqYxJiOLz-uBIr5w-yP4A) +We have a <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [video playlist](https://www.youtube.com/playlist?list=PL05JrBw4t0KpMqYxJiOLz-uBIr5w-yP4A) that may be helpful as part of this process. This covers various topics related to integrating your tool. diff --git a/doc/development/internal_api.md b/doc/development/internal_api.md index 43655c37048..b0e8dc0d22f 100644 --- a/doc/development/internal_api.md +++ b/doc/development/internal_api.md @@ -26,7 +26,7 @@ file, and include the token Base64 encoded in a `secret_token` parameter or in the `Gitlab-Shared-Secret` header. NOTE: -The internal API used by GitLab Pages, and GitLab Kubernetes Agent Server (kas) uses JSON Web Token (JWT) +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 @@ -51,7 +51,7 @@ POST /internal/allowed | `key_id` | string | no | ID of the SSH-key used to connect to GitLab Shell | | `username` | string | no | Username from the certificate used to connect to GitLab Shell | | `project` | string | no (if `gl_repository` is passed) | Path to the project | -| `gl_repository` | string | no (if `project` is passed) | Repository identifier (e.g. `project-7`) | +| `gl_repository` | string | no (if `project` is passed) | Repository identifier, such as `project-7` | | `protocol` | string | yes | SSH when called from GitLab Shell, HTTP or SSH when called from Gitaly | | `action` | string | yes | Git command being run (`git-upload-pack`, `git-receive-pack`, `git-upload-archive`) | | `changes` | string | yes | `<oldrev> <newrev> <refname>` when called from Gitaly, the magic string `_any` when called from GitLab Shell | @@ -378,7 +378,7 @@ Example response: > - 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) +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 @@ -390,9 +390,9 @@ The Kubernetes agent is under development and is not recommended for production ### Kubernetes agent information -Called from GitLab Kubernetes Agent Server (kas) to retrieve agent +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 +information for the agent's project in order for `kas` to fetch and update the agent's configuration. ```plaintext @@ -407,13 +407,13 @@ curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Auth ### Kubernetes agent project information -Called from GitLab Kubernetes Agent Server (kas) to retrieve project +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 +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 +Only public projects are 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 | @@ -432,7 +432,7 @@ curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Auth ### Kubernetes agent usage metrics -Called from GitLab Kubernetes Agent Server (kas) to increase the usage +Called from GitLab Kubernetes Agent Server (`kas`) to increase the usage metric counters. | Attribute | Type | Required | Description | @@ -456,7 +456,7 @@ Cluster. | Attribute | Type | Required | Description | |:----------|:-------|:---------|:------------| -| `alert` | Hash | yes | Alerts detail. Currently same format as [3rd party alert](../operations/incident_management/alert_integrations.md#customize-the-alert-payload-outside-of-gitlab). | +| `alert` | Hash | yes | Alerts detail. Same format as [3rd party alert](../operations/incident_management/integrations.md#customize-the-alert-payload-outside-of-gitlab). | ```plaintext POST internal/kubernetes/modules/cilium_alert diff --git a/doc/development/iterating_tables_in_batches.md b/doc/development/iterating_tables_in_batches.md index 43d7f32ad7f..bae55bccf7c 100644 --- a/doc/development/iterating_tables_in_batches.md +++ b/doc/development/iterating_tables_in_batches.md @@ -46,7 +46,7 @@ all of the arguments that `in_batches` supports. You should always use One should proceed with extra caution, and possibly avoid iterating over a column that can contain duplicate values. When you iterate over an attribute that is not unique, even with the applied max batch size, there is no guarantee that the resulting batches will not surpass it. -The following snippet demonstrates this situation, whe one attempt to select `Ci::Build` entries for users with `id` between `1` and `10,s000`, database returns `1 215 178` +The following snippet demonstrates this situation, when one attempt to select `Ci::Build` entries for users with `id` between `1` and `10,s000`, database returns `1 215 178` matching rows ```ruby diff --git a/doc/development/kubernetes.md b/doc/development/kubernetes.md index a56a0bd48be..6976dda433e 100644 --- a/doc/development/kubernetes.md +++ b/doc/development/kubernetes.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Kubernetes integration - development guidelines +# Kubernetes integration - development guidelines **(CORE)** This document provides various guidelines when developing for the GitLab [Kubernetes integration](../user/project/clusters/index.md). diff --git a/doc/development/lfs.md b/doc/development/lfs.md index 9df1f659654..eeeebd52ecb 100644 --- a/doc/development/lfs.md +++ b/doc/development/lfs.md @@ -9,13 +9,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Deep Dive In April 2019, Francisco Javier López hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) -on the GitLab [Git LFS](../topics/git/lfs/index.md) implementation to share his domain -specific knowledge 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=Yyxwcksr0Qc), +on the GitLab [Git LFS](../topics/git/lfs/index.md) implementation to share domain-specific +knowledge with anyone who may work in this part of the codebase in the future. +You can find the <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [recording on YouTube](https://www.youtube.com/watch?v=Yyxwcksr0Qc), and the slides on [Google Slides](https://docs.google.com/presentation/d/1E-aw6-z0rYd0346YhIWE7E9A65zISL9iIMAOq2zaw9E/edit) and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/07a89257a140db067bdfb484aecd35e1/Git_LFS_Deep_Dive__Create_.pdf). -Everything covered in this deep dive was accurate as of GitLab 11.10, and while specific -details may have changed since then, it should still serve as a good introduction. +This deep dive was accurate as of GitLab 11.10, and while specific +details may have changed, it should still serve as a good introduction. ## Including LFS blobs in project archives @@ -52,7 +52,7 @@ JSON payload prefaced with `git-archive`. This payload includes the archive already exists in the archive cache, Workhorse sends that file. Otherwise, Workhorse sends the `SendArchiveRequest` to the appropriate Gitaly server. -1. The Gitaly server will call `git archive <ref>` to begin generating +1. The Gitaly server calls `git archive <ref>` to begin generating the Git archive on-the-fly. If the `include_lfs_blobs` flag is enabled, Gitaly enables a custom LFS smudge filter via the `-c filter.lfs.smudge=/path/to/gitaly-lfs-smudge` Git option. @@ -76,7 +76,7 @@ process, which writes the contents to the standard output. 1. The archive data is sent back to the client. In step 7, the `gitaly-lfs-smudge` filter must talk to Workhorse, not to -Rails, or an invalid LFS blob will be saved. To support this, GitLab +Rails, or an invalid LFS blob is saved. To support this, GitLab 13.5 [changed the default Omnibus configuration to have Gitaly talk to the Workhorse](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4592) instead of Rails. @@ -84,6 +84,6 @@ instead of Rails. One side effect of this change: the correlation ID of the original request is not preserved for the internal API requests made by Gitaly (or `gitaly-lfs-smudge`), such as the one made in step 8. The -correlation IDs for those API requests will be random values until [this +correlation IDs for those API requests are random values until [this Workhorse issue](https://gitlab.com/gitlab-org/gitlab-workhorse/-/issues/309) is resolved. diff --git a/doc/development/logging.md b/doc/development/logging.md index 07ec9d53145..30398eb87a1 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -4,7 +4,7 @@ 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/#assignments --- -# GitLab Developers Guide to Logging +# GitLab Developers Guide to Logging **(FREE)** [GitLab Logs](../administration/logs.md) play a critical role for both administrators and GitLab team members to diagnose problems in the field. @@ -291,7 +291,7 @@ method or variable shouldn't be evaluated right away) - Change `Gitlab::ApplicationContext` to accept these new values - Make sure the new attributes are accepted at [`Labkit::Context`](https://gitlab.com/gitlab-org/labkit-ruby/blob/master/lib/labkit/context.rb) -See our [HOWTO: Use Sidekiq metadata logs](https://www.youtube.com/watch?v=_wDllvO_IY0) for further knowledge on +See our <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [HOWTO: Use Sidekiq metadata logs](https://www.youtube.com/watch?v=_wDllvO_IY0) for further knowledge on creating visualizations in Kibana. The fields of the context are currently only logged for Sidekiq jobs triggered @@ -299,6 +299,28 @@ through web requests. See the [follow-up work](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/68) for more information. +### Logging context metadata (through workers) + +Additional metadata can be attached to a worker through the use of the [`ApplicationWorker#log_extra_metadata_on_done`](https://gitlab.com/gitlab-org/gitlab/-/blob/16ecc33341a3f6b6bebdf78d863c5bce76b040d3/app/workers/concerns/application_worker.rb#L31-34) +method. Using this method adds metadata that is later logged to Kibana with the done job payload. + +```ruby +class MyExampleWorker + include ApplicationWorker + + def perform(*args) + # Worker performs work + # ... + + # The contents of value will appear in Kibana under `json.extra.my_example_worker.my_key` + log_extra_metadata_on_done(:my_key, value) + end +end +``` + +Please see [this example](https://gitlab.com/gitlab-org/gitlab/-/blob/16ecc33341a3f6b6bebdf78d863c5bce76b040d3/app/workers/ci/pipeline_artifacts/expire_artifacts_worker.rb#L20-21) +which logs a count of how many artifacts are destroyed per run of the `ExpireArtifactsWorker`. + ## Exception Handling It often happens that you catch the exception and want to track it. diff --git a/doc/development/module_with_instance_variables.md b/doc/development/module_with_instance_variables.md index 75575105178..16c7a807053 100644 --- a/doc/development/module_with_instance_variables.md +++ b/doc/development/module_with_instance_variables.md @@ -121,71 +121,7 @@ module Gitlab end ``` -Now the cop doesn't complain. Here's a bad example which we could rewrite: - -``` ruby -module SpamCheckService - def filter_spam_check_params - @request = params.delete(:request) - @api = params.delete(:api) - @recaptcha_verified = params.delete(:recaptcha_verified) - @spam_log_id = params.delete(:spam_log_id) - end - - def spam_check(spammable, user) - spam_service = SpamService.new(spammable, @request) - - spam_service.when_recaptcha_verified(@recaptcha_verified, @api) do - user.spam_logs.find_by(id: @spam_log_id)&.update!(recaptcha_verified: true) - end - end -end -``` - -There are several implicit dependencies here. First, `params` should be -defined before use. Second, `filter_spam_check_params` should be called -before `spam_check`. These are all implicit and the includer could be using -those instance variables without awareness. - -This should be rewritten like: - -``` ruby -class SpamCheckService - def initialize(request:, api:, recaptcha_verified:, spam_log_id:) - @request = request - @api = api - @recaptcha_verified = recaptcha_verified - @spam_log_id = spam_log_id - end - - def spam_check(spammable, user) - spam_service = SpamService.new(spammable, @request) - - spam_service.when_recaptcha_verified(@recaptcha_verified, @api) do - user.spam_logs.find_by(id: @spam_log_id)&.update!(recaptcha_verified: true) - end - end -end -``` - -And use it like: - -``` ruby -class UpdateSnippetService < BaseService - def execute - # ... - spam = SpamCheckService.new(params.slice!(:request, :api, :recaptcha_verified, :spam_log_id)) - - spam.check(snippet, current_user) - # ... - end -end -``` - -This way, all those instance variables are isolated in `SpamCheckService` -rather than whatever includes the module, and those modules which were also -included, making it much easier to track down any issues, -and reducing the chance of having name conflicts. +Now the cop doesn't complain. ## How to disable this cop diff --git a/doc/development/new_fe_guide/development/testing.md b/doc/development/new_fe_guide/development/testing.md deleted file mode 100644 index 034324989ef..00000000000 --- a/doc/development/new_fe_guide/development/testing.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../testing_guide/frontend_testing.md' ---- - -This document was moved to [another location](../../testing_guide/frontend_testing.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/new_fe_guide/modules/widget_extensions.md b/doc/development/new_fe_guide/modules/widget_extensions.md index ffcd736511a..375baea0444 100644 --- a/doc/development/new_fe_guide/modules/widget_extensions.md +++ b/doc/development/new_fe_guide/modules/widget_extensions.md @@ -10,13 +10,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Summary -Extensions in the merge request widget allow for others team to quickly and easily add new features -into the widget that will match the existing design and interaction as other extensions. +Extensions in the merge request widget enable you to add new features +into the widget that match the existing design and interaction as other extensions. ## Usage -To use extensions you need to first create a new extension object that will be used to fetch the -data that will be rendered in the extension. See the example file in +To use extensions you need to first create a new extension object to fetch the +data to render in the extension. See the example file in `app/assets/javascripts/vue_merge_request_widget/extensions/issues.js` for a working example. The basic object structure is as below: @@ -36,8 +36,8 @@ export default { }; ``` -Following the same data structure allows each extension to follow the same registering structure -but allows for each extension to manage where it gets its own data from. +By following the same data structure, each extension can follow the same registering structure, +but each extension can manage its data sources. After creating this structure you need to register it. Registering the extension can happen at any point _after_ the widget has been created. diff --git a/doc/development/new_fe_guide/style/html.md b/doc/development/new_fe_guide/style/html.md deleted file mode 100644 index afbfbdcf834..00000000000 --- a/doc/development/new_fe_guide/style/html.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../fe_guide/style/html.md' ---- - -This document was moved to [another location](../../fe_guide/style/html.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/new_fe_guide/style/index.md b/doc/development/new_fe_guide/style/index.md deleted file mode 100644 index 77700441aa3..00000000000 --- a/doc/development/new_fe_guide/style/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../fe_guide/style/index.md' ---- - -This document was moved to [another location](../../fe_guide/style/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/new_fe_guide/style/javascript.md b/doc/development/new_fe_guide/style/javascript.md deleted file mode 100644 index 17722d2c41b..00000000000 --- a/doc/development/new_fe_guide/style/javascript.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../fe_guide/style/javascript.md' ---- - -This document was moved to [another location](../../fe_guide/style/javascript.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/new_fe_guide/style/prettier.md b/doc/development/new_fe_guide/style/prettier.md deleted file mode 100644 index 6c0f3b77505..00000000000 --- a/doc/development/new_fe_guide/style/prettier.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../fe_guide/tooling.md#formatting-with-prettier' ---- - -This document was moved to [another location](../../fe_guide/tooling.md#formatting-with-prettier). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/ordering_table_columns.md b/doc/development/ordering_table_columns.md index a0a38acd816..00ce15fcc10 100644 --- a/doc/development/ordering_table_columns.md +++ b/doc/development/ordering_table_columns.md @@ -63,17 +63,17 @@ bits platform and 8 bytes for a 64 bits platform. | Type | Size | Alignment needed | |:-----------------|:-------------------------------------|:-----------| -| smallint | 2 bytes | 1 word | -| integer | 4 bytes | 1 word | -| bigint | 8 bytes | 8 bytes | -| real | 4 bytes | 1 word | -| double precision | 8 bytes | 8 bytes | -| boolean | 1 byte | not needed | -| text / string | variable, 1 byte plus the data | 1 word | -| bytea | variable, 1 or 4 bytes plus the data | 1 word | -| timestamp | 8 bytes | 8 bytes | -| timestamptz | 8 bytes | 8 bytes | -| date | 4 bytes | 1 word | +| `smallint` | 2 bytes | 1 word | +| `integer` | 4 bytes | 1 word | +| `bigint` | 8 bytes | 8 bytes | +| `real` | 4 bytes | 1 word | +| `double precision` | 8 bytes | 8 bytes | +| `boolean` | 1 byte | not needed | +| `text` / `string` | variable, 1 byte plus the data | 1 word | +| `bytea` | variable, 1 or 4 bytes plus the data | 1 word | +| `timestamp` | 8 bytes | 8 bytes | +| `timestamptz` | 8 bytes | 8 bytes | +| `date` | 4 bytes | 1 word | A "variable" size means the actual size depends on the value being stored. If PostgreSQL determines this can be embedded directly into a row it may do so, but diff --git a/doc/development/packages.md b/doc/development/packages.md index aadd71c9ffa..e1fa48cc350 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -70,7 +70,7 @@ The current state of existing package registries availability is: | Maven | Yes | Yes | 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 | +| NuGet | Yes | Yes | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/36425) | | PyPI | Yes | No | No | | Go | Yes | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213900) | No - [open-issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213902) | | Composer | Yes | Yes | No | @@ -191,7 +191,7 @@ support is done by overriding a specific function in the API helpers, like For this authentication mechanism, keep in mind that some clients can send an unauthenticated request first, wait for the 401 Unauthorized response with the [`WWW-Authenticate`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate) field, then send an updated (authenticated) request. This case is more involved as -GitLab needs to handle the 401 Unauthorized response. The [Nuget API](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/nuget_packages.rb) +GitLab needs to handle the 401 Unauthorized response. The [NuGet API](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/nuget_packages.rb) supports this case. #### Authorization @@ -245,8 +245,8 @@ in your local development environment. #### Rate Limits on GitLab.com Package manager clients can make rapid requests that exceed the -[GitLab.com standard API rate limits](../user/gitlab_com/index.md#gitlabcom-specific-rate-limits). -This results in a `429 Too Many Requests` error. +[GitLab.com standard API rate limits](../user/gitlab_com/index.md#gitlabcom-specific-rate-limits). +This results in a `429 Too Many Requests` error. We have opened a set of paths to allow higher rate limits. Unless it is not possible, new package managers should follow these conventions so they can take advantage of the diff --git a/doc/development/performance.md b/doc/development/performance.md index f3ce924de38..3b4525dc8ee 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -50,7 +50,7 @@ GitLab provides built-in tools to help improve performance and availability: - [Service measurement](service_measurement.md) for measuring and logging service execution. GitLab team members can use [GitLab.com's performance monitoring systems](https://about.gitlab.com/handbook/engineering/monitoring/) located at -<https://dashboards.gitlab.net>, this requires you to log in using your +[`dashboards.gitlab.net`](https://dashboards.gitlab.net), this requires you to log in using your `@gitlab.com` email address. Non-GitLab team-members are advised to set up their own Prometheus and Grafana stack. @@ -176,7 +176,7 @@ stackprof tmp/project_policy_spec.rb.dump --graphviz > project_policy_spec.dot dot -Tsvg project_policy_spec.dot > project_policy_spec.svg ``` -To load the profile in [kcachegrind](https://kcachegrind.github.io/): +To load the profile in [KCachegrind](https://kcachegrind.github.io/): ```shell stackprof tmp/project_policy_spec.rb.dump --callgrind > project_policy_spec.callgrind @@ -184,7 +184,7 @@ kcachegrind project_policy_spec.callgrind # Linux qcachegrind project_policy_spec.callgrind # Mac ``` -For flamegraphs, enable raw collection first. Note that raw +For flame graphs, enable raw collection first. Note that raw collection can generate a very large file, so increase the `INTERVAL`, or run on a smaller number of specs for smaller file size: @@ -192,7 +192,7 @@ run on a smaller number of specs for smaller file size: RAW=true bin/rspec-stackprof spec/policies/group_member_policy_spec.rb ``` -You can then generate, and view the resultant flamegraph. It might take a +You can then generate, and view the resultant flame graph. It might take a while to generate based on the output file size: ```shell @@ -251,7 +251,7 @@ In order to enable production profiling for Ruby processes, you can set the `STA The following configuration options can be configured: -- `STACKPROF_ENABLED`: Enables stackprof signal handler on SIGUSR2 signal. +- `STACKPROF_ENABLED`: Enables Stackprof signal handler on SIGUSR2 signal. Defaults to `false`. - `STACKPROF_MODE`: See [sampling modes](https://github.com/tmm1/stackprof#sampling). Defaults to `cpu`. @@ -264,7 +264,7 @@ The following configuration options can be configured: - `STACKPROF_TIMEOUT_S`: Profiling timeout in seconds. Profiling will automatically stop after this time has elapsed. Defaults to `30`. - `STACKPROF_RAW`: Whether to collect raw samples or only aggregates. Raw - samples are needed to generate flamegraphs, but they do have a higher memory + samples are needed to generate flame graphs, but they do have a higher memory and disk overhead. Defaults to `true`. Once enabled, profiling can be triggered by sending a `SIGUSR2` signal to the @@ -287,7 +287,7 @@ The Puma master process is not supported. Neither is Unicorn. Sending SIGUSR2 to either of those triggers restarts. In the case of Puma, take care to only send the signal to Puma workers. -This can be done via `pkill -USR2 puma:`. The `:` disambiguates between `puma +This can be done via `pkill -USR2 puma:`. The `:` distinguishes between `puma 4.3.3.gitlab.2 ...` (the master process) from `puma: cluster worker 0: ...` (the worker processes), selecting the latter. @@ -296,7 +296,7 @@ For Sidekiq, the signal can be sent to the `sidekiq-cluster` process via `pkill children. Alternatively, you can also select a specific pid of interest. Production profiles can be especially noisy. It can be helpful to visualize them -as a [flamegraph](https://github.com/brendangregg/FlameGraph). This can be done +as a [flame graph](https://github.com/brendangregg/FlameGraph). This can be done via: ```shell @@ -543,6 +543,88 @@ test += " world" When adding new Ruby files, please check that you can add the above header, as omitting it may lead to style check failures. +## Banzai pipelines and filters + +When writing or updating [Banzai filters and pipelines](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/banzai), +it can be difficult to understand what the performance of the filter is, and what effect it might +have on the overall pipeline performance. + +To perform benchmarks run: + +```shell +bin/rake benchmark:banzai +``` + +This command generates output like this: + +```plaintext +--> Benchmarking Full, Wiki, and Plain pipelines +Calculating ------------------------------------- + Full pipeline 1.000 i/100ms + Wiki pipeline 1.000 i/100ms + Plain pipeline 1.000 i/100ms +------------------------------------------------- + Full pipeline 3.357 (±29.8%) i/s - 31.000 + Wiki pipeline 2.893 (±34.6%) i/s - 25.000 in 10.677014s + Plain pipeline 15.447 (±32.4%) i/s - 119.000 + +Comparison: + Plain pipeline: 15.4 i/s + Full pipeline: 3.4 i/s - 4.60x slower + Wiki pipeline: 2.9 i/s - 5.34x slower + +. +--> Benchmarking FullPipeline filters +Calculating ------------------------------------- + Markdown 24.000 i/100ms + Plantuml 8.000 i/100ms + SpacedLink 22.000 i/100ms + +... + + TaskList 49.000 i/100ms + InlineDiff 9.000 i/100ms + SetDirection 369.000 i/100ms +------------------------------------------------- + Markdown 237.796 (±16.4%) i/s - 2.304k + Plantuml 80.415 (±36.1%) i/s - 520.000 + SpacedLink 168.188 (±10.1%) i/s - 1.672k + +... + + TaskList 101.145 (± 6.9%) i/s - 1.029k + InlineDiff 52.925 (±15.1%) i/s - 522.000 + SetDirection 3.728k (±17.2%) i/s - 34.317k in 10.617882s + +Comparison: + Suggestion: 739616.9 i/s + Kroki: 306449.0 i/s - 2.41x slower +InlineGrafanaMetrics: 156535.6 i/s - 4.72x slower + SetDirection: 3728.3 i/s - 198.38x slower + +... + + UserReference: 2.1 i/s - 360365.80x slower + ExternalLink: 1.6 i/s - 470400.67x slower + ProjectReference: 0.7 i/s - 1128756.09x slower + +. +--> Benchmarking PlainMarkdownPipeline filters +Calculating ------------------------------------- + Markdown 19.000 i/100ms +------------------------------------------------- + Markdown 241.476 (±15.3%) i/s - 2.356k + +``` + +This can give you an idea how various filters perform, and which ones might be performing the slowest. + +The test data has a lot to do with how well a filter performs. If there is nothing in the test data +that specifically triggers the filter, it might look like it's running incredibly fast. +Make sure that you have relevant test data for your filter in the +[`spec/fixtures/markdown.md.erb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/fixtures/markdown.md.erb) +file. + ## Reading from files and other data sources Ruby offers several convenience functions that deal with file contents specifically @@ -665,5 +747,4 @@ Assuming you are working with ActiveRecord models, you might also find these lin ### Examples -You may find some useful examples in this snippet: -<https://gitlab.com/gitlab-org/gitlab-foss/snippets/33946> +You may find some useful examples in [this snippet](https://gitlab.com/gitlab-org/gitlab-foss/snippets/33946). diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md index 0354e703357..be725a702e9 100644 --- a/doc/development/pipelines.md +++ b/doc/development/pipelines.md @@ -1,12 +1,12 @@ --- stage: none -group: unassigned +group: Engineering Productivity info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Pipelines for the GitLab project -Pipelines for <https://gitlab.com/gitlab-org/gitlab> and <https://gitlab.com/gitlab-org/gitlab-foss> (as well as the +Pipelines for [`gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab) and [`gitlab-org/gitlab-foss`](https://gitlab.com/gitlab-org/gitlab-foss) (as well as the `dev` instance's mirrors) are configured in the usual [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml) which itself includes files under @@ -37,14 +37,14 @@ Pipeline creation is also affected by the following CI variables: No pipeline is created in any other cases (for example, when pushing a branch with no MR for it). -The source of truth for these workflow rules is defined in <https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml>. +The source of truth for these workflow rules is defined in [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml). ### Pipelines for Merge Requests In general, pipelines for an MR fall into one or more of the following types, depending on the changes made in the MR: -- [Docs-only MR pipeline](#docs-only-mr-pipeline): This is typically created for an MR that only changes documentation. +- [Documentation only MR pipeline](#documentation-only-mr-pipeline): This is typically created for an MR that only changes documentation. - [Code-only MR pipeline](#code-only-mr-pipeline): This is typically created for an MR that only changes code, either backend or frontend. - [Frontend-only MR pipeline](#frontend-only-mr-pipeline): This is typically created for an MR that only changes frontend code. - [QA-only MR pipeline](#qa-only-mr-pipeline): This is typically created for an MR that only changes end to end tests related code. @@ -53,23 +53,27 @@ We use the [`rules:`](../ci/yaml/README.md#rules) and [`needs:`](../ci/yaml/READ to determine the jobs that need to be run in a pipeline. Note that an MR that includes multiple types of changes would have a pipelines that include jobs from multiple types (e.g. a combination of docs-only and code-only pipelines). -#### Docs-only MR pipeline +#### Documentation only MR pipeline -Reference pipeline: <https://gitlab.com/gitlab-org/gitlab/pipelines/135236627> +[Reference pipeline](https://gitlab.com/gitlab-org/gitlab/-/pipelines/250546928): ```mermaid graph LR subgraph "No needed jobs"; 1-1["danger-review (2.3 minutes)"]; click 1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8100542&udv=0" - 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 + 1-2["docs-lint markdown (1.5 minutes)"]; + click 1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=10224335&udv=0" + 1-3["docs-lint links (6 minutes)"]; + click 1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356757&udv=0" + 1-4["ui-docs-links lint (2.5 minutes)"]; + click 1-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=10823717&udv=1020379" + end ``` #### Code-only MR pipeline -Reference pipeline: <https://gitlab.com/gitlab-org/gitlab/pipelines/136295694> +[Reference pipeline](https://gitlab.com/gitlab-org/gitlab/pipelines/136295694) ```mermaid graph RL; @@ -107,7 +111,7 @@ graph RL; class 1-6 criticalPath; end - 2_1-1["graphql-reference-verify (5 minutes)"]; + 2_1-1["graphql-verify (4 minutes)"]; click 2_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356715&udv=0" 2_1-2["memory-static (4.75 minutes)"]; click 2_1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356721&udv=0" @@ -173,7 +177,7 @@ graph RL; #### Frontend-only MR pipeline -Reference pipeline: <https://gitlab.com/gitlab-org/gitlab/pipelines/134661039> +[Reference pipeline](https://gitlab.com/gitlab-org/gitlab/pipelines/134661039): ```mermaid graph RL; @@ -212,7 +216,7 @@ graph RL; class 1-6 criticalPath; end - 2_1-1["graphql-reference-verify (5 minutes)"]; + 2_1-1["graphql-verify (4 minutes)"]; click 2_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356715&udv=0" 2_1-2["memory-static (4.75 minutes)"]; click 2_1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356721&udv=0" @@ -304,7 +308,7 @@ graph RL; #### QA-only MR pipeline -Reference pipeline: <https://gitlab.com/gitlab-org/gitlab/pipelines/134645109> +[Reference pipeline](https://gitlab.com/gitlab-org/gitlab/pipelines/134645109): ```mermaid graph RL; @@ -341,7 +345,7 @@ graph RL; class 1-5 criticalPath; end - 2_1-1["graphql-reference-verify (5 minutes)"]; + 2_1-1["graphql-verify (4 minutes)"]; click 2_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356715&udv=0" subgraph "Needs `setup-test-env`"; 2_1-1 --> 1-6; @@ -493,6 +497,7 @@ request, be sure to start the `dont-interrupt-me` job before pushing. 1. We currently have several different caches defined in [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml), with fixed keys: + - `.setup-test-env-cache`. - `.rails-cache`. - `.static-analysis-cache`. - `.coverage-cache` @@ -500,6 +505,7 @@ request, be sure to start the `dont-interrupt-me` job before pushing. - `.yarn-cache`. - `.assets-compile-cache` (the key includes `${NODE_ENV}` so it's actually two different caches). 1. Only 6 specific jobs, running in 2-hourly scheduled pipelines, are pushing (i.e. updating) to the caches: + - `update-setup-test-env-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/rails.gitlab-ci.yml). - `update-rails-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/rails.gitlab-ci.yml). - `update-static-analysis-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/rails.gitlab-ci.yml). - `update-coverage-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/rails.gitlab-ci.yml). @@ -584,8 +590,8 @@ runner, or [you can incur network egress charges](https://cloud.google.com/stora The current stages are: -- `sync`: This stage is used to synchronize changes from <https://gitlab.com/gitlab-org/gitlab> to - <https://gitlab.com/gitlab-org/gitlab-foss>. +- `sync`: This stage is used to synchronize changes from [`gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab) to + [`gitlab-org/gitlab-foss`](https://gitlab.com/gitlab-org/gitlab-foss). - `prepare`: This stage includes jobs that prepare artifacts that are needed by jobs in subsequent stages. - `build-images`: This stage includes jobs that prepare Docker images @@ -614,7 +620,9 @@ that is deployed in stage `review`. The default image is defined in [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml). +<!-- vale gitlab.Spelling = NO --> It includes Ruby, Go, Git, Git LFS, Chrome, Node, Yarn, PostgreSQL, and Graphics Magick. +<!-- vale gitlab.Spelling = YES --> The images used in our pipelines are configured in the [`gitlab-org/gitlab-build-images`](https://gitlab.com/gitlab-org/gitlab-build-images) @@ -628,7 +636,7 @@ The current version of the build images can be found in the In addition to the [predefined variables](../ci/variables/predefined_variables.md), each pipeline includes default variables defined in -<https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml>. +[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml). ### Common job definitions @@ -640,6 +648,7 @@ that are scoped to a single [configuration keyword](../ci/yaml/README.md#job-key |------------------|-------------| | `.default-retry` | Allows a job to [retry](../ci/yaml/README.md#retry) upon `unknown_failure`, `api_failure`, `runner_system_failure`, `job_execution_timeout`, or `stuck_or_timeout_failure`. | | `.default-before_script` | Allows a job to use a default `before_script` definition suitable for Ruby/Rails tasks that may need a database running (e.g. tests). | +| `.setup-test-env-cache` | Allows a job to use a default `cache` definition suitable for setting up test environment for subsequent Ruby/Rails tasks. | | `.rails-cache` | Allows a job to use a default `cache` definition suitable for Ruby/Rails tasks. | | `.static-analysis-cache` | Allows a job to use a default `cache` definition suitable for static analysis tasks. | | `.coverage-cache` | Allows a job to use a default `cache` definition suitable for coverage tasks. | @@ -659,7 +668,7 @@ that are scoped to a single [configuration keyword](../ci/yaml/README.md#job-key We're using the [`rules` keyword](../ci/yaml/README.md#rules) extensively. All `rules` definitions are defined in -<https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rules.gitlab-ci.yml>, +[`rules.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rules.gitlab-ci.yml), then included in individual jobs via [`extends`](../ci/yaml/README.md#extends). The `rules` definitions are composed of `if:` conditions and `changes:` patterns, diff --git a/doc/development/polling.md b/doc/development/polling.md index 18f9fb954dd..f854891a528 100644 --- a/doc/development/polling.md +++ b/doc/development/polling.md @@ -60,6 +60,6 @@ route matching easier. For more information see: -- [`Poll-Interval` header](fe_guide/performance.md#realtime-components) +- [`Poll-Interval` header](fe_guide/performance.md#real-time-components) - [RFC 7232](https://tools.ietf.org/html/rfc7232) - [ETag proposal](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26926) diff --git a/doc/development/product_analytics/index.md b/doc/development/product_analytics/index.md index 4d2168cf304..e8b8e0c4885 100644 --- a/doc/development/product_analytics/index.md +++ b/doc/development/product_analytics/index.md @@ -4,10 +4,5 @@ redirect_to: 'https://about.gitlab.com/handbook/product/product-intelligence-gui This document was moved to [another location](https://about.gitlab.com/handbook/product/product-intelligence-guide/). -<!-- Needed by the Product Intelligence group - -Since our new standard for redirects otherwise lies within the gitlab-docs repo, -as long as we need a redirect to the handbook, we need to retain this file. - --> <!-- This redirect file can be deleted after December 1, 2021. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/product_analytics/snowplow.md b/doc/development/product_analytics/snowplow.md index bb056ffddfe..ff91e450e1e 100644 --- a/doc/development/product_analytics/snowplow.md +++ b/doc/development/product_analytics/snowplow.md @@ -4,5 +4,5 @@ redirect_to: '../snowplow.md' This document was moved to [another location](../snowplow.md). -<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- This redirect file can be deleted after April 1, 2021. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/product_analytics/usage_ping.md b/doc/development/product_analytics/usage_ping.md index 5fbdb508bb1..79075157ce4 100644 --- a/doc/development/product_analytics/usage_ping.md +++ b/doc/development/product_analytics/usage_ping.md @@ -4,5 +4,5 @@ redirect_to: '../usage_ping.md' This document was moved to [another location](../usage_ping.md). -<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- This redirect file can be deleted after April 1, 2021. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/profiling.md b/doc/development/profiling.md index ce9c1191648..5714d25cedd 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -227,5 +227,5 @@ The following table lists these variables along with their default values. GitLab may decide to change these settings in order to speed up application performance, lower memory requirements, or both. You can see how each of these settings affect GC performance, memory use and application start-up time for an idle instance of -GitLab by runnning the `scripts/perf/gc/collect_gc_stats.rb` script. It will output GC stats and general timing data to standard +GitLab by running the `scripts/perf/gc/collect_gc_stats.rb` script. It will output GC stats and general timing data to standard out as CSV. diff --git a/doc/development/projections.md b/doc/development/projections.md index e62f13981c9..c112ec6f119 100644 --- a/doc/development/projections.md +++ b/doc/development/projections.md @@ -27,7 +27,7 @@ You can find a basic list of projection options in - VSCode - [Alternate File](https://marketplace.visualstudio.com/items?itemName=will-wow.vscode-alternate-file) - [projectionist](https://github.com/jarsen/projectionist) - - [jumpto](https://github.com/gmdayley/jumpto) + - [`jumpto`](https://github.com/gmdayley/jumpto) - Atom - [projectionist-atom](https://atom.io/packages/projectionist-atom) - Command-line @@ -35,6 +35,8 @@ You can find a basic list of projection options in ## History +<!-- vale gitlab.Spelling = NO --> This started as a [plugin for vim by tpope](https://github.com/tpope/vim-projectionist) It has since become editor-agnostic and ported to most modern editors. +<!-- vale gitlab.Spelling = YES -->
\ No newline at end of file diff --git a/doc/development/prometheus_metrics.md b/doc/development/prometheus_metrics.md index df13cb7d56c..7296ea726ca 100644 --- a/doc/development/prometheus_metrics.md +++ b/doc/development/prometheus_metrics.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Working with Prometheus Metrics +# Working with Prometheus Metrics **(FREE)** ## Adding to the library diff --git a/doc/development/pry_debugging.md b/doc/development/pry_debugging.md index f29e0d403cd..7182cf33ccc 100644 --- a/doc/development/pry_debugging.md +++ b/doc/development/pry_debugging.md @@ -79,7 +79,7 @@ Similar to source browsing, is [Documentation browsing](https://github.com/pry/p ### Command history -With **Ctrl+R** you can search your [command history](https://github.com/pry/pry/wiki/History). +With <kbd>Control</kbd> + <kbd>R</kbd> you can search your [command history](https://github.com/pry/pry/wiki/History). ## Stepping diff --git a/doc/development/python_guide/index.md b/doc/development/python_guide/index.md index 3291b6c31a9..fe5492c3bd8 100644 --- a/doc/development/python_guide/index.md +++ b/doc/development/python_guide/index.md @@ -14,8 +14,8 @@ As of GitLab 11.10, we require Python 3. ## Installation There are several ways of installing Python on your system. To be able to use the same version we use in production, -we suggest you use [pyenv](https://github.com/pyenv/pyenv). It works and behaves similarly to its counterpart in the -Ruby world: [rbenv](https://github.com/rbenv/rbenv). +we suggest you use [`pyenv`](https://github.com/pyenv/pyenv). It works and behaves similarly to its counterpart in the +Ruby world: [`rbenv`](https://github.com/rbenv/rbenv). ### macOS @@ -35,11 +35,11 @@ curl "https://pyenv.run" | bash Alternatively, you may find `pyenv` available as a system package via your distribution's package manager. -You can read more about it in: <https://github.com/pyenv/pyenv-installer#prerequisites>. +You can read more about it in [the `pyenv` prerequisites](https://github.com/pyenv/pyenv-installer#prerequisites). ### Shell integration -Pyenv installation adds required changes to Bash. If you use a different shell, +`Pyenv` installation adds required changes to Bash. If you use a different shell, check for any additional steps required for it. For Fish, you can install a plugin for [Fisher](https://github.com/jorgebucaran/fisher): diff --git a/doc/development/reactive_caching.md b/doc/development/reactive_caching.md index 5d514ffbfc9..0223f5d91d6 100644 --- a/doc/development/reactive_caching.md +++ b/doc/development/reactive_caching.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # `ReactiveCaching` -> This doc refers to <https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/concerns/reactive_caching.rb>. +> This doc refers to [`reactive_caching.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/concerns/reactive_caching.rb). The `ReactiveCaching` concern is used for fetching some data in the background and storing it in the Rails cache, keeping it up-to-date for as long as it is being requested. If the @@ -103,7 +103,7 @@ not wait until the background worker completes. - An API that calls a model or service method that uses `ReactiveCaching` should return `202 accepted` when the cache is being calculated (when `#with_reactive_cache` returns `nil`). - It should also - [set the polling interval header](fe_guide/performance.md#realtime-components) with + [set the polling interval header](fe_guide/performance.md#real-time-components) with `Gitlab::PollingInterval.set_header`. - The consumer of the API is expected to poll the API. - You can also consider implementing [ETag caching](polling.md) to reduce the server diff --git a/doc/development/redis.md b/doc/development/redis.md index bb725e3c321..0dca415b77c 100644 --- a/doc/development/redis.md +++ b/doc/development/redis.md @@ -74,8 +74,10 @@ which is enabled for the `cache` and `shared_state` ## Redis in structured logging -For GitLab Team Members: There are [basic](https://www.youtube.com/watch?v=Uhdj19Dc6vU) and -[advanced](https://youtu.be/jw1Wv2IJxzs) videos that show how you can work with the Redis +For GitLab Team Members: There are <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +[basic](https://www.youtube.com/watch?v=Uhdj19Dc6vU) and +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [advanced](https://youtu.be/jw1Wv2IJxzs) +videos that show how you can work with the Redis structured logging fields on GitLab.com. Our [structured logging](logging.md#use-structured-json-logging) for web diff --git a/doc/development/refactoring_guide/index.md b/doc/development/refactoring_guide/index.md index 224b6bf9b38..a25000589c0 100644 --- a/doc/development/refactoring_guide/index.md +++ b/doc/development/refactoring_guide/index.md @@ -80,4 +80,4 @@ expect(cleanForSnapshot(wrapper.element)).toMatchSnapshot(); - [Pinning test in refactoring dropdown](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28173) - [Pinning test in refactoring vulnerability_details.vue](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25830/commits) - [Pinning test in refactoring notes_award_list.vue](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29528#pinning-test) -- [Video of pair programming session on pinning tests](https://youtu.be/LrakPcspBK4) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Video of pair programming session on pinning tests](https://youtu.be/LrakPcspBK4) diff --git a/doc/development/repository_mirroring.md b/doc/development/repository_mirroring.md index 4153bcf77a5..61157c88618 100644 --- a/doc/development/repository_mirroring.md +++ b/doc/development/repository_mirroring.md @@ -8,10 +8,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Deep Dive +<!-- vale gitlab.Spelling = NO --> + In December 2018, Tiago Botelho hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) on the GitLab [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 -codebase in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=sSZq0fpdY-Y), +codebase in the future. You can find the <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [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). Everything covered in this deep dive was accurate as of GitLab 11.6, and while specific details may have changed since then, it should still serve as a good introduction. + +<!-- vale gitlab.Spelling = YES -->
\ No newline at end of file diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md deleted file mode 100644 index 7456e8df8d9..00000000000 --- a/doc/development/rolling_out_changes_using_feature_flags.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'feature_flags/index.md' ---- - -This document was moved to [another location](feature_flags/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md index bd98ea170e5..41a7defbc26 100644 --- a/doc/development/secure_coding_guidelines.md +++ b/doc/development/secure_coding_guidelines.md @@ -180,7 +180,7 @@ For other regular expressions, here are a few guidelines: - If there's a clean non-regex solution, such as `String#start_with?`, consider using it - Ruby supports some advanced regex features like [atomic groups](https://www.regular-expressions.info/atomic.html) -and [possessive quantifiers](https://www.regular-expressions.info/possessive.html) that eleminate backtracking +and [possessive quantifiers](https://www.regular-expressions.info/possessive.html) that eliminate backtracking - Avoid nested quantifiers if possible (for example `(a+)+`) - Try to be as precise as possible in your regex and avoid the `.` if there's an alternative - For example, Use `_[^_]+_` instead of `_.*_` to match `_text here_` @@ -288,9 +288,9 @@ XSS issues are commonly classified in three categories, by their delivery method The injected client-side code is executed on the victim's browser in the context of their current session. This means the attacker could perform any same action the victim would normally be able to do through a browser. The attacker would also have the ability to: -- [log victim keystrokes](https://youtu.be/2VFavqfDS6w?t=1367) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [log victim keystrokes](https://youtu.be/2VFavqfDS6w?t=1367) - launch a network scan from the victim's browser -- potentially [obtain the victim's session tokens](https://youtu.be/2VFavqfDS6w?t=739) +- potentially <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [obtain the victim's session tokens](https://youtu.be/2VFavqfDS6w?t=739) - perform actions that lead to data loss/theft or account takeover Much of the impact is contingent upon the function of the application and the capabilities of the victim's session. For further impact possibilities, please check out [the beef project](https://beefproject.com/). @@ -309,14 +309,14 @@ In most situations, a two-step solution can be used: input validation and output ##### Setting expectations -For any and all input fields, ensure to define expectations on the type/format of input, the contents, [size limits](https://youtu.be/2VFavqfDS6w?t=7582), the context in which it will be output. It's important to work with both security and product teams to determine what is considered acceptable input. +For any and all input fields, ensure to define expectations on the type/format of input, the contents, <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [size limits](https://youtu.be/2VFavqfDS6w?t=7582), the context in which it will be output. It's important to work with both security and product teams to determine what is considered acceptable input. ##### Validate input - Treat all user input as untrusted. - Based on the expectations you [defined above](#setting-expectations): - - Validate the [input size limits](https://youtu.be/2VFavqfDS6w?t=7582). - - Validate the input using an [allowlist approach](https://youtu.be/2VFavqfDS6w?t=7816) to only allow characters through which you are expecting to receive for the field. + - Validate the <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [input size limits](https://youtu.be/2VFavqfDS6w?t=7582). + - Validate the input using an <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [allowlist approach](https://youtu.be/2VFavqfDS6w?t=7816) to only allow characters through which you are expecting to receive for the field. - Input which fails validation should be **rejected**, and not sanitized. - When adding redirects or links to a user-controlled URL, ensure that the scheme is HTTP or HTTPS. Allowing other schemes like `javascript://` can lead to XSS and other security issues. @@ -328,8 +328,8 @@ Once you've [determined when and where](#setting-expectations) the user submitte - Content placed inside HTML elements need to be [HTML entity encoded](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html#rule-1---html-escape-before-inserting-untrusted-data-into-html-element-content). - Content placed into a JSON response needs to be [JSON encoded](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html#rule-31---html-escape-json-values-in-an-html-context-and-read-the-data-with-jsonparse). -- Content placed inside [HTML URL GET parameters](https://youtu.be/2VFavqfDS6w?t=3494) need to be [URL-encoded](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html#rule-5---url-escape-before-inserting-untrusted-data-into-html-url-parameter-values) -- [Additional contexts may require context-specific encoding](https://youtu.be/2VFavqfDS6w?t=2341). +- Content placed inside <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [HTML URL GET parameters](https://youtu.be/2VFavqfDS6w?t=3494) need to be [URL-encoded](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html#rule-5---url-escape-before-inserting-untrusted-data-into-html-url-parameter-values) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Additional contexts may require context-specific encoding](https://youtu.be/2VFavqfDS6w?t=2341). ### Additional information @@ -352,10 +352,10 @@ Do also sanitize and validate URL schemes. References: -- [XSS Defense in Rails](https://youtu.be/2VFavqfDS6w?t=2442) -- [XSS Defense with HAML](https://youtu.be/2VFavqfDS6w?t=2796) -- [Validating Untrusted URLs in Ruby](https://youtu.be/2VFavqfDS6w?t=3936) -- [RoR Model Validators](https://youtu.be/2VFavqfDS6w?t=7636) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [XSS Defense in Rails](https://youtu.be/2VFavqfDS6w?t=2442) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [XSS Defense with HAML](https://youtu.be/2VFavqfDS6w?t=2796) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Validating Untrusted URLs in Ruby](https://youtu.be/2VFavqfDS6w?t=3936) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [RoR Model Validators](https://youtu.be/2VFavqfDS6w?t=7636) #### XSS mitigation and prevention in JavaScript and Vue @@ -376,7 +376,7 @@ References: #### Content Security Policy -- [Content Security Policy](https://www.youtube.com/watch?v=2VFavqfDS6w&t=12991s) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Content Security Policy](https://www.youtube.com/watch?v=2VFavqfDS6w&t=12991s) - [Use nonce-based Content Security Policy for inline JavaScript](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/65330) #### Free form input field @@ -390,26 +390,26 @@ References: ### Internal Developer Training -- [Introduction to XSS](https://www.youtube.com/watch?v=PXR8PTojHmc&t=7785s) -- [Reflected XSS](https://youtu.be/2VFavqfDS6w?t=603s) -- [Persistent XSS](https://youtu.be/2VFavqfDS6w?t=643) -- [DOM XSS](https://youtu.be/2VFavqfDS6w?t=5871) -- [XSS in depth](https://www.youtube.com/watch?v=2VFavqfDS6w&t=111s) -- [XSS Defense](https://youtu.be/2VFavqfDS6w?t=1685) -- [XSS Defense in Rails](https://youtu.be/2VFavqfDS6w?t=2442) -- [XSS Defense with HAML](https://youtu.be/2VFavqfDS6w?t=2796) -- [JavaScript URLs](https://youtu.be/2VFavqfDS6w?t=3274) -- [URL encoding context](https://youtu.be/2VFavqfDS6w?t=3494) -- [Validating Untrusted URLs in Ruby](https://youtu.be/2VFavqfDS6w?t=3936) -- [HTML Sanitization](https://youtu.be/2VFavqfDS6w?t=5075) -- [DOMPurify](https://youtu.be/2VFavqfDS6w?t=5381) -- [Safe Client-side JSON Handling](https://youtu.be/2VFavqfDS6w?t=6334) -- [iframe sandboxing](https://youtu.be/2VFavqfDS6w?t=7043) -- [Input Validation](https://youtu.be/2VFavqfDS6w?t=7489) -- [Validate size limits](https://youtu.be/2VFavqfDS6w?t=7582) -- [RoR model validators](https://youtu.be/2VFavqfDS6w?t=7636) -- [Allowlist input validation](https://youtu.be/2VFavqfDS6w?t=7816) -- [Content Security Policy](https://www.youtube.com/watch?v=2VFavqfDS6w&t=12991s) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Introduction to XSS](https://www.youtube.com/watch?v=PXR8PTojHmc&t=7785s) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Reflected XSS](https://youtu.be/2VFavqfDS6w?t=603s) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Persistent XSS](https://youtu.be/2VFavqfDS6w?t=643) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [DOM XSS](https://youtu.be/2VFavqfDS6w?t=5871) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [XSS in depth](https://www.youtube.com/watch?v=2VFavqfDS6w&t=111s) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [XSS Defense](https://youtu.be/2VFavqfDS6w?t=1685) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [XSS Defense in Rails](https://youtu.be/2VFavqfDS6w?t=2442) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [XSS Defense with HAML](https://youtu.be/2VFavqfDS6w?t=2796) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [JavaScript URLs](https://youtu.be/2VFavqfDS6w?t=3274) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [URL encoding context](https://youtu.be/2VFavqfDS6w?t=3494) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Validating Untrusted URLs in Ruby](https://youtu.be/2VFavqfDS6w?t=3936) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [HTML Sanitization](https://youtu.be/2VFavqfDS6w?t=5075) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [DOMPurify](https://youtu.be/2VFavqfDS6w?t=5381) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Safe Client-side JSON Handling](https://youtu.be/2VFavqfDS6w?t=6334) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [iframe sandboxing](https://youtu.be/2VFavqfDS6w?t=7043) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Input Validation](https://youtu.be/2VFavqfDS6w?t=7489) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Validate size limits](https://youtu.be/2VFavqfDS6w?t=7582) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [RoR model validators](https://youtu.be/2VFavqfDS6w?t=7636) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Allowlist input validation](https://youtu.be/2VFavqfDS6w?t=7816) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Content Security Policy](https://www.youtube.com/watch?v=2VFavqfDS6w&t=12991s) ## Path Traversal guidelines @@ -423,14 +423,14 @@ Path Traversal attacks can lead to multiple critical and high severity issues, l ### When to consider -When working with user-controlled filenames/paths and filesystem APIs. +When working with user-controlled filenames/paths and file system APIs. ### Mitigation and prevention In order to prevent Path Traversal vulnerabilities, user-controlled filenames or paths should be validated before being processed. - Comparing user input against an allowlist of allowed values or verifying that it only contains allowed characters. -- After validating the user supplied input, it should be appended to the base directory and the path should be canonicalized using the filesystem API. +- After validating the user supplied input, it should be appended to the base directory and the path should be canonicalized using the file system API. #### GitLab specific validations diff --git a/doc/development/shared_files.md b/doc/development/shared_files.md index 859650c2e6c..6c273f2899d 100644 --- a/doc/development/shared_files.md +++ b/doc/development/shared_files.md @@ -32,7 +32,7 @@ disk in a temporary file so you can perform some checks on it. When the checks pass, you make the file official. In scenarios like this please follow these rules: -- Store the temporary file under `shared/tmp`, i.e. on the same filesystem you +- Store the temporary file under `shared/tmp`, i.e. on the same file system you want the official file to be on. - Use move/rename operations when operating on the file instead of copy operations where possible, because renaming a file is much faster than diff --git a/doc/development/shell_commands.md b/doc/development/shell_commands.md index db72454b482..f28828c2e4e 100644 --- a/doc/development/shell_commands.md +++ b/doc/development/shell_commands.md @@ -202,7 +202,7 @@ When using regular expressions to validate user input that is passed as an argum If you don't, an attacker could use this to execute commands with potentially harmful effect. -For example, when a project's `import_url` is validated like below, the user could trick GitLab into cloning from a Git repository on the local filesystem. +For example, when a project's `import_url` is validated like below, the user could trick GitLab into cloning from a Git repository on the local file system. ```ruby validates :import_url, format: { with: URI.regexp(%w(ssh git http https)) } diff --git a/doc/development/sidekiq_debugging.md b/doc/development/sidekiq_debugging.md deleted file mode 100644 index a9b6e246861..00000000000 --- a/doc/development/sidekiq_debugging.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../administration/troubleshooting/sidekiq.md' ---- - -This document was moved to [another location](../administration/troubleshooting/sidekiq.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md index e290eaee7c2..ce00934b35c 100644 --- a/doc/development/sidekiq_style_guide.md +++ b/doc/development/sidekiq_style_guide.md @@ -550,7 +550,7 @@ in the default execution mode - using does not account for weights. As we are [moving towards using `sidekiq-cluster` in -Core](https://gitlab.com/gitlab-org/gitlab/-/issues/34396), newly-added +Free](https://gitlab.com/gitlab-org/gitlab/-/issues/34396), newly-added workers do not need to have weights specified. They can simply use the default weight, which is 1. diff --git a/doc/development/snowplow.md b/doc/development/snowplow.md index 6b37936cd93..fa912f8f41f 100644 --- a/doc/development/snowplow.md +++ b/doc/development/snowplow.md @@ -104,9 +104,9 @@ The current method provides several attributes that are sent on each click event | attribute | type | required | description | | --------- | ------- | -------- | ----------- | -| category | text | true | The page or backend area of the application. Unless infeasible, please use the Rails page attribute by default in the frontend, and namespace + classname on the backend. | +| category | text | true | The page or backend area of the application. Unless infeasible, please use the Rails page attribute by default in the frontend, and namespace + class name on the backend. | | action | text | true | The action the user is taking, or aspect that's being instrumented. The first word should always describe the action or aspect: clicks should be `click`, activations should be `activate`, creations should be `create`, etc. Use underscores to describe what was acted on; for example, activating a form field would be `activate_form_input`. An interface action like clicking on a dropdown would be `click_dropdown`, while a behavior like creating a project record from the backend would be `create_project` | -| label | text | false | The specific element, or object that's being acted on. This is either the label of the element (e.g. a tab labeled 'Create from template' may be `create_from_template`) or a unique identifier if no text is available (e.g. closing the Groups dropdown in the top navbar might be `groups_dropdown_close`), or it could be the name or title attribute of a record being created. | +| label | text | false | The specific element, or object that's being acted on. This is either the label of the element (e.g. a tab labeled 'Create from template' may be `create_from_template`) or a unique identifier if no text is available (e.g. closing the Groups dropdown in the top navigation bar might be `groups_dropdown_close`), or it could be the name or title attribute of a record being created. | | property | text | false | Any additional property of the element, or object being acted on. | | value | decimal | false | Describes a numeric value or something directly related to the event. This could be the value of an input (e.g. `10` when clicking `internal` visibility). | @@ -120,9 +120,9 @@ GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tra | field | type | default value | description | |:-----------|:-------|:---------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `category` | string | document.body.dataset.page | Page or subsection of a page that events are being captured within. | +| `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 [Structured event taxonomy](#structured-event-taxonomy). | +| `data` | object | `{}` | Additional data such as `label`, `property`, `value`, and `context` as described in our [Structured event taxonomy](#structured-event-taxonomy). | ### Tracking in HAML (or Vue Templates) @@ -303,11 +303,14 @@ GitLab provides `Gitlab::Tracking`, an interface that wraps the [Snowplow Ruby T Custom event tracking and instrumentation can be added by directly calling the `GitLab::Tracking.event` class method, which accepts the following arguments: -| argument | type | default value | description | -|:-----------|:-------|:--------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `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 [Structured event taxonomy](#structured-event-taxonomy). These are set as empty strings if you don't provide them. | +| argument | type | default value | description | +|------------|---------------------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------| +| `category` | String | | Area or aspect of the application. This could be `HealthCheckController` or `Lfs::FileTransformer` for instance. | +| `action` | String | | The action being taken, which can be anything from a controller action like `create` to something like an Active Record callback. | +| `label` | String | nil | As described in [Structured event taxonomy](#structured-event-taxonomy). | +| `property` | String | nil | As described in [Structured event taxonomy](#structured-event-taxonomy). | +| `value` | Numeric | nil | As described in [Structured event taxonomy](#structured-event-taxonomy). | +| `context` | Array\[SelfDescribingJSON\] | nil | An array of custom contexts to send with this event. Most events should not have any custom contexts. | Tracking can be viewed as either tracking user behavior, or can be used for instrumentation to monitor and visualize performance over time in an area or aspect of code. @@ -379,7 +382,7 @@ Snowplow Micro is a Docker-based solution for testing frontend and backend event - Read [Introducing Snowplow Micro](https://snowplowanalytics.com/blog/2019/07/17/introducing-snowplow-micro/) - Look at the [Snowplow Micro repository](https://github.com/snowplow-incubator/snowplow-micro) -- Watch our [installation guide recording](https://www.youtube.com/watch?v=OX46fo_A0Ag) +- Watch our <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [installation guide recording](https://www.youtube.com/watch?v=OX46fo_A0Ag) 1. Ensure Docker is installed and running. @@ -478,146 +481,152 @@ For GitLab.com, we're setting up a [QA and Testing environment](https://gitlab.c ## Snowplow Schemas -### [gitlab_standard](https://gitlab.com/gitlab-org/iglu/-/blob/master/public/schemas/com.gitlab/gitlab_standard/jsonschema/1-0-0) Schema +### `gitlab_standard` -| Field Name | Required | Type | Description | -|--------------|---------------------|---------|--------------------------------| -| project_id | **{dotted-circle}** | integer | ID of the associated project | -| namespace_id | **{dotted-circle}** | integer | ID of the associated namespace | +We are currently working towards including the [`gitlab_standard` schema](https://gitlab.com/gitlab-org/iglu/-/blob/master/public/schemas/com.gitlab/gitlab_standard/jsonschema/) with every event. See [Standardize Snowplow Schema](https://gitlab.com/groups/gitlab-org/-/epics/5218) for details. + +The [`StandardContext`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/tracking/standard_context.rb) class represents this schema in the application. + +| Field Name | Required | Type | Description | +|----------------|---------------------|-----------------------|---------------------------------------------------------------------------------------------| +| `project_id` | **{dotted-circle}** | integer | | +| `namespace_id` | **{dotted-circle}** | integer | | +| `environment` | **{check-circle}** | string (max 32 chars) | Name of the source environment, such as `production` or `staging` | +| `source` | **{check-circle}** | string (max 32 chars) | Name of the source application, such as `gitlab-rails` or `gitlab-javascript` | ### Default Schema | Field Name | Required | Type | Description | |--------------------------|---------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------| -| app_id | **{check-circle}** | string | Unique identifier for website / application | -| base_currency | **{dotted-circle}** | string | Reporting currency | -| br_colordepth | **{dotted-circle}** | integer | Browser color depth | -| br_cookies | **{dotted-circle}** | boolean | Does the browser permit cookies? | -| br_family | **{dotted-circle}** | string | Browser family | -| br_features_director | **{dotted-circle}** | boolean | Director plugin installed? | -| br_features_flash | **{dotted-circle}** | boolean | Flash plugin installed? | -| br_features_gears | **{dotted-circle}** | boolean | Google gears installed? | -| br_features_java | **{dotted-circle}** | boolean | Java plugin installed? | -| br_features_pdf | **{dotted-circle}** | boolean | Adobe PDF plugin installed? | -| br_features_quicktime | **{dotted-circle}** | boolean | Quicktime plugin installed? | -| br_features_realplayer | **{dotted-circle}** | boolean | Realplayer plugin installed? | -| br_features_silverlight | **{dotted-circle}** | boolean | Silverlight plugin installed? | -| br_features_windowsmedia | **{dotted-circle}** | boolean | Windows media plugin installed? | -| br_lang | **{dotted-circle}** | string | Language the browser is set to | -| br_name | **{dotted-circle}** | string | Browser name | -| br_renderengine | **{dotted-circle}** | string | Browser rendering engine | -| br_type | **{dotted-circle}** | string | Browser type | -| br_version | **{dotted-circle}** | string | Browser version | -| br_viewheight | **{dotted-circle}** | string | Browser viewport height | -| br_viewwidth | **{dotted-circle}** | string | Browser viewport width | -| collector_tstamp | **{dotted-circle}** | timestamp | Time stamp for the event recorded by the collector | -| contexts | **{dotted-circle}** | | | -| derived_contexts | **{dotted-circle}** | | Contexts derived in the Enrich process | -| derived_tstamp | **{dotted-circle}** | timestamp | Timestamp making allowance for innaccurate device clock | -| doc_charset | **{dotted-circle}** | string | Web page’s character encoding | -| doc_height | **{dotted-circle}** | string | Web page height | -| doc_width | **{dotted-circle}** | string | Web page width | -| domain_sessionid | **{dotted-circle}** | string | Unique identifier (UUID) for this visit of this user_id to this domain | -| domain_sessionidx | **{dotted-circle}** | integer | Index of number of visits that this user_id has made to this domain (The first visit is `1`) | -| domain_userid | **{dotted-circle}** | string | Unique identifier for a user, based on a first party cookie (so domain specific) | -| dvce_created_tstamp | **{dotted-circle}** | timestamp | Timestamp when event occurred, as recorded by client device | -| dvce_ismobile | **{dotted-circle}** | boolean | Indicates whether device is mobile | -| dvce_screenheight | **{dotted-circle}** | string | Screen / monitor resolution | -| dvce_screenwidth | **{dotted-circle}** | string | Screen / monitor resolution | -| dvce_sent_tstamp | **{dotted-circle}** | timestamp | Timestamp when event was sent by client device to collector | -| dvce_type | **{dotted-circle}** | string | Type of device | -| etl_tags | **{dotted-circle}** | string | JSON of tags for this ETL run | -| etl_tstamp | **{dotted-circle}** | timestamp | Timestamp event began ETL | -| event | **{dotted-circle}** | string | Event type | -| event_fingerprint | **{dotted-circle}** | string | Hash client-set event fields | -| event_format | **{dotted-circle}** | string | Format for event | -| event_id | **{dotted-circle}** | string | Event UUID | -| event_name | **{dotted-circle}** | string | Event name | -| event_vendor | **{dotted-circle}** | string | The company who developed the event model | -| event_version | **{dotted-circle}** | string | Version of event schema | -| geo_city | **{dotted-circle}** | string | City of IP origin | -| geo_country | **{dotted-circle}** | string | Country of IP origin | -| geo_latitude | **{dotted-circle}** | string | An approximate latitude | -| geo_longitude | **{dotted-circle}** | string | An approximate longitude | -| geo_region | **{dotted-circle}** | string | Region of IP origin | -| geo_region_name | **{dotted-circle}** | string | Region of IP origin | -| geo_timezone | **{dotted-circle}** | string | Timezone of IP origin | -| geo_zipcode | **{dotted-circle}** | string | Zip (postal) code of IP origin | -| ip_domain | **{dotted-circle}** | string | Second level domain name associated with the visitor’s IP address | -| ip_isp | **{dotted-circle}** | string | Visitor’s ISP | -| ip_netspeed | **{dotted-circle}** | string | Visitor’s connection type | -| ip_organization | **{dotted-circle}** | string | Organization associated with the visitor’s IP address – defaults to ISP name if none is found | -| mkt_campaign | **{dotted-circle}** | string | The campaign ID | -| mkt_clickid | **{dotted-circle}** | string | The click ID | -| mkt_content | **{dotted-circle}** | string | The content or ID of the ad. | -| mkt_medium | **{dotted-circle}** | string | Type of traffic source | -| mkt_network | **{dotted-circle}** | string | The ad network to which the click ID belongs | -| mkt_source | **{dotted-circle}** | string | The company / website where the traffic came from | -| mkt_term | **{dotted-circle}** | string | Keywords associated with the referrer | -| name_tracker | **{dotted-circle}** | string | The tracker namespace | -| network_userid | **{dotted-circle}** | string | Unique identifier for a user, based on a cookie from the collector (so set at a network level and shouldn’t be set by a tracker) | -| os_family | **{dotted-circle}** | string | Operating system family | -| os_manufacturer | **{dotted-circle}** | string | Manufacturers of operating system | -| os_name | **{dotted-circle}** | string | Name of operating system | -| os_timezone | **{dotted-circle}** | string | Client operating system timezone | -| page_referrer | **{dotted-circle}** | string | Referrer URL | -| page_title | **{dotted-circle}** | string | Page title | -| page_url | **{dotted-circle}** | string | Page URL | -| page_urlfragment | **{dotted-circle}** | string | Fragment aka anchor | -| page_urlhost | **{dotted-circle}** | string | Host aka domain | -| page_urlpath | **{dotted-circle}** | string | Path to page | -| page_urlport | **{dotted-circle}** | integer | Port if specified, 80 if not | -| page_urlquery | **{dotted-circle}** | string | Query string | -| page_urlscheme | **{dotted-circle}** | string | Scheme (protocol name) | -| platform | **{dotted-circle}** | string | The platform the app runs on | -| pp_xoffset_max | **{dotted-circle}** | integer | Maximum page x offset seen in the last ping period | -| pp_xoffset_min | **{dotted-circle}** | integer | Minimum page x offset seen in the last ping period | -| pp_yoffset_max | **{dotted-circle}** | integer | Maximum page y offset seen in the last ping period | -| pp_yoffset_min | **{dotted-circle}** | integer | Minimum page y offset seen in the last ping period | -| refr_domain_userid | **{dotted-circle}** | string | The Snowplow domain_userid of the referring website | -| refr_dvce_tstamp | **{dotted-circle}** | timestamp | The time of attaching the domain_userid to the inbound link | -| refr_medium | **{dotted-circle}** | string | Type of referer | -| refr_source | **{dotted-circle}** | string | Name of referer if recognised | -| refr_term | **{dotted-circle}** | string | Keywords if source is a search engine | -| refr_urlfragment | **{dotted-circle}** | string | Referer URL fragment | -| refr_urlhost | **{dotted-circle}** | string | Referer host | -| refr_urlpath | **{dotted-circle}** | string | Referer page path | -| refr_urlport | **{dotted-circle}** | integer | Referer port | -| refr_urlquery | **{dotted-circle}** | string | Referer URL querystring | -| refr_urlscheme | **{dotted-circle}** | string | Referer scheme | -| se_action | **{dotted-circle}** | string | The action / event itself | -| se_category | **{dotted-circle}** | string | The category of event | -| se_label | **{dotted-circle}** | string | A label often used to refer to the ‘object’ the action is performed on | -| se_property | **{dotted-circle}** | string | A property associated with either the action or the object | -| se_value | **{dotted-circle}** | decimal | A value associated with the user action | -| ti_category | **{dotted-circle}** | string | Item category | -| ti_currency | **{dotted-circle}** | string | Currency | -| ti_name | **{dotted-circle}** | string | Item name | -| ti_orderid | **{dotted-circle}** | string | Order ID | -| ti_price | **{dotted-circle}** | decimal | Item price | -| ti_price_base | **{dotted-circle}** | decimal | Item price in base currency | -| ti_quantity | **{dotted-circle}** | integer | Item quantity | -| ti_sku | **{dotted-circle}** | string | Item SKU | -| tr_affiliation | **{dotted-circle}** | string | Transaction affiliation (such as channel) | -| tr_city | **{dotted-circle}** | string | Delivery address: city | -| tr_country | **{dotted-circle}** | string | Delivery address: country | -| tr_currency | **{dotted-circle}** | string | Transaction Currency | -| tr_orderid | **{dotted-circle}** | string | Order ID | -| tr_shipping | **{dotted-circle}** | decimal | Delivery cost charged | -| tr_shipping_base | **{dotted-circle}** | decimal | Shipping cost in base currency | -| tr_state | **{dotted-circle}** | string | Delivery address: state | -| tr_tax | **{dotted-circle}** | decimal | Transaction tax value (such as amount of VAT included) | -| tr_tax_base | **{dotted-circle}** | decimal | Tax applied in base currency | -| tr_total | **{dotted-circle}** | decimal | Transaction total value | -| tr_total_base | **{dotted-circle}** | decimal | Total amount of transaction in base currency | -| true_tstamp | **{dotted-circle}** | timestamp | User-set exact timestamp | -| txn_id | **{dotted-circle}** | string | Transaction ID | -| unstruct_event | **{dotted-circle}** | JSON | The properties of the event | -| uploaded_at | **{dotted-circle}** | | | -| user_fingerprint | **{dotted-circle}** | integer | User identifier based on (hopefully unique) browser features | -| user_id | **{dotted-circle}** | string | Unique identifier for user, set by the business using setUserId | -| user_ipaddress | **{dotted-circle}** | string | IP address | -| useragent | **{dotted-circle}** | string | User agent (expressed as a browser string) | -| v_collector | **{dotted-circle}** | string | Collector version | -| v_etl | **{dotted-circle}** | string | ETL version | -| v_tracker | **{dotted-circle}** | string | Identifier for Snowplow tracker | +| `app_id` | **{check-circle}** | string | Unique identifier for website / application | +| `base_currency` | **{dotted-circle}** | string | Reporting currency | +| `br_colordepth` | **{dotted-circle}** | integer | Browser color depth | +| `br_cookies` | **{dotted-circle}** | boolean | Does the browser permit cookies? | +| `br_family` | **{dotted-circle}** | string | Browser family | +| `br_features_director` | **{dotted-circle}** | boolean | Director plugin installed? | +| `br_features_flash` | **{dotted-circle}** | boolean | Flash plugin installed? | +| `br_features_gears` | **{dotted-circle}** | boolean | Google gears installed? | +| `br_features_java` | **{dotted-circle}** | boolean | Java plugin installed? | +| `br_features_pdf` | **{dotted-circle}** | boolean | Adobe PDF plugin installed? | +| `br_features_quicktime` | **{dotted-circle}** | boolean | Quicktime plugin installed? | +| `br_features_realplayer` | **{dotted-circle}** | boolean | RealPlayer plugin installed? | +| `br_features_silverlight` | **{dotted-circle}** | boolean | Silverlight plugin installed? | +| `br_features_windowsmedia` | **{dotted-circle}** | boolean | Windows media plugin installed? | +| `br_lang` | **{dotted-circle}** | string | Language the browser is set to | +| `br_name` | **{dotted-circle}** | string | Browser name | +| `br_renderengine` | **{dotted-circle}** | string | Browser rendering engine | +| `br_type` | **{dotted-circle}** | string | Browser type | +| `br_version` | **{dotted-circle}** | string | Browser version | +| `br_viewheight` | **{dotted-circle}** | string | Browser viewport height | +| `br_viewwidth` | **{dotted-circle}** | string | Browser viewport width | +| `collector_tstamp` | **{dotted-circle}** | timestamp | Time stamp for the event recorded by the collector | +| `contexts` | **{dotted-circle}** | | | +| `derived_contexts` | **{dotted-circle}** | | Contexts derived in the Enrich process | +| `derived_tstamp` | **{dotted-circle}** | timestamp | Timestamp making allowance for inaccurate device clock | +| `doc_charset` | **{dotted-circle}** | string | Web page’s character encoding | +| `doc_height` | **{dotted-circle}** | string | Web page height | +| `doc_width` | **{dotted-circle}** | string | Web page width | +| `domain_sessionid` | **{dotted-circle}** | string | Unique identifier (UUID) for this visit of this user_id to this domain | +| `domain_sessionidx` | **{dotted-circle}** | integer | Index of number of visits that this user_id has made to this domain (The first visit is `1`) | +| `domain_userid` | **{dotted-circle}** | string | Unique identifier for a user, based on a first party cookie (so domain specific) | +| `dvce_created_tstamp` | **{dotted-circle}** | timestamp | Timestamp when event occurred, as recorded by client device | +| `dvce_ismobile` | **{dotted-circle}** | boolean | Indicates whether device is mobile | +| `dvce_screenheight` | **{dotted-circle}** | string | Screen / monitor resolution | +| `dvce_screenwidth` | **{dotted-circle}** | string | Screen / monitor resolution | +| `dvce_sent_tstamp` | **{dotted-circle}** | timestamp | Timestamp when event was sent by client device to collector | +| `dvce_type` | **{dotted-circle}** | string | Type of device | +| `etl_tags` | **{dotted-circle}** | string | JSON of tags for this ETL run | +| `etl_tstamp` | **{dotted-circle}** | timestamp | Timestamp event began ETL | +| `event` | **{dotted-circle}** | string | Event type | +| `event_fingerprint` | **{dotted-circle}** | string | Hash client-set event fields | +| `event_format` | **{dotted-circle}** | string | Format for event | +| `event_id` | **{dotted-circle}** | string | Event UUID | +| `event_name` | **{dotted-circle}** | string | Event name | +| `event_vendor` | **{dotted-circle}** | string | The company who developed the event model | +| `event_version` | **{dotted-circle}** | string | Version of event schema | +| `geo_city` | **{dotted-circle}** | string | City of IP origin | +| `geo_country` | **{dotted-circle}** | string | Country of IP origin | +| `geo_latitude` | **{dotted-circle}** | string | An approximate latitude | +| `geo_longitude` | **{dotted-circle}** | string | An approximate longitude | +| `geo_region` | **{dotted-circle}** | string | Region of IP origin | +| `geo_region_name` | **{dotted-circle}** | string | Region of IP origin | +| `geo_timezone` | **{dotted-circle}** | string | Timezone of IP origin | +| `geo_zipcode` | **{dotted-circle}** | string | Zip (postal) code of IP origin | +| `ip_domain` | **{dotted-circle}** | string | Second level domain name associated with the visitor’s IP address | +| `ip_isp` | **{dotted-circle}** | string | Visitor’s ISP | +| `ip_netspeed` | **{dotted-circle}** | string | Visitor’s connection type | +| `ip_organization` | **{dotted-circle}** | string | Organization associated with the visitor’s IP address – defaults to ISP name if none is found | +| `mkt_campaign` | **{dotted-circle}** | string | The campaign ID | +| `mkt_clickid` | **{dotted-circle}** | string | The click ID | +| `mkt_content` | **{dotted-circle}** | string | The content or ID of the ad. | +| `mkt_medium` | **{dotted-circle}** | string | Type of traffic source | +| `mkt_network` | **{dotted-circle}** | string | The ad network to which the click ID belongs | +| `mkt_source` | **{dotted-circle}** | string | The company / website where the traffic came from | +| `mkt_term` | **{dotted-circle}** | string | Keywords associated with the referrer | +| `name_tracker` | **{dotted-circle}** | string | The tracker namespace | +| `network_userid` | **{dotted-circle}** | string | Unique identifier for a user, based on a cookie from the collector (so set at a network level and shouldn’t be set by a tracker) | +| `os_family` | **{dotted-circle}** | string | Operating system family | +| `os_manufacturer` | **{dotted-circle}** | string | Manufacturers of operating system | +| `os_name` | **{dotted-circle}** | string | Name of operating system | +| `os_timezone` | **{dotted-circle}** | string | Client operating system timezone | +| `page_referrer` | **{dotted-circle}** | string | Referrer URL | +| `page_title` | **{dotted-circle}** | string | Page title | +| `page_url` | **{dotted-circle}** | string | Page URL | +| `page_urlfragment` | **{dotted-circle}** | string | Fragment aka anchor | +| `page_urlhost` | **{dotted-circle}** | string | Host aka domain | +| `page_urlpath` | **{dotted-circle}** | string | Path to page | +| `page_urlport` | **{dotted-circle}** | integer | Port if specified, 80 if not | +| `page_urlquery` | **{dotted-circle}** | string | Query string | +| `page_urlscheme` | **{dotted-circle}** | string | Scheme (protocol name) | +| `platform` | **{dotted-circle}** | string | The platform the app runs on | +| `pp_xoffset_max` | **{dotted-circle}** | integer | Maximum page x offset seen in the last ping period | +| `pp_xoffset_min` | **{dotted-circle}** | integer | Minimum page x offset seen in the last ping period | +| `pp_yoffset_max` | **{dotted-circle}** | integer | Maximum page y offset seen in the last ping period | +| `pp_yoffset_min` | **{dotted-circle}** | integer | Minimum page y offset seen in the last ping period | +| `refr_domain_userid` | **{dotted-circle}** | string | The Snowplow `domain_userid` of the referring website | +| `refr_dvce_tstamp` | **{dotted-circle}** | timestamp | The time of attaching the `domain_userid` to the inbound link | +| `refr_medium` | **{dotted-circle}** | string | Type of referer | +| `refr_source` | **{dotted-circle}** | string | Name of referer if recognised | +| `refr_term` | **{dotted-circle}** | string | Keywords if source is a search engine | +| `refr_urlfragment` | **{dotted-circle}** | string | Referer URL fragment | +| `refr_urlhost` | **{dotted-circle}** | string | Referer host | +| `refr_urlpath` | **{dotted-circle}** | string | Referer page path | +| `refr_urlport` | **{dotted-circle}** | integer | Referer port | +| `refr_urlquery` | **{dotted-circle}** | string | Referer URL query string | +| `refr_urlscheme` | **{dotted-circle}** | string | Referer scheme | +| `se_action` | **{dotted-circle}** | string | The action / event itself | +| `se_category` | **{dotted-circle}** | string | The category of event | +| `se_label` | **{dotted-circle}** | string | A label often used to refer to the ‘object’ the action is performed on | +| `se_property` | **{dotted-circle}** | string | A property associated with either the action or the object | +| `se_value` | **{dotted-circle}** | decimal | A value associated with the user action | +| `ti_category` | **{dotted-circle}** | string | Item category | +| `ti_currency` | **{dotted-circle}** | string | Currency | +| `ti_name` | **{dotted-circle}** | string | Item name | +| `ti_orderid` | **{dotted-circle}** | string | Order ID | +| `ti_price` | **{dotted-circle}** | decimal | Item price | +| `ti_price_base` | **{dotted-circle}** | decimal | Item price in base currency | +| `ti_quantity` | **{dotted-circle}** | integer | Item quantity | +| `ti_sku` | **{dotted-circle}** | string | Item SKU | +| `tr_affiliation` | **{dotted-circle}** | string | Transaction affiliation (such as channel) | +| `tr_city` | **{dotted-circle}** | string | Delivery address: city | +| `tr_country` | **{dotted-circle}** | string | Delivery address: country | +| `tr_currency` | **{dotted-circle}** | string | Transaction Currency | +| `tr_orderid` | **{dotted-circle}** | string | Order ID | +| `tr_shipping` | **{dotted-circle}** | decimal | Delivery cost charged | +| `tr_shipping_base` | **{dotted-circle}** | decimal | Shipping cost in base currency | +| `tr_state` | **{dotted-circle}** | string | Delivery address: state | +| `tr_tax` | **{dotted-circle}** | decimal | Transaction tax value (such as amount of VAT included) | +| `tr_tax_base` | **{dotted-circle}** | decimal | Tax applied in base currency | +| `tr_total` | **{dotted-circle}** | decimal | Transaction total value | +| `tr_total_base` | **{dotted-circle}** | decimal | Total amount of transaction in base currency | +| `true_tstamp` | **{dotted-circle}** | timestamp | User-set exact timestamp | +| `txn_id` | **{dotted-circle}** | string | Transaction ID | +| `unstruct_event` | **{dotted-circle}** | JSON | The properties of the event | +| `uploaded_at` | **{dotted-circle}** | | | +| `user_fingerprint` | **{dotted-circle}** | integer | User identifier based on (hopefully unique) browser features | +| `user_id` | **{dotted-circle}** | string | Unique identifier for user, set by the business using setUserId | +| `user_ipaddress` | **{dotted-circle}** | string | IP address | +| `useragent` | **{dotted-circle}** | string | User agent (expressed as a browser string) | +| `v_collector` | **{dotted-circle}** | string | Collector version | +| `v_etl` | **{dotted-circle}** | string | ETL version | +| `v_tracker` | **{dotted-circle}** | string | Identifier for Snowplow tracker | diff --git a/doc/development/stage_group_dashboards.md b/doc/development/stage_group_dashboards.md index 453d71411c3..e75237869ba 100644 --- a/doc/development/stage_group_dashboards.md +++ b/doc/development/stage_group_dashboards.md @@ -61,7 +61,7 @@ Although most of the metrics displayed in the panels are self-explanatory in the To inspect the raw data of the panel for further calculation, click on the Inspect button from the dropdown menu of a panel. Queries, raw data, and panel JSON structure are available. Read more at [Grafana panel inspection](https://grafana.com/docs/grafana/latest/panels/inspect-panel/). -All the dashboards are powered by [Grafana](https://grafana.com/), a frontend for displaying metrics. Grafana consumes the data returned from queries to backend Prometheus data source, then presents them under different visualizations. The stage group dashboards are built to serve the most common use cases with a limited set of filters, and pre-built queries. Grafana provides a way to explore and visualize the metrics data with [Grafana Explore](https://grafana.com/docs/grafana/latest/explore/). This would require some knowledge about [Prometheus Promql query language](https://prometheus.io/docs/prometheus/latest/querying/basics/). +All the dashboards are powered by [Grafana](https://grafana.com/), a frontend for displaying metrics. Grafana consumes the data returned from queries to backend Prometheus data source, then presents them under different visualizations. The stage group dashboards are built to serve the most common use cases with a limited set of filters, and pre-built queries. Grafana provides a way to explore and visualize the metrics data with [Grafana Explore](https://grafana.com/docs/grafana/latest/explore/). This would require some knowledge about [Prometheus PromQL query language](https://prometheus.io/docs/prometheus/latest/querying/basics/). ## How to debug with the dashboards @@ -83,7 +83,7 @@ All the dashboards are powered by [Grafana](https://grafana.com/), a frontend fo ## How to customize the dashboard -All Grafana dashboards at GitLab are generated from the [Jsonnet files](https://github.com/grafana/grafonnet-lib) stored in [the runbook project](https://gitlab.com/gitlab-com/runbooks/-/tree/master/dashboards). Particularly, the stage group dashboards definitions are stored in [/dashboards/stage-groups](https://gitlab.com/gitlab-com/runbooks/-/tree/master/dashboards/stage-groups) subfolder in the Runbook. By convention, each group has a corresponding jsonnet file. The dashboards are synced with GitLab [stage group data](https://gitlab.com/gitlab-com/www-gitlab-com/-/raw/master/data/stages.yml) every month. Expansion and customization are one of the key principles used when we designed this system. To customize your group's dashboard, you need to edit the corresponding file and follow the [Runbook workflow](https://gitlab.com/gitlab-com/runbooks/-/tree/master/dashboards#dashboard-source). The dashboard is updated after the MR is merged. Looking at an autogenerated file, for example, [`product_planning.dashboard.jsonnet`](https://gitlab.com/gitlab-com/runbooks/-/blob/master/dashboards/stage-groups/product_planning.dashboard.jsonnet): +All Grafana dashboards at GitLab are generated from the [Jsonnet files](https://github.com/grafana/grafonnet-lib) stored in [the runbook project](https://gitlab.com/gitlab-com/runbooks/-/tree/master/dashboards). Particularly, the stage group dashboards definitions are stored in [/dashboards/stage-groups](https://gitlab.com/gitlab-com/runbooks/-/tree/master/dashboards/stage-groups) subfolder in the Runbook. By convention, each group has a corresponding Jsonnet file. The dashboards are synced with GitLab [stage group data](https://gitlab.com/gitlab-com/www-gitlab-com/-/raw/master/data/stages.yml) every month. Expansion and customization are one of the key principles used when we designed this system. To customize your group's dashboard, you need to edit the corresponding file and follow the [Runbook workflow](https://gitlab.com/gitlab-com/runbooks/-/tree/master/dashboards#dashboard-source). The dashboard is updated after the MR is merged. Looking at an autogenerated file, for example, [`product_planning.dashboard.jsonnet`](https://gitlab.com/gitlab-com/runbooks/-/blob/master/dashboards/stage-groups/product_planning.dashboard.jsonnet): ```jsonnet // This file is autogenerated using scripts/update_stage_groups_dashboards.rb @@ -145,4 +145,8 @@ stageGroupDashboards.dashboard('source_code')  +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +If you want to see the workflow in action, we've recorded a pairing session on customizing a dashboard, +available on [GitLab Unfiltered](https://youtu.be/shEd_eiUjdI). + For deeper customization and more complicated metrics, visit the [Grafonnet lib](https://github.com/grafana/grafonnet-lib) project and the [GitLab Prometheus Metrics](../administration/monitoring/prometheus/gitlab_metrics.md#gitlab-prometheus-metrics) documentation. diff --git a/doc/development/telemetry/event_dictionary.md b/doc/development/telemetry/event_dictionary.md deleted file mode 100644 index b3b3b0b4fdd..00000000000 --- a/doc/development/telemetry/event_dictionary.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'https://about.gitlab.com/handbook/product/product-intelligence-guide/' ---- - -This document was moved to [another location](https://about.gitlab.com/handbook/product/product-intelligence-guide/). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/telemetry/index.md b/doc/development/telemetry/index.md deleted file mode 100644 index b3b3b0b4fdd..00000000000 --- a/doc/development/telemetry/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'https://about.gitlab.com/handbook/product/product-intelligence-guide/' ---- - -This document was moved to [another location](https://about.gitlab.com/handbook/product/product-intelligence-guide/). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/telemetry/snowplow.md b/doc/development/telemetry/snowplow.md deleted file mode 100644 index bb056ffddfe..00000000000 --- a/doc/development/telemetry/snowplow.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../snowplow.md' ---- - -This document was moved to [another location](../snowplow.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/telemetry/usage_ping.md b/doc/development/telemetry/usage_ping.md deleted file mode 100644 index 5fbdb508bb1..00000000000 --- a/doc/development/telemetry/usage_ping.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../usage_ping.md' ---- - -This document was moved to [another location](../usage_ping.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/testing.md b/doc/development/testing.md deleted file mode 100644 index a0130bfb4ac..00000000000 --- a/doc/development/testing.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'testing_guide/index.md' ---- - -This document was moved to [another location](testing_guide/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index ac5f1a47f9b..0ccf513f5d8 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -13,13 +13,13 @@ description: "GitLab development guidelines - testing best practices." Testing at GitLab is a first class citizen, not an afterthought. It's important we consider the design of our tests as we do the design of our features. -When implementing a feature, we think about developing the right capabilities the right way, which helps us +When implementing a feature, we think about developing the right capabilities the right way. This helps us narrow our scope to a manageable level. When implementing tests for a feature, we must think about developing -the right tests, but then cover _all_ the important ways the test may fail, which can quickly widen our scope to +the right tests, but then cover _all_ the important ways the test may fail. This can quickly widen our scope to a level that is difficult to manage. Test heuristics can help solve this problem. They concisely address many of the common ways bugs -manifest themselves within our code. When designing our tests, take time to review known test heuristics to inform +manifest themselves in our code. When designing our tests, take time to review known test heuristics to inform 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. @@ -90,7 +90,7 @@ 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 +test requires JavaScript reactivity in the browser. Using a headless browser is much slower than parsing the HTML response from the app. #### Optimize factory usage @@ -108,8 +108,8 @@ 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! +- Don't `create` an object when you can use `build`, `build_stubbed`, `attributes_for`, + `spy`, or `instance_double`. 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. @@ -171,14 +171,14 @@ RSpec.describe API::Search, factory_default: :keep do let_it_be(:namespace) { create_default(:namespace) } ``` -Then every project we create will use this `namespace`, without us having to pass +Then every project we create uses this `namespace`, without us having to pass it as `namespace: namespace`. In order to make it work along with `let_it_be`, `factory_default: :keep` -must be explicitly specified. That will keep the default factory for every example in a suite instead of +must be explicitly specified. That keeps the default factory for every example in a suite instead of recreating it for each example. 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 +projects we create are ones we ask for (76/208). There is benefit in setting a default value for projects as well: ```ruby @@ -233,8 +233,8 @@ Finished in 2 minutes 19 seconds (files took 1 minute 4.42 seconds to load) ``` 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 +a place to start. The most expensive examples here are in +shared examples; any reductions generally have a larger impact as they are called in multiple places. #### Avoid repeating expensive actions @@ -287,7 +287,7 @@ results are available, and not just the first failure. - Use `.method` to describe class methods and `#method` to describe instance methods. - Use `context` to test branching logic. -- Try to match the ordering of tests to the ordering within the class. +- Try to match the ordering of tests to the ordering in the class. - Try to follow the [Four-Phase Test](https://thoughtbot.com/blog/four-phase-test) pattern, using newlines to separate phases. - Use `Gitlab.config.gitlab.host` rather than hard coding `'localhost'` @@ -295,10 +295,10 @@ results are available, and not just the first failure. [Gotchas](../gotchas.md#do-not-assert-against-the-absolute-value-of-a-sequence-generated-attribute)). - Avoid using `expect_any_instance_of` or `allow_any_instance_of` (see [Gotchas](../gotchas.md#do-not-assert-against-the-absolute-value-of-a-sequence-generated-attribute)). -- Don't supply the `:each` argument to hooks since it's the default. +- Don't supply the `:each` argument to hooks because it's the default. - On `before` and `after` hooks, prefer it scoped to `:context` over `:all` - When using `evaluate_script("$('.js-foo').testSomething()")` (or `execute_script`) which acts on a given element, - use a Capybara matcher beforehand (e.g. `find('.js-foo')`) to ensure the element actually exists. + use a Capybara matcher beforehand (such as `find('.js-foo')`) to ensure the element actually exists. - Use `focus: true` to isolate parts of the specs you want to run. - Use [`:aggregate_failures`](https://relishapp.com/rspec/rspec-core/docs/expectation-framework-integration/aggregating-failures) when there is more than one expectation in a test. - For [empty test description blocks](https://github.com/rubocop-hq/rspec-style-guide#it-and-specify), use `specify` rather than `it do` if the test is self-explanatory. @@ -343,7 +343,7 @@ writing one](testing_levels.md#consider-not-writing-a-system-test)! For instance, if you want to verify that a record was created, add expectations that its attributes are displayed on the page, not that `Model.count` increased by one. -- It's ok to look for DOM elements but don't abuse it since it makes the tests +- It's ok to look for DOM elements, but don't abuse it, because it makes the tests more brittle #### Debugging Capybara @@ -353,7 +353,7 @@ Sometimes you may need to debug Capybara tests by observing browser behavior. #### Live debug You can pause Capybara and view the website on the browser by using the -`live_debug` method in your spec. The current page will be automatically opened +`live_debug` method in your spec. The current page is automatically opened in your default browser. You may need to sign in first (the current user's credentials are displayed in the terminal). @@ -381,13 +381,13 @@ Finished in 34.51 seconds (files took 0.76702 seconds to load) #### Run `:js` spec in a visible browser -Run the spec with `CHROME_HEADLESS=0`, e.g.: +Run the spec with `CHROME_HEADLESS=0`, like this: ```shell CHROME_HEADLESS=0 bin/rspec some_spec.rb ``` -The test will go by quickly, but this will give you an idea of what's happening. +The test completes quickly, but this gives you an idea of what's happening. Using `live_debug` with `CHROME_HEADLESS=0` pauses the open browser, and does not open the page again. This can be used to debug and inspect elements. @@ -416,20 +416,20 @@ There is a [small hack](https://gitlab.com/gitlab-org/gitlab-foss/snippets/17184 ### Fast unit tests -Some classes are well-isolated from Rails and you should be able to test them +Some classes are well-isolated from Rails. You should be able to test them without the overhead added by the Rails environment and Bundler's `:default` group's gem loading. In these cases, you can `require 'fast_spec_helper'` instead of `require 'spec_helper'` in your test file, and your test should run -really fast since: +really fast because: -- Gems loading is skipped +- Gem loading is skipped - Rails app boot is skipped - GitLab Shell and Gitaly setup are skipped - Test repositories setup are skipped `fast_spec_helper` also support autoloading classes that are located inside the -`lib/` directory. It means that as long as your class / module is using only -code from the `lib/` directory you will not need to explicitly load any +`lib/` directory. If your class or module is using only +code from the `lib/` directory, you don't need to explicitly load any dependencies. `fast_spec_helper` also loads all ActiveSupport extensions, including core extensions that are commonly used in the Rails environment. @@ -439,9 +439,11 @@ in `lib/`. For example, if you want to test your code that is calling the `Gitlab::UntrustedRegexp` class, which under the hood uses `re2` library, you -should either add `require_dependency 're2'` to files in your library that -need `re2` gem, to make this requirement explicit, or you can add it to the -spec itself, but the former is preferred. +should either: + +- Add `require_dependency 're2'` to files in your library that need `re2` gem, + to make this requirement explicit. This approach is preferred. +- Add it to the spec itself. 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`. @@ -465,7 +467,7 @@ so we need to set some guidelines for their use going forward: - Don't define a `let` variable that's only used by the definition of another. Use a helper method instead. - `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 + order is required, otherwise `let` suffices. 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. @@ -475,7 +477,7 @@ so we need to set some guidelines for their use going forward: In some cases, there is no need to recreate the same object for tests again for each example. For example, a project and a guest of that project -is needed to test issues on the same project, one project and user will do for the entire file. +are needed to test issues on the same project, so one project and user are enough for the entire file. As much as possible, do not implement this using `before(:all)` or `before(:context)`. If you do, you would need to manually clean up the data as those hooks run outside a database transaction. @@ -494,9 +496,9 @@ before_all do end ``` -This will result in only one `Project`, `User`, and `ProjectMember` created for this context. +This results in only one `Project`, `User`, and `ProjectMember` created for this context. -`let_it_be` and `before_all` are also available within nested contexts. Cleanup after the context +`let_it_be` and `before_all` are also available in nested contexts. Cleanup after the context is handled automatically using a transaction rollback. Note that if you modify an object defined inside a `let_it_be` block, @@ -519,6 +521,35 @@ let_it_be_with_refind(:project) { create(:project) } let_it_be(:project, refind: true) { create(:project) } ``` +### License stubbing with `let_it_be` + +`let_it_be_with_refind` is also useful when using `stub_licensed_features` in your tests: + +```ruby +let_it_be_with_refind(:project) { create(:project) } +# Project#licensed_feature_available? is memoized, and so we need to refind +# the project for license updates to be applied. +# An alternative is `project.clear_memoization(:licensed_feature_available)`. + +subject { project.allows_multiple_assignees? } + +context 'with license multiple_issue_assignees disabled' do + before do + stub_licensed_features(multiple_issue_assignees: true) + end + + it { is_expected.to eq(true) } +end + +context 'with license multiple_issue_assignees disabled' do + before do + stub_licensed_features(multiple_issue_assignees: false) + end + + it { is_expected.to eq(false) } +end +``` + ### Time-sensitive tests [`ActiveSupport::Testing::TimeHelpers`](https://api.rubyonrails.org/v6.0.3.1/classes/ActiveSupport/Testing/TimeHelpers.html) @@ -545,14 +576,14 @@ This section was moved to [developing with feature flags](../feature_flags/devel The code exercised by a single GitLab test may access and modify many items of data. Without careful preparation before a test runs, and cleanup afterward, -data can be changed by a test in such a way that it affects the behavior of +a test can change data in a way that affects the behavior of following tests. This should be avoided at all costs! Fortunately, the existing test framework handles most cases already. When the test environment does get polluted, a common outcome is -[flaky tests](flaky_tests.md). Pollution will often manifest as an order -dependency: running spec A followed by spec B will reliably fail, but running -spec B followed by spec A will reliably succeed. In these cases, you can use +[flaky tests](flaky_tests.md). Pollution often manifests as an order +dependency: running spec A followed by spec B reliably fails, but running +spec B followed by spec A reliably succeeds. In these cases, you can use `rspec --bisect` (or a manual pairwise bisect of spec files) to determine which spec is at fault. Fixing the problem requires some understanding of how the test suite ensures the environment is pristine. Read on to discover more about each @@ -561,15 +592,15 @@ data store! #### SQL database This is managed for us by the `database_cleaner` gem. Each spec is surrounded in -a transaction, which is rolled back once the test completes. Certain specs will -instead issue `DELETE FROM` queries against every table after completion; this +a transaction, which is rolled back after the test completes. Certain specs +instead issue `DELETE FROM` queries against every table after completion. This allows the created rows to be viewed from multiple database connections, which is important for specs that run in a browser, or migration specs, among others. One consequence of using these strategies, instead of the well-known `TRUNCATE TABLES` approach, is that primary keys and other sequences are **not** reset across specs. So if you create a project in spec A, then create a project -in spec B, the first will have `id=1`, while the second will have `id=2`. +in spec B, the first has `id=1`, while the second has `id=2`. This means that specs should **never** rely on the value of an ID, or any other sequence-generated column. To avoid accidental conflicts, specs should also @@ -610,7 +641,7 @@ DNS requests are stubbed universally in the test suite (as of [!22368](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22368)), as DNS can cause issues depending on the developer's local network. There are RSpec labels available in `spec/support/dns.rb` which you can apply to tests if you need to -bypass the DNS stubbing, e.g.: +bypass the DNS stubbing, like this: ```ruby it "really connects to Prometheus", :permit_dns do @@ -625,8 +656,8 @@ In the situations where you need to [stub](https://relishapp.com/rspec/rspec-mocks/v/3-9/docs/basics/allowing-messages) methods such as `File.read`, make sure to: -1. Stub `File.read` for only the filepath you are interested in. -1. Call the original implementation for other filepaths. +1. Stub `File.read` for only the file path you are interested in. +1. Call the original implementation for other file paths. Otherwise `File.read` calls from other parts of the codebase get stubbed incorrectly. You should use the `stub_file_read`, and @@ -645,19 +676,19 @@ allow(File).to receive(:read).and_call_original allow(File).to receive(:read).with(my_filepath) ``` -#### Filesystem +#### File system -Filesystem data can be roughly split into "repositories", and "everything else". +File system data can be roughly split into "repositories", and "everything else". Repositories are stored in `tmp/tests/repositories`. This directory is emptied before a test run starts, and after the test run ends. It is not emptied between -specs, so created repositories accumulate within this directory over the +specs, so created repositories accumulate in this directory over the lifetime of the process. Deleting them is expensive, but this could lead to pollution unless carefully managed. To avoid this, [hashed storage](../../administration/repository_storage_types.md) is enabled in the test suite. This means that repositories are given a unique -path that depends on their project's ID. Since the project IDs are not reset -between specs, this guarantees that each spec gets its own repository on disk, +path that depends on their project's ID. Because the project IDs are not reset +between specs, each spec gets its own repository on disk, and prevents changes from being visible between specs. If a spec manually specifies a project ID, or inspects the state of the @@ -671,9 +702,9 @@ written to disk in locations determined by ID, so conflicts should not occur. Some specs disable hashed storage by passing the `:legacy_storage` trait to the `projects` factory. Specs that do this must **never** override the `path` of the -project, or any of its groups. The default path includes the project ID, so will -not conflict; but if two specs create a `:legacy_storage` project with the same -path, they will use the same repository on disk and lead to test environment +project, or any of its groups. The default path includes the project ID, so it +does not conflict. If two specs create a `:legacy_storage` project with the same +path, they use the same repository on disk and lead to test environment pollution. Other files must be managed manually by the spec. If you run code that creates a @@ -712,21 +743,20 @@ If you need to modify the contents of the `ENV` constant, you can use the While most Ruby **instances** are not shared between specs, **classes** and **modules** generally are. Class and module instance variables, accessors, class variables, and other stateful idioms, should be treated in the same way as -global variables - don't modify them unless you have to! In particular, prefer +global variables. Don't modify them unless you have to! In particular, prefer using expectations, or dependency injection along with stubs, to avoid the need -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. +for modifications. If you have no other choice, an `around` block like the global +variables example can be used, but avoid this if at all possible. #### Test Snowplow events 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 +Because 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 +To catch runtime errors due to type checks, you can enable Snowplow in tests. Mark the spec with +`:snowplow` and use the `expect_snowplow_event` helper, which checks for calls to `Gitlab::Tracking#event`. ```ruby @@ -737,12 +767,14 @@ describe '#show', :snowplow do expect_snowplow_event( category: 'Experiment', action: 'start', + standard_context: { namespace: group, project: project } ) expect_snowplow_event( category: 'Experiment', action: 'sent', property: 'property', - label: 'label' + label: 'label', + standard_context: { namespace: group, project: project } ) end end @@ -794,7 +826,7 @@ end WARNING: Only use simple values as input in the `where` block. Using procs, stateful -objects, FactoryBot-created objects etc. can lead to +objects, FactoryBot-created objects, and similar items can lead to [unexpected results](https://github.com/tomykaira/rspec-parameterized/issues/8). ### Prometheus tests @@ -807,7 +839,7 @@ reset before each example, add the `:prometheus` tag to the RSpec test. Custom matchers should be created to clarify the intent and/or hide the complexity of RSpec expectations. They should be placed under `spec/support/matchers/`. Matchers can be placed in subfolder if they apply to -a certain type of specs only (e.g. features, requests etc.) but shouldn't be if +a certain type of specs only (such as features or requests) but shouldn't be if they apply to multiple type of specs. #### `be_like_time` @@ -881,13 +913,13 @@ expect(json_string).to be_valid_json.and match_schema(schema) Testing query performance allows us to: -- Assert that N+1 problems do not exist within a block of code. -- Ensure that the number of queries within a block of code does not increase unnoticed. +- Assert that N+1 problems do not exist in a block of code. +- Ensure that the number of queries in a block of code does not increase unnoticed. #### QueryRecorder `QueryRecorder` allows profiling and testing of the number of database queries -performed within a given block of code. +performed in a given block of code. See the [`QueryRecorder`](../query_recorder.md) section for more details. @@ -905,9 +937,9 @@ Any shared contexts used by more than one spec file: - Should be placed under `spec/support/shared_contexts/`. - Can be placed in subfolder if they apply to a certain type of specs only - (e.g. features, requests etc.) but shouldn't be if they apply to multiple type of specs. + (such as features or requests) but shouldn't be if they apply to multiple type of specs. -Each file should include only one context and have a descriptive name, e.g. +Each file should include only one context and have a descriptive name, such as `spec/support/shared_contexts/controllers/githubish_import_controller_shared_context.rb`. ### Shared examples @@ -917,9 +949,9 @@ Any shared examples used by more than one spec file: - Should be placed under `spec/support/shared_examples/`. - Can be placed in subfolder if they apply to a certain type of specs only - (e.g. features, requests etc.) but shouldn't be if they apply to multiple type of specs. + (such as features or requests) but shouldn't be if they apply to multiple type of specs. -Each file should include only one context and have a descriptive name, e.g. +Each file should include only one context and have a descriptive name, such as `spec/support/shared_examples/controllers/githubish_import_controller_shared_example.rb`. ### Helpers @@ -927,8 +959,8 @@ Each file should include only one context and have a descriptive name, e.g. Helpers are usually modules that provide some methods to hide the complexity of specific RSpec examples. You can define helpers in RSpec files if they're not intended to be shared with other specs. Otherwise, they should be placed -under `spec/support/helpers/`. Helpers can be placed in subfolder if they apply -to a certain type of specs only (e.g. features, requests etc.) but shouldn't be +under `spec/support/helpers/`. Helpers can be placed in a subfolder if they apply +to a certain type of specs only (such as features or requests) but shouldn't be if they apply to multiple type of specs. Helpers should follow the Rails naming / namespacing convention. For instance @@ -985,7 +1017,7 @@ All fixtures should be placed under `spec/fixtures/`. ### Repositories -Testing some functionality, e.g., merging a merge request, requires a Git +Testing some functionality, such as merging a merge request, requires a Git repository with a certain state to be present in the test environment. GitLab maintains the [`gitlab-test`](https://gitlab.com/gitlab-org/gitlab-test) repository for certain common cases - you can ensure a copy of the repository is @@ -996,7 +1028,7 @@ let(:project) { create(:project, :repository) } ``` Where you can, consider using the `:custom_repo` trait instead of `:repository`. -This allows you to specify exactly what files will appear in the `master` branch +This allows you to specify exactly what files appear in the `master` branch of the project's repository. For example: ```ruby @@ -1011,17 +1043,17 @@ let(:project) do end ``` -This will create a repository containing two files, with default permissions and +This creates a repository containing two files, with default permissions and the specified content. ### Configuration -RSpec configuration files are files that change the RSpec configuration (i.e. +RSpec configuration files are files that change the RSpec configuration (like `RSpec.configure do |config|` blocks). They should be placed under `spec/support/`. -Each file should be related to a specific domain, e.g. -`spec/support/capybara.rb`, `spec/support/carrierwave.rb`, etc. +Each file should be related to a specific domain, such as +`spec/support/capybara.rb` or `spec/support/carrierwave.rb`. If a helpers module applies only to a certain kind of specs, it should add modifiers to the `config.include` call. For instance if @@ -1047,7 +1079,7 @@ file which is used by the `spec/fast_spec_helper.rb` file. See Services for the test environment are automatically configured and started when tests are run, including Gitaly, Workhorse, Elasticsearch, and Capybara. When run in CI, or -if the service needs to be installed, the test environment will log information +if the service needs to be installed, the test environment logs information about set-up time, producing log messages like the following: ```plaintext 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 b761e33367f..a5a2d2a1113 100644 --- a/doc/development/testing_guide/end_to_end/best_practices.md +++ b/doc/development/testing_guide/end_to_end/best_practices.md @@ -10,7 +10,7 @@ This is a tailored extension of the Best Practices [found in the testing guide]( ## 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/). +Every test should have a corresponding issue in the [Quality Test Cases 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. @@ -244,7 +244,7 @@ point of failure and so the screenshot would not be captured at the right moment All tests expect to be able to log in at the start of the test. -For an example see: <https://gitlab.com/gitlab-org/gitlab/-/issues/34736> +For an example see [issue #34736](https://gitlab.com/gitlab-org/gitlab/-/issues/34736). Ideally, actions performed in an `after(:context)` (or [`before(:context)`](#limit-the-use-of-the-ui-in-beforecontext-and-after-hooks)) diff --git a/doc/development/testing_guide/end_to_end/feature_flags.md b/doc/development/testing_guide/end_to_end/feature_flags.md index 1e0eda6491a..1bc33b79c7c 100644 --- a/doc/development/testing_guide/end_to_end/feature_flags.md +++ b/doc/development/testing_guide/end_to_end/feature_flags.md @@ -74,3 +74,16 @@ existing tests or write new ones. Please see the [QA README](https://gitlab.com/gitlab-org/gitlab/tree/master/qa#running-tests-with-a-feature-flag-enabled) for details. + +## Confirming that end-to-end tests pass with a feature flag enabled + +End-to-end tests should pass with a feature flag enabled before it is enabled on Staging or on GitLab.com. Tests that need to be updated should be identified as part of [quad-planning](https://about.gitlab.com/handbook/engineering/quality/quad-planning/). The relevant [counterpart Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors) is responsible for updating the tests or assisting another engineer to do so. However, if a change does not go through quad-planning and a required test update is not made, test failures could block deployment. + +If a test enables a feature flag as describe above, it is sufficient to run the `package-and-qa` job in a merge request containing the relevant changes. +Or, if the feature flag and relevant changes have already been merged, you can confirm that the tests +pass on `master`. The end-to-end tests run on `master` every two hours, and the results are posted to a [Test +Session Report, which is available in the testcase-sessions project](https://gitlab.com/gitlab-org/quality/testcase-sessions/-/issues?label_name%5B%5D=found%3Amaster). + +If the relevant tests do not enable the feature flag themselves, you can check if the tests will need +to be updated by opening a draft merge request that enables the flag by default and then running the `package-and-qa` job. +The merge request can be closed once the tests pass. If you need assistance to update the tests, please contact the relevant [stable counterpart in the Quality department](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors), or any Software Engineer in Test if there is no stable counterpart for your group. diff --git a/doc/development/testing_guide/end_to_end/page_objects.md b/doc/development/testing_guide/end_to_end/page_objects.md index 939e44cedd9..d9309f74e0e 100644 --- a/doc/development/testing_guide/end_to_end/page_objects.md +++ b/doc/development/testing_guide/end_to_end/page_objects.md @@ -145,7 +145,7 @@ for each element defined. In our case, `data-qa-selector="login_field"`, `data-qa-selector="password_field"` and `data-qa-selector="sign_in_button"` -**app/views/my/view.html.haml** +`app/views/my/view.html.haml` ```haml = f.text_field :login, class: "form-control top", autofocus: "autofocus", autocapitalize: "off", autocorrect: "off", required: true, title: "This field is required.", data: { qa_selector: 'login_field' } 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 6d6f7fbcf8d..8a929737ebe 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 @@ -14,31 +14,32 @@ 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. | +| `:geo` | The test requires two GitLab Geo instances - a primary and a secondary - to be spun up. | | `:gitaly_cluster` | The test runs 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. | +| `:github` | The test requires a GitHub personal access token. | +| `:group_saml` | The test requires a GitLab instance that has SAML SSO enabled at the group level. Interacts with an external SAML identity provider. Paired with the `:orchestrated` tag. | +| `:instance_saml` | The test requires a GitLab instance that has SAML SSO enabled at the instance level. Interacts with an external SAML identity provider. Paired with the `:orchestrated` tag. | | `:jira` | The test requires a Jira Server. [GitLab-QA](https://gitlab.com/gitlab-org/gitlab-qa) provisions 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 also includes provisioning of at least one Kubernetes cluster to test against. _This tag is often be paired with `:orchestrated`._ | +| `:ldap_no_server` | The test requires a GitLab instance to be configured to use LDAP. To be used with the `:orchestrated` tag. It does not spin up an LDAP server at orchestration time. Instead, it creates the LDAP server at runtime. | +| `:ldap_no_tls` | The test requires a GitLab instance to be configured to use an external LDAP server with TLS not enabled. | +| `:ldap_tls` | The test requires a GitLab instance to be configured to use an external LDAP server with TLS enabled. | +| `:mattermost` | The test requires a GitLab Mattermost service on the GitLab instance. | +| `:object_storage` | The test requires a GitLab instance to be configured to use multiple [object storage types](../../../administration/object_storage.md). Uses MinIO as the object storage server. | | `:only` | The test is only to be run against specific environments or pipelines. 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 the GitLab configuration (for example, Staging). | +| `:packages` | The test requires a GitLab instance that has the [Package Registry](../../../administration/packages/#gitlab-package-registry-administration) enabled. | | `:quarantine` | The test has been [quarantined](https://about.gitlab.com/handbook/engineering/quality/guidelines/debugging-qa-test-failures/#quarantining-tests), runs in a separate job that only includes quarantined tests, and is allowed to fail. The test is skipped in its regular job so that if it fails it doesn't 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). | +| `:relative_url` | The test requires a GitLab instance to be installed under a [relative URL](../../../install/relative_url.md). | | `: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. | +| `:repository_storage` | The test requires a GitLab instance to be configured to use multiple [repository storage paths](../../../administration/repository_storage_paths.md). Paired with the `:orchestrated` tag. | | `:requires_admin` | The test requires an admin account. Tests with the tag are excluded when run against Canary and Production environments. | +| `:requires_git_protocol_v2` | The test requires that Git protocol version 2 is enabled on the server. It's assumed to be enabled by default but if not the test can be skipped by setting `QA_CAN_TEST_GIT_PROTOCOL_V2` to `false`. | +| `:requires_praefect` | The test requires that the GitLab instance uses [Gitaly Cluster](../../../administration/gitaly/praefect.md) (a.k.a. Praefect) as the repository storage . It's assumed to be used by default but if not the test can be skipped by setting `QA_CAN_TEST_PRAEFECT` to `false`. | | `:runner` | The test depends on and sets up a GitLab Runner instance, typically to run a pipeline. | | `:skip_live_env` | The test is excluded when run against live deployed environments such as Staging, Canary, and Production. | -| `:testcase` | The link to the test case issue in the [Quality Testcases project](https://gitlab.com/gitlab-org/quality/testcases/). | -| `:mattermost` | The test requires a GitLab Mattermost service on the GitLab instance. | -| `:ldap_no_server` | The test requires a GitLab instance to be configured to use LDAP. To be used with the `:orchestrated` tag. It does not spin up an LDAP server at orchestration time. Instead, it creates the LDAP server at runtime. | -| `:ldap_no_tls` | The test requires a GitLab instance to be configured to use an external LDAP server with TLS not enabled. | -| `:ldap_tls` | The test requires a GitLab instance to be configured to use an external LDAP server with TLS enabled. | -| `:object_storage` | The test requires a GitLab instance to be configured to use multiple [object storage types](../../../administration/object_storage.md). Uses MinIO as the object storage server. | -| `:smtp` | The test requires a GitLab instance to be configured to use an SMTP server. Tests SMTP notification email delivery from GitLab by using MailHog. | -| `:group_saml` | The test requires a GitLab instance that has SAML SSO enabled at the group level. Interacts with an external SAML identity provider. Paired with the `:orchestrated` tag. | -| `:instance_saml` | The test requires a GitLab instance that has SAML SSO enabled at the instance level. Interacts with an external SAML identity provider. Paired with the `:orchestrated` tag. | | `:skip_signup_disabled` | The test uses UI to sign up a new user and is skipped in any environment that does not allow new user registration via the UI. | | `:smoke` | The test belongs to the test suite which verifies basic functionality of a GitLab instance.| -| `:github` | The test requires a GitHub personal access token. | -| `:repository_storage` | The test requires a GitLab instance to be configured to use multiple [repository storage paths](../../../administration/repository_storage_paths.md). Paired with the `:orchestrated` tag. | -| `:geo` | The test requires two GitLab Geo instances - a primary and a secondary - to be spun up. | -| `:relative_url` | The test requires a GitLab instance to be installed under a [relative URL](../../../install/relative_url.md). | -| `:requires_git_protocol_v2` | The test requires that Git protocol version 2 is enabled on the server. It's assumed to be enabled by default but if not the test can be skipped by setting `QA_CAN_TEST_GIT_PROTOCOL_V2` to `false`. | -| `:requires_praefect` | The test requires that the GitLab instance uses [Gitaly Cluster](../../../administration/gitaly/praefect.md) (a.k.a. Praefect) as the repository storage . It's assumed to be used by default but if not the test can be skipped by setting `QA_CAN_TEST_PRAEFECT` to `false`. | -| `:packages` | The test requires a GitLab instance that has the [Package Registry](../../../administration/packages/#gitlab-package-registry-administration) enabled. | +| `:smtp` | The test requires a GitLab instance to be configured to use an SMTP server. Tests SMTP notification email delivery from GitLab by using MailHog. | +| `:testcase` | The link to the test case issue in the [Quality Test Cases project](https://gitlab.com/gitlab-org/quality/testcases/). | +| `:transient` | The test tests transient bugs. It is excluded by default. | 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 cd429a74a2a..b6293ec41b8 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 @@ -75,17 +75,17 @@ When all the containers are running, the output of the `docker ps` command shows ```plaintext CONTAINER ID ... PORTS NAMES -d15d3386a0a8 ... 22/tcp, 443/tcp, 0.0.0.0:32772->80/tcp gitlab-gitaly-ha +d15d3386a0a8 ... 22/tcp, 443/tcp, 0.0.0.0:32772->80/tcp gitlab-gitaly-cluster ``` -That shows that the GitLab instance running in the `gitlab-gitaly-ha` container can be reached via `http://localhost:32772`. However, Git operations like cloning and pushing are performed against the URL revealed via the UI as the clone URL. It uses the hostname configured for the GitLab instance, which in this case matches the Docker container name and network, `gitlab-gitaly-ha.test`. Before you can run the tests you need to configure your computer to access the container via that address. One option is to [use caddyserver as described for running tests against GDK](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/run_qa_against_gdk.md#workarounds). +That shows that the GitLab instance running in the `gitlab-gitaly-cluster` container can be reached via `http://localhost:32772`. However, Git operations like cloning and pushing are performed against the URL revealed via the UI as the clone URL. It uses the hostname configured for the GitLab instance, which in this case matches the Docker container name and network, `gitlab-gitaly-cluster.test`. Before you can run the tests you need to configure your computer to access the container via that address. One option is to [use Caddy server as described for running tests against GDK](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/run_qa_against_gdk.md#workarounds). Another option is to use NGINX. -In both cases you must configure your machine to translate `gitlab-gitlab-ha.test` into an appropriate IP address: +In both cases you must configure your machine to translate `gitlab-gitaly-cluster.test` into an appropriate IP address: ```shell -echo '127.0.0.1 gitlab-gitaly-ha.test' | sudo tee -a /etc/hosts +echo '127.0.0.1 gitlab-gitaly-cluster.test' | sudo tee -a /etc/hosts ``` Then install NGINX: @@ -101,19 +101,19 @@ apt install nginx yum install nginx ``` -Finally, configure NGINX to pass requests for `gitlab-gitaly-ha.test` to the GitLab instance: +Finally, configure NGINX to pass requests for `gitlab-gitaly-cluster.test` to the GitLab instance: ```plaintext # On Debian/Ubuntu, in /etc/nginx/sites-enabled/gitlab-cluster # On macOS, in /usr/local/etc/nginx/nginx.conf server { - server_name gitlab-gitaly-ha.test; + server_name gitlab-gitaly-cluster.test; client_max_body_size 500m; location / { proxy_pass http://127.0.0.1:32772; - proxy_set_header Host gitlab-gitaly-ha.test; + proxy_set_header Host gitlab-gitaly-cluster.test; } } ``` @@ -131,14 +131,14 @@ sudo nginx -s reload You could then run the tests from the `/qa` directory: ```shell -CHROME_HEADLESS=false bin/qa Test::Instance::All http://gitlab-gitaly-ha.test -- --tag gitaly_ha +CHROME_HEADLESS=false bin/qa Test::Instance::All http://gitlab-gitaly-cluster.test -- --tag gitaly_cluster ``` Once you have finished testing you can stop and remove the Docker containers: ```shell -docker stop gitlab-gitaly-ha praefect postgres gitaly3 gitaly2 gitaly1 -docker rm gitlab-gitaly-ha praefect postgres gitaly3 gitaly2 gitaly1 +docker stop gitlab-gitaly-cluster praefect postgres gitaly3 gitaly2 gitaly1 +docker rm gitlab-gitaly-cluster praefect postgres gitaly3 gitaly2 gitaly1 ``` ## Guide to run and debug Monitor tests @@ -177,7 +177,7 @@ The following includes more information on the command: 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/browser_ui/8_monitor/all_monitor_core_features_spec.rb` - has the specs of features in GitLab Free -`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 @@ -408,15 +408,15 @@ Geo requires an EE license. To visit the Geo sites in your browser, you need a r Tests that are tagged with `:ldap_tls` and `:ldap_no_tls` meta are orchestrated tests where the sign-in happens via LDAP. -These tests spin up a Docker container [(osixia/openldap)](https://hub.docker.com/r/osixia/openldap) running an instance of [OpenLDAP](https://www.openldap.org/). -The container uses fixtures [checked into the GitLab-QA repo](https://gitlab.com/gitlab-org/gitlab-qa/-/tree/9ffb9ad3be847a9054967d792d6772a74220fb42/fixtures/ldap) to create +These tests spin up a Docker container [(`osixia/openldap`)](https://hub.docker.com/r/osixia/openldap) running an instance of [OpenLDAP](https://www.openldap.org/). +The container uses fixtures [checked into the GitLab-QA repository](https://gitlab.com/gitlab-org/gitlab-qa/-/tree/9ffb9ad3be847a9054967d792d6772a74220fb42/fixtures/ldap) to create base data such as users and groups including the admin group. The password for [all users](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/9ffb9ad3be847a9054967d792d6772a74220fb42/fixtures/ldap/2_add_users.ldif) including [the `tanuki` user](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/9ffb9ad3be847a9054967d792d6772a74220fb42/fixtures/ldap/tanuki.ldif) is `password`. A GitLab instance is also created in a Docker container based on our [General LDAP setup](../../../administration/auth/ldap/index.md#general-ldap-setup) documentation. -Tests that are tagged `:ldap_tls` enable TLS on GitLab using the certificate [checked into the GitLab-QA repo](https://gitlab.com/gitlab-org/gitlab-qa/-/tree/9ffb9ad3be847a9054967d792d6772a74220fb42/tls_certificates/gitlab). +Tests that are tagged `:ldap_tls` enable TLS on GitLab using the certificate [checked into the GitLab-QA repository](https://gitlab.com/gitlab-org/gitlab-qa/-/tree/9ffb9ad3be847a9054967d792d6772a74220fb42/tls_certificates/gitlab). -The certificate was generated with openssl using this command: +The certificate was generated with OpenSSL using this command: ```shell openssl req -x509 -newkey rsa:4096 -keyout gitlab.test.key -out gitlab.test.crt -days 3650 -nodes -subj "/C=US/ST=CA/L=San Francisco/O=GitLab/OU=Org/CN=gitlab.test" @@ -432,7 +432,7 @@ To run the LDAP tests on your local with TLS enabled, follow these steps: `127.0.0.1 gitlab.test` - You can then run tests against GitLab in a Docker container on `https://gitlab.test`. Please note that the TLS certificate [checked into the GitLab-QA repo](https://gitlab.com/gitlab-org/gitlab-qa/-/tree/9ffb9ad3be847a9054967d792d6772a74220fb42/tls_certificates/gitlab) is configured for this domain. + You can then run tests against GitLab in a Docker container on `https://gitlab.test`. Please note that the TLS certificate [checked into the GitLab-QA repository](https://gitlab.com/gitlab-org/gitlab-qa/-/tree/9ffb9ad3be847a9054967d792d6772a74220fb42/tls_certificates/gitlab) is configured for this domain. 1. Run the OpenLDAP container with TLS enabled. Change the path to [`gitlab-qa/fixtures/ldap`](https://gitlab.com/gitlab-org/gitlab-qa/-/tree/9ffb9ad3be847a9054967d792d6772a74220fb42/fixtures/ldap) directory to your local checkout path: ```shell diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 94bc80abcdb..7e7f62e41dd 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -31,7 +31,7 @@ Jest tests can be found in `/spec/frontend` and `/ee/spec/frontend` in EE. ## Karma test suite While GitLab has switched over to [Jest](https://jestjs.io), Karma tests still exist in our -application because some of our specs require a browser and can't be easiliy migrated to Jest. +application because some of our specs require a browser and can't be easily migrated to Jest. Those specs intend to eventually drop Karma in favor of either Jest or RSpec. You can track this migration in the [related epic](https://gitlab.com/groups/gitlab-org/-/epics/4900). @@ -258,7 +258,7 @@ it('exists', () => { ### Naming unit tests When writing describe test blocks to test specific functions/methods, -please use the method name as the describe block name. +use the method name as the describe block name. **Bad**: @@ -439,7 +439,7 @@ it('waits for an Ajax call', done => { }); ``` -If you are not able to register handlers to the `Promise`, for example because it is executed in a synchronous Vue life cycle hook, please take a look at the [waitFor](#wait-until-axios-requests-finish) helpers or you can flush all pending `Promise`s: +If you are not able to register handlers to the `Promise`, for example because it is executed in a synchronous Vue life cycle hook, take a look at the [waitFor](#wait-until-axios-requests-finish) helpers or you can flush all pending `Promise`s: **in Jest:** @@ -702,10 +702,10 @@ unit testing by mocking out modules which cannot be easily consumed in our test Jest supports [manual module mocks](https://jestjs.io/docs/en/manual-mocks) by placing a mock in a `__mocks__/` directory next to the source module (e.g. `app/assets/javascripts/ide/__mocks__`). **Don't do this.** We want to keep all of our test-related code in one place (the `spec/` folder). -If a manual mock is needed for a `node_modules` package, please use the `spec/frontend/__mocks__` folder. Here's an example of +If a manual mock is needed for a `node_modules` package, use the `spec/frontend/__mocks__` folder. Here's an example of a [Jest mock for the package `monaco-editor`](https://gitlab.com/gitlab-org/gitlab/blob/b7f914cddec9fc5971238cdf12766e79fa1629d7/spec/frontend/__mocks__/monaco-editor/index.js#L1). -If a manual mock is needed for a CE module, please place it in `spec/frontend/mocks/ce`. +If a manual mock is needed for a CE module, place it in `spec/frontend/mocks/ce`. - Files in `spec/frontend/mocks/ce` mocks the corresponding CE module from `app/assets/javascripts`, mirroring the source module's path. - Example: `spec/frontend/mocks/ce/lib/utils/axios_utils` mocks the module `~/lib/utils/axios_utils`. @@ -728,11 +728,11 @@ If a manual mock is needed for a CE module, please place it in `spec/frontend/mo Global mocks introduce magic and technically can reduce test coverage. When mocking is deemed profitable: - Keep the mock short and focused. -- Please leave a top-level comment in the mock on why it is necessary. +- Leave a top-level comment in the mock on why it is necessary. ### Additional mocking techniques -Please consult the [official Jest docs](https://jestjs.io/docs/en/jest-object#mock-modules) for a full overview of the available mocking features. +Consult the [official Jest docs](https://jestjs.io/docs/en/jest-object#mock-modules) for a full overview of the available mocking features. ## Running Frontend Tests @@ -865,7 +865,7 @@ end This will create a new fixture located at `tmp/tests/frontend/fixtures-ee/graphql/releases/queries/all_releases.query.graphql.json`. -Note that you will need to provide the paths to all fragments used by the query. +You will need to provide the paths to all fragments used by the query. `get_graphql_query_as_string` reads all of the provided file paths and returns the result as a single, concatenated string. @@ -929,7 +929,8 @@ it.each([ ); ``` -**Note**: only use template literal block if pretty print is **not** needed for spec output. For example, empty strings, nested objects etc. +NOTE: +Only use template literal block if pretty print is not needed for spec output. For example, empty strings, nested objects etc. For example, when testing the difference between an empty search string and a non-empty search string, the use of the array block syntax with the pretty print option would be preferred. That way the differences between an empty string e.g. `''` and a non-empty string e.g. `'search string'` would be visible in the spec output. Whereas with a template literal block, the empty string would be shown as a space, which could lead to a confusing developer experience @@ -1038,7 +1039,8 @@ import Subject from '~/feature/the_subject.vue'; import _Thing from '~/feature/path/to/thing.vue'; ``` -**PLEASE NOTE:** Do not simply disregard test timeouts. This could be a sign that there's +NOTE: +Do not disregard test timeouts. This could be a sign that there's actually a production problem. Use this opportunity to analyze the production webpack bundles and chunks and confirm that there is not a production issue with the async imports. @@ -1063,7 +1065,7 @@ See also [Notes on testing Vue components](../fe_guide/vue.md#testing-vue-compon ## Test helpers Test helpers can be found in [`spec/frontend/__helpers__`](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/frontend/__helpers__). -If you introduce new helpers, please place them in that directory. +If you introduce new helpers, place them in that directory. ### Vuex Helper: `testAction` diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md index 68326879dd0..c22a4e0b3ad 100644 --- a/doc/development/testing_guide/index.md +++ b/doc/development/testing_guide/index.md @@ -9,9 +9,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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 +It is meant to be an _extension_ of the [Thoughtbot testing style guide](https://github.com/thoughtbot/guides/tree/master/testing-rspec). If -this guide defines a rule that contradicts the thoughtbot guide, this guide +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 a5294be40a9..f1c74f990cb 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -186,9 +186,9 @@ the GitLab handbook information for the [shared 1Password account](https://about ### Find my Review App slug 1. Open the `review-deploy` job. -1. Look for `Checking for previous deployment of review-*`. -1. For instance for `Checking for previous deployment of review-qa-raise-e-12chm0`, - your Review App slug would be `review-qa-raise-e-12chm0` in this case. +1. Look for `** Deploying review-*`. +1. For instance for `** Deploying review-1234-abc-defg... **`, + your Review App slug would be `review-1234-abc-defg` in this case. ### Run a Rails console @@ -357,7 +357,7 @@ using `v232`. For the record, the debugging steps to find out this issue were: -1. Switch kubectl context to review-apps-ce (we recommend using [kubectx](https://github.com/ahmetb/kubectx/)) +1. Switch kubectl context to `review-apps-ce` (we recommend using [`kubectx`](https://github.com/ahmetb/kubectx/)) 1. `kubectl get pods | grep dns` 1. `kubectl describe pod <pod name>` & confirm exact error message 1. Web search for exact error message, following rabbit hole to [a relevant Kubernetes bug report](https://github.com/kubernetes/kubernetes/issues/57345) diff --git a/doc/development/testing_guide/testing_migrations_guide.md b/doc/development/testing_guide/testing_migrations_guide.md index 31054d0ffb2..d54ca0d3c64 100644 --- a/doc/development/testing_guide/testing_migrations_guide.md +++ b/doc/development/testing_guide/testing_migrations_guide.md @@ -32,7 +32,7 @@ migrate the database **down** to the previous migration version. With this approach you can test a migration against a database schema. -An `after` hook migrates the database **up** and reinstitutes the latest +An `after` hook migrates the database **up** and restores the latest schema version, so that the process does not affect subsequent specs and ensures proper isolation. diff --git a/doc/development/ui_guide.md b/doc/development/ui_guide.md deleted file mode 100644 index 1e84bf608f4..00000000000 --- a/doc/development/ui_guide.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/' ---- - -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/usage_ping.md b/doc/development/usage_ping.md index 10c3de2f0a1..02a070bc3ad 100644 --- a/doc/development/usage_ping.md +++ b/doc/development/usage_ping.md @@ -6,10 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Usage Ping Guide -> - Introduced in GitLab Enterprise Edition 8.10. -> - More statistics were added in GitLab Enterprise Edition 8.12. -> - Moved to GitLab Core in 9.1. -> - More statistics were added in GitLab Ultimate 11.2. +> Introduced in GitLab Ultimate 11.2, more statistics. This guide describes Usage Ping's purpose and how it's implemented. @@ -122,6 +119,60 @@ sequenceDiagram the hostname is `version.gitlab.com`, the protocol is `TCP`, and the port number is `443`, the required URL is <https://version.gitlab.com/>. +## Usage Ping Metric Life cycle + +### 1. New metrics addition + +Please follow the [Implementing Usage Ping](#implementing-usage-ping) guide. + +### 2. Existing metric change + +Because we do not control when customers update their self-managed instances of GitLab, +we **STRONGLY DISCOURAGE** changes to the logic used to calculate any metric. +Any such changes lead to inconsistent reports from multiple GitLab instances. +If there is a problem with an existing metric, it's best to deprecate the existing metric, +and use it, side by side, with the desired new metric. + +Example: +Consider following change. Before GitLab 12.6, the `example_metric` was implemented as: + +```ruby +{ + ... + example_metric: distinct_count(Project, :creator_id) +} +``` + +For GitLab 12.6, the metric was changed to filter out archived projects: + +```ruby +{ + ... + example_metric: distinct_count(Project.non_archived, :creator_id) +} +``` + +In this scenario all instances running up to GitLab 12.5 continue to report `example_metric`, +including all archived projects, while all instances running GitLab 12.6 and higher filters +out such projects. As Usage Ping data is collected from all reporting instances, the +resulting dataset includes mixed data, which distorts any following business analysis. + +The correct approach is to add a new metric for GitLab 12.6 release with updated logic: + +```ruby +{ + ... + example_metric_without_archived: distinct_count(Project.non_archived, :creator_id) +} +``` + +and update existing business analysis artefacts to use `example_metric_without_archived` instead of `example_metric` + +### 3. Metrics deprecation and removal + +The process for deprecating and removing metrics is currently under development. For +more information, see the following [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284637). + ## Implementing Usage Ping Usage Ping consists of two kinds of data, counters and observations. Counters track how often a certain event @@ -175,9 +226,9 @@ Arguments: - `relation` the ActiveRecord_Relation to perform the count - `column` the column to perform the count on, by default is the primary key -- `batch`: default `true` in order to use batch counting -- `start`: custom start of the batch counting in order to avoid complex min calculations -- `end`: custom end of the batch counting in order to avoid complex min calculations +- `batch`: default `true` to use batch counting +- `start`: custom start of the batch counting to avoid complex min calculations +- `end`: custom end of the batch counting to avoid complex min calculations Examples: @@ -199,10 +250,10 @@ Arguments: - `relation` the ActiveRecord_Relation to perform the count - `column` the column to perform the distinct count, by default is the primary key -- `batch`: default `true` in order to use batch counting +- `batch`: default `true` to use batch counting - `batch_size`: if none set it uses default value 10000 from `Gitlab::Database::BatchCounter` -- `start`: custom start of the batch counting in order to avoid complex min calculations -- `end`: custom end of the batch counting in order to avoid complex min calculations +- `start`: custom start of the batch counting to avoid complex min calculations +- `end`: custom end of the batch counting to avoid complex min calculations WARNING: Counting over non-unique columns can lead to performance issues. Take a look at the [iterating tables in batches](iterating_tables_in_batches.md) guide for more details. @@ -228,8 +279,8 @@ Arguments: - `relation` the ActiveRecord_Relation to perform the operation - `column` the column to sum on - `batch_size`: if none set it uses default value 1000 from `Gitlab::Database::BatchCounter` -- `start`: custom start of the batch counting in order to avoid complex min calculations -- `end`: custom end of the batch counting in order to avoid complex min calculations +- `start`: custom start of the batch counting to avoid complex min calculations +- `end`: custom end of the batch counting to avoid complex min calculations Examples: @@ -281,7 +332,7 @@ The method includes the following arguments: - `column`: The column to perform the distinct count. The default is the primary key. - `batch_size`: The default is 10,000, from `Gitlab::Database::PostgresHll::BatchDistinctCounter::DEFAULT_BATCH_SIZE`. - `start`: The custom start of the batch count, to avoid complex minimum calculations. -- `finish`: The custom end of the batch count in order to avoid complex maximum calculations. +- `finish`: The custom end of the batch count to avoid complex maximum calculations. The method includes the following prerequisites: @@ -364,7 +415,7 @@ Examples of implementation: 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. + To be able to increment the values, the related feature `usage_data_<event_name>` should be enabled. ```plaintext POST /usage_data/increment_counter @@ -383,7 +434,7 @@ Examples of implementation: 1. Track events using JavaScript/Vue API helper which calls the API above - Note that `usage_data_api` and `usage_data_#{event_name}` should be enabled in order to be able to track events + Note that `usage_data_api` and `usage_data_#{event_name}` should be enabled to be able to track events ```javascript import api from '~/api'; @@ -429,7 +480,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF - `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. + Consider including in the event's name the Redis slot to be able to count totals for a specific category. Example names: `i_compliance_credential_inventory`, `g_analytics_contribution`. @@ -444,7 +495,9 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF aggregation. - `aggregation`: may be set to a `:daily` or `:weekly` key. Defines how counting data is stored in Redis. Aggregation on a `daily` basis does not pull more fine grained data. - - `feature_flag`: optional. For details, see our [GitLab internal Feature flags](feature_flags/) documentation. + - `feature_flag`: optional. For details, see our [GitLab internal Feature flags](feature_flags/) documentation. The feature flags are owned by the group adding the event tracking. + +Use one of the following methods to track events: 1. Track event in controller using `RedisTracking` module with `track_redis_hll_event(*controller_actions, name:, feature:, feature_default_enabled: false)`. @@ -481,7 +534,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF 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. + To be able to track the event, Usage Ping must be enabled and the event feature `usage_data_<event_name>` must be enabled. Arguments: @@ -526,7 +579,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF API requests are protected by checking for a valid CSRF token. - In order to increment the values, the related feature `usage_data_<event_name>` should be + To increment the values, the related feature `usage_data_<event_name>` should be set to `default_enabled: true`. For more information, see [Feature flags in development of GitLab](feature_flags/index.md). @@ -562,21 +615,6 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF api.trackRedisHllUserEvent('my_already_defined_event_name'), ``` -1. Track event using base module `Gitlab::UsageDataCounters::HLLRedisCounter.track_event(event_name, values:)`. - - Arguments: - - - `event_name`: event name. - - `values`: One value or array of values we count. For example: user_id, visitor_id, user_ids. - -1. Track event on context level using base module `Gitlab::UsageDataCounters::HLLRedisCounter.track_event_in_context(event_name, values:, context:)`. - - Arguments: - - - `event_name`: event name. - - `values`: values we count. For example: user_id, visitor_id. - - `context`: context value. Allowed values are `default`, `free`, `bronze`, `silver`, `gold`, `starter`, `premium`, `ultimate` - 1. Get event data using `Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names:, start_date:, end_date:, context: '')`. Arguments: @@ -780,7 +818,7 @@ Paste the SQL query into `#database-lab` to see how the query performs at scale. - Any single query must stay below [1 second execution time](query_performance.md#timing-guidelines-for-queries) with cold caches. - Add a specialized index on columns involved to reduce the execution time. -In order to have an understanding of the query's execution we add in the MR description the following information: +To have an understanding of the query's execution we add in the MR description the following information: - For counters that have a `time_period` test we add information for both cases: - `time_period = {}` for all time periods @@ -839,16 +877,16 @@ There are currently three kinds of components that may export data to Prometheus This is the recommended approach to test Prometheus based Usage Ping. -The easiest way to verify your changes is to build a new Omnibus image from your code branch via CI, then download the image +The easiest way to verify your changes is to build a new Omnibus image from your code branch by using CI, then download the image and run a local container instance: 1. From your merge request, click on the `qa` stage, then trigger the `package-and-qa` job. This job triggers an Omnibus build in a [downstream pipeline of the `omnibus-gitlab-mirror` project](https://gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/-/pipelines). 1. In the downstream pipeline, wait for the `gitlab-docker` job to finish. 1. Open the job logs and locate the full container name including the version. It takes the following form: `registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>`. -1. On your local machine, make sure you are logged in to the GitLab Docker registry. You can find the instructions for this in +1. On your local machine, make sure you are signed in to the GitLab Docker registry. You can find the instructions for this in [Authenticate to the GitLab Container Registry](../user/packages/container_registry/index.md#authenticate-with-the-container-registry). -1. Once logged in, download the new image via `docker pull registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>` +1. Once signed in, download the new image by using `docker pull registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>` 1. For more information about working with and running Omnibus GitLab containers in Docker, please refer to [GitLab Docker images](https://docs.gitlab.com/omnibus/docker/README.html) in the Omnibus documentation. #### Test with GitLab development toolkits @@ -875,7 +913,7 @@ appear to be associated to any of the services running, since they all appear to WARNING: This feature is intended solely for internal GitLab use. -In order to add data for aggregated metrics into Usage Ping payload you should add corresponding definition in [`aggregated_metrics`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/aggregated_metrics/). Each aggregate definition includes following parts: +To add data for aggregated metrics into Usage Ping payload you should add corresponding definition in [`aggregated_metrics`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/aggregated_metrics/). Each aggregate definition includes following parts: - name: unique name under which aggregate metric is added to Usage Ping payload - operator: operator that defines how aggregated metric data is counted. Available operators are: diff --git a/doc/development/usage_ping/dictionary.md b/doc/development/usage_ping/dictionary.md new file mode 100644 index 00000000000..27a3ac42af6 --- /dev/null +++ b/doc/development/usage_ping/dictionary.md @@ -0,0 +1,158 @@ +--- +stage: Growth +group: Product Intelligence +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 +--- + +<!--- + This documentation is auto generated by a script. + + Please do not edit this file directly, check generate_metrics_dictionary task on lib/tasks/gitlab/usage_data.rake. +---> + +<!-- vale gitlab.Spelling = NO --> + +# Metrics Dictionary + +This file is autogenerated, please do not edit directly. + +To generate these files from the GitLab repository, run: + +```shell +bundle exec rake gitlab:usage_data:generate_metrics_dictionary +``` + +The Metrics Dictionary is based on the following metrics definition YAML files: + +- [`config/metrics`]('https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/metrics') +- [`ee/config/metrics`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/config/metrics) +Each table includes a `milestone`, which corresponds to the GitLab version when the metric +was released. + +## counts.deployments + +Total deployments count + +| field | value | +| --- | --- | +| `key_path` | **counts.deployments** | +| `value_type` | integer | +| `stage` | release | +| `status` | data_available | +| `milestone` | 8.12 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/735) | +| `group` | `group::ops release` | +| `time_frame` | all | +| `data_source` | Database | +| `distribution` | ee, ce | +| `tier` | free, starter, premium, ultimate, bronze, silver, gold | + +## counts.geo_nodes + +Total number of sites in a Geo deployment + +| field | value | +| --- | --- | +| `key_path` | **counts.geo_nodes** | +| `value_type` | integer | +| `product_category` | disaster_recovery | +| `stage` | enablement | +| `status` | data_available | +| `milestone` | 11.2 | +| `group` | `group::geo` | +| `time_frame` | all | +| `data_source` | Database | +| `distribution` | ee | +| `tier` | premium, ultimate | + +## counts_monthly.deployments + +Total deployments count for recent 28 days + +| field | value | +| --- | --- | +| `key_path` | **counts_monthly.deployments** | +| `value_type` | integer | +| `stage` | release | +| `status` | data_available | +| `milestone` | 13.2 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35493) | +| `group` | `group::ops release` | +| `time_frame` | 28d | +| `data_source` | Database | +| `distribution` | ee, ce | +| `tier` | free, starter, premium, ultimate, bronze, silver, gold | + +## database.adapter + +This metric only returns a value of PostgreSQL in supported versions of GitLab. It could be removed from the usage ping. Historically MySQL was also supported. + +| field | value | +| --- | --- | +| `key_path` | **database.adapter** | +| `value_type` | string | +| `product_category` | collection | +| `stage` | growth | +| `status` | data_available | +| `group` | `group::enablement distribution` | +| `time_frame` | none | +| `data_source` | Database | +| `distribution` | ee, ce | +| `tier` | free, starter, premium, ultimate, bronze, silver, gold | + +## recorded_at + +When the Usage Ping computation was started + +| field | value | +| --- | --- | +| `key_path` | **recorded_at** | +| `value_type` | string | +| `product_category` | collection | +| `stage` | growth | +| `status` | data_available | +| `milestone` | 8.1 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/557) | +| `group` | `group::product analytics` | +| `time_frame` | none | +| `data_source` | Ruby | +| `distribution` | ee, ce | +| `tier` | free, starter, premium, ultimate, bronze, silver, gold | + +## redis_hll_counters.issues_edit.g_project_management_issue_title_changed_weekly + +Distinct users count that changed issue title in a group for last recent week + +| field | value | +| --- | --- | +| `key_path` | **redis_hll_counters.issues_edit.g_project_management_issue_title_changed_weekly** | +| `value_type` | integer | +| `product_category` | issue_tracking | +| `stage` | plan | +| `status` | data_available | +| `milestone` | 13.6 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/issues/229918) | +| `group` | `group::project management` | +| `time_frame` | 7d | +| `data_source` | Redis_hll | +| `distribution` | ee, ce | +| `tier` | free, starter, premium, ultimate, bronze, silver, gold | + +## uuid + +GitLab instance unique identifier + +| field | value | +| --- | --- | +| `key_path` | **uuid** | +| `value_type` | string | +| `product_category` | collection | +| `stage` | growth | +| `status` | data_available | +| `milestone` | 9.1 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1521) | +| `group` | `group::product analytics` | +| `time_frame` | none | +| `data_source` | Database | +| `distribution` | ee, ce | +| `tier` | free, starter, premium, ultimate, bronze, silver, gold | diff --git a/doc/development/usage_ping/metrics_dictionary.md b/doc/development/usage_ping/metrics_dictionary.md index bae79689f3b..7c41c331e88 100644 --- a/doc/development/usage_ping/metrics_dictionary.md +++ b/doc/development/usage_ping/metrics_dictionary.md @@ -14,24 +14,22 @@ We are using [JSON Schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/co This process is meant to ensure consistent and valid metrics defined for Usage Ping. All metrics *must*: -- Comply with the definied [JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/schema.json). -- Have a unique `full_path` . +- Comply with the defined [JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/schema.json). +- Have a unique `key_path` . - Have an owner. All metrics are stored in YAML files: - [`config/metrics`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/metrics) -Each metric is definied in a separate YAML file consisting of a number of fields: +Each metric is defined in a separate YAML file consisting of a number of fields: | Field | Required | Additional information | |---------------------|----------|----------------------------------------------------------------| -| `name` | yes | | +| `key_path` | yes | JSON key path for the metric, location in Usage Ping payload. | | `description` | yes | | | `value_type` | yes | | | `status` | yes | | -| `default_generation`| yes | Default generation path of the metric. One full_path value. (1) | -| `full_path` | yes | Full path of the metric for one or multiple generations. Path of the metric in Usage Ping payload. (1) | | `group` | yes | The [group](https://about.gitlab.com/handbook/product/categories/#devops-stages) that owns the metric. | | `time_frame` | yes | `string`; may be set to a value like "7d" | | `data_source` | yes | `string`: may be set to a value like `database` or `redis_hll`. | @@ -43,9 +41,6 @@ Each metric is definied in a separate YAML file consisting of a number of fields | `milestone_removed` | no | The milestone when the metric is removed. | | `introduced_by_url` | no | The URL to the Merge Request that introduced the metric. | -1. The default generation path is the location of the metric in the Usage Ping payload. - The `full_path` is the list locations for multiple Usage Ping generaations. - ### Example metric definition The linked [`uuid`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/license/uuid.yml) @@ -53,16 +48,12 @@ YAML file includes an example metric definition, where the `uuid` metric is the instance unique identifier. ```yaml -name: uuid +key_path: uuid description: GitLab instance unique identifier value_type: string product_category: collection stage: growth status: data_available -default_generation: generation_1 -full_path: - generation_1: uuid - generation_2: license.uuid milestone: 9.1 introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1521 group: group::product intelligence @@ -71,3 +62,25 @@ data_source: database distribution: [ee, ce] tier: ['free', 'starter', 'premium', 'ultimate', 'bronze', 'silver', 'gold'] ``` + +## Create a new metric definition + +The GitLab codebase provides a dedicated [generator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/generators/gitlab/usage_metric_definition_generator.rb) to create new metric definitions. + +The generator takes the key path argument and 2 options and creates the metric YAML definition in corresponding location: + +- `--ee`, `--no-ee` Indicates if metric is for EE. +- `--dir=DIR` indicates the metric directory. It must be one of: `counts_7d`, `7d`, `counts_28d`, `28d`, `counts_all`, `all`, `settings`, `license`. + +```shell +bundle exec rails generate gitlab:usage_metric_definition counts.issues --dir=7d +create config/metrics/counts_7d/issues.yml +``` + +NOTE: +To create a metric definition used in EE, add the `--ee` flag. + +```shell +bundle exec rails generate gitlab:usage_metric_definition counts.issues --ee --dir=7d +create ee/config/metrics/counts_7d/issues.yml +``` diff --git a/doc/development/utilities.md b/doc/development/utilities.md index 2d347df0559..d7baa6b23a5 100644 --- a/doc/development/utilities.md +++ b/doc/development/utilities.md @@ -10,7 +10,7 @@ We have developed a number of utilities to help ease development: ## `MergeHash` -Refer to: <https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/utils/merge_hash.rb>: +Refer to [`merge_hash.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/utils/merge_hash.rb): - Deep merges an array of hashes: @@ -109,9 +109,50 @@ Refer to [`override.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gi Because only a class or prepended module can actually override a method. Including or extending a module into another cannot override anything. +### Interactions with `ActiveSupport::Concern`, `prepend`, and `class_methods` + +When you use `ActiveSupport::Concern` that includes class methods, you do not +get expected results because `ActiveSupport::Concern` doesn't work like a +regular Ruby module. + +Since we already have `Prependable` as a patch for `ActiveSupport::Concern` +to enable `prepend`, it has consequences with how it would interact with +`override` and `class_methods`. As a workaround, `extend` `ClassMethods` +into the defining `Prependable` module. + +This allows us to use `override` to verify `class_methods` used in the +context mentioned above. This workaround only applies when we run the +verification, not when running the application itself. + +Here are example code blocks that demonstrate the effect of this workaround: +following codes: + +```ruby +module Base + extend ActiveSupport::Concern + + class_methods do + def f + end + end +end + +module Derived + include Base +end + +# Without the workaround +Base.f # => NoMethodError +Derived.f # => nil + +# With the workaround +Base.f # => nil +Derived.f # => nil +``` + ## `StrongMemoize` -Refer to <https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/utils/strong_memoize.rb>: +Refer to [`strong_memoize.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/utils/strong_memoize.rb): - Memoize the value even if it is `nil` or `false`. diff --git a/doc/development/ux_guide/animation.md b/doc/development/ux_guide/animation.md deleted file mode 100644 index 0f7a24042bb..00000000000 --- a/doc/development/ux_guide/animation.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/product-foundations/motion/' ---- - -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/product-foundations/motion/). diff --git a/doc/development/ux_guide/basics.md b/doc/development/ux_guide/basics.md deleted file mode 100644 index 1e84bf608f4..00000000000 --- a/doc/development/ux_guide/basics.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/' ---- - -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/components.md b/doc/development/ux_guide/components.md deleted file mode 100644 index 1e84bf608f4..00000000000 --- a/doc/development/ux_guide/components.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/' ---- - -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md deleted file mode 100644 index 1e84bf608f4..00000000000 --- a/doc/development/ux_guide/copy.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/' ---- - -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/features.md b/doc/development/ux_guide/features.md deleted file mode 100644 index 1e84bf608f4..00000000000 --- a/doc/development/ux_guide/features.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/' ---- - -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/illustrations.md b/doc/development/ux_guide/illustrations.md deleted file mode 100644 index 815f870f8c5..00000000000 --- a/doc/development/ux_guide/illustrations.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/product-foundations/illustration/' ---- - -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/product-foundations/illustration/). diff --git a/doc/development/ux_guide/index.md b/doc/development/ux_guide/index.md deleted file mode 100644 index 1e84bf608f4..00000000000 --- a/doc/development/ux_guide/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/' ---- - -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/principles.md b/doc/development/ux_guide/principles.md deleted file mode 100644 index 1e84bf608f4..00000000000 --- a/doc/development/ux_guide/principles.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/' ---- - -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/resources.md b/doc/development/ux_guide/resources.md deleted file mode 100644 index ae092246d05..00000000000 --- a/doc/development/ux_guide/resources.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/resources/design-resources/' ---- - -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/resources/design-resources/). diff --git a/doc/development/ux_guide/surfaces.md b/doc/development/ux_guide/surfaces.md deleted file mode 100644 index 1e84bf608f4..00000000000 --- a/doc/development/ux_guide/surfaces.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/' ---- - -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/tips.md b/doc/development/ux_guide/tips.md deleted file mode 100644 index 1e84bf608f4..00000000000 --- a/doc/development/ux_guide/tips.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://design.gitlab.com/' ---- - -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/users.md b/doc/development/ux_guide/users.md deleted file mode 100644 index a01aa4bcf35..00000000000 --- a/doc/development/ux_guide/users.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/' ---- - -This document was moved to [another location](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/wikis.md b/doc/development/wikis.md index a2da4843eac..7995afb1e17 100644 --- a/doc/development/wikis.md +++ b/doc/development/wikis.md @@ -1,7 +1,7 @@ --- type: reference, dev stage: Create -group: Knowledge +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/#assignments description: "GitLab's development guidelines for Wikis" --- @@ -12,8 +12,8 @@ description: "GitLab's development guidelines for Wikis" ## Overview -The wiki functionality in GitLab is based on [Gollum 4.x](https://github.com/gollum/gollum/), -which is used in [Gitaly's](gitaly.md) Ruby service and accessed from the Rails app through Gitaly RPC calls. +The wiki functionality in GitLab is based on [Gollum 4.x](https://github.com/gollum/gollum/). +It's used in [Gitaly's](gitaly.md) Ruby service, and accessed from the Rails app through Gitaly RPC calls. Wikis use Git repositories as storage backend, and can be accessed through: @@ -43,7 +43,7 @@ When rendering wiki pages, we don't use Gollum at all and instead go through a [custom Banzai pipeline](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/banzai/pipeline/wiki_pipeline.rb). This adds some [wiki-specific markup](../user/markdown.md#wiki-specific-markdown), such as Gollum's `[[link]]` syntax. -Since we do not make use of most of Gollum's features, we plan to move away from it entirely at some point. +Because we do not make use of most of Gollum's features, we plan to move away from it entirely at some point. [See this epic](https://gitlab.com/groups/gitlab-org/-/epics/2381) for reference. ## Model classes diff --git a/doc/development/windows.md b/doc/development/windows.md index 08ff29a4e58..07f8a80e95f 100644 --- a/doc/development/windows.md +++ b/doc/development/windows.md @@ -63,7 +63,7 @@ Build a Google Cloud image with the above shared runners repository by doing the ## How to use a Windows image in GCP -1. In a web browser, go to <https://console.cloud.google.com/compute/images>. +1. In a web browser, go to the [Google Cloud Platform console](https://console.cloud.google.com/compute/images). 1. Filter images by the name you used when creating image, `windows` is likely all you need to filter by. 1. Click the image's name. 1. Click the **CREATE INSTANCE** link. @@ -81,7 +81,7 @@ Build a Google Cloud image with the above shared runners repository by doing the 1. Click **Continue** to accept the certificate. 1. Enter the password and click **Next**. -You should now be remoted into a Windows machine with a command prompt. +You should now be connected into a Windows machine with a command prompt. ### Optional: Use GCP VM Instance as a runner diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md deleted file mode 100644 index 038a4b1e6ea..00000000000 --- a/doc/development/writing_documentation.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_to: 'documentation/index.md' ---- diff --git a/doc/gitlab-basics/add-image.md b/doc/gitlab-basics/add-image.md deleted file mode 100644 index 8eb60f03877..00000000000 --- a/doc/gitlab-basics/add-image.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'add-file.md' ---- - -This document was moved to [another location](add-file.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/add-merge-request.md b/doc/gitlab-basics/add-merge-request.md deleted file mode 100644 index a04bc5704e5..00000000000 --- a/doc/gitlab-basics/add-merge-request.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/project/merge_requests/creating_merge_requests.md' ---- - -This document was moved to [another location](../user/project/merge_requests/creating_merge_requests.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/basic-git-commands.md b/doc/gitlab-basics/basic-git-commands.md deleted file mode 100644 index 506fe89fc18..00000000000 --- a/doc/gitlab-basics/basic-git-commands.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'start-using-git.md' ---- - -This document was moved to [another location](start-using-git.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/command-line-commands.md b/doc/gitlab-basics/command-line-commands.md index d237fa940e3..c747c33a480 100644 --- a/doc/gitlab-basics/command-line-commands.md +++ b/doc/gitlab-basics/command-line-commands.md @@ -106,9 +106,9 @@ WARNING: Be careful of the commands you run with `sudo`. Certain commands may cause damage to your data or system. -## Sample Git taskflow +## Sample Git task flow -If you're completely new to Git, looking through some [sample taskflows](https://rogerdudler.github.io/git-guide/) +If you're completely new to Git, looking through some [sample task flows](https://rogerdudler.github.io/git-guide/) may help you understand the best practices for using these commands as you work. <!-- ## Troubleshooting diff --git a/doc/gitlab-basics/create-group.md b/doc/gitlab-basics/create-group.md deleted file mode 100644 index f683b92af89..00000000000 --- a/doc/gitlab-basics/create-group.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/group/index.md#create-a-new-group' ---- - -This document was moved to [another location](../user/group/index.md#create-a-new-group). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/create-issue.md b/doc/gitlab-basics/create-issue.md deleted file mode 100644 index 39e47690264..00000000000 --- a/doc/gitlab-basics/create-issue.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/project/issues/index.md#viewing-and-managing-issues' ---- - -This document was moved to [another location](../user/project/issues/index.md#viewing-and-managing-issues). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md index 7f3e90dc6bd..778bbc63099 100644 --- a/doc/gitlab-basics/start-using-git.md +++ b/doc/gitlab-basics/start-using-git.md @@ -51,7 +51,7 @@ prompt, terminal, and command line) of your preference. Here are some suggestion - Built-in: [Terminal](https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line). Press <kbd>⌘ command</kbd> + <kbd>space</kbd> and type "terminal" to find it. - [iTerm2](https://iterm2.com/), which you can integrate with [zsh](https://git-scm.com/book/id/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Zsh) and [oh my zsh](https://ohmyz.sh/) for color highlighting, among other handy features for Git users. - For Windows users: - - Built-in: **cmd**. Click the search icon on the bottom navbar on Windows and type "cmd" to find it. + - Built-in: `cmd`. Click the search icon on the bottom navigation bar on Windows and type `cmd` to find it. - [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7): a Windows "powered up" shell, from which you can execute a greater number of commands. - Git Bash: it comes built into [Git for Windows](https://gitforwindows.org/). - For Linux users: @@ -152,8 +152,12 @@ Your files in GitLab live in a **repository**, similar to how you have them in a directory in your computer. **Remote** repository refers to the files in GitLab and the copy in your computer is called **local** copy. A **project** in GitLab is what holds a repository, which holds your files. -Often, the word "repository" is shortened to "repo". +<!-- vale gitlab.Spelling = NO --> +<!-- vale gitlab.SubstitutionWarning = NO --> +Often, the word "repository" is shortened to "repo". +<!-- vale gitlab.Spelling = YES --> +<!-- vale gitlab.SubstitutionWarning = YES --> ### Fork When you want to copy someone else's repository, you [**fork**](../user/project/repository/forking_workflow.md#creating-a-fork) diff --git a/doc/install/README.md b/doc/install/README.md index 7ed478439e0..092aca8a5b7 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -7,7 +7,7 @@ description: Read through the GitLab installation methods. type: index --- -# Installation **(CORE ONLY)** +# Installation **(FREE SELF)** GitLab can be installed in most GNU/Linux distributions and with several cloud providers. To get the best experience from GitLab, you must balance @@ -24,7 +24,7 @@ install GitLab: The cloud native Helm chart for installing GitLab and all of its components on Kubernetes. - [_Docker_](#installing-gitlab-with-docker): The Omnibus GitLab packages, - dockerized. + Dockerized. - [_Source_](#installing-gitlab-from-source): Install GitLab and all of its components from scratch. - [_Cloud provider_](#installing-gitlab-on-cloud-providers): Install directly diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index 8a8e3a053b6..8fa1883da59 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -122,7 +122,7 @@ Internet Gateway. We'll now create a VPC, a virtual networking environment that you'll control: -1. Navigate to <https://console.aws.amazon.com/vpc/home>. +1. Sign in to [Amazon Web Services](https://console.aws.amazon.com/vpc/home). 1. Select **Your VPCs** from the left menu and then click **Create VPC**. At the "Name tag" enter `gitlab-vpc` and at the "IPv4 CIDR block" enter `10.0.0.0/16`. If you don't require dedicated hardware, you can leave @@ -277,7 +277,7 @@ On the Route 53 dashboard, click **Hosted zones** in the left navigation bar: 1. Click **Create**. 1. If you registered your domain through Route 53, you're done. If you used a different domain registrar, you need to update your DNS records with your domain registrar. You'll need to: 1. Click on **Hosted zones** and select the domain you added above. - 1. You'll see a list of `NS` records. From your domain registrar's admin panel, add each of these as `NS` records to your domain's DNS records. These steps may vary between domain registrars. If you're stuck, Google **"name of your registrar" add dns records** and you should find a help article specific to your domain registrar. + 1. You'll see a list of `NS` records. From your domain registrar's admin panel, add each of these as `NS` records to your domain's DNS records. These steps may vary between domain registrars. If you're stuck, Google **"name of your registrar" add DNS records** and you should find a help article specific to your domain registrar. The steps for doing this vary depending on which registrar you use and is beyond the scope of this guide. @@ -568,7 +568,7 @@ Let's create an EC2 instance where we'll install Gitaly: 1. From the EC2 dashboard, click **Launch instance**. 1. Choose an AMI. In this example, we'll select the **Ubuntu Server 18.04 LTS (HVM), SSD Volume Type**. -1. Choose an instance type. We'll pick a **c5.xlarge**. +1. Choose an instance type. We'll pick a `c5.xlarge`. 1. Click **Configure Instance Details**. 1. In the **Network** dropdown, select `gitlab-vpc`, the VPC we created earlier. 1. In the **Subnet** dropdown, select `gitlab-private-10.0.1.0` from the list of subnets we created earlier. diff --git a/doc/install/google-protobuf.md b/doc/install/google-protobuf.md deleted file mode 100644 index ae7b0548d51..00000000000 --- a/doc/install/google-protobuf.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'installation.md#google-protobuf-loaderror-libx86_64-linux-gnulibcso6-version-glibc_214-not-found' ---- - -This document was moved to [another location](installation.md#google-protobuf-loaderror-libx86_64-linux-gnulibcso6-version-glibc_214-not-found). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md index d579e214efc..7f38970a2b1 100644 --- a/doc/install/google_cloud_platform/index.md +++ b/doc/install/google_cloud_platform/index.md @@ -36,7 +36,7 @@ To deploy GitLab on GCP you first need to create a virtual machine:  1. On the next page, you can select the type of VM as well as the - estimated costs. Provide the name of the instance, desired datacenter, and machine type. + estimated costs. Provide the name of the instance, desired data center, and machine type. Note our [hardware requirements for different user base sizes](../requirements.md#hardware-requirements).  diff --git a/doc/install/installation.md b/doc/install/installation.md index 80f3f6ab092..86f8476a786 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -172,8 +172,12 @@ sudo apt-get install -y postfix Then select 'Internet Site' and press enter to confirm the hostname. +<!-- vale gitlab.Spelling = NO --> + ### Exiftool +<!-- vale gitlab.Spelling = YES --> + [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse#dependencies) requires `exiftool` to remove EXIF data from uploaded images. @@ -187,7 +191,7 @@ The Ruby interpreter is required to run GitLab. See the [requirements page](requirements.md#ruby-versions) for the minimum Ruby requirements. -The use of Ruby version managers such as [RVM](https://rvm.io/), [rbenv](https://github.com/rbenv/rbenv) or [chruby](https://github.com/postmodern/chruby) with GitLab +The use of Ruby version managers such as [`RVM`](https://rvm.io/), [`rbenv`](https://github.com/rbenv/rbenv) or [`chruby`](https://github.com/postmodern/chruby) with GitLab in production, frequently leads to hard to diagnose problems. Version managers are not supported and we strongly advise everyone to follow the instructions below to use a system Ruby. @@ -205,7 +209,7 @@ Download Ruby and compile it: ```shell mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress "https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.2.tar.gz" +curl --remote-name --progress-bar "https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.2.tar.gz" echo 'cb9731a17487e0ad84037490a6baf8bfa31a09e8 ruby-2.7.2.tar.gz' | shasum -c - && tar xzf ruby-2.7.2.tar.gz cd ruby-2.7.2 @@ -225,7 +229,7 @@ page](https://golang.org/dl). # Remove former Go installation folder sudo rm -rf /usr/local/go -curl --remote-name --progress "https://dl.google.com/go/go1.13.5.linux-amd64.tar.gz" +curl --remote-name --progress-bar "https://dl.google.com/go/go1.13.5.linux-amd64.tar.gz" echo '512103d7ad296467814a6e3f635631bd35574cab3369a97a323c9a585ccaa569 go1.13.5.linux-amd64.tar.gz' | shasum -a256 -c - && \ sudo tar -C /usr/local -xzf go1.13.5.linux-amd64.tar.gz sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ @@ -238,16 +242,16 @@ In GitLab 8.17 and later, GitLab requires the use of Node to compile JavaScript assets, and Yarn to manage JavaScript dependencies. The current minimum requirements for these are: -- `node` >= v10.13.0. (We recommend node 12.x as it is faster) +- `node` >= v10.14.2. (We recommend node 14.x as it is faster) - `yarn` >= v1.10.0. -In many distros, +In many distributions, the versions provided by the official package repositories are out of date, so we need to install through the following commands: ```shell -# install node v12.x -curl --location "https://deb.nodesource.com/setup_12.x" | sudo bash - +# install node v14.x +curl --location "https://deb.nodesource.com/setup_14.x" | sudo bash - sudo apt-get install -y nodejs curl --silent --show-error "https://dl.yarnpkg.com/debian/pubkey.gpg" | sudo apt-key add - @@ -603,7 +607,7 @@ You can specify a different Git repository by providing it as an extra parameter sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse,https://example.com/gitlab-workhorse.git]" RAILS_ENV=production ``` -### Install GitLab-Elasticsearch-indexer on Enterprise Edition **(STARTER ONLY)** +### Install GitLab-Elasticsearch-indexer on Enterprise Edition **(PREMIUM SELF)** GitLab-Elasticsearch-Indexer uses [GNU Make](https://www.gnu.org/software/make/). The following command-line installs GitLab-Elasticsearch-Indexer in `/home/git/gitlab-elasticsearch-indexer` @@ -935,7 +939,7 @@ production: url: redis://redis.example.tld:6379 ``` -If you want to connect the Redis server via socket, use the "unix:" URL scheme and the path to the Redis socket file in the `config/resque.yml` file. +If you want to connect the Redis server via socket, use the `unix:` URL scheme and the path to the Redis socket file in the `config/resque.yml` file. ```yaml # example diff --git a/doc/install/ldap.md b/doc/install/ldap.md deleted file mode 100644 index e88363f81b1..00000000000 --- a/doc/install/ldap.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../administration/auth/ldap/index.md' ---- - -This document was moved to [another location](../administration/auth/ldap/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/install/openshift_and_gitlab/index.md b/doc/install/openshift_and_gitlab/index.md index 21fe87a71b1..3ee899958af 100644 --- a/doc/install/openshift_and_gitlab/index.md +++ b/doc/install/openshift_and_gitlab/index.md @@ -15,7 +15,7 @@ for details. ## Introduction -[OpenShift Origin](https://www.okd.io/) (**Note:** renamed to OKD in Aug 2018) is an open source container application +[OpenShift Origin](https://www.okd.io/) (**Note:** renamed to OKD in August 2018) is an open source container application platform created by [RedHat](https://www.redhat.com/en), based on [Kubernetes](https://kubernetes.io/) and [Docker](https://www.docker.com). That means you can host your own PaaS for free and almost with no hassle. @@ -44,7 +44,7 @@ test OpenShift easily: It is also important to mention that for the purposes of this tutorial, the latest Origin release is used: -- **oc** `v1.3.0` (must be [installed](https://github.com/openshift/origin/releases/tag/v1.3.0) locally on your computer) +- **`oc`** `v1.3.0` (must be [installed](https://github.com/openshift/origin/releases/tag/v1.3.0) locally on your computer) - **OpenShift** `v1.3.0` (is pre-installed in the [VM image](https://app.vagrantup.com/openshift/boxes/origin-all-in-one)) - **Kubernetes** `v1.3.0` (is pre-installed in the [VM image](https://app.vagrantup.com/openshift/boxes/origin-all-in-one)) @@ -59,8 +59,8 @@ on your computer. ## Getting familiar with OpenShift Origin -The environment we are about to use is based on CentOS 7 which comes with all -the tools needed pre-installed: Docker, Kubernetes, OpenShift, etcd. +The environment we are about to use is based on CentOS 7, which comes with all +the tools needed pre-installed, including Docker, Kubernetes, and OpenShift. ### Test OpenShift using Vagrant @@ -100,14 +100,14 @@ order to proceed. Let's login as admin with username/password `admin/admin`. This is what the landing page looks like: - + You can see that a number of [projects](https://docs.okd.io/3.11/dev_guide/projects.html) are already created for testing purposes. If you head over the `openshift-infra` project, a number of services with their respective pods are there to explore. - + We are not going to explore the whole interface, but if you want to learn about the key concepts of OpenShift, read the [core concepts reference](https://docs.okd.io/3.11/architecture/core_concepts/index.html) @@ -318,7 +318,7 @@ NOTE: The `gitlab.apps.10.2.2.2.nip.io` hostname that is used by default will resolve to the host with IP `10.2.2.2` which is the IP our VM uses. It is a trick to have distinct FQDNs pointing to services that are on our local network. -Read more on how this works in <https://nip.io>. +Read more on how this works at [nip.io](https://nip.io). Now that we configured this, let's see how to manage and scale GitLab. @@ -343,7 +343,7 @@ created the GitLab app? This is where you can see them in action.  -You can see GitLab being reconfigured by taking look at the logs in realtime. +You can see GitLab being reconfigured by taking look at the logs in real time. Click on `gitlab-ce-2-j7ioe` (your ID will be different) and go to the **Logs** tab. @@ -464,7 +464,7 @@ OpenShift's website about [autoscaling](https://docs.okd.io/3.11/dev_guide/pod_a As stated in the [all-in-one VM](https://www.okd.io/minishift/) page: > By default, OpenShift will not allow a container to run as root or even a -non-random container assigned userid. Most Docker images in Docker Hub do not +non-random container assigned user ID. Most Docker images in Docker Hub do not follow this best practice and instead run as root. The all-in-one VM we are using has this security turned off so it will not diff --git a/doc/install/pivotal/index.md b/doc/install/pivotal/index.md index 1ac667898ab..eee70c2c578 100644 --- a/doc/install/pivotal/index.md +++ b/doc/install/pivotal/index.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Pivotal Tile **(PREMIUM ONLY)** +# GitLab Pivotal Tile **(PREMIUM SELF)** WARNING: As of September 13, 2017, the GitLab Enterprise Plus for Pivotal Cloud Foundry diff --git a/doc/install/redis.md b/doc/install/redis.md deleted file mode 100644 index 9048f777a0d..00000000000 --- a/doc/install/redis.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: installation.md#7-redis ---- - -This document was moved to [another location](installation.md#7-redis). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 69983edc383..482109646eb 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -179,7 +179,7 @@ Omnibus GitLab defaults to the recommended Puma settings. Regardless of installa tune the Puma settings. If you're using Omnibus GitLab, see [Puma settings](https://docs.gitlab.com/omnibus/settings/puma.html) -for instructions on changing the Puma settings. If you're using the GitLab Helm chart, see the [Webservice chart](https://docs.gitlab.com/charts/charts/gitlab/webservice/index.html). +for instructions on changing the Puma settings. If you're using the GitLab Helm chart, see the [`webservice` chart](https://docs.gitlab.com/charts/charts/gitlab/webservice/index.html). ### Puma workers @@ -227,7 +227,7 @@ recommendation above) please see [the Unicorn settings in the Omnibus GitLab doc Redis stores all user sessions and the background task queue. The storage requirements for Redis are minimal, about 25kB per user. -Sidekiq processes the background jobs with a multithreaded process. +Sidekiq processes the background jobs with a multi-threaded process. This process starts with the entire Rails stack (200MB+) but it can grow over time due to memory leaks. On a very active server (10,000 billable users) the Sidekiq process can use 1GB+ of memory. diff --git a/doc/install/structure.md b/doc/install/structure.md deleted file mode 100644 index ca90a3de1b8..00000000000 --- a/doc/install/structure.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: installation.md#gitlab-directory-structure ---- - -This page was moved to [another location](installation.md#gitlab-directory-structure). diff --git a/doc/integration/README.md b/doc/integration/README.md index 227e2eec53c..7d38dd6222a 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -25,7 +25,7 @@ GitLab can be configured to authenticate access requests with the following auth - Enable sign in via [LDAP](../administration/auth/ldap/index.md). - Enable [OAuth2 provider](oauth_provider.md) application creation. - Use [OmniAuth](omniauth.md) to enable sign in via Twitter, GitHub, GitLab.com, Google, - Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure or Authentiq ID. + Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure, or Authentiq ID. - Use GitLab as an [OpenID Connect](openid_connect_provider.md) identity provider. - Authenticate to [Vault](vault.md) through GitLab OpenID Connect. - Configure GitLab as a [SAML](saml.md) 2.0 Service Provider. @@ -39,6 +39,11 @@ GitLab can be integrated with the following external services to enhance securit GitLab also provides features to improve the security of your own application. For more details see [GitLab Secure](../user/application_security/index.md). +## Security partners + +GitLab has integrated with several security partners. For more information, see +[Security partners integration](security_partners/index.md). + ## Continuous integration GitLab can be integrated with the following external service for continuous integration: @@ -65,7 +70,9 @@ Integration with services such as Campfire, Flowdock, HipChat, Pivotal Tracker, ### SSL certificate errors -When trying to integrate GitLab with services that are using self-signed certificates, it is very likely that SSL certificate errors occur in different parts of the application, most likely Sidekiq. +When trying to integrate GitLab with services using self-signed certificates, +SSL certificate errors can occur in different parts of the application. Sidekiq +is a common culprit. There are two approaches you can take to solve this: diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index 4bc9d39ae3f..8999f4da9a2 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -10,8 +10,8 @@ NOTE: Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an earlier version, you must explicitly enable it. -You can set up Bitbucket.org as an OAuth2 provider so that you can use your -Bitbucket.org account credentials to sign into GitLab or import your projects from +You can set up Bitbucket.org as an OAuth2 provider to use your +Bitbucket.org account credentials to sign in to GitLab, or import your projects from Bitbucket.org. - To use Bitbucket.org as an OmniAuth provider, follow the diff --git a/doc/integration/cas.md b/doc/integration/cas.md index 5a198e85f5c..b444143b03e 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # CAS OmniAuth Provider -To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab supplies to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for backchannel logout. +To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab supplies to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for back-channel logout. 1. On your GitLab server, open the configuration file. @@ -57,7 +57,7 @@ To enable the CAS OmniAuth provider you must register your application with your logout_url: '/CAS_PATH/logout' } } ``` -1. Change 'CAS_PATH' to the root of your CAS instance (ie. `cas`). +1. Change 'CAS_PATH' to the root of your CAS instance (such as `cas`). 1. If your CAS instance does not use default TGC lifetimes, update the `cas3.session_duration` to at least the current TGC maximum lifetime. To explicitly disable SLO, regardless of CAS settings, set this to 0. diff --git a/doc/integration/chat_commands.md b/doc/integration/chat_commands.md deleted file mode 100644 index a0361064d87..00000000000 --- a/doc/integration/chat_commands.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'slash_commands.md' ---- - -This document was moved to [integration/slash_commands.md](slash_commands.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/crowd.md b/doc/integration/crowd.md deleted file mode 100644 index e07e3435baf..00000000000 --- a/doc/integration/crowd.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../administration/auth/crowd.md' ---- - -This document was moved to [`administration/auth/crowd`](../administration/auth/crowd.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index b1fc2573bb0..6e27d535b63 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -5,10 +5,11 @@ 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/#assignments --- -# Elasticsearch integration **(STARTER ONLY)** +# Elasticsearch integration **(PREMIUM SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109 "Elasticsearch Merge Request") in GitLab [Starter](https://about.gitlab.com/pricing/) 8.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109 "Elasticsearch Merge Request") in GitLab 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. +> - [Moved](../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. This document describes how to enable Advanced Search. After Advanced Search is enabled, you'll have the benefit of fast search response times @@ -152,7 +153,7 @@ cd $indexer_path && sudo make install The `gitlab-elasticsearch-indexer` will be installed to `/usr/local/bin`. -You can change the installation path with the `PREFIX` env variable. +You can change the installation path with the `PREFIX` environment variable. Please remember to pass the `-E` flag to `sudo` if you do so. Example: @@ -175,8 +176,7 @@ instances](#indexing-large-instances) below. To enable Advanced Search, you need to have admin access to GitLab: -1. Navigate to **Admin Area**, then **Settings > General** - and expand the **Advanced Search** section. +1. Navigate to **Admin Area**, then **Settings > Advanced Search**. NOTE: To see the Advanced Search section, you need an active Starter @@ -186,7 +186,7 @@ To enable Advanced Search, you need to have admin access to GitLab: your Elasticsearch cluster. Do not enable **Search with Elasticsearch enabled** yet. 1. Now enable **Elasticsearch indexing** in **Admin Area > Settings > - General > Advanced Search** and click **Save changes**. This will create + Advanced Search** and click **Save changes**. This will create an empty index if one does not already exist. 1. Click **Index all projects**. 1. Click **Check progress** in the confirmation message to see the status of @@ -202,7 +202,7 @@ To enable Advanced Search, you need to have admin access to GitLab: ``` 1. After the indexing has completed, enable **Search with Elasticsearch enabled** in - **Admin Area > Settings > General > Advanced Search** and click **Save + **Admin Area > Settings > Advanced Search** and click **Save changes**. NOTE: @@ -218,7 +218,7 @@ The following Elasticsearch settings are available: | Parameter | Description | |-------------------------------------------------------|-------------| | `Elasticsearch indexing` | Enables or disables Elasticsearch indexing and creates an empty index if one does not already exist. 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. | +| `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 resumed. | | `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). | @@ -260,13 +260,13 @@ from the Elasticsearch index as expected. ## Enabling custom language analyzers -You can improve the language support for Chinese and Japanese languages by utilizing [smartcn](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) and/or [kuromoji](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) analysis plugins from Elastic. +You can improve the language support for Chinese and Japanese languages by utilizing [`smartcn`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) and/or [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) analysis plugins from Elastic. To enable language(s) support: 1. Install the desired plugin(s), please refer to [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/plugins/7.9/installation.html) for plugins installation instructions. The plugin(s) must be installed on every node in the cluster, and each node must be restarted after installation. For a list of plugins, see the table later in this section. -1. Navigate to the **Admin Area**, then **Settings > General**.. -1. Expand the **Advanced Search** section and locate **Custom analyzers: language support**. +1. Navigate to the **Admin Area**, then **Settings > Advanced Search**.. +1. Locate **Custom analyzers: language support**. 1. Enable plugin(s) support for **Indexing**. 1. Click **Save changes** for the changes to take effect. 1. Trigger [Zero downtime reindexing](#zero-downtime-reindexing) or reindex everything from scratch to create a new index with updated mappings. @@ -276,18 +276,17 @@ For guidance on what to install, see the following Elasticsearch language plugin | Parameter | Description | |-------------------------------------------------------|-------------| -| `Enable Chinese (smartcn) custom analyzer: Indexing` | Enables or disables Chinese language support using [smartcn](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) custom analyzer for newly created indices.| -| `Enable Chinese (smartcn) custom analyzer: Search` | Enables or disables using [smartcn](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html), enabling custom analyzer indexing and recreating the index.| -| `Enable Japanese (kuromoji) custom analyzer: Indexing` | Enables or disables Japanese language support using [kuromoji](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) custom analyzer for newly created indices.| -| `Enable Japanese (kuromoji) custom analyzer: Search` | Enables or disables using [kuromoji](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html), enabling custom analyzer indexing and recreating the index.| +| `Enable Chinese (smartcn) custom analyzer: Indexing` | Enables or disables Chinese language support using [`smartcn`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) custom analyzer for newly created indices.| +| `Enable Chinese (smartcn) custom analyzer: Search` | Enables or disables using [`smartcn`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html), enabling custom analyzer indexing and recreating the index.| +| `Enable Japanese (kuromoji) custom analyzer: Indexing` | Enables or disables Japanese language support using [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) custom analyzer for newly created indices.| +| `Enable Japanese (kuromoji) custom analyzer: Search` | Enables or disables using [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html), enabling custom analyzer indexing and recreating the index.| ## Disabling Advanced Search To disable the Elasticsearch integration: -1. Navigate to the **Admin Area**, then **Settings > General**. -1. Expand the **Advanced Search** section and uncheck **Elasticsearch indexing** - and **Search with Elasticsearch enabled**. +1. Navigate to the **Admin Area**, then **Settings > Advanced Search**. +1. Uncheck **Elasticsearch indexing** and **Search with Elasticsearch enabled**. 1. Click **Save changes** for the changes to take effect. 1. (Optional) Delete the existing indexes: @@ -315,12 +314,12 @@ used by the GitLab Advanced Search integration. ### Pause the indexing -In the **Admin Area > Settings > General > Advanced Search** section, select the +In the **Admin Area > Settings > 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. +buffered and caught up after resuming. -The indexing will also be automatically paused when the [**Trigger cluster reindexing**](#trigger-the-reindex-via-the-advanced-search-administration) button is used, and unpaused when the reindexing completes or aborts. +The indexing will also be automatically paused when the [**Trigger cluster reindexing**](#trigger-the-reindex-via-the-advanced-search-administration) button is used, and resumes when the reindexing completes or aborts. ### Setup @@ -332,7 +331,7 @@ 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 > Settings > General > Advanced Search > URL +# You can find this value under Admin Area > Settings > Advanced Search > URL export CLUSTER_URL="http://localhost:9200" export PRIMARY_INDEX="gitlab-production" export SECONDARY_INDEX="gitlab-production-$(date +%s)" @@ -431,16 +430,16 @@ To trigger the re-index from `primary` index: 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 +1. Resume the indexing - Under **Admin Area > Settings > General > Advanced Search**, uncheck the **Pause Elasticsearch Indexing** setting and save. + Under **Admin Area > Settings > Advanced Search**, uncheck the **Pause Elasticsearch Indexing** setting and save. ### 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 > Settings > General > Advanced Search > Elasticsearch zero-downtime reindexing**, click on **Trigger cluster reindexing**. +Under **Admin Area > Settings > Advanced Search > Elasticsearch zero-downtime reindexing**, click on **Trigger cluster reindexing**. Reindexing can be a lengthy process depending on the size of your Elasticsearch cluster. @@ -449,9 +448,9 @@ After the reindexing is completed, the original index will be scheduled to be de While the reindexing is running, you will be able to follow its progress under that same section. -### Mark the most recent reindex job as failed and unpause the indexing +### Mark the most recent reindex job as failed and resume the indexing -Sometimes, you might want to abandon the unfinished reindex job and unpause the indexing. You can achieve this via the following steps: +Sometimes, you might want to abandon the unfinished reindex job and resume the indexing. You can achieve this via the following steps: 1. Mark the most recent reindex job as failed: @@ -463,7 +462,7 @@ Sometimes, you might want to abandon the unfinished reindex job and unpause the bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production ``` -1. Uncheck the "Pause Elasticsearch indexing" checkbox in **Admin Area > Settings > General > Advanced Search**. +1. Uncheck the "Pause Elasticsearch indexing" checkbox in **Admin Area > Settings > Advanced Search**. ## Background migrations @@ -519,8 +518,8 @@ In order to debug issues with the migrations you can check the [`elasticsearch.l Some migrations are built with a retry limit. If the migration cannot finish within the retry limit, it will be halted and a notification will be displayed in the Advanced Search integration settings. It is recommended to check the [`elasticsearch.log` file](../administration/logs.md#elasticsearchlog) to -debug why the migration was halted and make any changes before retrying the migration. Once you believe you've -fixed the cause of the failure, click "Retry migration", and the migration will be scheduled to be retried +debug why the migration was halted and make any changes before retrying the migration. Once you believe you've +fixed the cause of the failure, click "Retry migration", and the migration will be scheduled to be retried in the background. ## GitLab Advanced Search Rake tasks @@ -599,7 +598,7 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic - Number of CPUs (CPU cores) per node usually corresponds to the `Number of Elasticsearch shards` setting described below. - A good guideline is to ensure you keep the number of shards per node below 20 per GB heap it has configured. A node with a 30GB heap should therefore have a maximum of 600 shards, but the further below this limit you can keep it the better. This will generally help the cluster stay in good health. - Small shards result in small segments, which increases overhead. Aim to keep the average shard size between at least a few GB and a few tens of GB. Another consideration is the number of documents, you should aim for this simple formula for the number of shards: `number of expected documents / 5M +1`. -- `refresh_interval` is a per index setting. You may want to adjust that from default `1s` to a bigger value if you don't need data in realtime. This will change how soon you will see fresh results. If that's important for you, you should leave it as close as possible to the default value. +- `refresh_interval` is a per index setting. You may want to adjust that from default `1s` to a bigger value if you don't need data in real-time. This will change how soon you will see fresh results. If that's important for you, you should leave it as close as possible to the default value. - You might want to raise [`indices.memory.index_buffer_size`](https://www.elastic.co/guide/en/elasticsearch/reference/current/indexing-buffer.html) to 30% or 40% if you have a lot of heavy indexing operations. ### Advanced Search integration settings guidance @@ -823,7 +822,7 @@ There are a couple of ways to achieve that: This is always correctly identifying whether the current project/namespace being searched is using Elasticsearch. -- From the admin area under **Settings > General > Advanced Search** check that the +- From the admin area under **Settings > Advanced Search** check that the Advanced Search settings are checked. Those same settings there can be obtained from the Rails console if necessary: @@ -994,7 +993,7 @@ 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 results and assuming that basic search is supported in that scope. This "basic search" will behave as though you don't have Advanced Search enabled at all for -your instance and search using other data sources (ie. PostgreSQL data and Git +your instance and search using other data sources (such as PostgreSQL data and Git data). ### Data recovery: Elasticsearch is a secondary data store only diff --git a/doc/integration/github.md b/doc/integration/github.md index 858614a0571..8c2a48225dd 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Integrate your GitLab instance with GitHub -You can integrate your GitLab instance with GitHub.com and GitHub Enterprise to -enable users to import projects from GitHub or sign in to your GitLab instance -with your GitHub account. +You can integrate your GitLab instance with GitHub.com and GitHub Enterprise. This integration +enables users to import projects from GitHub, or sign in to your GitLab instance +with their GitHub account. ## Enabling GitHub OAuth @@ -24,7 +24,7 @@ To prevent an [OAuth2 covert redirect](https://oauth.net/advisories/2014-1-cover See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. -After you have configured the GitHub provider, you need the following information, which you must substitute in the GitLab configuration file, in the steps shown next. +After you have configured the GitHub provider, you need the following information. You must substitute that information in the GitLab configuration file in these next steps. | Setting from GitHub | Substitute in the GitLab configuration file | Description | |:---------------------|:---------------------------------------------|:------------| diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 3bd3099e390..94a26ee792b 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -11,7 +11,7 @@ Import projects from GitLab.com and login to your GitLab instance with your GitL To enable the GitLab.com OmniAuth provider you must register your application with GitLab.com. GitLab.com generates an application ID and secret key for you to use. -1. Sign in to GitLab.com +1. Sign in to GitLab.com. 1. On the upper right corner, click on your avatar and go to your **Settings**. diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index 05f129e6049..cc6e08259fa 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -10,45 +10,55 @@ info: "To determine the technical writer assigned to the Stage/Group associated > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228893) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/258206) in GitLab 13.8 -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. +With [Gitpod](https://gitpod.io/) you can describe your development environment as code to get fully +set up, compiled, and tested development environments for any GitLab project. The development +environments are not only automated but also prebuilt which means that Gitpod continuously builds +your Git branches like a CI/CD server. -In short: With Gitpod you can start coding instantly on any project, branch, and merge request from -any device, at any time. +This means you don't have to wait for dependencies to be downloaded and builds to finish, you can start +coding immediately. With Gitpod you can start coding instantly on any project, branch, and merge +request from any device, at any time. - +To use the GitLab Gitpod integration, it must be enabled for your GitLab instance. Users of: -You can launch Gitpod directly from GitLab by clicking the **Gitpod** button from the **Web IDE** -dropdown on the project page: - - +- GitLab.com can use it immediately after it's [enabled in their user settings](#enable-gitpod-in-your-user-settings). +- GitLab self-managed instances can use it after: + 1. It's [enabled and configured by a GitLab administrator](#configure-a-self-managed-instance). + 1. It's [enabled in their user settings](#enable-gitpod-in-your-user-settings). 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: +## Enable Gitpod in your user settings + +With the Gitpod integration enabled for your GitLab instance, to enable it for yourself: + +1. Select your avatar in the top-right corner, then select **Settings > Preferences**. +1. Under **Integrations**, locate the **Gitpod** section. +1. Check the **Enable Gitpod integration** checkbox and select the **Save changes** button. -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**. +## Configure a self-managed instance **(FREE SELF)** -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. +For GitLab self-managed instances, a GitLab administrator needs to: -## Configure your GitLab instance with Gitpod **(CORE ONLY)** +1. Set up a Gitpod instance to integrate with GitLab. Refer to the [Gitpod documentation](https://www.gitpod.io/docs/self-hosted/latest/self-hosted/) + to get your instance up and running. +1. Enable it in GitLab: + 1. Go to **Admin Area > Settings > General**. + 1. Expand the **Gitpod** configuration section. + 1. Check the **Enable Gitpod integration** checkbox. + 1. Add your Gitpod instance URL (for example, `https://gitpod.example.com`). + 1. Select the **Save changes** button. -The integration of Gitpod with GitLab is enabled on GitLab.com and available to all users. -For GitLab self-managed instances, a GitLab administrator needs to enable it through the admin settings. +Your users then need to [enable it for themselves](#enable-gitpod-in-your-user-settings). -First, you (GitLab admin) need to set up a Gitpod instance to integrate with GitLab. -Head over to the [Gitpod documentation](https://www.gitpod.io/docs/self-hosted/latest/self-hosted/) to -get your instance up and running. Once done: +## Launch Gitpod in GitLab -1. In GitLab, go to **Admin Area > Settings > General**. -1. Expand the **Gitpod** configuration section. -1. Check **Enable Gitpod**. -1. Add your Gitpod instance URL (for example, `https://gitpod.example.com`). +You can launch Gitpod directly from GitLab by clicking the **Gitpod** button from the **Web IDE** +dropdown on the project page: + + + +A project launched in GitLab looks like: + + diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 1158d6c9bc8..af9972e825e 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -10,20 +10,29 @@ GitLab supports [Google actions in email](https://developers.google.com/gmail/ma If correctly set up, emails that require an action are marked in Gmail. - + To get this functioning, you need to be registered with Google. For instructions, see [Register with Google](https://developers.google.com/gmail/markup/registering-with-google). -*This process has a lot of steps so make sure that you fulfill all requirements set by Google to avoid your application being rejected by Google.* +This process has many steps. Make sure that you fulfill all requirements set by Google to avoid your application being rejected by Google. In particular, note: +<!-- vale gitlab.InclusionCultural = NO --> + - The email account used by GitLab to send notification emails must: - Have a "Consistent history of sending a high volume of mail from your domain (order of hundred emails a day minimum to Gmail) for a few weeks at least". - Have a very low rate of spam complaints from users. - Emails must be authenticated via DKIM or SPF. -- Before sending the final form ("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you must find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there. +- Before sending the final form (**Gmail Schema Whitelist Request**), you must + send a real email from your production server. This means that you must find + a way to send this email from the email address you are registering. You can + do this by forwarding the real email from the email address you are + registering. You can also go into the Rails console on the GitLab server and + trigger sending the email from there. + +<!-- vale gitlab.InclusionCultural = YES --> You can check how it looks going through all the steps laid out in the "Registering with Google" doc in [this GitLab.com issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/1517). diff --git a/doc/integration/google_workspace_saml.md b/doc/integration/google_workspace_saml.md new file mode 100644 index 00000000000..7b561750b0f --- /dev/null +++ b/doc/integration/google_workspace_saml.md @@ -0,0 +1,163 @@ +--- +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/#assignments +--- + +# Google Workspace SSO provider + +Google Workspace (formerly G Suite) is a [Single Sign-on provider](https://support.google.com/a/answer/60224?hl=en) that can be used to authenticate +with GitLab. + +The following documentation enables Google Workspace as a SAML provider for GitLab. + +## Configure the Google Workspace SAML app + +The following guidance is based on this Google Workspace article, on how to [Set up your own custom SAML application](https://support.google.com/a/answer/6087519?hl=en): + +Make sure you have access to a Google Workspace [Super Admin](https://support.google.com/a/answer/2405986#super_admin) account. + Follow the instructions in the linked Google Workspace article, where you'll need the following information: + +| | Typical value | Description | +|------------------|--------------------------------------------------|----------------------------------------------------------| +| Name of SAML App | GitLab | Other names OK. | +| ACS URL | `https://<GITLAB_DOMAIN>/users/auth/saml/callback` | ACS is short for Assertion Consumer Service. | +| GITLAB_DOMAIN | `gitlab.example.com` | Set to the domain of your GitLab instance. | +| Entity ID | `https://gitlab.example.com` | A value unique to your SAML app, you'll set it to the `issuer` in your GitLab configuration. | +| Name ID format | EMAIL | Required value. Also known as `name_identifier_format` | +| Name ID | Primary email address | Make sure someone receives content sent to that address | +| First name | `first_name` | Required value to communicate with GitLab. | +| Last name | `last_name` | Required value to communicate with GitLab. | + +You will also need to setup the following SAML attribute mappings: + +| Google Directory attributes | App attributes | +|-----------------------------------|----------------| +| Basic information > Email | `email` | +| Basic Information > First name | `first_name` | +| Basic Information > Last name | `last_name` | + +You may also use some of this information when you [Configure GitLab](#configure-gitlab). + +When configuring the Google Workspace SAML app, be sure to record the following information: + +| | Value | Description | +|-------------|--------------|-----------------------------------------------------------------------------------| +| SSO URL | Depends | Google Identity Provider details. Set to the GitLab `idp_sso_target_url` setting. | +| Certificate | Downloadable | Run `openssl x509 -in <your_certificate.crt> -noout -fingerprint` to generate the SHA1 fingerprint that can be used in the `idp_cert_fingerprint` setting. | + +While the Google Workspace Admin provides IDP metadata, Entity ID and SHA-256 fingerprint, +GitLab does not need that information to connect to the Google Workspace SAML app. + +--- + +Now that the Google Workspace SAML app is configured, it's time to enable it in GitLab. + +## Configure GitLab + +1. See [Initial OmniAuth Configuration](../integration/omniauth.md#initial-omniauth-configuration) + for initial settings. + +1. To allow people to register for GitLab, through their Google accounts, add the following + values to your configuration: + + **For Omnibus GitLab installations** + + Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml'] + gitlab_rails['omniauth_block_auto_created_users'] = false + ``` + + --- + + **For installations from source** + + Edit `config/gitlab.yml`: + + ```yaml + allow_single_sign_on: ["saml"] + block_auto_created_users: false + ``` + +1. If an existing GitLab user has the same email address as a Google Workspace user, the registration + process automatically links their accounts, if you add the following setting: + their email addresses match by adding the following setting: + + **For Omnibus GitLab installations** + + Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_auto_link_saml_user'] = true + ``` + + --- + + **For installations from source** + + Edit `config/gitlab.yml`: + + ```yaml + auto_link_saml_user: true + ``` + +1. Add the provider configuration. + +For guidance on how to set up these values, see the [SAML General Setup steps](saml.md#general-setup). +Pay particular attention to the values for: + +- `assertion_consumer_service_url` +- `idp_cert_fingerprint` +- `idp_sso_target_url` +- `issuer` +- `name_identifier_format` + + **For Omnibus GitLab installations** + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: 'saml', + args: { + assertion_consumer_service_url: 'https://<GITLAB_DOMAIN>/users/auth/saml/callback', + idp_cert_fingerprint: '00:00:00:00:00:00:0:00:00:00:00:00:00:00:00:00', + idp_sso_target_url: 'https://accounts.google.com/o/saml2/idp?idpid=00000000', + issuer: 'https://<GITLAB_DOMAIN>', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress' + }, + label: 'Google Workspace' # optional label for SAML log in button, defaults to "Saml" + } + ] + ``` + + **For installations from source** + + ```yaml + - { + name: 'saml', + args: { + assertion_consumer_service_url: 'https://<GITLAB_DOMAIN>/users/auth/saml/callback', + idp_cert_fingerprint: '00:00:00:00:00:00:0:00:00:00:00:00:00:00:00:00', + idp_sso_target_url: 'https://accounts.google.com/o/saml2/idp?idpid=00000000', + issuer: 'https://<GITLAB_DOMAIN>', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress' + }, + label: 'Google Workspace' # optional label for SAML log in button, defaults to "Saml" + } + ``` + +1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for Omnibus and installations + from source respectively for the changes to take effect. + +To avoid caching issues, test the result on an incognito or private browser window. + +## Troubleshooting + +The Google Workspace documentation on [SAML app error messages](https://support.google.com/a/answer/6301076?hl=en) is helpful for debugging if you are seeing an error from Google while signing in. +Pay particular attention to the following 403 errors: + +- `app_not_configured` +- `app_not_configured_for_user` diff --git a/doc/integration/img/oauth_provider_application_form.png b/doc/integration/img/oauth_provider_application_form.png Binary files differdeleted file mode 100644 index c4546d8b3f5..00000000000 --- a/doc/integration/img/oauth_provider_application_form.png +++ /dev/null diff --git a/doc/integration/img/oauth_provider_application_id_secret.png b/doc/integration/img/oauth_provider_application_id_secret.png Binary files differdeleted file mode 100644 index 21e442b5d04..00000000000 --- a/doc/integration/img/oauth_provider_application_id_secret.png +++ /dev/null diff --git a/doc/integration/img/oauth_provider_authorized_application.png b/doc/integration/img/oauth_provider_authorized_application.png Binary files differdeleted file mode 100644 index ebff8529b4e..00000000000 --- a/doc/integration/img/oauth_provider_authorized_application.png +++ /dev/null diff --git a/doc/integration/img/oauth_provider_user_wide_applications.png b/doc/integration/img/oauth_provider_user_wide_applications.png Binary files differdeleted file mode 100644 index 9cc12555574..00000000000 --- a/doc/integration/img/oauth_provider_user_wide_applications.png +++ /dev/null diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 7be2a6efd71..81d352cfee6 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -4,9 +4,9 @@ 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/#assignments --- -# Jenkins CI service **(CORE)** +# Jenkins CI service **(FREE)** -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) to Core in GitLab 13.7. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) to GitLab Free in 13.7. From GitLab, you can trigger a Jenkins build when you push code to a repository, or when a merge request is created. In return, the Jenkins pipeline status is shown on merge requests widgets and @@ -64,7 +64,7 @@ Grant a GitLab user access to the select GitLab projects. 1. Grant the user permission to the GitLab projects. If you're integrating Jenkins with many GitLab projects, consider granting the user global - Admin permission. Otherwise, add the user to each project, and grant Developer permission. + Administrator permission. Otherwise, add the user to each project, and grant Developer permission. ## Configure GitLab API access @@ -166,7 +166,7 @@ to integrate GitLab and Jenkins. 1. In the configuration of your Jenkins job, in the GitLab configuration section, click **Advanced**. 1. Click the **Generate** button under the **Secret Token** field. 1. Copy the resulting token, and save the job configuration. -1. In GitLab, create a webhook for your project, enter the trigger URL (e.g. `https://JENKINS_URL/project/YOUR_JOB`) and paste the token in the **Secret Token** field. +1. In GitLab, create a webhook for your project, enter the trigger URL (such as `https://JENKINS_URL/project/YOUR_JOB`) and paste the token in the **Secret Token** field. 1. After you add the webhook, click the **Test** button, and it should succeed. ## Troubleshooting @@ -205,8 +205,8 @@ which is set to 10 seconds by default. To fix this the `gitlab_rails['webhook_timeout']` value must be increased in the `gitlab.rb` configuration file, followed by the [`gitlab-ctl reconfigure` command](../administration/restart_gitlab.md). -If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`), this -could also indicate that [webhook requests are timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered): +If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`), +[webhook requests may be timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered): ```plaintext 2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index b5d68e3183f..2ed87456ea1 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -50,7 +50,7 @@ Now navigate to GitLab services page and activate Jenkins  -Done! Now when you push to GitLab - it creates a build for Jenkins, and you can view the merge request build status with a link to the Jenkins build. +Done! When you push to GitLab, it creates a build for Jenkins. You can view the merge request build status with a link to the Jenkins build. ### Multi-project Configuration diff --git a/doc/integration/jira.md b/doc/integration/jira.md deleted file mode 100644 index 0e22bedd1cc..00000000000 --- a/doc/integration/jira.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/project/integrations/jira.md' ---- - -This document was moved to [another location](../user/project/integrations/jira.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md index 1c0b2bdc85e..463f8a6efaa 100644 --- a/doc/integration/jira_development_panel.md +++ b/doc/integration/jira_development_panel.md @@ -4,12 +4,11 @@ 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/#assignments --- -# GitLab Jira Development Panel integration **(CORE)** +# GitLab Jira Development Panel integration **(FREE)** -> - [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. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) to GitLab Free in 13.4. -The Jira Development Panel integration allows you to reference Jira issues within GitLab, displaying +The Jira Development Panel integration allows you to reference Jira issues in GitLab, displaying activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) in the issue. @@ -35,7 +34,7 @@ See the [Configuration](#configuration) section for details. With this integration, you can access related GitLab merge requests, branches, and commits directly from a Jira issue, reflecting your work in GitLab. From the Development panel, you can open a detailed view and take actions including creating a new merge request from a branch. For more information, see [Usage](#usage). -This integration connects all GitLab projects to projects in the Jira instance within either: +This integration connects all GitLab projects to projects in the Jira instance in either: - A top-level group. A top-level GitLab group is one that does not have any parent group itself. All the projects of that top-level group, as well as projects of the top-level group's subgroups nesting @@ -57,13 +56,13 @@ If you're using: - Self-managed GitLab, self-managed Jira, or both, configure the integration using [Jira's DVCS Connector](#jira-dvcs-configuration), which syncs data hourly. -We recommend that a GitLab group administrator or instance administrator (in the case of +We recommend that a GitLab group maintainer or group owner, or instance administrator (in the case of self-managed GitLab) set up the integration to simplify administration. ### Jira DVCS configuration -If you're using GitLab.com and Jira Cloud, we recommend you use the -[GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. +If you're using GitLab.com and Jira Cloud, use the +[GitLab for Jira app](#gitlab-for-jira-app) unless you have a specific need for the DVCS Connector. When configuring Jira DVCS Connector: @@ -79,13 +78,11 @@ create and use a single-purpose `jira` user in GitLab. 1. In GitLab, create a new application to allow Jira to connect with your GitLab account. - While signed in to the GitLab account that you want Jira to use to connect to GitLab, - click your profile avatar at the top right, and then click **Settings > Applications**. - Use the form to create a new application. - - In the **Name** field, enter a descriptive name for the integration, such as `Jira`. - - For the **Redirect URI** field, enter `https://<gitlab.example.com>/login/oauth/callback`, +1. Sign in to the GitLab account that you want Jira to use to connect to GitLab. +1. In the top right corner, click your profile avatar. +1. Click **Settings > Applications** to display the form to create a new application. +1. In the **Name** field, enter a descriptive name for the integration, such as `Jira`. +1. In the **Redirect URI** field, enter `https://<gitlab.example.com>/login/oauth/callback`, replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com, this would be `https://gitlab.com/login/oauth/callback`. @@ -97,15 +94,15 @@ create and use a single-purpose `jira` user in GitLab.  - - Check **API** in the Scopes section and uncheck any other checkboxes. +1. Check **API** in the Scopes section, and uncheck any other checkboxes. 1. Click **Save application**. GitLab displays the generated **Application ID** and **Secret** values. Copy these values, which you use in Jira. #### Jira DVCS Connector setup -If you're using GitLab.com and Jira Cloud, we recommend you use the -[GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. +If you're using GitLab.com and Jira Cloud, use the +[GitLab for Jira app](#gitlab-for-jira-app) unless you have a specific need for the DVCS Connector. 1. Ensure you have completed the [GitLab configuration](#gitlab-account-configuration-for-dvcs). 1. If you're using Jira Server, go to **Settings (gear) > Applications > DVCS accounts**. @@ -114,37 +111,39 @@ If you're using GitLab.com and Jira Cloud, we recommend you use the (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. +1. Select **GitHub Enterprise** for the **Host** field. + +1. In the **Team or User Account** field, enter either: - In the **Team or User Account** field, enter the relative path of a top-level GitLab group that you have access to, - or the relative path of your personal namespace. + - The relative path of a top-level GitLab group that you have access to. + - The relative path of your personal namespace.  - In the **Host URL** field, enter `https://<gitlab.example.com>/`, +1. In the **Host URL** field, enter `https://<gitlab.example.com>/`, replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com, this would be `https://gitlab.com/`. NOTE: If using a GitLab version earlier than 11.3 the **Host URL** value should be `https://<gitlab.example.com>/-/jira` - For the **Client ID** field, use the **Application ID** value from the previous section. +1. For the **Client ID** field, use the **Application ID** value from the previous section. - For the **Client Secret** field, use the **Secret** value from the previous section. +1. For the **Client Secret** field, use the **Secret** value from the previous section. - Ensure that the rest of the checkboxes are checked. +1. Ensure that the rest of the checkboxes are checked. 1. Click **Add** to complete and create the integration. - Jira takes up to a few minutes to know about (import behind the scenes) all the commits and branches - for all the projects in the GitLab group you specified in the previous step. These are refreshed - every 60 minutes. + Jira takes up to a few minutes to know about (import behind the scenes) all the commits and branches + for all the projects in the GitLab group you specified in the previous step. These are refreshed + every 60 minutes. - In the future, we plan on implementing real-time integration. If you need - to refresh the data manually, you can do this from the `Applications -> DVCS - accounts` screen where you initially set up the integration: + In the future, we plan on implementing real-time integration. If you need + to refresh the data manually, you can do this from the `Applications -> DVCS + accounts` screen where you initially set up the integration: -  +  To connect additional GitLab projects from other GitLab top-level groups (or personal namespaces), repeat the previous steps with additional Jira DVCS accounts. @@ -173,26 +172,26 @@ If there was an issue with SSL/TLS, this error message is generated. as GitLab is the TLS client. - The Jira Development Panel integration requires Jira to connect to GitLab, which causes Jira to be the TLS client. If your GitLab server's certificate is not - issued by a public certificate authority, the Java truststore on Jira's server + issued by a public certificate authority, the Java Truststore on Jira's server needs to have the appropriate certificate added to it (such as your organization's root certificate). Refer to Atlassian's documentation and Atlassian Support for assistance setting up Jira correctly: - [Adding a certificate to the trust store](https://confluence.atlassian.com/kb/how-to-import-a-public-ssl-certificate-into-a-jvm-867025849.html). - - Simplest approach is to use [keytool](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html). - - Add additional roots to Java's default truststore (`cacerts`) to allow Jira to + - Simplest approach is to use [`keytool`](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html). + - Add additional roots to Java's default Truststore (`cacerts`) to allow Jira to also trust public certificate authorities. - If the integration stops working after upgrading Jira's Java runtime, this - might be because the `cacerts` truststore got replaced. + might be because the `cacerts` Truststore got replaced. - [Troubleshooting connectivity up to and including TLS handshaking](https://confluence.atlassian.com/kb/unable-to-connect-to-ssl-services-due-to-pkix-path-building-failed-error-779355358.html), using the a java class called `SSLPoke`. -- Download the class from Atlassian's knowledgebase to Jira's server, for example to `/tmp`. +- Download the class from Atlassian's knowledge base to Jira's server, for example to `/tmp`. - Use the same Java runtime as Jira. - Pass all networking-related parameters that Jira is called with, such as proxy - settings or an alternative root truststore (`-Djavax.net.ssl.trustStore`): + settings or an alternative root Truststore (`-Djavax.net.ssl.trustStore`): ```shell ${JAVA_HOME}/bin/java -Djavax.net.ssl.trustStore=/var/atlassian/application-data/jira/cacerts -classpath /tmp SSLPoke gitlab.example.com 443 @@ -211,7 +210,7 @@ The requested scope is invalid, unknown, or malformed. Potential resolutions: -- Verify the URL shown in the browser after being redirected from Jira in step 5 of [Jira DVCS Connector Setp](#jira-dvcs-connector-setup) includes `scope=api` within the query string. +- Verify the URL shown in the browser after being redirected from Jira in step 5 of [Jira DVCS Connector Setup](#jira-dvcs-connector-setup) includes `scope=api` in the query string. - If `scope=api` is missing from the URL, return to [GitLab account configuration](#gitlab-account-configuration-for-dvcs) and ensure the application you created in step 1 has the `api` box checked under scopes. ##### Jira error adding account and no repositories listed @@ -230,7 +229,7 @@ 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). -- If you're using GitLab Core or GitLab Starter, be sure you're using +- If you're using GitLab Free 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. @@ -252,7 +251,7 @@ resynchronize the information. To do so: You can integrate GitLab.com and Jira Cloud using the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace. -This method is recommended when using GitLab.com and Jira Cloud because data is synchronized in realtime, while the DVCS connector updates data only once per hour. If you are not using both of these environments, use the [Jira DVCS Connector](#jira-dvcs-configuration) method. +This method is recommended when using GitLab.com and Jira Cloud because data is synchronized in real-time. The DVCS connector updates data only once per hour. If you are not using both of these environments, use the [Jira DVCS Connector](#jira-dvcs-configuration) method. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a walkthrough of the integration with GitLab for Jira, watch [Configure GitLab Jira Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube. @@ -285,7 +284,7 @@ For more information, see [Usage](#usage). #### Troubleshooting GitLab for Jira -The GitLab for Jira App uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies which can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in. +The GitLab for Jira App uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies. This can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in. > "You need to sign in or sign up before continuing." @@ -314,6 +313,6 @@ For more information on using Jira Smart Commits to track time against an issue, ## Limitations -This integration is currently not supported on GitLab instances under a +This integration is not supported on GitLab instances under a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab). For example, `http://example.com/gitlab`. diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 390c3ae3e7c..d8297ac87b3 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, how-to --- -# Kerberos integration **(STARTER ONLY)** +# Kerberos integration **(PREMIUM SELF)** GitLab can integrate with [Kerberos](https://web.mit.edu/kerberos/) as an authentication mechanism. @@ -109,7 +109,7 @@ existing GitLab account. To do so: 1. Navigate to **Admin Area > Overview > Users > Example User**. 1. Select the Identities tab. -1. Select 'Kerberos Spnego' in the 'Provider' dropdown box. +1. Select 'Kerberos SPNEGO' in the 'Provider' dropdown box. 1. Make sure the **Identifier** corresponds to the Kerberos username. 1. Select **Save changes**. @@ -117,7 +117,7 @@ If you're not an administrator: 1. Select your avatar in the upper-right corner, and select **Settings**. 1. Select Account. In the **Social sign-in** section, select - **Connect Kerberos Spnego**. + **Connect Kerberos SPNEGO**. If you don't see a **Social sign-in** Kerberos option, follow the requirements in [Enable single sign-on](#enable-single-sign-on). @@ -291,10 +291,10 @@ remove support for password-based Kerberos sign-ins in a future release, so we recommend that you upgrade to ticket-based sign-ins. Depending on your existing GitLab configuration, the 'Sign in with: -Kerberos Spnego' button may already be visible on your GitLab sign-in +Kerberos SPNEGO' button may already be visible on your GitLab sign-in page. If not, then add the settings [described above](#configuration). -Once you have verified that the 'Kerberos Spnego' button works +Once you have verified that the 'Kerberos SPNEGO' button works without entering any passwords, you can proceed to disable password-based Kerberos sign-ins. To do this you need only need to remove the OmniAuth provider named `kerberos` from your `gitlab.yml` / diff --git a/doc/integration/ldap.md b/doc/integration/ldap.md deleted file mode 100644 index 55c169bca80..00000000000 --- a/doc/integration/ldap.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../administration/auth/ldap/index.md' ---- - -This document was moved to [`administration/auth/ldap`](../administration/auth/ldap/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index 88e9e3ef05c..41656bd2216 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Sign into GitLab with (almost) any OAuth2 provider -The `omniauth-oauth2-generic` gem allows Single Sign On between GitLab and your own OAuth2 provider +The `omniauth-oauth2-generic` gem allows Single Sign-On between GitLab and your own OAuth2 provider (or any OAuth2 provider compatible with this gem) This strategy is designed to allow configuration of the simple OmniAuth SSO process outlined below: diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 82cb409c560..8f1c625d142 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,83 +1,87 @@ --- -stage: Create -group: Ecosystem +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/#assignments --- # GitLab as OAuth2 authentication service provider -This document is about using GitLab as an OAuth authentication service provider -to sign in to other services. +This document describes how you can use GitLab as an OAuth 2 +authentication service provider. If you want to use: - The [OAuth2](https://oauth.net/2/) protocol to access GitLab resources on user's behalf, - see [OAuth2 provider](../api/oauth2.md) -- Other OAuth authentication service providers to sign in to + see [OAuth2 provider](../api/oauth2.md). +- Other OAuth 2 authentication service providers to sign in to GitLab, see the [OAuth2 client documentation](omniauth.md). - The related API, see [Applications API](../api/applications.md). ## Introduction to OAuth -[OAuth](https://oauth.net/2/) provides to client applications a 'secure delegated access' to server -resources on behalf of a resource owner. In fact, OAuth allows an authorization -server to issue access tokens to third-party clients with the approval of the -resource owner, or the end-user. +[OAuth 2](https://oauth.net/2/) provides to client applications a 'secure delegated +access' to server resources on behalf of a resource owner. OAuth 2 allows +authorization servers to issue access tokens to third-party clients with the approval +of the resource owner or the end-user. -OAuth is mostly used as a Single Sign-On service (SSO), but you can find a -lot of different uses for this functionality. For example, you can allow users -to sign in to your application with their GitLab.com account, or GitLab.com -can be used for authentication to your GitLab instance +OAuth 2 can be used: + +- To allow users to sign in to your application with their GitLab.com account. +- To set up GitLab.com for authentication to your GitLab instance. (see [GitLab OmniAuth](gitlab.md)). -The 'GitLab Importer' feature is also using the OAuth protocol to give access +The 'GitLab Importer' feature also uses OAuth 2 to give access to repositories without sharing user credentials to your GitLab.com account. -GitLab supports two ways of adding a new OAuth2 application to an instance. You -can either add an application as a regular user or add it in the Admin Area. -What this means is that GitLab can actually have instance-wide and a user-wide -applications. There is no difference between them except for the different -permission levels they are set (user/admin). The default callback URL is -`http://your-gitlab.example.com/users/auth/gitlab/callback` +GitLab supports two ways of adding a new OAuth 2 application to an instance: -## Adding an application through the profile +- As a regular user, for applications owned by an individual. +- Through the Admin Area menu for instance-wide apps. -In order to add a new application via your profile, navigate to -**Profile Settings > Applications** and select **New Application**. +The only difference between these two methods is the [permission](../user/permissions.md) +levels. The default callback URL is `http://your-gitlab.example.com/users/auth/gitlab/callback`. - +## Add an application through the profile -In the application form, enter a **Name** (arbitrary), and make sure to set up -correctly the **Redirect URI** which is the URL where users are sent after -they authorize with GitLab. +To add a new application via your profile, select your avatar in the top right, and then select +**Settings > Applications**. You can then enter a **Name**, **Redirect URI** and +OAuth 2 scopes as defined in [Authorized Applications](#authorized-applications). - +- The **Redirect URI** is the URL where users are sent after they authorize with GitLab. -When you click **Submit** you are provided with the application ID and -the application secret which you can then use with your application that -connects to GitLab. +When you select **Save application**, GitLab displays: - +- Application ID: OAuth 2 Client ID. +- Secret: OAuth 2 Client Secret. ## OAuth applications in the Admin Area -To create an application that does not belong to a certain user, you can create -it from the Admin Area. - - +To create an application for your GitLab instance, select +**Admin Area > Applications > New application**. -You're also able to mark an application as _trusted_ when creating it through the Admin Area. By doing that, -the user authorization step is automatically skipped for this application. +When creating an **Admin Area** application, you can mark it as _trusted_. +The user authorization step is automatically skipped for this application. ## Authorized applications -Every application you authorized to use your GitLab credentials is shown -in the **Authorized applications** section under **Profile Settings > Applications**. - - - -The GitLab OAuth applications support scopes, which allow various actions that any given -application can perform such as `read_user` and `api`. There are many more scopes -available. - -At any time you can revoke any access by just clicking **Revoke**. +Every application you authorize with your GitLab credentials is shown +in the **Authorized applications** section under **Settings > Applications**. + +The GitLab OAuth 2 applications support scopes, which allow various actions that any given +application can perform. Available scopes are depicted in the following table. + +| Scope | Description | +| ------------------ | ----------- | +| `api` | Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry. | +| `read_user` | Grants read-only access to the authenticated user's profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users. | +| `read_api` | Grants read access to the API, including all groups and projects, the container registry, and the package registry. | +| `read_repository` | Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API. | +| `write_repository` | Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API). | +| `read_registry` | Grants read-only access to container registry images on private projects. | +| `write_registry` | Grants read-only access to container registry images on private projects. | +| `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator user. | +| `openid` | Grants permission to authenticate with GitLab using [OpenID Connect](openid_connect_provider.md). Also gives read-only access to the user's profile and group memberships. | +| `profile` | Grants read-only access to the user's profile data using [OpenID Connect](openid_connect_provider.md). | +| `email` | Grants read-only access to the user's primary email address using [OpenID Connect](openid_connect_provider.md). | + +At any time you can revoke any access by clicking **Revoke**. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 53c19ddfdb1..54fa5b0a732 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -55,7 +55,7 @@ earlier version, you must explicitly enable it. - `allow_single_sign_on` allows you to specify the providers you want to allow to automatically create an account. It defaults to `false`. If `false` users must - be created manually or they can't sign in via OmniAuth. + be created manually or they can't sign in by using OmniAuth. - `auto_link_ldap_user` can be used if you have [LDAP / ActiveDirectory](../administration/auth/ldap/index.md) integration enabled. It defaults to `false`. When enabled, users automatically created through an OmniAuth provider have their LDAP identity created in GitLab as well. @@ -66,7 +66,7 @@ earlier version, you must explicitly enable it. NOTE: If you set `block_auto_created_users` to `false`, make sure to only define providers under `allow_single_sign_on` that you are able to control, like -SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on +SAML, Shibboleth, Crowd, or Google. Otherwise, set it to `false`, or any user on the Internet can successfully sign in to your GitLab without administrative approval. @@ -168,10 +168,8 @@ omniauth: ## Configure OmniAuth Providers as External -> Introduced in GitLab 8.7. - -You can define which OmniAuth providers you want to be `external` so that all users -**creating accounts, or logging in via these providers** can't have +You can define which OmniAuth providers you want to be `external`. Users +creating accounts, or logging in by using these `external` providers cannot have access to internal projects. You must use the full name of the provider, like `google_oauth2` for Google. Refer to the examples for the full names of the supported providers. @@ -200,9 +198,9 @@ NOTE: The following information only applies for installations from source. GitLab uses [OmniAuth](https://github.com/omniauth/omniauth) for authentication and already ships -with a few providers pre-installed (e.g. LDAP, GitHub, Twitter). But sometimes that -is not enough and you need to integrate with other authentication solutions. For -these cases you can use the OmniAuth provider. +with a few providers pre-installed, such as LDAP, GitHub, and Twitter. You may also +need to integrate with other authentication solutions. For +these cases, you can use the OmniAuth provider. ### Steps @@ -215,7 +213,7 @@ from the OmniAuth provider's documentation. sudo service gitlab stop ``` -- Add the gem to your [Gemfile](https://gitlab.com/gitlab-org/gitlab/blob/master/Gemfile): +- Add the gem to your [`Gemfile`](https://gitlab.com/gitlab-org/gitlab/blob/master/Gemfile): ```shell gem "omniauth-your-auth-provider" @@ -240,25 +238,28 @@ from the OmniAuth provider's documentation. If you have successfully set up a provider that is not shipped with GitLab itself, please let us know. +Share your experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations). You can help others by reporting successful configurations and probably share a -few insights or provide warnings for common errors or pitfalls by sharing your -experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations). +few insights or provide warnings for common errors or pitfalls. While we can't officially support every possible authentication mechanism out there, we'd like to at least help those with specific needs. ## Enable or disable Sign In with an OmniAuth provider without disabling import sources -> Introduced in GitLab 8.8. - -Administrators are able to enable or disable Sign In via some OmniAuth providers. +Administrators are able to enable or disable **Sign In** by using some OmniAuth providers. NOTE: -By default Sign In is enabled via all the OAuth Providers that have been configured in `config/gitlab.yml`. +By default, **Sign In** is enabled by using all the OAuth Providers that have been configured in `config/gitlab.yml`. + +To enable/disable an OmniAuth provider: -In order to enable/disable an OmniAuth provider, go to Admin Area -> Settings -> Sign-in Restrictions section -> Enabled OAuth Sign-In sources and select the providers you want to enable or disable. +1. In the top navigation bar, go to **Admin Area**. +1. In the left sidebar, go to **Settings**. +1. Scroll to the **Sign-in Restrictions** section, and click **Expand**. +1. Next to **Enabled OAuth Sign-In sources**, select the check box for each provider you want to enable or disable. - +  ## Disabling OmniAuth @@ -325,7 +326,7 @@ omniauth: You can add the `auto_sign_in_with_provider` setting to your GitLab configuration to redirect login requests to your OmniAuth provider for -authentication, removing the need to click a button before actually signing in. +authentication. This removes the need to click a button before actually signing in. For example, when using the Azure integration, set the following to enable auto sign-in: @@ -345,7 +346,7 @@ omniauth: Keep in mind that every sign-in attempt is redirected to the OmniAuth provider; you can't sign in using local credentials. Ensure at least -one of the OmniAuth users has admin permissions. +one of the OmniAuth users has administrator permissions. You may also bypass the auto sign in feature by browsing to `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index 5bf079df800..4455ace3e1f 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -12,11 +12,12 @@ to sign in to other services. ## Introduction to OpenID Connect [OpenID Connect](https://openid.net/connect/) \(OIDC) is a simple identity layer on top of the -OAuth 2.0 protocol. It allows clients to verify the identity of the end-user -based on the authentication performed by GitLab, as well as to obtain -basic profile information about the end-user in an interoperable and -REST-like manner. OIDC performs many of the same tasks as OpenID 2.0, -but does so in a way that is API-friendly, and usable by native and +OAuth 2.0 protocol. It allows clients to: + +- Verify the identity of the end-user based on the authentication performed by GitLab. +- Obtain basic profile information about the end-user in an interoperable and REST-like manner. + +OIDC performs many of the same tasks as OpenID 2.0, but is API-friendly and usable by native and mobile applications. On the client side, you can use [OmniAuth::OpenIDConnect](https://github.com/jjbohn/omniauth-openid-connect/) for Rails @@ -34,7 +35,7 @@ is select the `openid` scope in the application settings. ## Shared information -Currently the following user information is shared with clients: +The following user information is shared with clients: | Claim | Type | Description | |:-----------------|:----------|:------------| diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index bb5425187c1..8f090dfc588 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -14,7 +14,7 @@ to confirm that a real user, not a bot, is attempting to create an account. To use reCAPTCHA, first you must create a site and private key. -1. Go to the URL: <https://www.google.com/recaptcha/admin>. +1. Go to the [Google reCAPTCHA page](https://www.google.com/recaptcha/admin). 1. Fill out the form necessary to obtain reCAPTCHA v2 keys. 1. Log in to your GitLab server, with administrator credentials. 1. Go to Reporting Applications Settings in the Admin Area (`admin/application_settings/reporting`). @@ -26,7 +26,7 @@ To use reCAPTCHA, first you must create a site and private key. return `recaptcha_html`. NOTE: -Make sure you are viewing an issuable in a project that is public, and if you're working with an issue, the issue is public. +Make sure you are viewing an issuable in a project that is public. If you're working with an issue, the issue is public. ## Enabling reCAPTCHA for user logins via passwords diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 1aca3b04eee..156109518a6 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -86,4 +86,6 @@ Click the icon to begin the authentication process. Salesforce asks the user to If everything goes well, the user is returned to GitLab and is signed in. NOTE: -GitLab requires the email address of each new user. Once the user is logged in using Salesforce, GitLab redirects the user to the profile page where they must provide the email and verify the email. +GitLab requires the email address of each new user. After the user is signed in +using Salesforce, GitLab redirects the user to the profile page where they must +provide the email and verify the email. diff --git a/doc/integration/saml.md b/doc/integration/saml.md index af0a58eab59..9b6ad3f2755 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -5,7 +5,7 @@ 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/#assignments --- -# SAML OmniAuth Provider **(CORE ONLY)** +# SAML OmniAuth Provider **(FREE SELF)** This page describes instance-wide SAML for self-managed GitLab instances. For SAML on GitLab.com, see [SAML SSO for GitLab.com groups](../user/group/saml_sso/index.md). @@ -17,7 +17,7 @@ You should also reference the [OmniAuth documentation](omniauth.md) for general |------|-------------| | Identity Provider (IdP) | The service which manages your user identities such as ADFS, Okta, Onelogin, or Ping Identity. | | Service Provider (SP) | SAML considers GitLab to be a service provider. | -| Assertion | A piece of information about a user's identity, such as their name or role. Also know as claims or attributes. | +| Assertion | A piece of information about a user's identity, such as their name or role. Also known as claims or attributes. | | SSO | Single Sign-On. | | Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. | | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | @@ -163,9 +163,21 @@ will be returned to GitLab and will be signed in. ## SAML Groups -You can require users to be members of a certain group, or assign users `external`, `admin` or `auditor` roles based on group membership. This feature **does not** allow you to +You can require users to be members of a certain group, or assign users [external](../user/permissions.md#external-users), admin or [auditor](../user/permissions.md#auditor-users) roles based on group membership. +These groups are checked on each SAML login and user attributes updated as necessary. +This feature **does not** allow you to automatically add users to GitLab [Groups](../user/group/index.md). +Support for these groups depends on your [subscription](https://about.gitlab.com/pricing/) +and whether you've installed [GitLab Enterprise Edition (EE)](https://about.gitlab.com/install/). + +| Group | Tier | GitLab Enterprise Edition (EE) Only? | +|------------------------------|--------------------|--------------------------------------| +| [Required](#required-groups) | **(FREE SELF)** | Yes | +| [External](#external-groups) | **(FREE SELF)** | No | +| [Admin](#admin-groups) | **(FREE SELF)** | Yes | +| [Auditor](#auditor-groups) | **(PREMIUM SELF)** | Yes | + ### Requirements First you need to tell GitLab where to look for group information. For this you @@ -187,7 +199,7 @@ The name of the attribute can be anything you like, but it must contain the grou to which a user belongs. In order to tell GitLab where to find these groups, you need to add a `groups_attribute:` element to your SAML settings. -### Required groups **(STARTER ONLY)** +### Required groups **(FREE SELF)** Your IdP passes Group Information to the SP (GitLab) in the SAML Response. You need to configure GitLab to identify: @@ -213,9 +225,9 @@ Example: } } ``` -### External Groups **(STARTER ONLY)** +### External groups **(FREE SELF)** -SAML login supports automatic identification on whether a user should be considered an [external](../user/permissions.md) user. This is based on the user's group membership in the SAML identity provider. +SAML login supports automatic identification on whether a user should be considered an [external user](../user/permissions.md#external-users). This is based on the user's group membership in the SAML identity provider. ```yaml { name: 'saml', @@ -231,7 +243,7 @@ SAML login supports automatic identification on whether a user should be conside } } ``` -### Admin Groups **(STARTER ONLY)** +### Admin groups **(FREE SELF)** The requirements are the same as the previous settings, your IdP needs to pass Group information to GitLab, you need to tell GitLab where to look for the groups in the SAML response, and which group(s) should be @@ -251,13 +263,13 @@ considered admin users. } } ``` -### Auditor Groups **(STARTER ONLY)** +### Auditor groups **(PREMIUM SELF)** > Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 11.4. The requirements are the same as the previous settings, your IdP needs to pass Group information to GitLab, you need to tell GitLab where to look for the groups in the SAML response, and which group(s) should be -considered auditor users. +considered [auditor users](../user/permissions.md#auditor-users). ```yaml { name: 'saml', @@ -385,7 +397,7 @@ This setting should be used only to map attributes that are part of the OmniAuth `attribute_statements` is used to map Attribute Names in a SAMLResponse to entries in the OmniAuth [`info` hash](https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema#schema-10-and-later). -For example, if your SAMLResponse contains an Attribute called 'EmailAddress', +For example, if your SAMLResponse contains an Attribute called `EmailAddress`, specify `{ email: ['EmailAddress'] }` to map the Attribute to the corresponding key in the `info` hash. URI-named Attributes are also supported, e.g. `{ email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }`. @@ -582,8 +594,8 @@ GitLab will sign the request with the provided private key. GitLab will include Avoid user control of the following attributes: -- [`*NameID*`](../user/group/saml_sso/index.md#nameid) -- *Email* when used with `omniauth_auto_link_saml_user` +- [`NameID`](../user/group/saml_sso/index.md#nameid) +- `Email` when used with `omniauth_auto_link_saml_user` These attributes define the SAML user. If users can change these attributes, they can impersonate others. @@ -593,7 +605,7 @@ Refer to the documentation for your SAML Identity Provider for information on ho The [Generated passwords for users created through integrated authentication](../security/passwords_for_integrated_authentication_methods.md) guide provides an overview of how GitLab generates and sets passwords for users created via SAML. -## Configuring Group SAML on a self-managed GitLab instance **(PREMIUM ONLY)** +## Configuring Group SAML on a self-managed GitLab instance **(PREMIUM SELF)** For information on the GitLab.com implementation, please see the [SAML SSO for GitLab.com groups page](../user/group/saml_sso). diff --git a/doc/integration/security_partners/index.md b/doc/integration/security_partners/index.md new file mode 100644 index 00000000000..1053c612782 --- /dev/null +++ b/doc/integration/security_partners/index.md @@ -0,0 +1,17 @@ +--- +stage: Protect +group: Container Security +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: index +--- + +# Security partner integrations + +You can integrate GitLab with its security partners. This page has information on how do this with +each security partner: + +<!-- vale gitlab.Spelling = NO --> + +- [Anchore](https://docs.anchore.com/current/docs/using/integration/ci_cd/gitlab/) + +<!-- vale gitlab.Spelling = YES --> diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index e811cac4f0b..3b92f2858ac 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -10,17 +10,17 @@ NOTE: The preferred approach for integrating a Shibboleth authentication system with GitLab 10 or newer is to use the [GitLab SAML integration](saml.md). This documentation is for Omnibus GitLab 9.x installs or older. -In order to enable Shibboleth support in GitLab we need to use Apache instead of NGINX (It may be possible to use NGINX, however this is difficult to configure using the bundled NGINX provided in the Omnibus GitLab package). Apache uses mod_shib2 module for Shibboleth authentication and can pass attributes as headers to OmniAuth Shibboleth provider. +To enable Shibboleth support in GitLab we need to use Apache instead of NGINX. (It may be possible to use NGINX, however this is difficult to configure using the bundled NGINX provided in the Omnibus GitLab package.) Apache uses `mod_shib2` module for Shibboleth authentication and can pass attributes as headers to OmniAuth Shibboleth provider. To enable the Shibboleth OmniAuth provider you must configure Apache Shibboleth module. The installation and configuration of the module itself is out of the scope of this document. -Check <https://wiki.shibboleth.net/confluence/display/SP3/Apache> for more information. +Check [the Shibboleth documentation](https://wiki.shibboleth.net/confluence/display/SP3/Apache) for more information. You can find Apache configuration in [GitLab Recipes](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache). The following changes are needed to enable Shibboleth: -1. Protect OmniAuth Shibboleth callback URL: +1. Protect the OmniAuth Shibboleth callback URL: ```apache <Location /users/auth/shibboleth/callback> @@ -53,7 +53,7 @@ The following changes are needed to enable Shibboleth: ``` NOTE: - Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an + In GitLab versions 11.4 and later, OmniAuth is enabled by default. If you're using an earlier version, you must explicitly enable it in `/etc/gitlab/gitlab.rb`. 1. In addition, add Shibboleth to `/etc/gitlab/gitlab.rb` as an OmniAuth provider. @@ -100,7 +100,7 @@ The following changes are needed to enable Shibboleth: 1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab 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 a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You are redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user is returned to GitLab and is signed in. +On the sign in page, there should now be a **Sign in with: Shibboleth** icon below the regular sign in form. Click the icon to begin the authentication process. You are redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user is returned to GitLab and is signed in. ## Apache 2.4 / GitLab 8.6 update diff --git a/doc/integration/slack.md b/doc/integration/slack.md deleted file mode 100644 index fbea9d3035c..00000000000 --- a/doc/integration/slack.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/project/integrations/slack.md' ---- - -This document was moved to [another location](../user/project/integrations/slack.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index 6820ff8a0aa..80be6daa3a8 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Slash Commands -> The `run` command was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to GitLab Free in 11.9. -Slash commands in Mattermost and Slack allow you to control GitLab and view GitLab content right inside your chat client, without having to leave it. For Slack, this requires an [integration configuration](../user/project/integrations/slack_slash_commands.md). Simply type the command as a message in your chat client to activate it. +Slash commands in Mattermost and Slack allow you to control GitLab and view GitLab content right inside your chat client, without having to leave it. For Slack, this requires an [integration configuration](../user/project/integrations/slack_slash_commands.md). Type the command as a message in your chat client to activate it. Commands are scoped to a project, with a trigger term that is specified during configuration. @@ -28,20 +28,20 @@ Taking the trigger term as `project-name`, the commands are: | `/project-name deploy <from> to <to>` | Deploy from the `<from>` environment to the `<to>` environment | | `/project-name run <job name> <arguments>` | Execute [ChatOps](../ci/chatops/README.md) job `<job name>` on `master` | -Note that if you are using the [GitLab Slack application](../user/project/integrations/gitlab_slack_application.md) for -your GitLab.com projects, you need to [add the `gitlab` keyword at the beginning of the command](../user/project/integrations/gitlab_slack_application.md#usage). +If you are using the [GitLab Slack application](../user/project/integrations/gitlab_slack_application.md) for +your GitLab.com projects, [add the `gitlab` keyword at the beginning of the command](../user/project/integrations/gitlab_slack_application.md#usage). ## Issue commands -It is possible to create new issue, display issue details and search up to 5 issues. +It's possible to create new issue, display issue details and search up to 5 issues. ## Deploy command -In order to deploy to an environment, GitLab tries to find a deployment +To deploy to an environment, GitLab tries to find a deployment manual action in the pipeline. -If there is only one action for a given environment, it is triggered. -If there is more than one action defined, GitLab tries to find an action +If there's only one action for a given environment, it is triggered. +If more than one action is defined, GitLab tries to find an action which name equals the environment name we want to deploy to. The command returns an error when no matching action has been found. diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 8e1a6cdcfd1..aff0bb2f841 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -23,9 +23,9 @@ NOTE: This feature requires user opt-in. After Sourcegraph has been enabled for your GitLab instance, you can choose to enable Sourcegraph [through your user preferences](#enable-sourcegraph-in-user-preferences). -## Set up for self-managed GitLab instances **(CORE ONLY)** +## Set up for self-managed GitLab instances **(FREE SELF)** -Before you can enable Sourcegraph code intelligence in GitLab you will need to: +Before you can enable Sourcegraph code intelligence in GitLab you must: - Enable the `sourcegraph` feature flag for your GitLab instance. - Configure a Sourcegraph instance with your GitLab instance as an external service. @@ -33,7 +33,7 @@ Before you can enable Sourcegraph code intelligence in GitLab you will need to: ### Enable the Sourcegraph feature flag NOTE: -If you are running a self-managed instance, the Sourcegraph integration will not be available +If you are running a self-managed instance, the Sourcegraph integration is unavailable unless the feature flag `sourcegraph` is enabled. This can be done from the Rails console by instance administrators. @@ -64,7 +64,7 @@ Feature.enable(:sourcegraph, Project.find_by_full_path('my_group/my_project')) If you are new to Sourcegraph, head over to the [Sourcegraph installation documentation](https://docs.sourcegraph.com/admin) and get your instance up and running. -If you are using an HTTPS connection to GitLab, you will need to [configure HTTPS](https://docs.sourcegraph.com/admin/http_https_configuration) for your Sourcegraph instance. +If you are using an HTTPS connection to GitLab, you must [configure HTTPS](https://docs.sourcegraph.com/admin/http_https_configuration) for your Sourcegraph instance. ### Connect your Sourcegraph instance to your GitLab instance @@ -79,9 +79,9 @@ You can skip this step if you already have your GitLab repositories searchable i 1. In GitLab, go to **Admin Area > Settings > General**. 1. Expand the **Sourcegraph** configuration section. 1. Check **Enable Sourcegraph**. -1. Set the Sourcegraph URL to your Sourcegraph instance, e.g., `https://sourcegraph.example.com`. +1. Set the Sourcegraph URL to your Sourcegraph instance, such as `https://sourcegraph.example.com`. - + ## Enable Sourcegraph in user preferences @@ -95,7 +95,7 @@ If a GitLab administrator has enabled Sourcegraph, you can enable this feature i ## Using Sourcegraph code intelligence -Once enabled, participating projects will have a code intelligence popover available in +Once enabled, participating projects display a code intelligence popover available in the following code views: - Merge request diffs @@ -114,7 +114,7 @@ When visiting one of these views, you can now hover over a code reference to see Sourcegraph powered code intelligence is available for all public projects on GitLab.com. -Support for private projects is currently not available for GitLab.com; +Support for private projects is not yet available for GitLab.com; follow the epic [&2201](https://gitlab.com/groups/gitlab-org/-/epics/2201) for updates. @@ -122,7 +122,7 @@ for updates. ### Sourcegraph isn't working -If you enabled Sourcegraph for your project but still it doesn't look like it's working, it might be because Sourcegraph has not indexed the project yet. You can check for Sourcegraph's availability of your project by visiting `https://sourcegraph.com/gitlab.com/<project-path>`replacing `<project-path>` with the path to your GitLab project. +If you enabled Sourcegraph for your project but it isn't working, Sourcegraph may not have indexed the project yet. You can check for Sourcegraph's availability of your project by visiting `https://sourcegraph.com/gitlab.com/<project-path>`replacing `<project-path>` with the path to your GitLab project. ## Sourcegraph and Privacy @@ -130,5 +130,5 @@ From Sourcegraph's [extension documentation](https://docs.sourcegraph.com/integr engine behind the native GitLab integration: > Sourcegraph integrations never send any logs, pings, usage statistics, or telemetry to Sourcegraph.com. -> They will only connect to Sourcegraph.com as required to provide code intelligence or other functionality on public code. +> They connect only to Sourcegraph.com as required to provide code intelligence or other functionality on public code. > As a result, no private code, private repository names, usernames, or any other specific data is sent to Sourcegraph.com. diff --git a/doc/integration/vault.md b/doc/integration/vault.md index 3c49cd47509..d3102c2616a 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -44,7 +44,7 @@ The following assumes you already have Vault installed and running. Success! Enabled oidc auth method at: oidc/ ``` -1. **Write the OIDC config:** +1. **Write the OIDC configuration:** Next, Vault needs to be given the application ID and secret generated by GitLab. @@ -67,7 +67,7 @@ The following assumes you already have Vault installed and running. Success! Data written to: auth/oidc/config ``` -1. **Write the OIDC Role Config:** +1. **Write the OIDC Role Configuration:** Now that Vault has a GitLab application ID and secret, it needs to know the [**Redirect URIs**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris) and scopes given to GitLab during the application creation process. The redirect URIs need to match where your Vault instance is running. The `oidc_scopes` field needs to include the `openid`. Similarly to the previous step, replace `your_application_id` with the generated application ID from GitLab: @@ -108,7 +108,7 @@ The following assumes you already have Vault installed and running. Here's a short explanation of what this command does: - 1. In the **Write the OIDC Role Config** (step 4), we created a role called + 1. In the **Write the OIDC Role Configuration** (step 4), we created a role called `demo`. We set `role=demo` so Vault knows which configuration we'd like to sign in with. 1. To set Vault to use the `OIDC` sign-in method, we set `-method=oidc`. diff --git a/doc/license/README.md b/doc/license/README.md deleted file mode 100644 index f0ff27c315e..00000000000 --- a/doc/license/README.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/admin_area/license.md' ---- - -This document was moved to [another location](../user/admin_area/license.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/markdown/markdown.md b/doc/markdown/markdown.md deleted file mode 100644 index e68f9c217d5..00000000000 --- a/doc/markdown/markdown.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/markdown.md' ---- - -This document was moved to [another location](../user/markdown.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/monitoring/health_check.md b/doc/monitoring/health_check.md deleted file mode 100644 index d607ea03d5a..00000000000 --- a/doc/monitoring/health_check.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/admin_area/monitoring/health_check.md' ---- - -This document was moved to [user/admin_area/monitoring/health_check](../user/admin_area/monitoring/health_check.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/monitoring/performance/gitlab_configuration.md b/doc/monitoring/performance/gitlab_configuration.md deleted file mode 100644 index 6a6f297f674..00000000000 --- a/doc/monitoring/performance/gitlab_configuration.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../administration/monitoring/performance/gitlab_configuration.md' ---- - -This document was moved to [administration/monitoring/performance/gitlab_configuration](../../administration/monitoring/performance/gitlab_configuration.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/monitoring/performance/grafana_configuration.md b/doc/monitoring/performance/grafana_configuration.md deleted file mode 100644 index 98dfe51ae04..00000000000 --- a/doc/monitoring/performance/grafana_configuration.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../administration/monitoring/performance/grafana_configuration.md' ---- - -This document was moved to [administration/monitoring/performance/grafana_configuration](../../administration/monitoring/performance/grafana_configuration.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/monitoring/performance/influxdb_configuration.md b/doc/monitoring/performance/influxdb_configuration.md deleted file mode 100644 index 0bcb18bdfe7..00000000000 --- a/doc/monitoring/performance/influxdb_configuration.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../../administration/monitoring/performance/prometheus.md' ---- - -Support for InfluxDB was removed in GitLab 13.0. Use [Prometheus](../../administration/monitoring/performance/prometheus.md) for performance monitoring. diff --git a/doc/monitoring/performance/influxdb_schema.md b/doc/monitoring/performance/influxdb_schema.md deleted file mode 100644 index 0bcb18bdfe7..00000000000 --- a/doc/monitoring/performance/influxdb_schema.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../../administration/monitoring/performance/prometheus.md' ---- - -Support for InfluxDB was removed in GitLab 13.0. Use [Prometheus](../../administration/monitoring/performance/prometheus.md) for performance monitoring. diff --git a/doc/monitoring/performance/introduction.md b/doc/monitoring/performance/introduction.md deleted file mode 100644 index 71ecd24c743..00000000000 --- a/doc/monitoring/performance/introduction.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../administration/monitoring/performance/index.md' ---- - -This document was moved to [administration/monitoring/performance/introduction](../../administration/monitoring/performance/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/cleaning_up_redis_sessions.md b/doc/operations/cleaning_up_redis_sessions.md deleted file mode 100644 index 96f72099f8f..00000000000 --- a/doc/operations/cleaning_up_redis_sessions.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../administration/operations/cleaning_up_redis_sessions.md' ---- - -This document was moved to [another location](../administration/operations/cleaning_up_redis_sessions.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index 6fa67c375c9..8bf0e56c989 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Error Tracking +# Error Tracking **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/169) in GitLab 11.8. diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md index 9ce7eb0ede2..836631369bb 100644 --- a/doc/operations/feature_flags.md +++ b/doc/operations/feature_flags.md @@ -4,11 +4,10 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Feature Flags **(CORE)** +# Feature Flags **(FREE)** > - [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. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to GitLab Free in 13.5. 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. @@ -61,14 +60,13 @@ next to any feature flag in the list. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254379) in GitLab 13.5. The maximum number of feature flags per project on self-managed GitLab instances -is 200. On GitLab.com, the maximum number is determined by [GitLab.com tier](https://about.gitlab.com/pricing/): +is 200. For GitLab SaaS, the maximum number is determined by [tier](https://about.gitlab.com/pricing/): | Tier | Number of feature flags per project | |----------|-------------------------------------| | Free | 50 | -| Bronze | 100 | -| Silver | 150 | -| Gold | 200 | +| Premium | 150 | +| Ultimate | 200 | ## Feature flag strategies diff --git a/doc/operations/incident_management/alert_details.md b/doc/operations/incident_management/alert_details.md deleted file mode 100644 index cd73e9e7e1f..00000000000 --- a/doc/operations/incident_management/alert_details.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: alerts.md ---- - -This document was moved to [another location](alerts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/incident_management/alert_integrations.md b/doc/operations/incident_management/alert_integrations.md index 0f695e7a6c9..bec0653d464 100644 --- a/doc/operations/incident_management/alert_integrations.md +++ b/doc/operations/incident_management/alert_integrations.md @@ -1,199 +1,8 @@ --- -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/#assignments +redirect_to: 'integrations.md' --- -# Alert integrations +This document was moved to [another location](integrations.md). -> - [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 webhook receiver. This can be configured -generically or, in GitLab versions 13.1 and greater, you can configure -[External Prometheus instances](../metrics/alerts.md#external-prometheus-instances) -to use this endpoint. - -## Integrations list - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/245331) in [GitLab Core](https://about.gitlab.com/pricing/) 13.5. - -With Maintainer or higher [permissions](../../user/permissions.md), you can view -the list of configured alerts integrations by navigating to -**Settings > Operations** in your project's sidebar menu, and expanding **Alerts** section. -The list displays the integration name, type, and status (enabled or disabled): - - - -## Configuration - -GitLab can receive alerts via a HTTP endpoint that you configure, -or the [Prometheus integration](#external-prometheus-integration). - -### Single HTTP Endpoint **CORE** - -Enabling the HTTP Endpoint in a GitLab projects activates it to -receive alert payloads in JSON format. You can always -[customize the payload](#customize-the-alert-payload-outside-of-gitlab) to your liking. - -1. Sign in to GitLab as a user with maintainer [permissions](../../user/permissions.md) - for a project. -1. Navigate to **Settings > Operations** in your project. -1. Expand the **Alerts** section, and in the **Integration** dropdown menu, select **Generic**. -1. Toggle the **Active** alert setting to display the **URL** and **Authorization Key** - for the webhook configuration. - -### HTTP Endpoints **PREMIUM** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4442) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. - -In [GitLab Premium](https://about.gitlab.com/pricing/), you can create multiple -unique HTTP endpoints to receive alerts from any external source in JSON format, -and you can [customize the payload](#customize-the-alert-payload-outside-of-gitlab). - -1. Sign in to GitLab as a user with maintainer [permissions](../../user/permissions.md) - for a project. -1. Navigate to **Settings > Operations** in your project. -1. Expand the **Alerts** section. -1. For each endpoint you want to create: - - 1. In the **Integration** dropdown menu, select **HTTP Endpoint**. - 1. Name the integration. - 1. Toggle the **Active** alert setting to display the **URL** and **Authorization Key** - for the webhook configuration. You must also input the URL and Authorization Key - in your external service. - 1. _(Optional)_ To generate a test alert to test the new integration, enter a - sample payload, then click **Save and test alert payload**. Valid JSON is required. - 1. Click **Save Integration**. - -The new HTTP Endpoint displays in the [integrations list](#integrations-list). -You can edit the integration by selecting the **{pencil}** pencil icon on the right -side of the integrations list. - -### External Prometheus integration - -For GitLab versions 13.1 and greater, please read -[External Prometheus Instances](../metrics/alerts.md#external-prometheus-instances) -to configure alerts for this integration. - -## Customize the alert payload outside of GitLab - -For all integration types, you can customize the payload by sending the following -parameters. All fields are optional. If the incoming alert does not contain a value for the `Title` field, a default value of `New: Incident` will be applied. - -| Property | Type | Description | -| ------------------------- | --------------- | ----------- | -| `title` | String | The title of the incident. | -| `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 is 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 aren't limited to primitive types (such as strings or numbers), but -can be a nested JSON object. For example: - -```json -{ "foo": { "bar": { "baz": 42 } } } -``` - -NOTE: -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 configuring an alert integration. - -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](../../user/permissions.md) -configures an integration, 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`, GitLab creates a new alert instead. - - - -## Link to your Opsgenie Alerts - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. - -WARNING: -We are building deeper integration with Opsgenie and other alerting tools through -[HTTP endpoint integrations](#single-http-endpoint) so you can see alerts in -the GitLab interface. As a result, the previous direct link to Opsgenie Alerts from -the GitLab alerts list is deprecated in -GitLab versions [13.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/273657). - -You can monitor alerts using a GitLab integration with [Opsgenie](https://www.atlassian.com/software/opsgenie). - -If you enable the Opsgenie integration, you can't have other GitLab alert -services -active at the same time. - -To enable Opsgenie integration: - -1. Sign in as a user with Maintainer or Owner [permissions](../../user/permissions.md). -1. Navigate to **Operations > Alerts**. -1. In the **Integrations** select box, select **Opsgenie**. -1. Select the **Active** toggle. -1. In the **API URL** field, enter the base URL for your Opsgenie integration, - such as `https://app.opsgenie.com/alert/list`. -1. Select **Save changes**. - -After you enable the integration, navigate to the Alerts list page at -**Operations > Alerts**, and then select **View alerts in Opsgenie**. +<!-- This redirect file can be deleted after <2021-05-03>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/incident_management/alert_notifications.md b/doc/operations/incident_management/alert_notifications.md index eaf606105d6..4f46c2bec71 100644 --- a/doc/operations/incident_management/alert_notifications.md +++ b/doc/operations/incident_management/alert_notifications.md @@ -1,36 +1,8 @@ --- -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/#assignments +redirect_to: 'paging.md' --- -# Paging and notifications +This document was moved to [another location](paging.md). -When there is a new alert or incident, it is important for a responder to be notified -immediately so they can triage and respond to the problem. Responders can receive -notifications using the methods described on this page. - -## Slack notifications - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216326) in GitLab 13.1. - -Responders can be paged via Slack using the -[Slack Notifications Service](../../user/project/integrations/slack.md), which you -can configure for new alerts and new incidents. After configuring, responders -receive a **single** page via Slack. To set up Slack notifications on your mobile -device, make sure to enable notifications for the Slack app on your phone so -you never miss a page. - -## Email notifications - -Email notifications are available in projects that have been -[configured to create incidents automatically](incidents.md#create-incidents-automatically) -for triggered alerts. Project members with the **Owner** or **Maintainer** roles are -sent an email notification automatically. (This is not configurable.) To optionally -send additional email notifications to project members with the **Developer** role: - -1. Navigate to **Settings > Operations**. -1. Expand the **Incidents** section. -1. In the **Alert Integration** tab, select the **Send a separate email notification to Developers** - check box. -1. Select **Save changes**. +<!-- This redirect file can be deleted after 2021-04-21 --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index a8852a02f2b..3c60c737309 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Alerts +# Alerts **(FREE)** Alerts are a critical entity in your incident management workflow. They represent a notable event that might indicate a service outage or disruption. GitLab provides a list view for triage and detail view for deeper investigation of what happened. @@ -102,8 +102,9 @@ To view the metrics for an alert: #### View an alert's logs -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201846) in GitLab Ultimate 12.8. and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25455) to [GitLab Core](https://about.gitlab.com/pricing/) 12.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201846) in GitLab Ultimate 12.8. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25455) to GitLab Free 12.9. Viewing logs from a metrics panel can be useful if you're triaging an application incident and need to [explore logs](../metrics/dashboards/index.md#chart-context-menu) @@ -196,9 +197,9 @@ add a to-do item: 1. To display the list of current alerts, navigate to **Operations > Alerts**. 1. Select your desired alert to display its **Alert Management Details View**. -1. Select the **Add a To-Do** button in the right sidebar: +1. Select the **Add a to do** button in the right sidebar: -  +  Select the **To-Do List** **{todo-done}** in the navigation bar to view your current to-do list. diff --git a/doc/operations/incident_management/generic_alerts.md b/doc/operations/incident_management/generic_alerts.md deleted file mode 100644 index 44b1f4b088a..00000000000 --- a/doc/operations/incident_management/generic_alerts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: alert_integrations.md ---- - -This document was moved to [another location](alert_integrations.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/incident_management/img/alert_detail_add_todo_v13_1.png b/doc/operations/incident_management/img/alert_detail_add_todo_v13_1.png Binary files differdeleted file mode 100644 index 39aa9e33728..00000000000 --- a/doc/operations/incident_management/img/alert_detail_add_todo_v13_1.png +++ /dev/null diff --git a/doc/operations/incident_management/img/alert_detail_add_todo_v13_9.png b/doc/operations/incident_management/img/alert_detail_add_todo_v13_9.png Binary files differnew file mode 100644 index 00000000000..5beb1cd0bfb --- /dev/null +++ b/doc/operations/incident_management/img/alert_detail_add_todo_v13_9.png diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md index 3f6522b3f90..f0bb9a8e950 100644 --- a/doc/operations/incident_management/incidents.md +++ b/doc/operations/incident_management/incidents.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Incidents +# Incidents **(FREE)** Incidents are critical entities in incident management workflows. They represent a service disruption or outage that needs to be restored urgently. GitLab provides @@ -24,7 +24,7 @@ Incident, you have two options to do this manually. **From the Incidents List:** -> [Moved](https://gitlab.com/gitlab-org/monitor/health/-/issues/24) to GitLab core in 13.3. +> [Moved](https://gitlab.com/gitlab-org/monitor/health/-/issues/24) to GitLab Free in 13.3. - Navigate to **Operations > Incidents** and click **Create Incident**. - Create a new issue using the `incident` template available when creating it. @@ -36,9 +36,11 @@ Incident, you have two options to do this manually. > [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. +1. Go to **Issues > List**, and select **New issue**. +1. In the **Type** dropdown, select **Incident**. Only fields relevant to + incidents are displayed on the page. +1. Create the incident as needed, and select **Submit issue** to save the + incident.  @@ -53,7 +55,7 @@ With Maintainer or higher [permissions](../../user/permissions.md), you can enab 1. Check the **Create an incident** checkbox. 1. To customize the incident, select an [issue template](../../user/project/description_templates.md#creating-issue-templates). -1. To send [an email notification](alert_notifications.md#email-notifications) to users +1. To send [an email notification](paging.md#email-notifications) to users with [Developer permissions](../../user/permissions.md), select **Send a separate email notification to Developers**. Email notifications are also sent to users with **Maintainer** and **Owner** permissions. @@ -115,7 +117,7 @@ in your project's sidebar. The list contains the following metrics: 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 Free 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. @@ -185,7 +187,7 @@ field populated.  -### Timeline view +### Timeline view **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227836) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. @@ -195,7 +197,7 @@ un-threaded and ordered chronologically, newest to oldest:  -### Service Level Agreement countdown timer +### Service Level Agreement countdown timer **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241663) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. @@ -225,6 +227,10 @@ There are different actions available to help triage and respond to incidents. Assign incidents to users that are actively responding. Select **Edit** in the right-hand side bar to select or deselect assignees. +### Associate a milestone + +Associate an incident to a milestone by selecting **Edit** next to the milestone feature in the right-hand side bar. + ### Change severity See [Incident List](#incident-list) for a full description of the severity levels available. diff --git a/doc/operations/incident_management/index.md b/doc/operations/incident_management/index.md index b0274537941..6e285300b12 100644 --- a/doc/operations/incident_management/index.md +++ b/doc/operations/incident_management/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Incident management +# Incident management **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2877) in GitLab 13.0. @@ -12,7 +12,7 @@ Incident Management enables developers to easily triage and view the alerts and generated by their application. By surfacing alerts and incidents where the code is being developed, efficiency and awareness can be increased. Check out the following sections for more information: -- [Integrate your monitoring tools](alert_integrations.md). -- Receive [notifications](alert_notifications.md) for triggered alerts. +- [Integrate your monitoring tools](integrations.md). +- Receive [notifications](paging.md) for triggered alerts. - Triage [Alerts](alerts.md) and [Incidents](incidents.md). - Inform stakeholders with [Status Page](status_page.md). diff --git a/doc/operations/incident_management/integrations.md b/doc/operations/incident_management/integrations.md index 8c2159c130b..2ffe3e7e9fb 100644 --- a/doc/operations/incident_management/integrations.md +++ b/doc/operations/incident_management/integrations.md @@ -4,7 +4,17 @@ 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/#assignments --- -# Integrations +# Alert integrations **(FREE)** + +> - [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 webhook receiver. This can be configured +generically or, in GitLab versions 13.1 and greater, you can configure +[External Prometheus instances](../metrics/alerts.md#external-prometheus-instances) +to use this endpoint. + +## Integrations list > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/245331) in [GitLab Core](https://about.gitlab.com/pricing/) 13.5. @@ -14,3 +24,176 @@ the list of configured alerts integrations by navigating to The list displays the integration name, type, and status (enabled or disabled):  + +## Configuration + +GitLab can receive alerts via a HTTP endpoint that you configure, +or the [Prometheus integration](#external-prometheus-integration). + +### Single HTTP Endpoint **(FREE)** + +Enabling the HTTP Endpoint in a GitLab projects activates it to +receive alert payloads in JSON format. You can always +[customize the payload](#customize-the-alert-payload-outside-of-gitlab) to your liking. + +1. Sign in to GitLab as a user with maintainer [permissions](../../user/permissions.md) + for a project. +1. Navigate to **Settings > Operations** in your project. +1. Expand the **Alerts** section, and in the **Integration** dropdown menu, select **Generic**. +1. Toggle the **Active** alert setting to display the **URL** and **Authorization Key** + for the webhook configuration. + +### HTTP Endpoints **PREMIUM** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4442) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. + +In [GitLab Premium](https://about.gitlab.com/pricing/), you can create multiple +unique HTTP endpoints to receive alerts from any external source in JSON format, +and you can [customize the payload](#customize-the-alert-payload-outside-of-gitlab). + +1. Sign in to GitLab as a user with maintainer [permissions](../../user/permissions.md) + for a project. +1. Navigate to **Settings > Operations** in your project. +1. Expand the **Alerts** section. +1. For each endpoint you want to create: + + 1. In the **Integration** dropdown menu, select **HTTP Endpoint**. + 1. Name the integration. + 1. Toggle the **Active** alert setting to display the **URL** and **Authorization Key** + for the webhook configuration. You must also input the URL and Authorization Key + in your external service. + 1. _(Optional)_ To generate a test alert to test the new integration, enter a + sample payload, then click **Save and test alert payload**. Valid JSON is required. + 1. Click **Save Integration**. + +The new HTTP Endpoint displays in the [integrations list](#integrations-list). +You can edit the integration by selecting the **{pencil}** pencil icon on the right +side of the integrations list. + +### External Prometheus integration + +For GitLab versions 13.1 and greater, please read +[External Prometheus Instances](../metrics/alerts.md#external-prometheus-instances) +to configure alerts for this integration. + +## Customize the alert payload outside of GitLab + +For all integration types, you can customize the payload by sending the following +parameters. All fields are optional. If the incoming alert does not contain a value for the `Title` field, a default value of `New: Incident` will be applied. + +| Property | Type | Description | +| ------------------------- | --------------- | ----------- | +| `title` | String | The title of the incident. | +| `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 is 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). Required to [display alerts on a dashboard](../../user/operations_dashboard/index.md#adding-a-project-to-the-dashboard). | + +You can also add custom fields to the alert's payload. The values of extra +parameters aren't limited to primitive types (such as strings or numbers), but +can be a nested JSON object. For example: + +```json +{ "foo": { "bar": { "baz": 42 } } } +``` + +NOTE: +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 configuring an alert integration. + +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](../../user/permissions.md) +configures an integration, 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`, GitLab creates a new alert instead. + + + +## Link to your Opsgenie Alerts + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. + +WARNING: +We are building deeper integration with Opsgenie and other alerting tools through +[HTTP endpoint integrations](#single-http-endpoint) so you can see alerts in +the GitLab interface. As a result, the previous direct link to Opsgenie Alerts from +the GitLab alerts list is deprecated in +GitLab versions [13.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/273657). + +You can monitor alerts using a GitLab integration with [Opsgenie](https://www.atlassian.com/software/opsgenie). + +If you enable the Opsgenie integration, you can't have other GitLab alert +services +active at the same time. + +To enable Opsgenie integration: + +1. Sign in as a user with Maintainer or Owner [permissions](../../user/permissions.md). +1. Navigate to **Operations > Alerts**. +1. In the **Integrations** select box, select **Opsgenie**. +1. Select the **Active** toggle. +1. In the **API URL** field, enter the base URL for your Opsgenie integration, + such as `https://app.opsgenie.com/alert/list`. +1. Select **Save changes**. + +After you enable the integration, navigate to the Alerts list page at +**Operations > Alerts**, and then select **View alerts in Opsgenie**. diff --git a/doc/operations/incident_management/paging.md b/doc/operations/incident_management/paging.md new file mode 100644 index 00000000000..dd04cd63a54 --- /dev/null +++ b/doc/operations/incident_management/paging.md @@ -0,0 +1,36 @@ +--- +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/#assignments +--- + +# Paging and notifications **(FREE)** + +When there is a new alert or incident, it is important for a responder to be notified +immediately so they can triage and respond to the problem. Responders can receive +notifications using the methods described on this page. + +## Slack notifications + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216326) in GitLab 13.1. + +Responders can be paged via Slack using the +[Slack Notifications Service](../../user/project/integrations/slack.md), which you +can configure for new alerts and new incidents. After configuring, responders +receive a **single** page via Slack. To set up Slack notifications on your mobile +device, make sure to enable notifications for the Slack app on your phone so +you never miss a page. + +## Email notifications + +Email notifications are available in projects that have been +[configured to create incidents automatically](incidents.md#create-incidents-automatically) +for triggered alerts. Project members with the **Owner** or **Maintainer** roles are +sent an email notification automatically. (This is not configurable.) To optionally +send additional email notifications to project members with the **Developer** role: + +1. Navigate to **Settings > Operations**. +1. Expand the **Incidents** section. +1. In the **Alert Integration** tab, select the **Send a separate email notification to Developers** + check box. +1. Select **Save changes**. diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md index 6514a80a32b..fe0bfa3318b 100644 --- a/doc/operations/incident_management/status_page.md +++ b/doc/operations/incident_management/status_page.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Status Page +# Status Page **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2479) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. diff --git a/doc/operations/index.md b/doc/operations/index.md index 1d738768531..4427dd66f3d 100644 --- a/doc/operations/index.md +++ b/doc/operations/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Project operations **(CORE)** +# Project operations **(FREE)** GitLab provides a variety of tools to help operate and maintain your applications: diff --git a/doc/operations/metrics/alerts.md b/doc/operations/metrics/alerts.md index 36a73d66609..9c33ea98411 100644 --- a/doc/operations/metrics/alerts.md +++ b/doc/operations/metrics/alerts.md @@ -4,9 +4,9 @@ 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/#assignments --- -# Set up alerts for Prometheus metrics **(CORE)** +# Set up alerts for Prometheus metrics **(FREE)** -> [Moved from Ultimate to Core](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) in GitLab 12.10. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to GitLab Free in 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 @@ -47,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 11.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to GitLab Free 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,9 +78,12 @@ For GitLab to associate your alerts with an [environment](../../ci/environments/ you must configure a `gitlab_environment_name` label on the alerts you set up in Prometheus. The value of this should match the name of your environment in GitLab. +You can display alerts with a `gitlab_environment_name` of `production` +[on a dashboard](../../user/operations_dashboard/index.md#adding-a-project-to-the-dashboard). + In GitLab versions 13.1 and greater, you can configure your manually configured Prometheus server to use the -[Generic alerts integration](../incident_management/alert_integrations.md). +[Generic alerts integration](../incident_management/integrations.md). ## Trigger actions from alerts **(ULTIMATE)** @@ -101,6 +104,7 @@ values extracted from the [`alerts` field in webhook payload](https://prometheus - Issue author: `GitLab Alert Bot` - Issue title: Extracted from the alert payload fields `annotations/title`, `annotations/summary`, or `labels/alertname`. +- Issue description: Extracted from alert payload field `annotations/description`. - Alert `Summary`: A list of properties from the alert's payload. - `starts_at`: Alert start time from the payload's `startsAt` field - `full_query`: Alert query extracted from the payload's `generatorURL` field diff --git a/doc/operations/metrics/dashboards/default.md b/doc/operations/metrics/dashboards/default.md index 5c6187565dd..3c151586f12 100644 --- a/doc/operations/metrics/dashboards/default.md +++ b/doc/operations/metrics/dashboards/default.md @@ -4,7 +4,7 @@ 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/#assignments --- -# GitLab-defined metrics dashboards **(CORE)** +# GitLab-defined metrics dashboards **(FREE)** GitLab provides some dashboards out-of-the-box for any project with [Prometheus available](../../../user/project/integrations/prometheus.md). You can diff --git a/doc/operations/metrics/dashboards/develop.md b/doc/operations/metrics/dashboards/develop.md index 800ed401efb..76ad609870c 100644 --- a/doc/operations/metrics/dashboards/develop.md +++ b/doc/operations/metrics/dashboards/develop.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Developing templates for custom dashboards **(CORE)** +# Developing templates for custom dashboards **(FREE)** GitLab provides a template to make it easier for you to create templates for [custom dashboards](index.md). Templates provide helpful guidance and @@ -27,7 +27,7 @@ Navigate to the browser-based editor of your choice: 1. Click **{doc-new}** **New file**, then click **Choose a template** to see a list of available templates:  -## Custom dashboard templates **(PREMIUM ONLY)** +## Custom dashboard templates **(PREMIUM SELF)** To enable and use a custom dashboard templates on your GitLab instance, read the [guide for creating custom templates](../../../user/admin_area/settings/instance_template_repository.md). diff --git a/doc/operations/metrics/dashboards/index.md b/doc/operations/metrics/dashboards/index.md index f875c4a87c5..a0ac4fe6226 100644 --- a/doc/operations/metrics/dashboards/index.md +++ b/doc/operations/metrics/dashboards/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Custom dashboards **(CORE)** +# Custom dashboards **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/59974) in GitLab 12.1. @@ -94,7 +94,7 @@ with the **Add Panel** page: ## Duplicate a GitLab-defined dashboard > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/37238) in GitLab 12.7. -> - From [GitLab 12.8 onwards](https://gitlab.com/gitlab-org/gitlab/-/issues/39505), custom metrics are also duplicated when you duplicate a dashboard. +> - [GitLab versions 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/39505), custom metrics are also duplicated when you duplicate a dashboard. You can save a complete copy of a GitLab-defined dashboard along with all custom metrics added to it. The resulting `.yml` file can be customized and adapted to your project. @@ -128,7 +128,7 @@ any chart on a dashboard: The options are: - **Expand panel** - Displays a larger version of a visualization. To return to - the dashboard, click the **Back** button in your browser, or press the <kbd>Esc</kbd> key. + the dashboard, click the **Back** button in your browser, or press the <kbd>Escape</kbd> key. ([Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3100) in GitLab 13.0.) - **View logs** **(ULTIMATE)** - Displays [Logs](../../../user/project/clusters/kubernetes_pod_logs.md), if they are enabled. If used in conjunction with the [timeline zoom](#timeline-zoom-and-url-sharing) @@ -147,7 +147,7 @@ The options are: You can use the **Timeline zoom** function at the bottom of a chart to zoom in on a date and time of your choice. When you click and drag the sliders to select a different beginning or end date of data to display, GitLab adds your selected start -and end times to the URL, enabling you to share specific timeframes more easily. +and end times to the URL, enabling you to share specific time frames more easily. ## Dashboard Annotations diff --git a/doc/operations/metrics/dashboards/panel_types.md b/doc/operations/metrics/dashboards/panel_types.md index 86f6776e273..4b942ffcf4f 100644 --- a/doc/operations/metrics/dashboards/panel_types.md +++ b/doc/operations/metrics/dashboards/panel_types.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Panel types for dashboards **(CORE)** +# Panel types for dashboards **(FREE)** The below panel types are supported in monitoring dashboards. diff --git a/doc/operations/metrics/dashboards/settings.md b/doc/operations/metrics/dashboards/settings.md index 92f3a14aab9..18cfd6c53b8 100644 --- a/doc/operations/metrics/dashboards/settings.md +++ b/doc/operations/metrics/dashboards/settings.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Dashboard settings +# Dashboard settings **(FREE)** You can configure your [Monitoring dashboard](../index.md) to display the time zone of your choice, and the links of your choice. diff --git a/doc/operations/metrics/dashboards/templating_variables.md b/doc/operations/metrics/dashboards/templating_variables.md index db02cc3bf98..72541f7ced5 100644 --- a/doc/operations/metrics/dashboards/templating_variables.md +++ b/doc/operations/metrics/dashboards/templating_variables.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Templating variables for metrics dashboards **(CORE)** +# Templating variables for metrics dashboards **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214539) in GitLab 13.0. diff --git a/doc/operations/metrics/dashboards/variables.md b/doc/operations/metrics/dashboards/variables.md index 9c5ff3bd13b..c0d0f65cc65 100644 --- a/doc/operations/metrics/dashboards/variables.md +++ b/doc/operations/metrics/dashboards/variables.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Using variables **(CORE)** +# Using variables **(FREE)** ## Query variables diff --git a/doc/operations/metrics/dashboards/yaml.md b/doc/operations/metrics/dashboards/yaml.md index db49de7e800..138d9b28c76 100644 --- a/doc/operations/metrics/dashboards/yaml.md +++ b/doc/operations/metrics/dashboards/yaml.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Dashboard YAML properties **(CORE)** +# Dashboard YAML properties **(FREE)** Dashboards have several components: @@ -133,7 +133,7 @@ metrics: unit: 'count' ``` -This works by lowercasing the value of `label` and, if there are more words separated by spaces, replacing those spaces with an underscore (`_`). The transformed value is then checked against the labels of the time series returned by the Prometheus query. If a time series label is found that is equal to the transformed value, then the label value renders in the legend like this: +This works by converting the value of `label` to lower-case and, if there are more words separated by spaces, replacing those spaces with an underscore (`_`). The transformed value is then checked against the labels of the time series returned by the Prometheus query. If a time series label is found that is equal to the transformed value, then the label value renders in the legend like this:  diff --git a/doc/operations/metrics/dashboards/yaml_number_format.md b/doc/operations/metrics/dashboards/yaml_number_format.md index 27e4b905597..dd652a0cc2b 100644 --- a/doc/operations/metrics/dashboards/yaml_number_format.md +++ b/doc/operations/metrics/dashboards/yaml_number_format.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Unit formats reference **(CORE)** +# Unit formats reference **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201999) in GitLab 12.9. diff --git a/doc/operations/metrics/embed.md b/doc/operations/metrics/embed.md index 9a9a0b4cff2..e5ab391afe5 100644 --- a/doc/operations/metrics/embed.md +++ b/doc/operations/metrics/embed.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Embedding metric charts within GitLab-flavored Markdown **(CORE)** +# Embedding metric charts within GitLab-flavored Markdown **(FREE)** You can display metrics charts within [GitLab Flavored Markdown](../../user/markdown.md#gitlab-flavored-markdown-gfm) diff --git a/doc/operations/metrics/embed_grafana.md b/doc/operations/metrics/embed_grafana.md index 21950354ae9..f9db3750bb9 100644 --- a/doc/operations/metrics/embed_grafana.md +++ b/doc/operations/metrics/embed_grafana.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Embedding Grafana charts **(CORE)** +# Embedding Grafana charts **(FREE)** Grafana metrics can be embedded in [GitLab Flavored Markdown](../../user/markdown.md). diff --git a/doc/operations/metrics/index.md b/doc/operations/metrics/index.md index 7cd18e5606b..ca7bce347d3 100644 --- a/doc/operations/metrics/index.md +++ b/doc/operations/metrics/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Monitor your environment's metrics **(CORE)** +# Monitor your environment's metrics **(FREE)** GitLab helps your team monitor the health and performance of your applications and infrastructure by turning statistics and log files into charts and graphs @@ -131,8 +131,7 @@ dashboard is visible to authenticated and non-authenticated users. ## Adding custom metrics -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3799) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28527) to [GitLab Core](https://about.gitlab.com/pricing/) 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28527) to GitLab Free in 12.10. Custom metrics can be monitored by adding them on the monitoring dashboard page. After saving them, they display on the environment metrics dashboard provided that either: diff --git a/doc/operations/moving_repositories.md b/doc/operations/moving_repositories.md deleted file mode 100644 index 07df1607d37..00000000000 --- a/doc/operations/moving_repositories.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../administration/operations/moving_repositories.md' ---- - -This document was moved to [another location](../administration/operations/moving_repositories.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/product_analytics.md b/doc/operations/product_analytics.md index e6e887b9738..db6dc13607b 100644 --- a/doc/operations/product_analytics.md +++ b/doc/operations/product_analytics.md @@ -1,10 +1,10 @@ --- stage: Growth -group: Product Analytics +group: Product Intelligence info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Product Analytics **(CORE)** +# Product Analytics **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225167) in GitLab 13.3. > - It's deployed behind a feature flag, disabled by default. diff --git a/doc/operations/sidekiq_memory_killer.md b/doc/operations/sidekiq_memory_killer.md deleted file mode 100644 index b98e4abb4d0..00000000000 --- a/doc/operations/sidekiq_memory_killer.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../administration/operations/sidekiq_memory_killer.md' ---- - -This document was moved to [another location](../administration/operations/sidekiq_memory_killer.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/tracing.md b/doc/operations/tracing.md index c08651560e0..a4aae05c46d 100644 --- a/doc/operations/tracing.md +++ b/doc/operations/tracing.md @@ -4,10 +4,10 @@ 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/#assignments --- -# Tracing +# Tracing **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7903) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. -> - [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab/-/issues/42645) in 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7903) in GitLab Ultimate 11.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42645) to GitLab Free in 13.5. Tracing provides insight into the performance and health of a deployed application, tracking each function or microservice which handles a given request. diff --git a/doc/operations/unicorn.md b/doc/operations/unicorn.md deleted file mode 100644 index d10b7f8bbb9..00000000000 --- a/doc/operations/unicorn.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../administration/operations/unicorn.md' ---- - -This document was moved to [another location](../administration/operations/unicorn.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/permissions/permissions.md b/doc/permissions/permissions.md deleted file mode 100644 index 38b68ff9e42..00000000000 --- a/doc/permissions/permissions.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -redirect_to: '../user/permissions.md' ---- - -# Permissions - -This document was moved to [user/permissions.md](../user/permissions.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/push_rules/push_rules.md b/doc/push_rules/push_rules.md index 4f902382fd5..7c652e2326e 100644 --- a/doc/push_rules/push_rules.md +++ b/doc/push_rules/push_rules.md @@ -5,21 +5,21 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Push Rules **(STARTER)** +# Push Rules **(PREMIUM)** Gain additional control over what can and can't be pushed to your repository by using regular expressions to reject pushes based on commit contents, branch names or file details. -## Overview - GitLab already offers [protected branches](../user/project/protected_branches.md), but there are -cases when you need some specific rules like preventing Git tag removal or +cases when you need some specific rules. Some common scenarios: preventing Git tag removal, or enforcing a special format for commit messages. -Push rules are essentially [pre-receive Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) that are easy to -enable in a user-friendly interface. They are defined globally if you are an -admin or per project so you can have different rules applied to different -projects depending on your needs. +Push rules are [pre-receive Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) you +can enable in a user-friendly interface. They are defined either: + +- Globally if you are an administrator. +- Per project, so you can have different rules applied to different + projects depending on your needs. ## Use cases @@ -32,24 +32,24 @@ Let's assume you have the following requirements for your workflow: - every commit should reference a Jira issue, for example: `Refactored css. Fixes JIRA-123.` - users should not be able to remove Git tags with `git push` -All you need to do is write a simple regular expression that requires the mention +Write a regular expression that requires the mention of a Jira issue in the commit message, like `JIRA\-\d+`. -Now when a user tries to push a commit with a message `Bugfix`, their push will -be declined. Only pushing commits with messages like `Bugfix according to JIRA-123` -will be accepted. +Now when a user tries to push a commit with a message `Bugfix`, their push is +declined. Only pushing commits with messages like `Bugfix according to JIRA-123` +is accepted. ### Restrict branch names -Let's assume there's a strict policy for branch names in your company, and -you want the branches to start with a certain name because you have different -GitLab CI/CD jobs (`feature`, `hotfix`, `docker`, `android`, etc.) that rely on the +If your company has a strict policy for branch names, you may want the branches to start +with a certain name. This approach enables different +GitLab CI/CD jobs (such as `feature`, `hotfix`, `docker`, `android`) that rely on the branch name. -Your developers, however, don't always remember that policy, so they might push to +Your developers may not remember that policy, so they might push to various branches, and CI pipelines might not work as expected. By restricting the branch names globally in Push Rules, such mistakes are prevented. -Any branch name that doesn't match your push rule will get rejected. +Any branch name that doesn't match your push rule is rejected. Note that the name of your default branch is always allowed, regardless of the branch naming regular expression (regex) specified. GitLab is configured this way @@ -64,9 +64,9 @@ which already limits users from pushing directly. > Introduced in GitLab 12.10. By default, GitLab restricts certain formats of branch names for security purposes. -Currently 40-character hexadecimal names, similar to Git commit hashes, are prohibited. +40-character hexadecimal names, similar to Git commit hashes, are prohibited. -### Custom Push Rules **(CORE ONLY)** +### Custom Push Rules **(FREE SELF)** It's possible to create custom push rules rather than the push rules available in **Admin Area > Push Rules** by using more advanced server hooks. @@ -77,7 +77,7 @@ See [server hooks](../administration/server_hooks.md) for more information. NOTE: GitLab administrators can set push rules globally under -**Admin Area > Push Rules** that all new projects will inherit. You can later +**Admin Area > Push Rules** that all new projects 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). 1. Navigate to your project's **Settings > Repository** and expand **Push Rules** @@ -88,13 +88,13 @@ The following options are available: | Push rule | Description | |---------------------------------|-------------| -| Removal of tags with `git push` | Forbid users to remove Git tags with `git push`. Tags will still be able to be deleted through the web UI. | -| Check whether author is a GitLab user | Restrict commits by author (email) to existing GitLab users. | -| Committer restriction **(PREMIUM)** | GitLab will reject any commit that was not committed by the current authenticated user. | +| Removal of tags with `git push` | Forbid users to remove Git tags with `git push`. Tags can be deleted through the web UI. | +| Check whether the commit author is a GitLab user | Restrict commits to existing GitLab users (checked against their emails). | +| Reject unverified users **(PREMIUM)** | GitLab rejects any commit that was not committed by an authenticated user. | | Check whether commit is signed through GPG **(PREMIUM)** | Reject commit when it is not signed through GPG. Read [signing commits with GPG](../user/project/repository/gpg_signed_commits/index.md). | -| Prevent committing secrets to Git | GitLab will reject any files that are likely to contain secrets. Read [what files are forbidden](#prevent-pushing-secrets-to-the-repository). | -| Restrict by commit message | Only commit messages that match this regular expression are allowed to be pushed. Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. | -| Restrict by commit message (negative match) | Only commit messages that do not match this regular expression are allowed to be pushed. Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. | +| Prevent pushing secret files | GitLab rejects any files that are likely to contain secrets. See the [forbidden file names](#prevent-pushing-secrets-to-the-repository). | +| Require expression in commit messages | Only commit messages that match this regular expression are allowed to be pushed. Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. | +| Reject expression in commit messages | Only commit messages that do not match this regular expression are allowed to be pushed. Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. | | Restrict by branch name | Only branch names that match this regular expression are allowed to be pushed. Leave empty to allow any branch name. | | Restrict by commit author's email | Only commit author's email that match this regular expression are allowed to be pushed. Leave empty to allow any email. | | Prohibited file names | Any committed filenames that match this regular expression and do not already exist in the repository are not allowed to be pushed. Leave empty to allow any filenames. See [common examples](#prohibited-file-names). | @@ -105,11 +105,12 @@ GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular ## Prevent pushing secrets to the repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.12. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385) in GitLab 8.12. +> - Moved to GitLab Premium in 13.9. Secrets such as credential files, SSH private keys, and other files containing secrets should never be committed to source control. -GitLab allows you to turn on a predefined denylist of files which won't be allowed to be -pushed to a repository, stopping those commits from reaching the remote repository. +GitLab enables you to turn on a predefined denylist of files which can't be +pushed to a repository. The list stops those commits from reaching the remote repository. By selecting the checkbox *Prevent committing secrets to Git*, GitLab prevents pushes to the repository when a file matches a regular expression as read from @@ -117,9 +118,9 @@ pushes to the repository when a file matches a regular expression as read from as your GitLab version when viewing this file). NOTE: -Files already committed won't get restricted by this push rule. +Files already committed aren't restricted by this push rule. -Below is an example list of what will be rejected by these regular expressions: +Below is an example list of what GitLab rejects with these regular expressions: ```shell ##################### @@ -180,7 +181,8 @@ id_ecdsa ## Prohibited file names -> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 7.10. +> - Introduced in GitLab 7.10. +> - Moved to GitLab Premium in 13.9. Each filename contained in a Git push is compared to the regular expression in this field. Filenames in Git consist of both the file's name and any directory that may precede it. A singular regular expression can contain multiple independent matches used as exclusions. File names can be broadly matched to any location in the repository, or restricted to specific locations. Filenames can also be partial matches used to exclude file types by extension. @@ -204,13 +206,17 @@ Example: prevent a specific configuration file in a known directory from being p ^directory-name\/config\.yml$ ``` -Example: prevent the specific file named `install.exe` from being pushed to any location in the repository. Note that the parenthesized expression `(^|\/)` will match either a file following a directory separator or a file in the root directory of the repository: +Example: prevent the specific file named `install.exe` from being pushed to any +location in the repository. The parenthesized expression `(^|\/)` matches either +a file following a directory separator or a file in the root directory of the repository: ```plaintext (^|\/)install\.exe$ ``` -Example: combining all of the above in a single expression. Note that all of the preceding expressions rely on the end of string character `$`, so we can move that part of each expression to the end of the grouped collection of match conditions where it will be appended to all matches: +Example: combining all of the above in a single expression. The preceding expressions rely +on the end-of-string character `$`. We can move that part of each expression to the +end of the grouped collection of match conditions where it is appended to all matches: ```plaintext (\.exe|^config\.yml|^directory-name\/config\.yml|(^|\/)install\.exe)$ diff --git a/doc/raketasks/README.md b/doc/raketasks/README.md index e119563fd25..be7e55cba9b 100644 --- a/doc/raketasks/README.md +++ b/doc/raketasks/README.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w comments: false --- -# Rake tasks **(CORE ONLY)** +# Rake tasks **(FREE SELF)** GitLab provides [Rake](https://ruby.github.io/rake/) tasks for common administration and operational processes. @@ -24,10 +24,10 @@ The following are available Rake tasks: | [Clean up](cleanup.md) | Clean up unneeded items from GitLab instances. | | [Development](../development/rake_tasks.md) | Tasks for GitLab contributors. | | [Doctor tasks](../administration/raketasks/doctor.md) | Checks for data integrity issues. | -| [Elasticsearch](../integration/elasticsearch.md#gitlab-advanced-search-rake-tasks) **(STARTER ONLY)** | Maintain Elasticsearch in a GitLab instance. | +| [Elasticsearch](../integration/elasticsearch.md#gitlab-advanced-search-rake-tasks) **(PREMIUM SELF)** | 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/index.md)-related maintenance. | +| [Geo maintenance](../administration/raketasks/geo.md) **(PREMIUM SELF)** | [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). | @@ -38,7 +38,7 @@ The following are available Rake tasks: | [Praefect Rake tasks](../administration/raketasks/praefect.md) | [Praefect](../administration/gitaly/praefect.md)-related tasks. | | [Project import/export](../administration/raketasks/project_import_export.md) | Prepare for [project exports and imports](../user/project/settings/import_export.md). | | [Sample Prometheus data](generate_sample_prometheus_data.md) | Generate sample Prometheus data. | -| [SPDX license list import](spdx.md) **(PREMIUM ONLY)** | Import a local copy of the [SPDX license list](https://spdx.org/licenses/) for matching [License Compliance policies](../user/compliance/license_compliance/index.md).| | +| [SPDX license list import](spdx.md) **(PREMIUM SELF)** | Import a local copy of the [SPDX license list](https://spdx.org/licenses/) for matching [License Compliance policies](../user/compliance/license_compliance/index.md).| | | [Repository storage](../administration/raketasks/storage.md) | List and migrate existing projects and attachments from legacy storage to hashed storage. | | [Uploads migrate](../administration/raketasks/uploads/migrate.md) | Migrate uploads between storage local and object storage. | | [Uploads sanitize](../administration/raketasks/uploads/sanitize.md) | Remove EXIF data from images uploaded to earlier versions of GitLab. | diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 8a01975f771..24b1c7a6978 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -1,10 +1,10 @@ --- -stage: none -group: unassigned +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/#assignments --- -# Back up and restore GitLab **(CORE ONLY)** +# Back up and restore GitLab **(FREE SELF)** GitLab provides Rake tasks for backing up and restoring GitLab instances. @@ -16,7 +16,7 @@ of GitLab on which it was created. The best way to migrate your repositories from one server to another is through backup restore. WARNING: -GitLab doesn't back up items that aren't stored in the filesystem. If you're +GitLab doesn't back up items that aren't stored in the file system. If you're using [object storage](../administration/object_storage.md), be sure to enable backups with your object storage provider, if desired. @@ -100,7 +100,7 @@ the host, based on your installed version of GitLab: - GitLab 12.1 and earlier: ```shell - gitlab-rake gitlab:backup:create + docker exec -t <container name> gitlab-rake gitlab:backup:create ``` If you're using the [GitLab Helm chart](https://gitlab.com/gitlab-org/charts/gitlab) @@ -240,7 +240,7 @@ The resulting file is named `dump_gitlab_backup.tar`. This is useful for systems that make use of rsync and incremental backups, and results in considerably faster transfer speeds. -#### Rsyncable +#### Confirm archive can be transferred To ensure the generated archive is transferable by rsync, you can set the `GZIP_RSYNCABLE=yes` option. This sets the `--rsyncable` option to `gzip`, which is useful only in @@ -1042,12 +1042,12 @@ is being discussed in [issue #17517](https://gitlab.com/gitlab-org/gitlab/-/issu If your GitLab server contains a lot of Git repository data, you may find the GitLab backup script to be too slow. In this case you can consider using -filesystem snapshots as part of your backup strategy. +file system snapshots as part of your backup strategy. Example: Amazon EBS > A GitLab server using Omnibus GitLab hosted on Amazon AWS. -> An EBS drive containing an ext4 filesystem is mounted at `/var/opt/gitlab`. +> An EBS drive containing an ext4 file system is mounted at `/var/opt/gitlab`. > In this case you could make an application backup by taking an EBS snapshot. > The backup includes all repositories, uploads and PostgreSQL data. @@ -1055,7 +1055,7 @@ Example: LVM snapshots + rsync > A GitLab server using Omnibus GitLab, with an LVM logical volume mounted at `/var/opt/gitlab`. > Replicating the `/var/opt/gitlab` directory using rsync would not be reliable because too many files would change while rsync is running. -> Instead of rsync-ing `/var/opt/gitlab`, we create a temporary LVM snapshot, which we mount as a read-only filesystem at `/mnt/gitlab_backup`. +> Instead of rsync-ing `/var/opt/gitlab`, we create a temporary LVM snapshot, which we mount as a read-only file system at `/mnt/gitlab_backup`. > Now we can have a longer running rsync job which creates a consistent replica on the remote server. > The replica includes all repositories, uploads and PostgreSQL data. @@ -1204,9 +1204,9 @@ and the jobs begin running again. Use the information in the following sections at your own risk. -#### Check for undecryptable values +#### Verify that all values can be decrypted -You can determine if you have undecryptable values in the database by using the +You can determine if your database contains values that can't be decrypted by using the [Secrets Doctor Rake task](../administration/raketasks/doctor.md). #### Take a backup @@ -1370,7 +1370,7 @@ To get your registry working again: sudo chown -R registry:registry /var/opt/gitlab/gitlab-rails/shared/registry/docker ``` -If you changed the default filesystem location for the registry, run `chown` +If you changed the default file system location for the registry, run `chown` against your custom location, instead of `/var/opt/gitlab/gitlab-rails/shared/registry/docker`. ### Backup fails to complete with Gzip error diff --git a/doc/raketasks/check.md b/doc/raketasks/check.md deleted file mode 100644 index 1a8149ca04a..00000000000 --- a/doc/raketasks/check.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../administration/raketasks/check.md' ---- - -This document was moved to [another location](../administration/raketasks/check.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md index 0c184aa0075..82b947746de 100644 --- a/doc/raketasks/cleanup.md +++ b/doc/raketasks/cleanup.md @@ -1,10 +1,10 @@ --- -stage: none -group: unassigned +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/#assignments --- -# Clean up **(CORE ONLY)** +# Clean up **(FREE SELF)** GitLab provides Rake tasks for cleaning up GitLab instances. @@ -74,7 +74,7 @@ I, [2020-01-08T20:51:17.148765 #43765] INFO -- : Removed unreferenced LFS files Clean up project upload files if they don't exist in GitLab database. -### Clean up project upload files from filesystem +### Clean up project upload files from file system > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20863) in GitLab 11.2. diff --git a/doc/raketasks/features.md b/doc/raketasks/features.md index bf67522c256..2fd73d70cda 100644 --- a/doc/raketasks/features.md +++ b/doc/raketasks/features.md @@ -1,10 +1,10 @@ --- -stage: none -group: unassigned +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/#assignments --- -# Namespaces **(CORE ONLY)** +# Namespaces **(FREE SELF)** This Rake task enables [namespaces](../user/group/index.md#namespaces) for projects. diff --git a/doc/raketasks/generate_sample_prometheus_data.md b/doc/raketasks/generate_sample_prometheus_data.md index 9dbdf053693..41e31c0b817 100644 --- a/doc/raketasks/generate_sample_prometheus_data.md +++ b/doc/raketasks/generate_sample_prometheus_data.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Generate sample Prometheus data **(CORE ONLY)** +# Generate sample Prometheus data **(FREE SELF)** This command runs Prometheus queries for each of the metrics of a specific environment for a series of time intervals to now: diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md index 648cd784c1b..b18413987a3 100644 --- a/doc/raketasks/import.md +++ b/doc/raketasks/import.md @@ -1,10 +1,10 @@ --- -stage: none -group: unassigned +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/#assignments --- -# Import bare repositories **(CORE ONLY)** +# Import bare repositories **(FREE SELF)** Rake tasks are available to import bare repositories into a GitLab instance. When migrating from an existing GitLab instance, diff --git a/doc/raketasks/list_repos.md b/doc/raketasks/list_repos.md index e2442df3418..35c5e1e3357 100644 --- a/doc/raketasks/list_repos.md +++ b/doc/raketasks/list_repos.md @@ -1,10 +1,10 @@ --- -stage: none -group: unassigned +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/#assignments --- -# Listing repository directories **(CORE ONLY)** +# Listing repository directories **(FREE SELF)** You can print a list of all Git repositories on disk managed by GitLab. diff --git a/doc/raketasks/maintenance.md b/doc/raketasks/maintenance.md deleted file mode 100644 index b6d530256a7..00000000000 --- a/doc/raketasks/maintenance.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../administration/raketasks/maintenance.md' ---- - -This document was moved to [another location](../administration/raketasks/maintenance.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/raketasks/migrate_snippets.md b/doc/raketasks/migrate_snippets.md index 244ff4f2b56..0d2c4edb01f 100644 --- a/doc/raketasks/migrate_snippets.md +++ b/doc/raketasks/migrate_snippets.md @@ -4,25 +4,24 @@ 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/#assignments --- -# Migration to Versioned Snippets **(CORE ONLY)** +# Migration to versioned snippets **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215861) in GitLab 13.0. In GitLab 13.0, [GitLab Snippets are backed by Git repositories](../user/snippets.md#versioned-snippets). -This means that the snippet content will be stored in the repository -and users can update it directly through Git. +Snippet content is stored in the repository, and users can update it directly through Git. -Nevertheless, existing GitLab Snippets have to be migrated to this new functionality. -For each snippet, a new repository is created and the snippet content is committed -to the repository inside a file whose name is the filename used in the snippet -as well. +Nevertheless, existing GitLab Snippets must be migrated to this new feature. +For each snippet: -GitLab performs this migration through a [Background Migration](../development/background_migrations.md) -automatically when the GitLab instance is upgrade to 13.0 or a higher version. -However, if the migration fails for any of the snippets, they still need -to be migrated individually. +- A new repository is created. +- A file is created in the repository, using the snippet filename. +- The snippet is committed to the repository. -The following Rake tasks will help with that process. +GitLab performs this migration through a [Background Migration](../development/background_migrations.md) +when the GitLab instance is upgraded to 13.0 or a higher version. +However, if the migration fails for any of the snippets, they must be migrated individually. +The following Rake tasks help with that process. ## Migrate specific snippets to Git diff --git a/doc/raketasks/spdx.md b/doc/raketasks/spdx.md index fe7ac13c463..f330698daba 100644 --- a/doc/raketasks/spdx.md +++ b/doc/raketasks/spdx.md @@ -1,10 +1,10 @@ --- -stage: none -group: unassigned +stage: Secure +group: Composition 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/#assignments --- -# SPDX license list import **(PREMIUM ONLY)** +# SPDX license list import **(PREMIUM SELF)** GitLab provides a Rake task for uploading a fresh copy of the [SPDX license list](https://spdx.org/licenses/) to a GitLab instance. This list is needed for matching the names of [License Compliance policies](../user/compliance/license_compliance/index.md). diff --git a/doc/raketasks/user_management.md b/doc/raketasks/user_management.md index 6df978b2efd..08f0005883b 100644 --- a/doc/raketasks/user_management.md +++ b/doc/raketasks/user_management.md @@ -1,10 +1,10 @@ --- -stage: none -group: unassigned +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/#assignments --- -# User management **(CORE ONLY)** +# User management **(FREE SELF)** GitLab provides Rake tasks for user management. diff --git a/doc/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md index 1f40c60e23d..e48a03f6883 100644 --- a/doc/raketasks/web_hooks.md +++ b/doc/raketasks/web_hooks.md @@ -1,10 +1,10 @@ --- -stage: none -group: unassigned +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/#assignments --- -# Webhooks administration **(CORE ONLY)** +# Webhooks administration **(FREE SELF)** GitLab provides Rake tasks for webhooks management. diff --git a/doc/raketasks/x509_signatures.md b/doc/raketasks/x509_signatures.md index a98f0af8cd8..5090fc285cc 100644 --- a/doc/raketasks/x509_signatures.md +++ b/doc/raketasks/x509_signatures.md @@ -4,7 +4,7 @@ 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/#assignments --- -# X.509 signatures **(CORE ONLY)** +# X.509 signatures **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/122159) in GitLab 12.10. diff --git a/doc/security/asset_proxy.md b/doc/security/asset_proxy.md index 613743143d3..7774f5e0635 100644 --- a/doc/security/asset_proxy.md +++ b/doc/security/asset_proxy.md @@ -51,7 +51,8 @@ To install a Camo server as an asset proxy: | `asset_proxy_enabled` | Enable proxying of assets. If enabled, requires: `asset_proxy_url`). | | `asset_proxy_secret_key` | Shared secret with the asset proxy server. | | `asset_proxy_url` | URL of the asset proxy server. | - | `asset_proxy_whitelist` | Assets that match these domain(s) are NOT proxied. Wildcards allowed. Your GitLab installation URL is automatically whitelisted. | + | `asset_proxy_whitelist` | (Deprecated: Use `asset_proxy_allowlist` instead) Assets that match these domain(s) are NOT proxied. Wildcards allowed. Your GitLab installation URL is automatically allowed. | + | `asset_proxy_allowlist` | Assets that match these domain(s) are NOT proxied. Wildcards allowed. Your GitLab installation URL is automatically allowed. | 1. Restart the server for the changes to take effect. Each time you change any values for the asset proxy, you need to restart the server. diff --git a/doc/security/cicd_environment_variables.md b/doc/security/cicd_environment_variables.md index 4d60df8e531..914cf553991 100644 --- a/doc/security/cicd_environment_variables.md +++ b/doc/security/cicd_environment_variables.md @@ -8,6 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w Environment variables are applied to environments via the runner and can be set from the project's **Settings > CI/CD** page. -The values are encrypted using [aes-256-cbc](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) and stored in the database. +The values are encrypted using [`aes-256-cbc`](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) and stored in the database. This data can only be decrypted with a valid [secrets file](../raketasks/backup_restore.md#when-the-secrets-file-is-lost). diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md index c5f8afe36ad..9a43f5dfca8 100644 --- a/doc/security/crime_vulnerability.md +++ b/doc/security/crime_vulnerability.md @@ -58,7 +58,7 @@ vulnerability. ## References -- NGINX ["Module ngx_http_spdy_module"](http://nginx.org/en/docs/http/ngx_http_spdy_module.html) +- NGINX ["Module `ngx_http_spdy_module`"](http://nginx.org/en/docs/http/ngx_http_spdy_module.html) - Tenable Network Security, Inc. ["Transport Layer Security (TLS) Protocol CRIME Vulnerability"](https://www.tenable.com/plugins/index.php?view=single&id=62565) - Wikipedia contributors, ["CRIME"](https://en.wikipedia.org/wiki/CRIME) Wikipedia, The Free Encyclopedia diff --git a/doc/security/password_storage.md b/doc/security/password_storage.md index ca39defe6b9..af4b57e342a 100644 --- a/doc/security/password_storage.md +++ b/doc/security/password_storage.md @@ -11,6 +11,6 @@ GitLab stores user passwords in a hashed format, to prevent passwords from being GitLab uses the [Devise](https://github.com/heartcombo/devise) authentication library, which handles the hashing of user passwords. Password hashes are created with the following attributes: -- **Hashing**: the [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) hashing function is used to generate the hash of the provided password. This is a strong, industry-standard cryptographic hashing function. +- **Hashing**: the [`bcrypt`](https://en.wikipedia.org/wiki/Bcrypt) hashing function is used to generate the hash of the provided password. This is a strong, industry-standard cryptographic hashing function. - **Stretching**: Password hashes are [stretched](https://en.wikipedia.org/wiki/Key_stretching) to harden against brute-force attacks. GitLab uses a stretching factor of 10 by default. - **Salting**: A [cryptographic salt](https://en.wikipedia.org/wiki/Salt_(cryptography)) is added to each password to harden against pre-computed hash and dictionary attacks. Each salt is randomly generated for each password, so that no two passwords share a salt, to further increase security. diff --git a/doc/security/reset_user_password.md b/doc/security/reset_user_password.md index fc808452736..ed7b9f89616 100644 --- a/doc/security/reset_user_password.md +++ b/doc/security/reset_user_password.md @@ -7,70 +7,91 @@ type: howto # How to reset user password -To reset the password of a user, first log into your server with root privileges. +There are a few ways to reset the password of a user. -Start a Ruby on Rails console with this command: +## Rake Task + +GitLab provides a Rake Task to reset passwords of users using their usernames, +which can be invoked by the following command: ```shell -gitlab-rails console -e production +sudo gitlab-rake "gitlab:password:reset" ``` -Wait until the console has loaded. - -## Find the user +You will be asked for username, password, and password confirmation. Upon giving +proper values for them, the password of the specified user will be updated. -There are multiple ways to find your user. You can search by email or user ID number. +The Rake task also takes the username as an argument, as shown in the example +below: ```shell -user = User.where(id: 7).first +sudo gitlab-rake "gitlab:password:reset[johndoe]" ``` -or +NOTE: +To reset the default admin password, run this Rake task with the username +`root`, which is the default username of that admin account. -```shell -user = User.find_by(email: 'user@example.com') -``` +## Rails console -## Reset the password +The Rake task is capable of finding users via their usernames. However, if only +user ID or email ID of the user is known, Rails console can be used to find user +using user ID and then change password of the user manually. -Now you can change your password: +1. Start a Rails console -```shell -user.password = 'secret_pass' -user.password_confirmation = 'secret_pass' -``` + ```shell + sudo gitlab-rails console -e production + ``` -It's important that you change both password and password_confirmation to make it work. +1. Find the user either by user ID or email ID: -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. + ```ruby + user = User.find(123) -If the password was changed by an administrator, execute the following command to notify the user by email: + #or -```shell -user.send_only_admin_changed_your_password_notification! -``` + user = User.find_by(email: 'user@example.com') + ``` -Don't forget to save the changes. +1. Reset the password -```shell -user.save! -``` + ```ruby + user.password = 'secret_pass' + user.password_confirmation = 'secret_pass' + ``` + +1. 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: + + ```ruby + user.send_only_admin_changed_your_password_notification! + ``` -Exit the console, and then try to sign in with your new password. +1. Save the changes: + + ```ruby + user.save! + ``` + +1. Exit the console, and then try to sign in with your new password. NOTE: You can also reset passwords by using the [Users API](../api/users.md#user-modification). -### Reset your root password +## Reset your root password -The previously described steps can also be used to reset the root password. First, -identify the root user, with an `id` of `1`. To do so, run the following command: +The previously described steps can also be used to reset the root password. -```shell -user = User.where(id: 1).first -``` +In normal installations where the username of root account hasn't been changed +manually, the Rake task can be used with username `root` to reset the root +password. -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. +If the username was changed to something else and has been forgotten, one +possible way is to reset the password using Rails console with user ID `1` (in +almost all the cases, the first user will be the default admin account). <!-- ## Troubleshooting diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md index 2a26b71071b..45da283f33e 100644 --- a/doc/security/unlock_user.md +++ b/doc/security/unlock_user.md @@ -40,7 +40,7 @@ To unlock a locked user: user.unlock_access! ``` -1. Exit the console with <kbd>Ctrl</kbd>+<kbd>d</kbd> +1. Exit the console with <kbd>Control</kbd>+<kbd>d</kbd> The user should now be able to log in. diff --git a/doc/ssh/README.md b/doc/ssh/README.md index f34e38fb7ca..f3fa7dd6033 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -201,7 +201,7 @@ Now you can copy the SSH key you created to your GitLab account. To do so, follo pbcopy < ~/.ssh/id_ed25519.pub ``` - **Linux (requires the xclip package):** + **Linux (requires the `xclip` package):** ```shell xclip -sel clip < ~/.ssh/id_ed25519.pub diff --git a/doc/subscriptions/bronze_starter.md b/doc/subscriptions/bronze_starter.md new file mode 100644 index 00000000000..6977ccca0e2 --- /dev/null +++ b/doc/subscriptions/bronze_starter.md @@ -0,0 +1,139 @@ +--- +stage: Fulfillment +group: Purchase +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Features available to Starter and Bronze subscribers + +Although GitLab has discontinued selling the Bronze and Starter tiers, GitLab +continues to honor the entitlements of existing Bronze and Starter tier GitLab +customers for the duration of their contracts at that level. + +These features remain available to Bronze and Starter customers, even though +the tiers are no longer mentioned in GitLab documentation: + +- [Activate GitLab EE with a license](../user/admin_area/license.md) +- [Adding a help message to the login page](../user/admin_area/settings/help_page.md#adding-a-help-message-to-the-login-page) +- [Burndown and burnup charts](../user/project/milestones/burndown_and_burnup_charts.md), + including [per-project charts](../user/project/milestones/index.md#project-burndown-charts) and + [per-group charts](../user/project/milestones/index.md#group-burndown-charts) +- [Code owners](../user/project/code_owners.md) +- Description templates: + - [Setting a default template for merge requests and issues](../user/project/description_templates.md#setting-a-default-template-for-merge-requests-and-issues) +- [Email from GitLab](../tools/email.md) +- Groups: + - [Creating group memberships via CN](../user/group/index.md#creating-group-links-via-cn) + - [Group push rules](../user/group/index.md#group-push-rules) + - [Managing group memberships via LDAP](../user/group/index.md#manage-group-memberships-via-ldap) + - [Member locking](../user/group/index.md#member-lock) + - [Overriding user permissions](../user/group/index.md#overriding-user-permissions) + - [User contribution analysis](../user/group/index.md#user-contribution-analysis) + - [Kerberos integration](../integration/kerberos.md) +- Issue Boards: + - [Configurable issue boards](../user/project/issue_board.md#configurable-issue-boards) + - [Sum of issue weights](../user/project/issue_board.md#sum-of-issue-weights) + - [Work In Progress limits](../user/project/issue_board.md#work-in-progress-limits) +- Issues: + - [Multiple assignees for issues](../user/project/issues/multiple_assignees_for_issues.md) + - [Issue weights](../user/project/issues/issue_weight.md) + - [Issue histories](../user/project/issues/issue_data_and_actions.md#issue-history) contain changes to issue description + - [Adding an issue to an iteration](../user/project/issues/managing_issues.md#add-an-issue-to-an-iteration) +- [Iterations](../user/group/iterations/index.md) +- [Kerberos integration](../integration/kerberos.md) +- LDAP: + - Querying LDAP [from the Rails console](../administration/auth/ldap/ldap-troubleshooting.md#query-ldap), or + [querying a single group](../administration/auth/ldap/ldap-troubleshooting.md#query-a-group-in-ldap) + - [Sync all users](../administration/auth/ldap/ldap-troubleshooting.md#sync-all-users) + - [Group management through LDAP](../administration/auth/ldap/ldap-troubleshooting.md#group-memberships) + - Syncing information through LDAP: + - Groups: [one group](../administration/auth/ldap/ldap-troubleshooting.md#sync-one-group), + [all groups programmatically](../administration/auth/ldap/index.md#group-sync), + [group sync schedule](../administration/auth/ldap/index.md#adjusting-ldap-group-sync-schedule), and + [all groups manually](../administration/auth/ldap/ldap-troubleshooting.md#sync-all-groups) + - [Configuration settings](../administration/auth/ldap/index.md#ldap-sync-configuration-settings) + - Users: [all users](../administration/auth/ldap/index.md#user-sync), + [administrators](../administration/auth/ldap/index.md#administrator-sync), + [user sync schedule](../administration/auth/ldap/index.md#adjusting-ldap-user-sync-schedule) + - [Adding group links](../administration/auth/ldap/index.md#adding-group-links) + - [Lock memberships to LDAP synchronization](../administration/auth/ldap/index.md#global-group-memberships-lock) + - Rake tasks for [LDAP tasks](../administration/raketasks/ldap.md), including + [syncing groups](../administration/raketasks/ldap.md#run-a-group-sync) +- Logging: + - [`audit_json.log`](../administration/logs.md#audit_jsonlog) (specific entries) + - [`elasticsearch.log`](../administration/logs.md#elasticsearchlog) +- Merge requests: + - [Full code quality reports in the code quality tab](../user/project/merge_requests/code_quality.md#code-quality-reports) + - [Merge request approvals](../user/project/merge_requests/merge_request_approvals.md) + - [Multiple assignees](../user/project/merge_requests/getting_started.md#multiple-assignees) + - [Approval Rule information for Reviewers](../user/project/merge_requests/getting_started.md#approval-rule-information-for-reviewers), and [enabling or disabling it](../user/project/merge_requests/getting_started.md#enable-or-disable-approval-rule-information-for-reviewers) + - [Required Approvals](../user/project/merge_requests/merge_request_approvals.md#required-approvals) + - [Code Owners as eligible approvers](../user/project/merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers) + - All [Approval rules](../user/project/merge_requests/merge_request_approvals.md#approval-rules) features + - [Restricting push and merge access to certain users](../user/project/protected_branches.md#restricting-push-and-merge-access-to-certain-users) + - [Visual Reviews](../ci/review_apps/index.md#visual-reviews) +- Metrics and analytics: + - [Contribution Analytics](../user/group/contribution_analytics/index.md) + - [Merge Request Analytics](../user/analytics/merge_request_analytics.md) + - [Code Review Analytics](../user/analytics/code_review_analytics.md) + - [Audit Events](../administration/audit_events.md), including + [Group events](../administration/audit_events.md#group-events) and + [Project events](../administration/audit_events.md#project-events) +- Rake tasks: + - [Displaying GitLab license information](../administration/raketasks/maintenance.md#show-gitlab-license-information) +- Reference Architecture information: + - [Traffic load balancers](../administration/reference_architectures/index.md#traffic-load-balancer) + - [Zero downtime updates](../administration/reference_architectures/index.md#zero-downtime-updates) +- Repositories: + - [Repository size limit](../user/admin_area/settings/account_and_limit_settings.md#repository-size-limit) + - Repository mirroring: + - [Pull mirroring](../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository) outside repositories in a GitLab repository + - [Overwrite diverged branches](../user/project/repository/repository_mirroring.md#overwrite-diverged-branches) + - [Trigger pipelines for mirror updates](../user/project/repository/repository_mirroring.md#trigger-pipelines-for-mirror-updates) + - [Hard failures](../user/project/repository/repository_mirroring.md#hard-failure) when mirroring fails + - [Trigger pull mirroring from the API](../user/project/repository/repository_mirroring.md#trigger-an-update-using-the-api) + - [Mirror only protected branches](../user/project/repository/repository_mirroring.md#mirror-only-protected-branches) + - [Bidirectional mirroring](../user/project/repository/repository_mirroring.md#bidirectional-mirroring) + - [Mirroring with Perforce Helix via Git Fusion](../user/project/repository/repository_mirroring.md#mirroring-with-perforce-helix-via-git-fusion) +- Runners: + - Run pipelines in the parent project [for merge requests from a forked project](../ci/merge_request_pipelines/index.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project) + - [Shared runners pipeline minutes quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota) +- [Push rules](../push_rules/push_rules.md) +- SAML for self-managed GitLab instance: + - [Administrator groups](../integration/saml.md#admin-groups) + - [Auditor groups](../integration/saml.md#auditor-groups) + - [External groups](../integration/saml.md#external-groups) + - [Required groups](../integration/saml.md#required-groups) +- Search: + - [Filtering merge requests by approvers](../user/search/index.md#filtering-merge-requests-by-approvers) + - [Filtering merge requests by "approved by"](../user/search/index.md#filtering-merge-requests-by-approved-by) + - [Advanced Global Search (Elasticsearch)](../user/search/advanced_global_search.md) + - [Advanced Search Syntax](../user/search/advanced_search_syntax.md) +- [Service Desk](../user/project/service_desk.md) +- [Storage usage statistics](../user/usage_quotas.md#storage-usage-statistics) + +The following developer features continue to be available to Starter and +Bronze-level subscribers: + +- APIs: + - LDAP synchronization: + - Certain fields in the [group details API](../api/groups.md#details-of-a-group) + - [syncing groups](../api/groups.md#sync-group-with-ldap) + - Listing, adding, and deleting [group links](../api/groups.md#list-ldap-group-links) + - [Push rules](../api/groups.md#push-rules) + - [Audit events](../api/audit_events.md), including + [group audit events](../api/groups.md#group-audit-events) and + [project audit events](../api/audit_events.md#project-audit-events) + - Projects API: certain fields in the [Create project API](../api/projects.md) + - [Resource iteration events API](../api/resource_iteration_events.md) + - Group milestones API: [Get all burndown chart events for a single milestone](../api/group_milestones.md#get-all-burndown-chart-events-for-a-single-milestone) + - [Group iterations API](../api/group_iterations.md) + - Project milestones API: [Get all burndown chart events for a single milestone](../api/milestones.md#get-all-burndown-chart-events-for-a-single-milestone) + - [Project iterations API](../api/iterations.md) + - Fields in the [Search API](../api/search.md) available only to [Advanced Global Search (Elasticsearch)](../integration/elasticsearch.md) users + - Fields in the [Merge requests API](../api/merge_requests.md) for [merge request approvals](../user/project/merge_requests/merge_request_approvals.md) + - Fields in the [Protected branches API](../api/protected_branches.md) that specify users or groups allowed to merge + - [Merge request approvals API](../api/merge_request_approvals.md) + - [Visual review discussions API](../api/visual_review_discussions.md) +- Development information: + - [Run Jenkins in a macOS development environment](../development/integrations/jenkins.md) diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md index aef1c1127c5..a600ffe4ed3 100644 --- a/doc/subscriptions/gitlab_com/index.md +++ b/doc/subscriptions/gitlab_com/index.md @@ -5,115 +5,83 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# GitLab.com subscription **(BRONZE ONLY)** +# GitLab SaaS subscription **(PREMIUM SAAS)** -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 +GitLab SaaS is GitLab Inc.'s software-as-a-service offering. You don't need to +install anything to use GitLab SaaS, you only need to [sign up](https://gitlab.com/users/sign_up) and start using GitLab straight away. -This page reviews the details of your GitLab.com subscription. +This page reviews the details of your GitLab SaaS 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 contains 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 contain features with the - subscription applied, but as it's not a group, group features aren't available. - -You can read more about [common misconceptions](https://about.gitlab.com/handbook/marketing/strategic-marketing/enablement/dotcom-subscriptions/#common-misconceptions) regarding a GitLab.com subscription to help avoid issues. - -## Choose a GitLab.com tier +## Choose a GitLab SaaS 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/). +[GitLab SaaS feature comparison](https://about.gitlab.com/pricing/gitlab-com/feature-comparison/). ## Choose the number of users NOTE: Applied only to groups. -A GitLab.com subscription uses a concurrent (_seat_) model. You pay for a +A GitLab SaaS 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 doesn't exceed the subscription count. Every occupied seat is counted in the subscription, with the following exception: -- Members with Guest permissions on a Gold subscription. +- Members with Guest permissions on an Ultimate subscription. NOTE: To support the open source community and encourage the development of open -source projects, GitLab grants access to **Gold** features for all GitLab.com +source projects, GitLab grants access to **Ultimate** features for all GitLab SaaS **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_up). - 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, GitLab prompts you 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_up). - 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, GitLab prompts you 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. +## Obtain a GitLab SaaS subscription + +To subscribe to GitLab SaaS: + +1. Create a user account for yourself using our + [sign up page](https://gitlab.com/users/sign_up). +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 GitLab SaaS plan through the + [Customers Portal](https://customers.gitlab.com/). +1. Link your GitLab SaaS account with your Customers Portal account. + Once a plan has been selected, if your account is not + already linked, GitLab prompts you 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. NOTE: 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 +page to add or change the GitLab SaaS account link. -To see the status of your GitLab.com subscription, log in to GitLab.com and go -to the **Billing** section of the relevant namespace: +## View your GitLab SaaS subscription -- **For individuals**: Visit the [billing page](https://gitlab.com/profile/billings) - under your profile. -- **For groups**: From the group page (*not* from a project in the group), go to **Settings > Billing**. +To see the status of your GitLab SaaS subscription, log in to GitLab SaaS and go +to the **Billing** section: - NOTE: - You must have Owner level [permissions](../../user/permissions.md) to view a group's billing page. +NOTE: +You must have Owner level [permissions](../../user/permissions.md) to view the billing page. - The following table describes details of your subscription for groups: +The following table describes details of your subscription: - | Field | Description | - |-----------------------------|-------------| - | **Seats in subscription** | If this is a paid plan, represents the number of seats you've bought for this group. | - | **Seats currently in use** | Number of seats in use. Select **See usage** to see a list of the users using these seats. For more details, see [Seat usage](#seat-usage). | - | **Max seats used** | Highest number of seats you've used. | - | **Seats owed** | _Seats owed_ = _Max seats used_ - _Seats in subscription_. | - | **Subscription start date** | Date your subscription started. If this is for a Free plan, it's the date you transitioned off your group's paid plan. | - | **Subscription end date** | Date your current subscription ends. Does not apply to Free plans. | +| Field | Description | +|:----------------------------|:------------| +| **Seats in subscription** | If this is a paid plan, represents the number of seats you've bought for this group. | +| **Seats currently in use** | Number of seats in use. Select **See usage** to see a list of the users using these seats. For more details, see [Seat usage](#seat-usage). | +| **Max seats used** | Highest number of seats you've used. | +| **Seats owed** | _Seats owed_ = _Max seats used_ - _Seats in subscription_. | +| **Subscription start date** | Date your subscription started. If this is for a Free plan, it's the date you transitioned off your group's paid plan. | +| **Subscription end date** | Date your current subscription ends. Does not apply to Free plans. | ## Seat usage @@ -147,12 +115,12 @@ For example: | Amir | `ami` | Yes | | Amir | `amr` | No | -## Renew your GitLab.com subscription +## Renew your GitLab SaaS 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) +1. [Prepare for renewal by reviewing your account.](#prepare-for-renewal-by-reviewing-your-account) +1. [Renew your GitLab SaaS subscription.](#renew-or-change-a-gitlab-saas-subscription) ### Prepare for renewal by reviewing your account @@ -180,21 +148,21 @@ It's important to regularly review your user accounts, because: 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 number of [billable users](#view-your-gitlabcom-subscription) exceeds the number included in the subscription, known +If the number of [billable users](#view-your-gitlab-saas-subscription) 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. -### Renew or change a GitLab.com subscription +### Renew or change a GitLab SaaS subscription -You can adjust the number of users before renewing your GitLab.com subscription. +You can adjust the number of users before renewing your GitLab SaaS subscription. -- To renew for more users than are currently included in your GitLab.com plan, [add users to your subscription](#add-users-to-your-subscription). -- To renew for fewer users than are currently included in your GitLab.com plan, +- To renew for more users than are currently included in your GitLab SaaS plan, [add users to your subscription](#add-users-to-your-subscription). +- To renew for fewer users than are currently included in your GitLab SaaS plan, either [disable](../../user/admin_area/activating_deactivating_users.md#deactivating-a-user) or [block](../../user/admin_area/blocking_unblocking_users.md#blocking-a-user) the user accounts you no longer need. For details on upgrading your subscription tier, see -[Upgrade your GitLab.com subscription tier](#upgrade-your-gitlabcom-subscription-tier). +[Upgrade your GitLab SaaS subscription tier](#upgrade-your-gitlab-saas-subscription-tier). #### Automatic renewal @@ -235,7 +203,7 @@ The following is emailed to you: - A payment receipt. You can also access this information in the Customers Portal under [**View invoices**](https://customers.gitlab.com/receipts). -## Upgrade your GitLab.com subscription tier +## Upgrade your GitLab SaaS subscription tier To upgrade your [GitLab tier](https://about.gitlab.com/pricing/): @@ -266,13 +234,12 @@ If you renew or upgrade, your data is accessible again. CI pipeline minutes are the execution time for your [pipelines](../../ci/pipelines/index.md) on GitLab shared runners. Each -[GitLab.com tier](https://about.gitlab.com/pricing/) includes a monthly quota +[GitLab SaaS 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 +- Premium: 10,000 minutes +- Ultimate: 50,000 minutes Quotas apply to: @@ -284,18 +251,18 @@ Quotas apply to: **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. +specific runner set up for your projects, there is no limit to your build time on GitLab SaaS. 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/). +or upgrade your account to a higher [plan](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 +If you're using GitLab SaaS, you can purchase additional CI minutes so your pipelines aren't 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: @@ -303,11 +270,11 @@ main quota. You can find pricing for additional CI/CD minutes in the - Are only used after the shared quota included in your subscription runs out. - Roll over month to month. -To purchase additional minutes for your group on GitLab.com: +To purchase additional minutes for your group on GitLab SaaS: 1. From your group, go to **Settings > Usage Quotas**. 1. Select **Buy additional minutes** and GitLab directs you 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. Locate the subscription card that's linked to your group on GitLab SaaS, click **Buy more CI minutes**, and complete the details about the transaction. 1. Once we have processed your payment, the extra CI minutes are synced to your group namespace. 1. To confirm the available CI minutes, go to your group, then **Settings > Usage Quotas**. @@ -317,7 +284,7 @@ To purchase additional minutes for your personal namespace: 1. Click your avatar, then go to **Settings > Usage Quotas**. 1. Select **Buy additional minutes** and GitLab redirects you 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 are synced to your personal namespace. +1. Locate the subscription card that's linked to your personal namespace on GitLab SaaS, click **Buy more CI minutes**, and complete the details about the transaction. Once we have processed your payment, the extra CI minutes are 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. @@ -348,7 +315,7 @@ locked. Projects can only be unlocked by purchasing more storage subscription un To purchase more storage for either a personal or group namespace: -1. Sign in to GitLab.com. +1. Sign in to GitLab SaaS. 1. From either your personal homepage or the group's page, go to **Settings > Usage Quotas**. 1. For each locked project, total by how much its **Usage** exceeds the free quota and purchased storage. You must purchase the storage increment that exceeds this total. @@ -361,7 +328,7 @@ To purchase more storage for either a personal or group namespace: 1. Select the **Privacy Policy** and **Terms of Service** checkbox. 1. Select **Buy subscription**. 1. Sign out of the Customers Portal. -1. Switch back to the GitLab.com tab and refresh the page. +1. Switch back to the GitLab SaaS tab and refresh the page. The **Purchased storage available** total is incremented by the amount purchased. All locked projects are unlocked and their excess usage is deducted from the additional storage. diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md index 383ba471df4..aff392f61ff 100644 --- a/doc/subscriptions/index.md +++ b/doc/subscriptions/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# GitLab subscription **(STARTER)** +# GitLab subscription **(PREMIUM)** GitLab offers tiers of features. Your subscription determines which tier you have access to. Subscriptions are valid for 12 months. @@ -19,26 +19,26 @@ GitLab provides special subscriptions to participants in: When choosing a subscription, there are two factors to consider: -- [GitLab.com or self-managed](#choose-between-gitlabcom-or-self-managed) +- [GitLab SaaS or GitLab self-managed](#choose-between-gitlab-saas-or-gitlab-self-managed) - [GitLab tier](#choose-a-gitlab-tier) -### Choose between GitLab.com or self-managed +### Choose between GitLab SaaS or GitLab self-managed There are some differences in how a subscription applies, depending if you use -GitLab.com or a self-managed instance: +GitLab SaaS or GitLab self-managed: -- [GitLab.com](gitlab_com/index.md): The GitLab software-as-a-service offering. - You don't need to install anything to use GitLab.com, you only need to +- [GitLab SaaS](gitlab_com/index.md): The GitLab software-as-a-service offering. + You don't need to install anything to use GitLab SaaS, 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. -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 +On a GitLab self-managed instance, a GitLab subscription provides the same set of +features for _all_ users. On GitLab SaaS, you can apply a subscription to either a group or a personal namespace. NOTE: -Subscriptions cannot be transferred between GitLab.com and GitLab self-managed. +Subscriptions cannot be transferred between GitLab SaaS and GitLab self-managed. A new subscription must be purchased and applied as needed. ### Choose a GitLab tier @@ -47,8 +47,8 @@ Pricing is [tier-based](https://about.gitlab.com/pricing/), allowing you to choo the features which fit your budget. For information on what features are available at each tier for each product, see: -- [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/) +- [GitLab SaaS feature comparison](https://about.gitlab.com/pricing/gitlab-com/feature-comparison/) +- [GitLab self-managed feature comparison](https://about.gitlab.com/pricing/self-managed/feature-comparison/) ## Find your subscription @@ -76,7 +76,7 @@ With the [Customers Portal](https://customers.gitlab.com/) you can: - [Change your company details](#change-your-company-details) - [Change your payment method](#change-your-payment-method) - [Change the linked account](#change-the-linked-account) -- [Change the associated namespace](#change-the-associated-namespace) +- [Change the namespace the subscription is linked to](#change-the-linked-namespace) - [Change customers portal account password](#change-customers-portal-account-password) ### Change your personal details @@ -130,27 +130,27 @@ method as the default: ### Change the linked account -To change the GitLab.com account associated with your Customers Portal -account: +To change the GitLab.com account linked to your Customers Portal account: 1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). -1. In a separate browser tab, go to [GitLab.com](https://gitlab.com) and ensure you +1. In a separate browser tab, go to [GitLab SaaS](https://gitlab.com) and ensure you are not logged in. 1. On the Customers Portal page, click **My account > Account details**. 1. Under **Your GitLab.com account**, click **Change linked account**. -1. Log in to the [GitLab.com](https://gitlab.com) account you want to link to the Customers Portal +1. Log in to the [GitLab SaaS](https://gitlab.com) account you want to link to the Customers Portal account. -### Change the associated namespace +### Change the linked namespace -With a linked GitLab.com account: +To change the namespace linked to a subscription: -1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). +1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) with a + [linked](#change-the-linked-account) GitLab SaaS account. 1. Navigate to the **Manage Purchases** page. -1. Click **Change linked namespace**. +1. Select **Change linked namespace**. 1. Select the desired group from the **This subscription is for** dropdown. -1. Click **Proceed to checkout**. +1. Select **Proceed to checkout**. Subscription charges are calculated based on the total number of users in a group, including its subgroups and nested projects. If the total number of users exceeds the number of seats in your subscription, your account is charged for the additional users. @@ -173,7 +173,7 @@ Find more information how to apply and renew at ## GitLab for Open Source subscriptions -All [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/join/) +All [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/) 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. diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md index a9c0337509a..dc98a9415d7 100644 --- a/doc/subscriptions/self_managed/index.md +++ b/doc/subscriptions/self_managed/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# GitLab self-managed subscription **(STARTER ONLY)** +# GitLab self-managed subscription **(PREMIUM SELF)** You can install, administer, and maintain your own GitLab instance. @@ -37,10 +37,10 @@ at each tier, see the ## Subscription seats -A self-managed subscription uses a hybrid model. You pay for a subscription +A GitLab 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, +simultaneous users in the GitLab self-managed installation is checked each quarter, using [Seat Link](#seat-link). ### Billable users @@ -76,15 +76,14 @@ GitLab has several features which can help you manage the number of users: ## Obtain a subscription -To subscribe to GitLab through a self-managed installation: +To subscribe to GitLab through a GitLab self-managed installation: -1. Go to the [Customers Portal](https://customers.gitlab.com/) and purchase a - **Starter**, **Premium**, or **Ultimate** self-managed plan. +1. Go to the [Customers Portal](https://customers.gitlab.com/) and purchase a GitLab 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). NOTE: -If you're purchasing a subscription for an existing **Core** self-managed +If you're purchasing a subscription for an existing **Free** GitLab self-managed instance, ensure you're purchasing enough seats to [cover your users](../../user/admin_area/index.md#administering-users). @@ -114,7 +113,7 @@ It also displays the following important statistics: 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). +then [renew your GitLab self-managed subscription](#renew-a-subscription). ### Prepare for renewal by reviewing your account @@ -203,9 +202,9 @@ An invoice is generated for the renewal and available for viewing or download on > [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 allows GitLab Inc. to provide our GitLab 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 to `customers.gitlab.com` on port `443`. +Seat Link daily sends a count of all users in connected GitLab self-managed instances to GitLab. That information is used to automate prorated reconciliations. The data is sent securely through an encrypted HTTPS connection to `customers.gitlab.com` on port `443`. Seat Link provides **only** the following information to GitLab: @@ -325,11 +324,11 @@ 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 is again accessible. -For self-managed customers, there is a 14-day grace period when your features +For GitLab self-managed customers, there is a 14-day grace period when your features continue to work as-is, after which the entire instance becomes read only. -However, if you remove the license, you immediately revert to Core +However, if you remove the license, you immediately revert to Free features, and the instance become read / write again. ## Contact Support diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index 7e4d274f21b..196d88bc530 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -300,15 +300,11 @@ If the user is blocked via LDAP, `state` is `ldap_blocked`. "updated_at": "2012-07-21T07:38:22Z", "event_name": "group_create", "name": "StoreCloud", - "owner_email": null, - "owner_name": null, "path": "storecloud", "group_id": 78 } ``` -`owner_name` and `owner_email` are always `null`. Please see <https://gitlab.com/gitlab-org/gitlab/-/issues/20011>. - **Group removed:** ```json @@ -317,15 +313,11 @@ If the user is blocked via LDAP, `state` is `ldap_blocked`. "updated_at": "2012-07-21T07:38:22Z", "event_name": "group_destroy", "name": "StoreCloud", - "owner_email": null, - "owner_name": null, "path": "storecloud", "group_id": 78 } ``` -`owner_name` and `owner_email` are always `null`. Please see [issue #20011](https://gitlab.com/gitlab-org/gitlab/-/issues/20011). - **Group renamed:** ```json @@ -337,15 +329,11 @@ If the user is blocked via LDAP, `state` is `ldap_blocked`. "path": "better-name", "full_path": "parent-group/better-name", "group_id": 64, - "owner_name": null, - "owner_email": null, "old_path": "old-name", "old_full_path": "parent-group/old-name" } ``` -`owner_name` and `owner_email` are always `null`. Please see <https://gitlab.com/gitlab-org/gitlab/-/issues/20011>. - **New Group Member:** ```json diff --git a/doc/telemetry/index.md b/doc/telemetry/index.md deleted file mode 100644 index b3b3b0b4fdd..00000000000 --- a/doc/telemetry/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'https://about.gitlab.com/handbook/product/product-intelligence-guide/' ---- - -This document was moved to [another location](https://about.gitlab.com/handbook/product/product-intelligence-guide/). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/telemetry/snowplow.md b/doc/telemetry/snowplow.md deleted file mode 100644 index 709c61b9e64..00000000000 --- a/doc/telemetry/snowplow.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../development/snowplow.md' ---- - -This document was moved to [another location](../development/snowplow.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/topics/airgap/index.md b/doc/topics/airgap/index.md deleted file mode 100644 index 3866ec50253..00000000000 --- a/doc/topics/airgap/index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_to: '../offline/index.md' ---- diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 0e51042193c..1988e3e2890 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -33,8 +33,8 @@ This page gathers all the resources for the topic **Authentication** within GitL - [Atlassian Crowd OmniAuth Provider](../../administration/auth/crowd.md) - [CAS OmniAuth Provider](../../integration/cas.md) - [SAML OmniAuth Provider](../../integration/saml.md) - - [SAML for GitLab.com Groups](../../user/group/saml_sso/index.md) **(SILVER ONLY)** - - [SCIM user provisioning for GitLab.com Groups](../../user/group/saml_sso/scim_setup.md) **(SILVER ONLY)** + - [SAML for GitLab.com Groups](../../user/group/saml_sso/index.md) **(PREMIUM SAAS)** + - [SCIM user provisioning for GitLab.com Groups](../../user/group/saml_sso/scim_setup.md) **(PREMIUM SAAS)** - [Okta SSO provider](../../administration/auth/okta.md) - [Kerberos integration (GitLab EE)](../../integration/kerberos.md) **(STARTER)** @@ -42,12 +42,16 @@ This page gathers all the resources for the topic **Authentication** within GitL - [OAuth 2 Tokens](../../api/README.md#oauth2-tokens) - [Personal access tokens](../../api/README.md#personalproject-access-tokens) -- [Project access tokens](../../api/README.md#personalproject-access-tokens) **(CORE ONLY)** +- [Project access tokens](../../api/README.md#personalproject-access-tokens) **(FREE SELF)** - [Impersonation tokens](../../api/README.md#impersonation-tokens) - [GitLab as an OAuth2 provider](../../api/oauth2.md#gitlab-as-an-oauth2-provider) ## Third-party resources +<!-- vale gitlab.Spelling = NO --> + - [Kanboard Plugin GitLab Authentication](https://github.com/kanboard/plugin-gitlab-auth) - [Jenkins GitLab OAuth Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+OAuth+Plugin) - [OKD - Configuring Authentication and User Agent](https://docs.okd.io/3.11/install_config/configuring_authentication.html#GitLab) + +<!-- vale gitlab.Spelling = YES -->
\ No newline at end of file diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 0d4f86f1284..23928d236e5 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Customizing Auto DevOps +# Customizing Auto DevOps **(CORE)** While [Auto DevOps](index.md) provides great defaults to get you started, you can customize almost everything to fit your needs. Auto DevOps offers everything from custom @@ -163,7 +163,7 @@ to override the default chart values by setting `HELM_UPGRADE_EXTRA_ARGS` to `-- 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. +pre-upgrade 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. diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 78be67a5196..cce1eefce70 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Auto DevOps +# Auto DevOps **(CORE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/37115) in GitLab 10.0. > - Generally available on GitLab 11.0. @@ -157,16 +157,6 @@ as other environment [variables](../../ci/variables/README.md#priority-of-enviro If the CI/CD variable is not set and the cluster setting is left blank, the instance-wide **Auto DevOps domain** setting is used if set. -NOTE: -If you use the [GitLab managed app for Ingress](../../user/clusters/applications.md#ingress), -the URL endpoint should be automatically configured for you. All you must do -is use its value for the `KUBE_INGRESS_BASE_DOMAIN` variable. - -NOTE: -`AUTO_DEVOPS_DOMAIN` was [deprecated in GitLab 11.8](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52363) -and replaced with `KUBE_INGRESS_BASE_DOMAIN`, and removed in -[GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56959). - Auto DevOps requires a wildcard DNS A record matching the base domain(s). For a base domain of `example.com`, you'd need a DNS entry like: diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index effdb4d7b75..ddec5bf9f4d 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Getting started with Auto DevOps +# Getting started with Auto DevOps **(CORE)** This step-by-step guide helps you use [Auto DevOps](index.md) to deploy a project hosted on GitLab.com to Google Kubernetes Engine. @@ -51,7 +51,7 @@ those projects provide a bare-bones application built on some well-known framewo 1. Give your project a name, optionally a description, and make it public so that you can take advantage of the features available in the - [GitLab Gold plan](https://about.gitlab.com/pricing/#gitlab-com). + [GitLab Ultimate plan](https://about.gitlab.com/pricing/).  @@ -177,7 +177,7 @@ 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)** + ([Auto Code Quality](stages.md#auto-code-quality)) - 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)) - The `dependency_scanning` job checks if the application has any dependencies diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index 824874ed4d4..e4e68c9fcb8 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Requirements for Auto DevOps +# Requirements for Auto DevOps **(CORE)** You can set up Auto DevOps for [Kubernetes](#auto-devops-requirements-for-kubernetes), [Amazon Elastic Container Service (ECS)](#auto-devops-requirements-for-amazon-ecs), @@ -46,12 +46,9 @@ To make full use of Auto DevOps with Kubernetes, you need: - **Base domain** (for [Auto Review Apps](stages.md#auto-review-apps), [Auto Deploy](stages.md#auto-deploy), and [Auto Monitoring](stages.md#auto-monitoring)) - You need a domain configured with wildcard DNS, which all of your Auto DevOps - applications use. If you're using the - [GitLab-managed app for Ingress](../../user/clusters/applications.md#ingress), - the URL endpoint is automatically configured for you. - - You must also [specify the Auto DevOps base domain](index.md#auto-devops-base-domain). + You must [specify the Auto DevOps base domain](index.md#auto-devops-base-domain), + which all of your Auto DevOps applications use. This domain must be configured + with wildcard DNS. - **GitLab Runner** (for all stages) diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index 23ba6ad3356..1295d8b3a52 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Stages of Auto DevOps +# Stages of Auto DevOps **(CORE)** The following sections describe the stages of [Auto DevOps](index.md). Read them carefully to understand how each one works. @@ -135,7 +135,7 @@ might want to use a [custom buildpack](customize.md#custom-buildpacks). ## Auto Code Quality -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab](https://about.gitlab.com/pricing/) 9.3. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in GitLab 13.2. Auto Code Quality uses the diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 663060bf59d..bf07743fb0e 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -153,7 +153,7 @@ steps to upgrade to v2: ### Use a specific version of Auto Deploy dependencies -To use a specifc version of Auto Deploy dependencies, specify the previous Auto Deploy +To use a specific version of Auto Deploy dependencies, specify the previous Auto Deploy stable template that contains the [desired version of `auto-deploy-image` and `auto-deploy-app`](#verify-dependency-versions). For example, if the template is bundled in GitLab v13.3, change your `.gitlab-ci.yml` to: diff --git a/doc/topics/autodevops/upgrading_chart.md b/doc/topics/autodevops/upgrading_chart.md deleted file mode 100644 index 2162969b53e..00000000000 --- a/doc/topics/autodevops/upgrading_chart.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'upgrading_auto_deploy_dependencies.md' ---- - -This document was moved to [another location](upgrading_auto_deploy_dependencies.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md index 55432ad61fa..a62bf540ce7 100644 --- a/doc/topics/autodevops/upgrading_postgresql.md +++ b/doc/topics/autodevops/upgrading_postgresql.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Upgrading PostgreSQL for Auto DevOps +# Upgrading PostgreSQL for Auto DevOps **(CORE)** Auto DevOps provides an [in-cluster PostgreSQL database](customize.md#postgresql-database-support) for your application. diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index 6a4608223b4..607d9affc22 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.md @@ -69,7 +69,7 @@ changes by resetting `my-feature-branch` against `my-feature-branch-backup`: ``` Note that if you added changes to `my-feature-branch` after creating the backup branch, -you will lose them when resetting. +you lose them when resetting. ### Regular rebase @@ -116,7 +116,7 @@ example, `release-10-3`. You can also replace `origin` with other remote repositories, for example, `upstream`. To check what remotes you have linked to your local repository, you can run `git remote -v`. -If there are [merge conflicts](#merge-conflicts), Git will prompt you to fix +If there are [merge conflicts](#merge-conflicts), Git prompts you to fix them before continuing the rebase. To learn more, check Git's documentation on [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) @@ -126,13 +126,13 @@ and [rebasing strategies](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) You can use interactive rebase to modify commits. For example, amend a commit message, squash (join multiple commits into one), edit, or delete -commits. It is handy for changing past commit messages, -as well as for organizing the commit history of your branch to keep it clean. +commits. Use a rebase for changing past commit messages, +and organizing the commit history of your branch to keep it clean. NOTE: If you want to keep the default branch commit history clean, you don't need to -manually squash all your commits before merging every merge request; -with [Squash and Merge](../../user/project/merge_requests/squash_and_merge.md) +manually squash all your commits before merging every merge request. +With [Squash and Merge](../../user/project/merge_requests/squash_and_merge.md), GitLab does it automatically. When you want to change anything in recent commits, use interactive @@ -155,16 +155,17 @@ For example, if you're using [Vim](https://www.vim.org/) as the text editor in a macOS's `ZSH` shell, and you want to **squash** all the three commits (join them into one): -1. Press <kbd>i</kbd> on your keyboard to switch to Vim's editing mode. +1. Press <!-- vale gitlab.FirstPerson = NO --> <kbd>i</kbd> <!-- vale gitlab.FirstPerson = YES --> + on your keyboard to switch to Vim's editing mode. 1. Navigate with your keyboard arrows to edit the **second** commit keyword from `pick` to `squash` (or `s`). Do the same to the **third** commit. The first commit should be left **unchanged** (`pick`) as we want to squash the second and third into the first. -1. Press <kbd>Esc</kbd> to leave the editing mode. +1. Press <kbd>Escape</kbd> to leave the editing mode. 1. Type `:wq` to "write" (save) and "quit". 1. Git outputs the commit message so you have a chance to edit it: - - All lines starting with `#` will be ignored and not included in the commit - message. Everything else will be included. + - All lines starting with `#` are ignored and not included in the commit + message. Everything else is included. - To leave it as it is, type `:wq`. To edit the commit message: switch to the editing mode, edit the commit message, and save it as you just did. 1. If you haven't pushed your commits to the remote branch before rebasing, @@ -180,8 +181,8 @@ for a deeper look into interactive rebase. ## Force-push When you perform more complex operations, for example, squash commits, reset or -rebase your branch, you'll have to _force_ an update to the remote branch, -since these operations imply rewriting the commit history of the branch. +rebase your branch, you must _force_ an update to the remote branch. +These operations imply rewriting the commit history of the branch. To force an update, pass the flag `--force` or `-f` to the `push` command. For example: @@ -267,6 +268,6 @@ To fix conflicts locally, you can use the following method: Up to this point, you can run `git rebase --abort` to stop the process. Git aborts the rebase and rolls back the branch to the state you had before running `git rebase`. - Once you run `git rebase --continue` the rebase **cannot** be aborted. + After you run `git rebase --continue` the rebase **cannot** be aborted. 1. [Force-push](#force-push) to your remote branch. diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 6179175b4cd..f4ea884563c 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -14,13 +14,13 @@ larger than 1GB to preserve performance.  -An LFS icon is shown on files tracked by Git LFS to denote if a file is stored -as a blob or as an LFS pointer. +Files tracked by Git LFS display an icon to indicate if the file is stored as a +blob or an LFS pointer. ## How it works Git LFS client talks with the GitLab server over HTTPS. It uses HTTP Basic Authentication -to authorize client requests. Once the request is authorized, Git LFS client receives +to authorize client requests. After the request is authorized, Git LFS client receives instructions from where to fetch or where to push the large file. ## GitLab server configuration @@ -35,18 +35,18 @@ Documentation for GitLab instance administrators is under [LFS administration do ## Known limitations -- Git LFS v1 original API is not supported since it was deprecated early in LFS - development -- When SSH is set as a remote, Git LFS objects still go through HTTPS -- Any Git LFS request will ask for HTTPS credentials to be provided so a good Git - 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)) +- Git LFS v1 original API is not supported, because it was deprecated early in LFS + development. +- When SSH is set as a remote, Git LFS objects still go through HTTPS. +- Any Git LFS request asks for HTTPS credentials to be provided so a good Git + credentials store is recommended. +- Git LFS always assumes HTTPS so if you have GitLab server on HTTP you must + [add the URL to Git configuration manually](#troubleshooting). NOTE: With 8.12 GitLab added LFS support to SSH. The Git LFS communication still goes over HTTP, but now the SSH client passes the correct credentials -to the Git LFS client, so no action is required by the user. +to the Git LFS client. No action is required by the user. ## Using Git LFS @@ -60,8 +60,8 @@ git lfs install # initialize the Git LFS project git lfs track "*.iso" # select the file extensions that you want to treat as large files ``` -Once a certain file extension is marked for tracking as a LFS object you can use -Git as usual without having to redo the command to track a file with the same extension: +After you mark a file extension for tracking as a LFS object you can use +Git as usual without redoing the command to track a file with the same extension: ```shell cp ~/tmp/debian.iso ./ # copy a large file into the current directory @@ -71,7 +71,7 @@ git push origin master # sync the git repo and large file to the ``` **Make sure** that `.gitattributes` is tracked by Git. Otherwise Git -LFS will not be working properly for people cloning the project: +LFS doesn't work properly for people cloning the project: ```shell git add .gitattributes @@ -93,8 +93,8 @@ that are on the remote repository, such as for a branch from origin: git lfs fetch origin master ``` -Make sure your files aren't listed in `.gitignore`, otherwise, they will be ignored by Git thus will not -be pushed to the remote repository. +Make sure your files aren't listed in `.gitignore`, otherwise, they are ignored by Git +and are not pushed to the remote repository. ### Migrate an existing repository to Git LFS @@ -178,7 +178,7 @@ available to the project anymore. Probably the object was removed from the serve ### Invalid status for `<url>` : 501 -Git LFS will log the failures into a log file. +Git LFS logs the failures into a log file. To view this log file, while in project directory: ```shell @@ -201,12 +201,19 @@ If the status `error 501` is shown, it is because: remove the line and try to update your Git LFS client. Only version 1.0.1 and newer are supported. +<!-- vale gitlab.Spelling = NO --> + ### getsockopt: connection refused -If you push a LFS object to a project and you receive an error similar to: -`Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused`, +<!-- vale gitlab.Spelling = YES --> + +If you push an LFS object to a project and receive an error like this, the LFS client is trying to reach GitLab through HTTPS. However, your GitLab -instance is being served on HTTP. +instance is being served on HTTP: + +```plaintext +Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused +``` This behavior is caused by Git LFS using HTTPS connections by default when a `lfsurl` is not set in the Git configuration. @@ -222,10 +229,10 @@ git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs" NOTE: With 8.12 GitLab added LFS support to SSH. The Git LFS communication still goes over HTTP, but now the SSH client passes the correct credentials -to the Git LFS client, so no action is required by the user. +to the Git LFS client. No action is required by the user. -Given that Git LFS uses HTTP Basic Authentication to authenticate the user pushing -the LFS object on every push for every object, user HTTPS credentials are required. +Git LFS authenticates the user with HTTP Basic Authentication on every push for +every object, so user HTTPS credentials are required. By default, Git has support for remembering the credentials for each repository you use. This is described in [Git credentials man pages](https://git-scm.com/docs/gitcredentials). @@ -237,7 +244,7 @@ which you expect to push the objects: git config --global credential.helper 'cache --timeout=3600' ``` -This will remember the credentials for an hour after which Git operations will +This remembers the credentials for an hour, after which Git operations require re-authentication. If you are using OS X you can use `osxkeychain` to store and encrypt your credentials. @@ -258,7 +265,7 @@ If you are storing LFS files outside of GitLab you can disable LFS on the projec It is possible to host LFS objects externally by setting a custom LFS URL with `git config -f .lfsconfig lfs.url https://example.com/<project>.git/info/lfs`. -You might choose to do this if you are using an appliance like a Sonatype Nexus to store LFS data. If you choose to use an external LFS store, -GitLab will not be able to verify LFS objects which means that pushes will fail if you have GitLab LFS support enabled. +You might choose to do this if you are using an appliance like a <!-- vale gitlab.Spelling = NO --> Sonatype Nexus <!-- vale gitlab.Spelling = YES --> to store LFS data. If you choose to use an external LFS store, +GitLab can't verify LFS objects. Pushes then fail if you have GitLab LFS support enabled. -To stop push failure, LFS support can be disabled in the [Project settings](../../../user/project/settings/index.md). This means you will lose GitLab LFS value-adds (Verifying LFS objects, UI integration for LFS). +To stop push failure, LFS support can be disabled in the [Project settings](../../../user/project/settings/index.md), which also disables GitLab LFS value-adds (Verifying LFS objects, UI integration for LFS). diff --git a/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md b/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md index 3bd754aabfb..771b0a465ec 100644 --- a/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md @@ -37,9 +37,9 @@ ones that GitLab developed. ## Migration steps -Since Git Annex files are stored in a sub-directory of the normal repositories -(`.git/annex/objects`) and LFS files are stored outside of the repositories, -they are not compatible as they are using a different scheme. Therefore, the +Git Annex files are stored in a sub-directory of the normal repositories +(`.git/annex/objects`) and LFS files are stored outside of the repositories. +The two aren't compatible as they are using a different scheme. Therefore, the migration has to be done manually per repository. There are basically two steps you need to take in order to migrate from Git @@ -74,17 +74,17 @@ Fire up a terminal, navigate to your Git repository and: ### Disabling Git Annex in your repository Before changing anything, make sure you have a backup of your repository first. -There are a couple of ways to do that, but you can simply clone it to another +There are a couple of ways to do that, but you can clone it to another local path and maybe push it to GitLab if you want a remote backup as well. -Here you'll find a guide on -[how to back up a **git-annex** repository to an external hard drive](https://www.thomas-krenn.com/en/wiki/Git-annex_Repository_on_an_External_Hard_Drive). +A guide on +[how to back up a **git-annex** repository to an external hard drive](https://www.thomas-krenn.com/en/wiki/Git-annex_Repository_on_an_External_Hard_Drive) is also available. -Since Annex files are stored as objects with symlinks and cannot be directly +Because Annex files are stored as objects with symlinks and cannot be directly modified, we need to first remove those symlinks. NOTE: Make sure the you read about the [`direct` mode](https://git-annex.branchable.com/direct_mode/) as it contains -useful information that may fit in your use case. Note that `annex direct` is +information that may fit in your use case. The `annex direct` command is deprecated in Git Annex version 6, so you may need to upgrade your repository if the server also has Git Annex 6 installed. Read more in the [Git Annex troubleshooting tips](../../../administration/git_annex.md#troubleshooting-tips) section. @@ -133,7 +133,7 @@ if the server also has Git Annex 6 installed. Read more in the Deleted branch git-annex (was 2534d2c). ``` - This will `unannex` every file in the repository, leaving the original files. + This command runs `unannex` on every file in the repository, leaving the original files. 1. Switch back to `indirect` mode: @@ -161,7 +161,7 @@ if the server also has Git Annex 6 installed. Read more in the --- At this point, you have two options. Either add, commit and push the files -directly back to GitLab or switch to Git LFS. We will tackle the LFS switch in +directly back to GitLab or switch to Git LFS. The LFS switch is described in the next section. ### Enabling Git LFS in your repository @@ -194,7 +194,7 @@ GitLab.com), therefore, you don't need to do anything server-side. git lfs track images/ # per directory ``` - Once you do that, run `git status` and you'll see `.gitattributes` added + After this, run `git status` to see the `.gitattributes` added to your repository. It collects all file patterns that you chose to track via `git-lfs`. @@ -206,7 +206,7 @@ GitLab.com), therefore, you don't need to do anything server-side. git push ``` - If your remote is set up with HTTP, you will be asked to enter your login + If your remote is set up with HTTP, you are asked to enter your login credentials. If you have [2FA enabled](../../../user/profile/account/two_factor_authentication.md), make sure to use a [personal access token](../../../user/profile/account/two_factor_authentication.md#personal-access-tokens) instead of your password. @@ -244,5 +244,5 @@ git annex uninit - (Blog Post) [Getting Started with Git FLS](https://about.gitlab.com/blog/2017/01/30/getting-started-with-git-lfs-tutorial/) - (Blog Post) [Announcing LFS Support in GitLab](https://about.gitlab.com/blog/2015/11/23/announcing-git-lfs-support-in-gitlab/) - (Blog Post) [GitLab Annex Solves the Problem of Versioning Large Binaries with Git](https://about.gitlab.com/blog/2015/02/17/gitlab-annex-solves-the-problem-of-versioning-large-binaries-with-git/) -- (GitLab Docs) [Git Annex](../../../administration/git_annex.md) -- (GitLab Docs) [Git LFS](index.md) +- [Git Annex](../../../administration/git_annex.md) +- [Git LFS](index.md) diff --git a/doc/topics/git/migrate_to_git_lfs/index.md b/doc/topics/git/migrate_to_git_lfs/index.md deleted file mode 100644 index c530fa1dcb1..00000000000 --- a/doc/topics/git/migrate_to_git_lfs/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../lfs/migrate_to_git_lfs.md' ---- - -This document was moved to [another location](../lfs/migrate_to_git_lfs.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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 f6571c7b277..6edbd29c236 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -7,21 +7,19 @@ type: howto # Numerous undo possibilities in Git -In this tutorial, we will show you different ways of undoing your work in Git, for which -we will assume you have a basic working knowledge of. Check the GitLab +This tutorial shows you different ways of undoing your work in Git. +We assume you have a basic working knowledge of Git. Check the GitLab [Git documentation](../index.md) for reference. -Also, we will only provide some general information of the commands, which is enough -to get you started for the easy cases/examples, but for anything more advanced -please refer to the [Git book](https://git-scm.com/book/en/v2). +We only provide some general information about the commands to get you started. +For more advanced examples, refer to the [Git book](https://git-scm.com/book/en/v2). -We will explain a few different techniques to undo your changes based on the stage -of the change in your current development. Also, keep in mind that [nothing in -Git is really deleted](https://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery). - -This means that until Git automatically cleans detached commits (which cannot be -accessed by branch or tag) it will be possible to view them with `git reflog` command -and access them with direct commit ID. Read more about _[redoing the undo](#redoing-the-undo)_ in the section below. +A few different techniques exist to undo your changes, based on the stage +of the change in your current development. Remember that +[nothing in Git is really deleted](https://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery). +Until Git cleans detached commits - commits that cannot be accessed by branch or tag - +you can view them with `git reflog` command, and access them with direct commit ID. +Read more about [redoing the undo](#redoing-the-undo) in the section below. > For more information about working with Git and GitLab: > @@ -30,13 +28,16 @@ and access them with direct commit ID. Read more about _[redoing the undo](#redo ## Introduction -This guide is organized depending on the [stage of development](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository) -where you want to undo your changes from and if they were shared with other developers -or not. Because Git is tracking changes a created or edited file is in the unstaged state +This guide is organized depending on the [stage of development](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository): + +- Where do you want to undo your changes from? +- Were they shared with other developers? + +Because Git tracks changes, a created or edited file is in the unstaged state (if created it is untracked by Git). After you add it to a repository (`git add`) you put a file into the **staged** state, which is then committed (`git commit`) to your local repository. After that, file can be shared with other developers (`git push`). -Here's what we'll cover in this tutorial: +This tutorial covers: - [Undo local changes](#undo-local-changes) which were not pushed to a remote repository: @@ -54,38 +55,38 @@ Here's what we'll cover in this tutorial: ### Branching strategy -[Git](https://git-scm.com/) is a de-centralized version control system, which means that beside regular +[Git](https://git-scm.com/) is a de-centralized version control system. Beside regular versioning of the whole repository, it has possibilities to exchange changes with other repositories. To avoid chaos with [multiple sources of truth](https://git-scm.com/about/distributed), various -development workflows have to be followed, and it depends on your internal +development workflows have to be followed. It depends on your internal workflow how certain changes or commits can be undone or changed. [GitLab Flow](https://about.gitlab.com/blog/2014/09/29/gitlab-flow/) provides a good balance between developers clashing with each other while -developing the same feature and cooperating seamlessly, but it does not enable +developing the same feature and cooperating seamlessly. However, it does not enable joined development of the same feature by multiple developers by default. When multiple developers develop the same feature on the same branch, clashing -with every synchronization is unavoidable, but a proper or chosen Git Workflow will -prevent that anything is lost or out of sync when the feature is complete. +with every synchronization is unavoidable. However, a proper or chosen Git Workflow +prevents lost or out-of-sync data when the feature is complete. You can also read through this blog post on [Git Tips & Tricks](https://about.gitlab.com/blog/2016/12/08/git-tips-and-tricks/) -to learn how to easily **do** things in Git. +to learn how to do things in Git. ## Undo local changes -Until you push your changes to any remote repository, they will only affect you. +Until you push your changes to any remote repository, they only affect you. That broadens your options on how to handle undoing them. Still, local changes can be on various stages and each stage has a different approach on how to tackle them. ### Unstaged local changes (before you commit) -When a change is made, but it is not added to the staged tree, Git itself -proposes a solution to discard changes to a certain file. +When a change is made, but not added to the staged tree, Git +proposes a solution to discard changes to the file. Suppose you edited a file to change the content using your favorite editor: @@ -93,7 +94,7 @@ Suppose you edited a file to change the content using your favorite editor: vim <file> ``` -Since you did not `git add <file>` to staging, it should be under unstaged files (or +Because you did not `git add <file>` to staging, it should be under unstaged files (or untracked if file was created). You can confirm that with: ```shell @@ -136,32 +137,37 @@ you would like to apply them at some later time. You can read more about it in ### Quickly save local changes -You are working on a feature when a boss drops by with an urgent task. Since your +You are working on a feature when a boss drops by with an urgent task. Because your feature is not complete, but you need to swap to another branch, you can use -`git stash` to save what you had done, swap to another branch, commit, push, -test, then get back to previous feature branch, do `git stash pop` and continue -where you left. +`git stash` to: + +- Save what you have done. +- Swap to another branch. +- Commit, push, and test. +- Return to the feature branch. +- Run `git stash pop`. +- Resume your work. -The example above shows that discarding all changes is not always a preferred option, -but Git provides a way to save them for later, while resetting the repository to state without +The example above shows that discarding all changes is not always a preferred option. +However, Git provides a way to save them for later, while resetting the repository to state without them. This is achieved by Git stashing command `git stash`, which in fact saves your current work and runs `git reset --hard`, but it also has various additional options like: -- `git stash save`, which enables including temporary commit message, which will help you identify changes, among with other options +- `git stash save`, which enables including temporary commit message, which helps you identify changes, among with other options - `git stash list`, which lists all previously stashed commits (yes, there can be more) that were not `pop`ed - `git stash pop`, which redoes previously stashed changes and removes them from stashed list - `git stash apply`, which redoes previously stashed changes, but keeps them on stashed list ### Staged local changes (before you commit) -Let's say you have added some files to staging, but you want to remove them from the -current commit, yet you want to retain those changes - just move them outside -of the staging tree. You also have an option to discard all changes with +If you add some files to staging, but you want to remove them from the +current commit while retaining those changes, move them outside +of the staging tree. You can also discard all changes with `git reset --hard` or think about `git stash` [as described earlier.](#quickly-save-local-changes) -Lets start the example by editing a file, with your favorite editor, to change the -content and add it to staging +Lets start the example by editing a file with your favorite editor to change the +content and add it to staging: ```shell vim <file> @@ -208,17 +214,17 @@ Now you have 4 options to undo your changes: ## Committed local changes -Once you commit, your changes are recorded by the version control system. +After you commit, your changes are recorded by the version control system. Because you haven't pushed to your remote repository yet, your changes are still not public (or shared with other developers). At this point, undoing -things is a lot easier, we have quite some workaround options. Once you push -your code, you'll have less options to troubleshoot your work. +things is a lot easier, we have quite some workaround options. After you push +your code, you have fewer options to troubleshoot your work. ### Without modifying history Through the development process some of the previously committed changes do not -fit anymore in the end solution, or are source of the bugs. Once you find the -commit which triggered bug, or once you have a faulty commit, you can simply +fit anymore in the end solution, or are source of the bugs. After you find the +commit which triggered bug, or identify a faulty commit, you can revert it with `git revert commit-id`. This command inverts (swaps) the additions and @@ -226,19 +232,19 @@ deletions in that commit, so that it does not modify history. Retaining history can be helpful in future to notice that some changes have been tried unsuccessfully in the past. -In our example we will assume there are commits `A`,`B`,`C`,`D`,`E` committed in this order: `A-B-C-D-E`, +In our example we assume there are commits `A`,`B`,`C`,`D`,`E` committed in this order: `A-B-C-D-E`, and `B` is the commit you want to undo. There are many different ways to identify commit -`B` as bad, one of them is to pass a range to `git bisect` command. The provided range includes -last known good commit (we assume `A`) and first known bad commit (where bug was detected - we will assume `E`). +`B` as bad. One of them is to pass a range to `git bisect` command. The provided range includes +last known good commit (we assume `A`) and first known bad commit where the bug was detected (we assume `E`). ```shell 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 the bug/error. We have -4 options on how to remove it (or part of it) from our repository. +Bisect provides us with commit ID of the middle commit to test, and then guide us +through the bisection process. You can read more about it [in official Git Tools](https://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git) +Our example results in commit `B`, which introduced the bug/error. We have +these options to remove all or part of it from our repository: - Undo (swap additions and deletions) changes introduced by commit `B`: @@ -260,13 +266,13 @@ In our example we will end up with commit `B`, that introduced the bug/error. We - There is one command we also must not forget: **creating a new branch** from the point where changes are not applicable or where the development has hit a - dead end. For example you have done commits `A-B-C-D` on your feature-branch + dead end. For example you have done commits `A-B-C-D` on your feature branch and then you figure `C` and `D` are wrong. At this point you either reset to `B` - and do commit `F` (which will cause problems with pushing and if forced pushed also with other developers) - since branch now looks `A-B-F`, which clashes with what other developers have locally (you will - [change history](#with-history-modification)), or you simply checkout commit `B` create + and do commit `F` (which causes problems with pushing and if forced pushed also with other developers) + because the branch now looks `A-B-F`, which clashes with what other developers have locally (you will + [change history](#with-history-modification)), or you checkout commit `B` create a new branch and do commit `F`. In the last case, everyone else can still do their work while you have your new way to get it right and merge it back in later. Alternatively, with GitLab, you can [cherry-pick](../../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) @@ -291,7 +297,7 @@ provides interactive mode (`-i` flag) which enables you to: - **edit** the commit content (changes introduced by commit) and message. - **squash** multiple commits into a single one, and have a custom or aggregated commit message. -- **drop** commits - simply delete them. +- **drop** commits - delete them. - and few more options. Let us check few examples. Again there are commits `A-B-C-D` where you want to @@ -326,8 +332,8 @@ In case you want to modify something introduced in commit `B`. git commit -a ``` -You can find some more examples in [below section where we explain how to modify -history](#how-modifying-history-is-done) +You can find some more examples in the section explaining +[how to modify history](#how-modifying-history-is-done). ### Redoing the Undo @@ -391,12 +397,12 @@ git checkout -b new-path-of-feature ## Undo remote changes with modifying history This is useful when you want to *hide* certain things - like secret keys, -passwords, SSH keys, etc. It is and should not be used to hide mistakes, as -it will make it harder to debug in case there are some other bugs. The main -reason for this is that you loose the real development progress. **Also keep in +passwords, and SSH keys. It is and should not be used to hide mistakes, as +it makes it harder to debug in case there are some other bugs. The main +reason for this is that you loose the real development progress. Keep in mind that, even with modified history, commits are just detached and can still be -accessed through commit ID** - at least until all repositories perform -the cleanup of detached commits (happens automatically). +accessed through commit ID - at least until all repositories perform +the automated cleanup of detached commits.  @@ -404,16 +410,16 @@ the cleanup of detached commits (happens automatically). Modified history breaks the development chain of other developers, as changed 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. +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 +itself), it is acceptable to squash commits into a single one, to present a nicer history of your contribution. Keep in mind that this also removes the comments attached to certain commits in merge requests, so if you need to retain traceability in GitLab, then modifying history is not acceptable. -A feature-branch of a merge request is a public branch and might be used by +A feature branch of a merge request is a public branch and might be used by other developers, but project process and rules might allow or require you to use `git rebase` (command that changes history) to reduce number of displayed commits on target branch after reviews are done (for example @@ -427,7 +433,7 @@ Never modify the commit history of `master` or shared branch. ### How modifying history is done After you know what you want to modify (how far in history or how which range of -old commits), use `git rebase -i commit-id`. This command will then display all the commits from +old commits), use `git rebase -i commit-id`. This command displays all the commits from current version to chosen commit ID and allow modification, squashing, deletion of that commits. @@ -458,12 +464,12 @@ pick <commit3-id> <commit3-commit-message> ``` NOTE: -It is important to notice that comment from the output clearly states that, if -you decide to abort, then do not just close your editor (as that will in-fact -modify history), but remove all uncommented lines and save. +The comment from the output clearly states that, if +you decide to abort, don't just close your editor (as that +modifies history), but remove all uncommented lines and save. -That is one of the reasons why `git rebase` should be used carefully on -shared and remote branches. But don't worry, there will be nothing broken until +Use `git rebase` carefully on +shared and remote branches, but rest assured: nothing is broken until you push back to the remote repository (so you can freely explore the different outcomes locally). @@ -486,7 +492,7 @@ file from history altogether use: git filter-branch --tree-filter 'rm filename' HEAD ``` -Since `git filter-branch` command might be slow on big repositories, there are +Because `git filter-branch` command might be slow on big repositories, there are tools that can use some of Git specifics to enable faster execution of common tasks (which is exactly what removing sensitive information file is about). An alternative is the open source community-maintained tool [BFG](https://rtyley.github.io/bfg-repo-cleaner/). @@ -497,8 +503,8 @@ Refer [Reduce repository size](../../../user/project/repository/reducing_the_rep ## Conclusion -There are various options of undoing your work with any version control system, but -because of de-centralized nature of Git, these options are multiplied (or limited) +Various options exist for undoing your work with any version control system, but +because of the de-centralized nature of Git, these options are multiplied (or limited) depending on the stage of your process. Git also enables rewriting history, but that should be avoided as it might cause problems when multiple developers are contributing to the same codebase. diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index aace979004f..0724e503923 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_git.md @@ -14,7 +14,7 @@ with Git. ## Broken pipe errors on `git push` 'Broken pipe' errors can occur when attempting to push to a remote repository. -When pushing you will usually see: +When pushing you usually see: ```plaintext Write failed: Broken pipe @@ -45,14 +45,13 @@ set to 50MB. The default is 1MB. **If pushing over SSH**, first check your SSH configuration as 'Broken pipe' errors can sometimes be caused by underlying issues with SSH (such as authentication). Make sure that SSH is correctly configured by following the -instructions in the [SSH troubleshooting](../../ssh/README.md#troubleshooting) docs. +instructions in the [SSH troubleshooting](../../ssh/README.md#troubleshooting) documentation. -There's another option where you can prevent session timeouts by configuring -SSH 'keep alive' either on the client or on the server (if you are a GitLab -admin and have access to the server). +If you're a GitLab administrator and have access to the server, you can also prevent +session timeouts by configuring SSH `keep alive` either on the client or on the server. NOTE: -Configuring *both* the client and the server is unnecessary. +Configuring both the client and the server is unnecessary. **To configure SSH on the client side**: @@ -67,7 +66,7 @@ Configuring *both* the client and the server is unnecessary. - On Windows, if you are using PuTTY, go to your session properties, then navigate to "Connection" and under "Sending of null packets to keep - session active", set "Seconds between keepalives (0 to turn off)" to `60`. + session active", set `Seconds between keepalives (0 to turn off)` to `60`. **To configure SSH on the server side**, edit `/etc/ssh/sshd_config` and add: @@ -125,7 +124,7 @@ MaxStartups 100:30:200 ``` `100:30:200` means up to 100 SSH sessions are allowed without restriction, -after which 30% of connections will be dropped until reaching an absolute maximum of 200. +after which 30% of connections are dropped until reaching an absolute maximum of 200. Once configured, restart the SSH daemon for the change to take effect. @@ -140,7 +139,7 @@ sudo service sshd restart ## Timeout during `git push` / `git pull` If pulling/pushing from/to your repository ends up taking more than 50 seconds, -a timeout will be issued with a log of the number of operations performed +a timeout is issued. It contains a log of the number of operations performed and their respective timings, like the example below: ```plaintext @@ -154,7 +153,7 @@ and provide GitLab with more information on how to improve the service. ## `git clone` over HTTP fails with `transfer closed with outstanding read data remaining` error -If the buffer size is lower than what is allowed in the request, the action will fail with an error similar to the one below: +If the buffer size is lower than what is allowed in the request, the action fails with an error similar to the one below: ```plaintext error: RPC failed; curl 18 transfer closed with outstanding read data remaining @@ -163,7 +162,7 @@ fatal: early EOF fatal: index-pack failed ``` -This can be fixed by increasing the existing `http.postBuffer` value to one greater than the repository size. For example, if `git clone` fails when cloning a 500M repository, the solution will be to set `http.postBuffer` to `524288000` so that the request only starts buffering after the first 524288000 bytes. +This can be fixed by increasing the existing `http.postBuffer` value to one greater than the repository size. For example, if `git clone` fails when cloning a 500M repository, you should set `http.postBuffer` to `524288000`. That setting ensures the request only starts buffering after the first 524288000 bytes. NOTE: The default value of `http.postBuffer`, 1 MiB, is applied if the setting is not configured. diff --git a/doc/topics/git/useful_git_commands.md b/doc/topics/git/useful_git_commands.md index 6b4d1e06c2c..cef95746bb1 100644 --- a/doc/topics/git/useful_git_commands.md +++ b/doc/topics/git/useful_git_commands.md @@ -7,8 +7,8 @@ type: reference # Useful Git commands -Here are some useful Git commands collected by the GitLab support team. You may not -need to use often, but they can come in handy when needed. +The GitLab support team has collected these commands to help you. You may not +need to use them often. ## Remotes @@ -182,7 +182,7 @@ Git includes a complete set of [traces for debugging Git commands](https://git-s ### Rebase your branch onto master -The -i flag stands for 'interactive': +The `-i` flag stands for 'interactive': ```shell git rebase -i master diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index 87d8129dc7f..97135e421f8 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -16,7 +16,7 @@ It combines [feature-driven development](https://en.wikipedia.org/wiki/Feature-d Organizations coming to Git from other version control systems frequently find it hard to develop a productive workflow. This article describes GitLab flow, which integrates the Git workflow with an issue tracking system. -It offers a simple, transparent, and effective way to work with Git. +It offers a transparent and effective way to work with Git.  @@ -28,7 +28,7 @@ After getting used to these three steps, the next challenge is the branching mod  -Since many organizations new to Git have no conventions for how to work with it, their repositories can quickly become messy. +Because many organizations new to Git have no conventions for how to work with it, their repositories can quickly become messy. The biggest problem is that many long-running branches emerge that all contain part of the changes. People have a hard time figuring out which branch has the latest code, or which branch to deploy to production. Frequently, the reaction to this problem is to adopt a standardized pattern such as [Git flow](https://nvie.com/posts/a-successful-git-branching-model/) and [GitHub flow](http://scottchacon.com/2011/08/31/github-flow.html). @@ -38,8 +38,12 @@ For a video introduction of how this works in GitLab, see [GitLab Flow](https:// ## Git flow and its problems +<!-- vale gitlab.Spelling = NO --> +  +<!-- vale gitlab.Spelling = YES --> + Git flow was one of the first proposals to use Git branches, and it has received a lot of attention. It suggests a `master` branch and a separate `develop` branch, as well as supporting branches for features, releases, and hotfixes. The development happens on the `develop` branch, moves to a release branch, and is finally merged into the `master` branch. @@ -47,7 +51,7 @@ The development happens on the `develop` branch, moves to a release branch, and Git flow is a well-defined standard, but its complexity introduces two problems. The first problem is that developers must use the `develop` branch and not `master`. `master` is reserved for code that is released to production. It is a convention to call your default branch `master` and to mostly branch from and merge to this. -Since most tools automatically use the `master` branch as the default, it is annoying to have to switch to another branch. +Because most tools automatically use the `master` branch as the default, it is annoying to have to switch to another branch. The second problem of Git flow is the complexity introduced by the hotfix and release branches. These branches can be a good idea for some organizations but are overkill for the vast majority of them. @@ -61,28 +65,32 @@ For example, many projects do releases but don't need to do hotfixes. ## GitHub flow as a simpler alternative - + In reaction to Git flow, GitHub created a simpler alternative. [GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `master` branch. This flow is clean and straightforward, and many organizations have adopted it with great success. Atlassian recommends [a similar strategy](https://www.atlassian.com/blog/git/simple-git-workflow-is-simple), although they rebase feature branches. -Merging everything into the `master` branch and frequently deploying means you minimize the amount of unreleased code, which is in line with lean and continuous delivery best practices. +Merging everything into the `master` branch and frequently deploying means you minimize the amount of unreleased code. This approach is in line with lean and continuous delivery best practices. However, this flow still leaves a lot of questions unanswered regarding deployments, environments, releases, and integrations with issues. With GitLab flow, we offer additional guidance for these questions. ## Production branch with GitLab flow - + GitHub flow assumes you can deploy to production every time you merge a feature branch. -While this is possible in some cases, such as SaaS applications, there are many cases where this is not possible. -One case is where you don't control the timing of a release, for example, an iOS application that is released when it passes App Store validation. -Another case is when you have deployment windows — for example, workdays from 10 AM to 4 PM when the operations team is at full capacity — but you also merge code at other times. +While this is possible in some cases, such as SaaS applications, there are some cases where this is not possible, such as: + +- You don't control the timing of a release. For example, an iOS application that + is released when it passes App Store validation. +- You have deployment windows - for example, workdays from 10 AM to 4 PM when the + operations team is at full capacity - but you also merge code at other times. + In these cases, you can make a production branch that reflects the deployed code. You can deploy a new version by merging `master` into the production branch. -If you need to know what code is in production, you can just checkout the production branch to see. -The approximate time of deployment is easily visible as the merge commit in the version control system. +If you need to know what code is in production, you can check out the production branch to see. +The approximate time of deployment is visible as the merge commit in the version control system. This time is pretty accurate if you automatically deploy your production branch. If you need a more exact time, you can have your deployment script create a tag on each deployment. This flow prevents the overhead of releasing, tagging, and merging that happens with Git flow. @@ -105,10 +113,10 @@ If this is not possible because more manual testing is required, you can send me ## Release branches with GitLab flow - + You only need to work with release branches if you need to release software to the outside world. -In this case, each branch contains a minor version, for example, 2-3-stable, 2-4-stable, etc. +In this case, each branch contains a minor version, such as `2-3-stable` or `2-4-stable`. Create stable branches using `master` as a starting point, and branch as late as possible. By doing this, you minimize the length of time during which you have to apply bug fixes to multiple branches. After announcing a release branch, only add serious bug fixes to the branch. @@ -124,11 +132,11 @@ In this flow, it is not common to have a production branch (or Git flow `master`  Merge or pull requests are created in a Git management application. They ask an assigned person to merge two branches. -Tools such as GitHub and Bitbucket choose the name "pull request" since the first manual action is to pull the feature branch. -Tools such as GitLab and others choose the name "merge request" since the final action is to merge the feature branch. -In this article, we'll refer to them as merge requests. +Tools such as GitHub and Bitbucket choose the name "pull request", because the first manual action is to pull the feature branch. +Tools such as GitLab and others choose the name "merge request", because the final action is to merge the feature branch. +This article refers to them as merge requests. -If you work on a feature branch for more than a few hours, it is good to share the intermediate result with the rest of the team. +If you work on a feature branch for more than a few hours, share the intermediate result with the rest of your team. To do this, create a merge request without assigning it to anyone. Instead, mention people in the description or a comment, for example, "/cc @mark @susan." This indicates that the merge request is not ready to be merged yet, but feedback is welcome. @@ -143,7 +151,7 @@ Also, mention any other people from whom you would like feedback. After the assigned person feels comfortable with the result, they can merge the branch. If the assigned person does not feel comfortable, they can request more changes or close the merge request without merging. -In GitLab, it is common to protect the long-lived branches, e.g., the `master` branch, so that [most developers can't modify them](../user/permissions.md). +In GitLab, it is common to protect the long-lived branches, such as the `master` branch, so [most developers can't modify them](../user/permissions.md). So, if you want to merge into a protected branch, assign your merge request to someone with maintainer permissions. After you merge a feature branch, you should remove it from the source control software. @@ -165,10 +173,10 @@ GitLab flow is a way to make the relation between the code and the issue tracker Any significant change to the code should start with an issue that describes the goal. Having a reason for every code change helps to inform the rest of the team and to keep the scope of a feature branch small. In GitLab, each change to the codebase starts with an issue in the issue tracking system. -If there is no issue yet, create the issue, as long as the change will take a significant amount of work, i.e., more than 1 hour. +If there is no issue yet, create the issue if the change requires more than an hour's work. In many organizations, raising an issue is part of the development process because they are used in sprint planning. The issue title should describe the desired state of the system. -For example, the issue title "As an administrator, I want to remove users without receiving an error" is better than "Admin can't remove users." +For example, the issue title "As an administrator, I want to remove users without receiving an error" is better than "Administrators can't remove users." When you are ready to code, create a branch for the issue from the `master` branch. This branch is the place for any work related to this change. @@ -185,20 +193,20 @@ Start the title of the merge request with `[Draft]`, `Draft:` or `(Draft)` to pr When you think the code is ready, assign the merge request to a reviewer. The reviewer can merge the changes when they think the code is ready for inclusion in the `master` branch. -When they press the merge button, GitLab merges the code and creates a merge commit that makes this event easily visible later on. +When they press the merge button, GitLab merges the code and creates a merge commit that makes this event visible later on. Merge requests always create a merge commit, even when the branch could be merged without one. This merge strategy is called "no fast-forward" in Git. -After the merge, delete the feature branch since it is no longer needed. +After the merge, delete the feature branch, because it is no longer needed. In GitLab, this deletion is an option when merging. Suppose that a branch is merged but a problem occurs and the issue is reopened. -In this case, it is no problem to reuse the same branch name since the first branch was deleted when it was merged. +In this case, it is no problem to reuse the same branch name, because the first branch was deleted when it was merged. At any time, there is at most one branch for every issue. It is possible that one feature branch solves more than one issue. ## Linking and closing issues from merge requests - + Link to issues by mentioning them in commit messages or the description of a merge request, for example, "Fixes #16" or "Duck typing is preferred. See #12." GitLab then creates links to the mentioned issues and creates comments in the issues linking back to the merge request. @@ -212,12 +220,12 @@ 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. +This feature helps you replace a couple of small commits with a single commit, or if you want to make the order more logical. 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. +Because 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. +Also, if someone has already reviewed your code, rebasing makes it hard to tell what changed after the last review. 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. @@ -225,7 +233,7 @@ Rebasing prevents the other authors from being attributed and sharing part of th If a merge involves many commits, it may seem more difficult to undo. You might consider solving this by squashing all the changes into one commit just before merging by using the GitLab [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. +Fortunately, you can 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. @@ -243,8 +251,8 @@ Often, people avoid merge commits by just using rebase to reorder their commits 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 avoid rebasing commits in a feature branch that you're sharing with others. -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. +Rebasing could create more work, as every time you rebase, you may need to resolve the same conflicts. +Sometimes you can reuse recorded resolutions (`rerere`), but merging is better, because 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). A good way to prevent creating many merge commits is to not frequently merge `master` into the feature branch. @@ -270,8 +278,8 @@ You could also use [feature toggles](https://martinfowler.com/bliki/FeatureToggl NOTE: Don't confuse automatic branch testing with continuous integration. -Martin Fowler makes this distinction in [his article about feature branches](https://martinfowler.com/bliki/FeatureBranch.html): -"I've heard people say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit. +Martin Fowler makes this distinction in [an article about feature branches](https://martinfowler.com/bliki/FeatureBranch.html): +"\[People\] say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit. That's continuous building, and a Good Thing, but there's no *integration*, so it's not CI." In conclusion, you should try to prevent merge commits, but not eliminate them. @@ -285,19 +293,19 @@ If you rebase code, the history is incorrect, and there is no way for tools to r Another way to make your development work easier is to commit often. Every time you have a working set of tests and code, you should make a commit. Splitting up work into individual commits provides context for developers looking at your code later. -Smaller commits make it clear how a feature was developed, and they make it easy to roll back to a specific good point in time or to revert one code change without reverting several unrelated changes. +Smaller commits make it clear how a feature was developed. They help you roll back to a specific good point in time, or to revert one code change without reverting several unrelated changes. -Committing often also makes it easy to share your work, which is important so that everyone is aware of what you are working on. +Committing often also helps you share your work, which is important so that everyone is aware of what you are working on. You should push your feature branch frequently, even when it is not yet ready for review. By sharing your work in a feature branch or [a merge request](#mergepull-requests-with-gitlab-flow), you prevent your team members from duplicating work. -Sharing your work before it's complete also allows for discussion and feedback about the changes, which can help improve the code before it gets to review. +Sharing your work before it's complete also allows for discussion and feedback about the changes. This feedback can help improve the code before it gets to review. ## How to write a good commit message  A commit message should reflect your intention, not just the contents of the commit. -It is easy to see the changes in a commit, so the commit message should explain why you made those changes. +You can see the changes in a commit, so the commit message should explain why you made those changes. An example of a good commit message is: "Combine templates to reduce duplicate code in the user views." The words "change," "improve," "fix," and "refactor" don't add much information to a commit message. For example, "Improve XML generation" could be better written as "Properly escape special characters in XML generation." @@ -311,12 +319,12 @@ In old workflows, the continuous integration (CI) server commonly ran tests on t Developers had to ensure their code did not break the `master` branch. When using GitLab flow, developers create their branches from this `master` branch, so it is essential that it never breaks. Therefore, each merge request must be tested before it is accepted. -CI software like Travis CI and GitLab CI/CD show the build results right in the merge request itself to make this easy. +CI software like Travis CI and GitLab CI/CD show the build results right in the merge request itself to simplify the process. There is one drawback to testing merge requests: the CI server only tests the feature branch itself, not the merged result. Ideally, the server could also test the `master` branch after each change. However, retesting on every commit to `master` is computationally expensive and means you are more frequently waiting for test results. -Since feature branches should be short-lived, testing just the branch is an acceptable risk. +Because feature branches should be short-lived, testing just the branch is an acceptable risk. If new commits in `master` cause merge conflicts with the feature branch, merge `master` back into the branch to make the CI server re-run the tests. As said before, if you often have feature branches that last for more than a few days, you should make your issues smaller. diff --git a/doc/university/README.md b/doc/university/README.md index 7d6ecb536a6..26616312f98 100644 --- a/doc/university/README.md +++ b/doc/university/README.md @@ -28,9 +28,13 @@ The GitLab University curriculum is composed of GitLab videos, screencasts, pres ### 1.1. Version Control and Git +<!-- vale gitlab.Spelling = NO --> + 1. [Version Control Systems](https://docs.google.com/presentation/d/16sX7hUrCZyOFbpvnrAFrg6tVO5_yT98IgdAqOmXwBho/edit#slide=id.g72f2e4906_2_29) 1. [Katacoda: Learn Git Version Control using Interactive Browser-Based Scenarios](https://www.katacoda.com/courses/git) +<!-- vale gitlab.Spelling = YES --> + ### 1.2. GitLab Basics 1. [An Overview of GitLab.com - Video](https://www.youtube.com/watch?v=WaiL5DGEMR4) @@ -55,11 +59,14 @@ The GitLab University curriculum is composed of GitLab videos, screencasts, pres ### 1.5. Migrating from other Source Control +<!-- vale gitlab.Spelling = NO --> + 1. [Migrating from Bitbucket/Stash](../user/project/import/bitbucket.md) 1. [Migrating from GitHub](../user/project/import/github.md) 1. [Migrating from SVN](../user/project/import/svn.md) 1. [Migrating from Fogbugz](../user/project/import/fogbugz.md) +<!-- vale gitlab.Spelling = YES --> ### 1.6. The GitLab team 1. [About GitLab](https://about.gitlab.com/company/) @@ -185,6 +192,8 @@ The GitLab University curriculum is composed of GitLab videos, screencasts, pres ### 3.9. Integrations +<!-- vale gitlab.Spelling = NO --> + 1. [How to Integrate Jira and Jenkins with GitLab - Video](https://gitlabmeetings.webex.com/gitlabmeetings/ldr.php?RCID=44b548147a67ab4d8a62274047146415) 1. [How to Integrate Jira with GitLab](../user/project/integrations/jira.md) 1. [How to Integrate Jenkins with GitLab](../integration/jenkins.md) @@ -193,9 +202,11 @@ The GitLab University curriculum is composed of GitLab videos, screencasts, pres 1. [How to Integrate Convox with GitLab](https://about.gitlab.com/blog/2016/06/09/continuous-delivery-with-gitlab-and-convox/) 1. [Getting Started with GitLab and Shippable CI](https://about.gitlab.com/blog/2016/05/05/getting-started-gitlab-and-shippable/) +<!-- vale gitlab.Spelling = YES --> + ## 4. External Articles -1. [2011 WSJ article by Marc Andreessen - Software is Eating the World](https://www.wsj.com/articles/SB10001424053111903480904576512250915629460) +1. [2011 Wall Street Journal article - Software is Eating the World](https://www.wsj.com/articles/SB10001424053111903480904576512250915629460) 1. [2014 Blog post by Chris Dixon - Software eats software development](https://cdixon.org/2014/04/13/software-eats-software-development/) 1. [2015 Venture Beat article - Actually, Open Source is Eating the World](https://venturebeat.com/2015/12/06/its-actually-open-source-software-thats-eating-the-world/) diff --git a/doc/university/bookclub/booklist.md b/doc/university/bookclub/booklist.md deleted file mode 100644 index c0251229916..00000000000 --- a/doc/university/bookclub/booklist.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com' ---- - -Visit our [documentation page](https://docs.gitlab.com) for information about GitLab. diff --git a/doc/university/bookclub/index.md b/doc/university/bookclub/index.md deleted file mode 100644 index c0251229916..00000000000 --- a/doc/university/bookclub/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com' ---- - -Visit our [documentation page](https://docs.gitlab.com) for information about GitLab. diff --git a/doc/university/glossary/README.md b/doc/university/glossary/README.md deleted file mode 100644 index c0251229916..00000000000 --- a/doc/university/glossary/README.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com' ---- - -Visit our [documentation page](https://docs.gitlab.com) for information about GitLab. diff --git a/doc/university/high-availability/aws/README.md b/doc/university/high-availability/aws/README.md deleted file mode 100644 index cfaeea8f5c2..00000000000 --- a/doc/university/high-availability/aws/README.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../install/aws/index.md' ---- - -This document was moved to [another location](../../../install/aws/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/university/process/README.md b/doc/university/process/README.md deleted file mode 100644 index c0251229916..00000000000 --- a/doc/university/process/README.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com' ---- - -Visit our [documentation page](https://docs.gitlab.com) for information about GitLab. diff --git a/doc/university/training/end-user/README.md b/doc/university/training/end-user/README.md deleted file mode 100644 index c0251229916..00000000000 --- a/doc/university/training/end-user/README.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com' ---- - -Visit our [documentation page](https://docs.gitlab.com) for information about GitLab. diff --git a/doc/university/training/topics/explore_gitlab.md b/doc/university/training/topics/explore_gitlab.md deleted file mode 100644 index 584069aa7b0..00000000000 --- a/doc/university/training/topics/explore_gitlab.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../gitlab-basics/README.md' ---- - -This document was moved to [another location](../../../gitlab-basics/README.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/university/training/topics/getting_started.md b/doc/university/training/topics/getting_started.md index fd600624a25..2c3d5fe15de 100644 --- a/doc/university/training/topics/getting_started.md +++ b/doc/university/training/topics/getting_started.md @@ -21,7 +21,7 @@ comments: false git clone <url> ``` -## Central Repos +## Central Repositories - To instantiate a central repository a `--bare` flag is required. - Bare repositories don't allow file editing or committing changes. @@ -34,7 +34,7 @@ comments: false ## Instantiate workflow with clone 1. Create a project in your user namespace. - - Choose to import from 'Any Repo by URL' and use <https://gitlab.com/gitlab-org/training-examples.git>. + - Choose to import from **Any Repository by URL** and use <https://gitlab.com/gitlab-org/training-examples.git>. 1. Create a '`Workspace`' directory in your home directory. 1. Clone the '`training-examples`' project. diff --git a/doc/university/training/topics/gitlab_flow.md b/doc/university/training/topics/gitlab_flow.md deleted file mode 100644 index f6006ce0a60..00000000000 --- a/doc/university/training/topics/gitlab_flow.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_to: '../gitlab_flow.md' ---- diff --git a/doc/university/training/user_training.md b/doc/university/training/user_training.md index ad8f094d185..75c4fe25842 100644 --- a/doc/university/training/user_training.md +++ b/doc/university/training/user_training.md @@ -102,7 +102,7 @@ ssh-rsa AAAAB3NzaC1yc2EAAAADAQEL17Ufacg8cDhlQMS5NhV8z3GHZdhCrZbl4gz you@example. ## Create a project - Create a project in your user namespace. - - Choose to import from 'Any Repo by URL' and use <https://gitlab.com/gitlab-org/training-examples.git>. + - Choose to import from **Any Repository by URL** and use <https://gitlab.com/gitlab-org/training-examples.git>. - Create a '`development`' or '`workspace`' directory in your home directory. - Clone the '`training-examples`' project. @@ -214,9 +214,13 @@ Create your first merge request: ## Feedback and Collaboration resources +<!-- vale gitlab.Spelling = NO --> + Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests: <https://github.com/thoughtbot/guides/tree/master/code-review>. +<!-- vale gitlab.Spelling = YES --> + See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests>. ## Explore GitLab projects diff --git a/doc/update/README.md b/doc/update/README.md index 958beeeb321..b0b690c876d 100644 --- a/doc/update/README.md +++ b/doc/update/README.md @@ -147,7 +147,7 @@ Find where your version sits in the upgrade path below, and upgrade GitLab accordingly, while also consulting the [version-specific upgrade instructions](#version-specific-upgrading-instructions): -`8.11.x` -> `8.12.0` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` -> `13.0.14` -> `13.1.11` - > `13.5.3` +`8.11.x` -> `8.12.0` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` -> `13.0.14` -> `13.1.11` - > `13.x (latest)` The following table, while not exhaustive, shows some examples of the supported upgrade paths. diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md index fb1335acd7d..9a367d218f0 100644 --- a/doc/update/mysql_to_postgresql.md +++ b/doc/update/mysql_to_postgresql.md @@ -15,7 +15,7 @@ NOTE: Support for MySQL was removed in GitLab 12.1. This procedure should be performed **before** installing GitLab 12.1. -[pgloader](https://pgloader.io/) 3.4.1+ is required, confirm with `pgloader -V`. +[pgLoader](https://pgloader.io/) 3.4.1+ is required, confirm with `pgloader -V`. You can install it directly from your distribution, for example in Debian/Ubuntu: @@ -52,7 +52,7 @@ For other distributions, follow the instructions in PostgreSQL's and then install `pgloader`. If you are migrating to a Docker based installation, you must install -pgloader within the container as it is not included in the container image. +pgLoader within the container as it is not included in the container image. 1. Start a shell session in the context of the running container: @@ -60,7 +60,7 @@ pgloader within the container as it is not included in the container image. docker exec -it gitlab bash ``` -1. Install pgloader: +1. Install pgLoader: ```shell apt-get update @@ -142,7 +142,7 @@ new PostgreSQL one: sudo -u gitlab-psql pgloader commands.load ``` -1. Once the migration finishes, you should see a summary table that looks like +1. After the migration finishes, you should see a summary table that looks like the following: ```plaintext @@ -243,7 +243,7 @@ new PostgreSQL one: sudo -u postgres pgloader commands.load ``` -1. Once the migration finishes, you should see a summary table that looks like +1. After the migration finishes, you should see a summary table that looks like the following: ```plaintext diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md index 71c8c701775..e794ad64622 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -96,7 +96,7 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) sudo -u git -H make ``` -### 8. Install/Update `gitlab-elasticsearch-indexer` **(STARTER ONLY)** +### 8. Install/Update `gitlab-elasticsearch-indexer` **(PREMIUM SELF)** Please follow the [install instruction](../integration/elasticsearch.md#installing-elasticsearch). diff --git a/doc/update/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md index 7f190a310b0..36f0078a4f7 100644 --- a/doc/update/upgrading_from_ce_to_ee.md +++ b/doc/update/upgrading_from_ce_to_ee.md @@ -81,7 +81,7 @@ 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 ``` -### 4. Install `gitlab-elasticsearch-indexer` **(STARTER ONLY)** +### 4. Install `gitlab-elasticsearch-indexer` **(PREMIUM SELF)** Please follow the [install instruction](../integration/elasticsearch.md#installing-elasticsearch). diff --git a/doc/update/upgrading_postgresql_using_slony.md b/doc/update/upgrading_postgresql_using_slony.md index c5dd6cf16b7..c9f8f83749c 100644 --- a/doc/update/upgrading_postgresql_using_slony.md +++ b/doc/update/upgrading_postgresql_using_slony.md @@ -40,7 +40,7 @@ If you're not using the Omnibus GitLab package you may have to adjust the paths `pg_dump` and the PostgreSQL installation directory to match the paths of your configuration. -Once the structure dump is generated we also need to generate a dump for the +After the structure dump is generated we also need to generate a dump for the `schema_migrations` table. This table doesn't have any primary keys and as such can't be replicated easily by Slony. To generate this dump run the following command on your active database server: @@ -210,7 +210,7 @@ this output, don't just append it below it. The result looks like this: ] ``` -Once you have the configuration file generated you must install it on both the +After you have the configuration file generated you must install it on both the old and new database. To do so, place it in `/var/opt/gitlab/postgresql/slony/slon_tools.conf` (for which we created the directory earlier on). @@ -218,7 +218,7 @@ directory earlier on). Now that the configuration file is in place we can _finally_ start replicating our database. First we must set up the schema in our new database. To do so make sure that the SQL files we generated earlier can be found in the `/tmp` -directory of the new server. Once these files are in place start a `psql` +directory of the new server. After these files are in place start a `psql` session on this server: ```shell diff --git a/doc/user/account/security.md b/doc/user/account/security.md deleted file mode 100644 index d9db3a25c00..00000000000 --- a/doc/user/account/security.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../profile/account/index.md' ---- - -This document was moved to [profile](../profile/account/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/account/two_factor_authentication.md b/doc/user/account/two_factor_authentication.md deleted file mode 100644 index b085611f747..00000000000 --- a/doc/user/account/two_factor_authentication.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../profile/account/two_factor_authentication.md' ---- - -This document was moved to [profile/account/two_factor_authentication](../profile/account/two_factor_authentication.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md index 62f3bd3625c..653c67ed197 100644 --- a/doc/user/admin_area/abuse_reports.md +++ b/doc/user/admin_area/abuse_reports.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Abuse reports **(CORE ONLY)** +# Abuse reports **(FREE SELF)** View and resolve abuse reports from GitLab users. diff --git a/doc/user/admin_area/analytics/convdev.md b/doc/user/admin_area/analytics/convdev.md deleted file mode 100644 index d0f3a34e15e..00000000000 --- a/doc/user/admin_area/analytics/convdev.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'dev_ops_report.md' ---- - -This document was moved to [another location](dev_ops_report.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index 80108fba060..8e6934856ca 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# DevOps Report **(CORE)** +# 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. @@ -15,7 +15,7 @@ from planning to monitoring. To see DevOps Report, go to **Admin Area > Analytics > DevOps Report**. -## DevOps Score **(CORE)** +## DevOps Score **(FREE)** NOTE: Your GitLab instance's [usage ping](../settings/usage_statistics.md#usage-ping) must be activated in order to use this feature. 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 differdeleted file mode 100644 index 6f7dd5101f2..00000000000 --- a/doc/user/admin_area/analytics/img/cohorts_v13_4.png +++ /dev/null diff --git a/doc/user/admin_area/analytics/img/cohorts_v13_9.png b/doc/user/admin_area/analytics/img/cohorts_v13_9.png Binary files differnew file mode 100644 index 00000000000..3e141f24950 --- /dev/null +++ b/doc/user/admin_area/analytics/img/cohorts_v13_9.png diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index 098d758e42a..5cf5e33f2d2 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -12,6 +12,6 @@ Administrators have access to instance-wide analytics, as shown in **Admin Area There are several kinds of statistics: -- [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. **(CORE)** -- [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how that is changing. **(CORE)** -- [User Cohorts](user_cohorts.md): Display the monthly cohorts of new users and their activities over time. **(CORE)** +- [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. **(FREE)** +- [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how that is changing. **(FREE)** +- [User Cohorts](user_cohorts.md): Display the monthly cohorts of new users and their activities over time. **(FREE)** diff --git a/doc/user/admin_area/analytics/instance_statistics.md b/doc/user/admin_area/analytics/instance_statistics.md index 44fd04198b1..e44dd891029 100644 --- a/doc/user/admin_area/analytics/instance_statistics.md +++ b/doc/user/admin_area/analytics/instance_statistics.md @@ -3,3 +3,6 @@ redirect_to: 'usage_trends.md' --- This document was moved to [another location](usage_trends.md). + +<!-- This redirect file can be deleted after <2022-03-20>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index aeb577b8183..0c0cae09c16 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -4,7 +4,7 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Usage Trends **(CORE)** +# Usage Trends **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235754) in GitLab 13.5 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46962) in GitLab 13.6. diff --git a/doc/user/admin_area/analytics/user_cohorts.md b/doc/user/admin_area/analytics/user_cohorts.md index 7adc9ad59a5..a7c93160b69 100644 --- a/doc/user/admin_area/analytics/user_cohorts.md +++ b/doc/user/admin_area/analytics/user_cohorts.md @@ -4,19 +4,19 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cohorts **(CORE)** +# Cohorts **(FREE)** As a benefit of having the [usage ping active](../settings/usage_statistics.md), you can analyze your users' GitLab activities over time. -To see user cohorts, go to **Admin Area > Analytics > Cohorts**. +To see user cohorts, go to **Admin Area > Overview > Users**. ## Overview How do you interpret the user cohorts table? Let's review an example with the following user cohorts: - + For the cohort of March 2020, three users were added to this server and have been active since this month. One month later (April 2020), two users are still diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index b7f5afe7b70..e2e96f980f5 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -6,7 +6,7 @@ type: howto disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page.html' --- -# GitLab Appearance **(CORE ONLY)** +# GitLab Appearance **(FREE SELF)** There are several options for customizing the appearance of a self-managed instance of GitLab. These settings are accessed from the **Admin Area** in the **Appearance** @@ -20,7 +20,7 @@ used (less than 1MB) and it is automatically resized.  -Once you select and upload an image, click **Update appearance settings** at the bottom +After you select and upload an image, click **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. NOTE: @@ -41,8 +41,7 @@ of the page to activate it in the GitLab instance. ## System header and footer messages -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5023) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.7. -> - [Added](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55057) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55057) to GitLab Free in 11.9. You can add a small header message, a small footer message, or both, to the interface of your GitLab instance. These messages appear on all projects and pages of the diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index c96c57a99eb..6f6aed68620 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Broadcast Messages **(CORE ONLY)** +# Broadcast Messages **(FREE SELF)** GitLab can display broadcast messages to all users of a GitLab instance. There are two types of broadcast messages: diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index 70bb070b13e..02659276b53 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Credentials inventory **(ULTIMATE ONLY)** +# Credentials inventory **(ULTIMATE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20912) in GitLab 12.6. diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index a9bc2ecf324..26551d828bf 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Custom instance-level project templates **(PREMIUM ONLY)** +# Custom instance-level project templates **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index b5fcab58535..d5327aeffd8 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Diff limits administration **(CORE ONLY)** +# Diff limits administration **(FREE SELF)** You can set a maximum size for display of diff files (patches). diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index 81e987d25d6..f41170da975 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Geo nodes Admin Area **(PREMIUM ONLY)** +# Geo nodes Admin Area **(PREMIUM SELF)** You can configure various settings for GitLab Geo nodes. For more information, see [Geo documentation](../../administration/geo/index.md). diff --git a/doc/user/admin_area/img/license_details.png b/doc/user/admin_area/img/license_details.png Binary files differdeleted file mode 100644 index 3e980d9316d..00000000000 --- a/doc/user/admin_area/img/license_details.png +++ /dev/null diff --git a/doc/user/admin_area/img/license_details_v13_8.png b/doc/user/admin_area/img/license_details_v13_8.png Binary files differnew file mode 100644 index 00000000000..dc12649fbe9 --- /dev/null +++ b/doc/user/admin_area/img/license_details_v13_8.png diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 40cb6bd0853..7d77e7a6925 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab Admin Area **(CORE ONLY)** +# GitLab Admin Area **(FREE SELF)** The Admin Area provides a web UI for administering some features of GitLab self-managed instances. @@ -24,20 +24,20 @@ 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 events](#audit-events). | +| **{monitor}** Monitoring | View GitLab [system information](#system-information), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), [requests profiles](#requests-profiles), and [audit events](#audit-events). | | **{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. | | **{slight-frown}** Abuse Reports | Manage [abuse reports](abuse_reports.md) submitted by your users. | | **{license}** License **(STARTER ONLY)** | Upload, display, and remove [licenses](license.md). | | **{cloud-gear}** Kubernetes | Create and manage instance-level [Kubernetes clusters](../instance/clusters/index.md). | -| **{push-rules}** Push Rules **(STARTER ONLY)** | Configure pre-defined Git [push rules](../../push_rules/push_rules.md) for projects. Also, configure [merge requests approvers rules](merge_requests_approvals.md). **(PREMIUM ONLY)** | -| **{location-dot}** Geo **(PREMIUM ONLY)** | Configure and maintain [Geo nodes](geo_nodes.md). | +| **{push-rules}** Push Rules **(STARTER ONLY)** | Configure pre-defined Git [push rules](../../push_rules/push_rules.md) for projects. Also, configure [merge requests approvers rules](merge_requests_approvals.md). **(PREMIUM SELF)** | +| **{location-dot}** Geo **(PREMIUM SELF)** | Configure and maintain [Geo nodes](geo_nodes.md). | | **{key}** Deploy Keys | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys). | -| **{lock}** Credentials **(ULTIMATE ONLY)** | View [credentials](credentials_inventory.md) that can be used to access your instance. | +| **{lock}** Credentials **(ULTIMATE SELF)** | View [credentials](credentials_inventory.md) that can be used to access your instance. | | **{template}** Service Templates | Create [service templates](../project/integrations/services_templates.md) for projects. | | **{labels}** Labels | Create and maintain [labels](labels.md) for your GitLab instance. | -| **{appearance}** Appearance | Customize [GitLab appearance](appearance.md). | +| **{appearance}** Appearance | Customize [GitLab appearance](appearance.md). | | **{settings}** Settings | Modify the [settings](settings/index.md) for your GitLab instance. | ## Admin Dashboard @@ -242,7 +242,7 @@ For each runner, the following attributes are listed: | 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 | +| Last contact | Timestamp indicating when the runner last contacted the GitLab instance | You can also edit, pause, or remove each runner. @@ -267,7 +267,7 @@ For each Gitaly server, the following details are listed: The following topics document the **Monitoring** section of the Admin Area. -### System Info +### System Information The **System Info** page provides the following statistics: @@ -300,7 +300,9 @@ The Sidekiq dashboard consists of the following elements: ### Logs -The **Logs** page provides access to the following log files: +Since GitLab 13.0, **Log** view has been removed from the admin dashboard since the logging does not work in multi-node setups and could cause confusion for administrators by displaying partial information. + +For multi-node systems we recommend ingesting the logs into services like Elasticsearch and Splunk. | Log file | Contents | | :---------------------- | :------- | @@ -312,7 +314,7 @@ The **Logs** page provides access to the following log files: | `integrations_json.log` | Activity between GitLab and integrated systems | | `kubernetes.log` | Kubernetes activity | -The contents of these log files can be useful when troubleshooting a problem. Access is available to GitLab admins, without requiring direct access to the log files. +The contents of these log files can be useful when troubleshooting a problem. For details of these log files and their contents, see [Log system](../../administration/logs.md). @@ -322,6 +324,6 @@ The content of each log file is listed in chronological order. To minimize perfo The **Requests Profiles** page contains the token required for profiling. For more details, see [Request Profiling](../../administration/monitoring/performance/request_profiling.md). -### Audit Events **(PREMIUM ONLY)** +### Audit Events **(PREMIUM SELF)** The **Audit Events** page lists changes made within the GitLab server. With this information you can control, analyze, and track every change. diff --git a/doc/user/admin_area/labels.md b/doc/user/admin_area/labels.md index cc9735df9d6..b5dbf835d70 100644 --- a/doc/user/admin_area/labels.md +++ b/doc/user/admin_area/labels.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Labels administration **(CORE ONLY)** +# Labels administration **(FREE SELF)** In the Admin Area, you can manage labels for the GitLab instance. For more details, see [Labels](../project/labels.md). diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index d06b0c844ec..3541e4d2d16 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -25,7 +25,7 @@ by **signing into your GitLab instance as an admin** or adding it at installation time. As of GitLab Enterprise Edition 9.4.0, a newly-installed instance without an -uploaded license only has the Core features active. A trial license +uploaded license only has the Free features active. A trial license activates all Ultimate features, but after [the trial expires](#what-happens-when-your-license-expires), some functionality is locked. @@ -86,13 +86,13 @@ These methods only add a license at the time of installation. Use the After the license is uploaded, all GitLab Enterprise Edition functionality is active until the end of the license period. When that period ends, the -instance will [fall back](#what-happens-when-your-license-expires) to Core-only +instance will [fall back](#what-happens-when-your-license-expires) to Free-only functionality. You can review the license details at any time in the **License** section of the **Admin Area**. - + ## Notification before the license expires @@ -106,7 +106,7 @@ In case your license expires, GitLab locks down some features like Git pushes, and issue creation, and displays a message to all administrators to inform of the expired license. To get back all the previous functionality, you must upload a new license. -To fall back to having only the Core features active, you must delete the +To fall back to having only the Free features active, you must delete the expired license(s). ### Remove a license diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index 5264f3b770b..d6ffde7be95 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge request approval rules **(PREMIUM ONLY)** +# Merge request approval rules **(PREMIUM SELF)** > Introduced in [GitLab Premium](https://gitlab.com/gitlab-org/gitlab/-/issues/39060) 12.8. diff --git a/doc/user/admin_area/monitoring/convdev.md b/doc/user/admin_area/monitoring/convdev.md deleted file mode 100644 index d9c3950f2e4..00000000000 --- a/doc/user/admin_area/monitoring/convdev.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../analytics/dev_ops_report.md' ---- - -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 deleted file mode 100644 index 2cc9f153de3..00000000000 --- a/doc/user/admin_area/monitoring/dev_ops_report.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../analytics/dev_ops_report.md' ---- - -This document was moved to [another location](../analytics/dev_ops_report.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 3c08a330b13..2d4683911fb 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Health Check **(CORE ONLY)** +# Health Check **(FREE SELF)** > - Liveness and readiness probes were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10416) in GitLab 9.1. > - The `health_check` endpoint was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3888) in GitLab 8.8 and was @@ -15,7 +15,7 @@ type: concepts, howto GitLab provides liveness and readiness probes to indicate service health and reachability to required services. These probes report on the status of the -database connection, Redis connection, and access to the filesystem. These +database connection, Redis connection, and access to the file system. These endpoints [can be provided to schedulers like Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/) to hold traffic until the system is ready or restart the container as needed. 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 028858c96f6..e497c006f24 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Account and limit settings **(CORE ONLY)** +# Account and limit settings **(FREE SELF)** ## Default projects limit @@ -13,7 +13,8 @@ You can change the default maximum number of projects that users can create in t Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. You can increase or decrease that `Default projects limit` value. -- If you set `Default projects limit` to 0, users are not allowed to create projects in their users personal namespace. However, projects can still be created within a group. +- If you set `Default projects limit` to 0, users are not allowed to create projects + in their users personal namespace. However, projects can still be created in a group. ## Max attachment size @@ -22,8 +23,8 @@ Navigate to **Admin Area > Settings > General**, then expand **Account and Limit From here, you can increase or decrease by changing the value in `Maximum attachment size (MB)`. NOTE: -If you choose a size larger than what is currently configured for the web server, -you will likely get errors. See the [troubleshooting section](#troubleshooting) for more +If you choose a size larger than the configured value for the web server, +you may receive errors. See the [troubleshooting section](#troubleshooting) for more details. ## Max push size @@ -39,8 +40,8 @@ Navigate to **Admin Area > Settings > General**, then expand **Account and Limit From here, you can increase or decrease by changing the value in `Maximum import size (MB)`. NOTE: -If you choose a size larger than what is currently configured for the web server, -you will likely get errors. See the [troubleshooting section](#troubleshooting) for more +If you choose a size larger than the configured value for the web server, +you may receive errors. See the [troubleshooting section](#troubleshooting) for more details. ## Personal Access Token prefix @@ -62,14 +63,11 @@ to any PAT generated in the system by any user: It is also possible to configure the prefix via the [settings API](../../../api/settings.md) using the `personal_access_token_prefix` field. -## Repository size limit **(STARTER ONLY)** +## Repository size limit **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/740) in [GitLab Enterprise Edition 8.12](https://about.gitlab.com/releases/2016/09/22/gitlab-8-12-released/#limit-project-size-ee). - -Repositories within your GitLab instance can grow quickly, especially if you are +Repositories in your GitLab instance can grow quickly, especially if you are using LFS. Their size can grow exponentially, rapidly consuming available storage. - -To avoid this from happening, you can set a hard limit for your repositories' size. +To prevent this from happening, you can set a hard limit for your repositories' size. This limit can be set globally, per group, or per project, with per project limits taking the highest priority. @@ -88,7 +86,7 @@ For instance, consider the following workflow: Only a GitLab administrator can set those limits. Setting the limit to `0` means there are no restrictions. -These settings can be found within: +These settings can be found in: - Each project's settings: 1. From the Project's homepage, navigate to **Settings > General**. @@ -104,9 +102,9 @@ These settings can be found within: 1. Fill in the **Size limit per repository (MB)** field. 1. Click **Save changes**. -The first push of a new project, including LFS objects, will be checked for size -and **will** be rejected if the sum of their sizes exceeds the maximum allowed -repository size. +The first push of a new project, including LFS objects, is checked for size. +If the sum of their sizes exceeds the maximum allowed repository size, the push +is rejected. NOTE: The repository size limit includes repository files and LFS, but does not include artifacts, uploads, @@ -121,29 +119,29 @@ For GitLab.com repository size limits, see [accounts and limit settings](../../g ### 413 Request Entity Too Large -If you are attaching a file to a comment or reply in GitLab and receive the `413 Request Entity Too Large` -error, it is likely caused by having a [max attachment size](#max-attachment-size) -larger than what the web server is configured to allow. +When attaching a file to a comment or reply in GitLab displays a `413 Request Entity Too Large` +error, the [max attachment size](#max-attachment-size) +is probably larger than the web server's allowed value. -If you wanted to increase the max attachment size to 200m in a GitLab -[Omnibus](https://docs.gitlab.com/omnibus/) install, for example, you might need to +To increase the max attachment size to 200 MB in a +[Omnibus GitLab](https://docs.gitlab.com/omnibus/) install, you may need to add the line below to `/etc/gitlab/gitlab.rb` before increasing the max attachment size: ```ruby nginx['client_max_body_size'] = "200m" ``` -## Limiting lifetime of personal access tokens **(ULTIMATE ONLY)** +## Limiting lifetime of personal access tokens **(ULTIMATE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab Ultimate 12.6. Users can optionally specify an expiration date for [personal access tokens](../../profile/personal_access_tokens.md). This expiration date is not a requirement, and can be set to any arbitrary date. -Since personal access tokens are the only token needed for programmatic access to GitLab, -organizations with security requirements may want to enforce more protection to require -regular rotation of these tokens. +Personal access tokens are the only tokens needed for programmatic access to GitLab. +However, organizations with security requirements may want to enforce more protection by +requiring the regular rotation of these tokens. ### Setting a limit @@ -165,15 +163,27 @@ Once a lifetime for personal access tokens is set, GitLab will: allowed lifetime. Three hours is given to allow administrators to change the allowed lifetime, or remove it, before revocation takes place. -## Optional enforcement of Personal Access Token expiry **(ULTIMATE ONLY)** +## Enforcement of SSH key expiration **(ULTIMATE SELF)** + +GitLab administrators can choose to enforce the expiration of SSH keys after their expiration dates. +If you enable this feature, this disables all _expired_ SSH keys. + +To do this: + +1. Navigate to **Admin Area > Settings > General**. +1. Expand the **Account and limit** section. +1. Select the **Enforce SSH key expiration** checkbox. + +## Optional enforcement of Personal Access Token expiry **(ULTIMATE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214723) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214723) in GitLab Ultimate 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-optional-enforcement-of-personal-access-token-expiry-feature). **(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). **(FREE SELF)** -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. +GitLab administrators can choose to prevent personal access tokens from expiring +automatically. The tokens are usable after the expiry date, unless they are revoked explicitly. To do this: @@ -181,7 +191,7 @@ To do this: 1. Expand the **Account and limit** section. 1. Uncheck the **Enforce personal access token expiration** checkbox. -### Enable or disable optional enforcement of Personal Access Token expiry Feature **(CORE ONLY)** +### Enable or disable optional enforcement of Personal Access Token expiry Feature **(FREE SELF)** Optional Enforcement of Personal Access Token Expiry is deployed behind a feature flag and is **disabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it for your instance from the [rails console](../../../administration/feature_flags.md#start-the-gitlab-rails-console). @@ -198,7 +208,7 @@ To disable it: Feature.disable(:enforce_pat_expiration) ``` -## Disabling user profile name changes **(PREMIUM ONLY)** +## Disabling user profile name changes **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24605) in GitLab 12.7. @@ -210,4 +220,6 @@ To do this: 1. Check the **Prevent users from changing their profile name** checkbox. NOTE: -When this ability is disabled, GitLab administrators will still be able to update the name of any user in their instance via the [Admin UI](../index.md#administering-users) or the [API](../../../api/users.md#user-modification) +When this ability is disabled, GitLab administrators can still use the +[Admin UI](../index.md#administering-users) or the +[API](../../../api/users.md#user-modification) to update usernames. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 6418be13ee9..789f48bef4b 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -5,14 +5,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Continuous Integration and Deployment Admin settings **(CORE ONLY)** +# Continuous Integration and Deployment Admin settings **(FREE SELF)** 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**.  -## Auto DevOps **(CORE ONLY)** +## Auto DevOps **(FREE SELF)** To enable (or disable) [Auto DevOps](../../../topics/autodevops/index.md) for all projects: @@ -29,7 +29,7 @@ From now on, every existing project and newly created ones that don't have a If you want to disable it for a specific project, you can do so in [its settings](../../../topics/autodevops/index.md#enablingdisabling-auto-devops). -## Maximum artifacts size **(CORE ONLY)** +## Maximum artifacts size **(FREE SELF)** The maximum size of the [job artifacts](../../../administration/job_artifacts.md) can be set at: @@ -65,7 +65,7 @@ To change it at the: NOTE: The setting at all levels is only available to GitLab administrators. -## Default artifacts expiration **(CORE ONLY)** +## Default artifacts expiration **(FREE SELF)** The default expiration time of the [job artifacts](../../../administration/job_artifacts.md) can be set in the Admin Area of your GitLab instance. The syntax of duration is @@ -86,9 +86,9 @@ 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 **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1078) in GitLab Starter 8.16. +> [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. 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 @@ -126,7 +126,7 @@ a group in the **Usage Quotas** page available to the group page settings list.  -## Archive jobs **(CORE ONLY)** +## Archive jobs **(FREE SELF)** Archiving jobs is useful for reducing the CI/CD footprint on the system by removing some of the capabilities of the jobs (metadata needed to run the job), @@ -156,21 +156,9 @@ Area of your GitLab instance (`.gitlab-ci.yml` if not set): 1. Input the new path in the **Default CI configuration path** field. 1. Hit **Save changes** for the changes to take effect. -It is also possible to specify a [custom CI configuration path for a specific project](../../../ci/pipelines/settings.md#custom-ci-configuration-path). +It is also possible to specify a [custom CI/CD configuration path for a specific project](../../../ci/pipelines/settings.md#custom-cicd-configuration-path). -<!-- ## 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. --> - -## Required pipeline configuration **(PREMIUM ONLY)** +## Required pipeline configuration **(PREMIUM SELF)** WARNING: This feature is being re-evaluated in favor of a different @@ -204,7 +192,7 @@ To set required pipeline configuration: ## Package Registry configuration -### NPM Forwarding **(PREMIUM ONLY)** +### NPM Forwarding **(PREMIUM SELF)** GitLab administrators can disable the forwarding of NPM requests to [npmjs.com](https://www.npmjs.com/). @@ -228,3 +216,15 @@ To set the maximum file size: 1. Find the package type you would like to adjust. 1. Enter the maximum file size, in bytes. 1. Click **Save size limits**. + +<!-- ## 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/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 4ebfac57715..2eaff417ba3 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Email **(CORE ONLY)** +# Email **(FREE SELF)** You can customize some of the content in emails sent from your GitLab instance. @@ -13,7 +13,7 @@ You can customize some of the content in emails sent from your GitLab instance. The logo in the header of some emails can be customized, see the [logo customization section](../appearance.md#navigation-bar). -## Custom additional text **(PREMIUM ONLY)** +## Custom additional text **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5031) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.7. @@ -40,7 +40,7 @@ In order to change this option: 1. Select **Save changes**. NOTE: -Once the hostname gets configured, every private commit email using the previous hostname, will not get +After the hostname gets configured, every private commit email using the previous hostname is not recognized by GitLab. This can directly conflict with certain [Push rules](../../../push_rules/push_rules.md) such as `Check whether author is a GitLab user` and `Check whether committer is the current authenticated user`. diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 18ae7e6f05a..0975b93f98f 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -5,10 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# External authorization control **(CORE ONLY)** +# External authorization control **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4216) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27056) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27056) to GitLab Free in 11.10. In highly controlled environments, it may be necessary for access policy to be controlled by an external service that permits access based on project diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index d196dc1730e..3570634b9ba 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Gitaly timeouts **(CORE ONLY)** +# Gitaly timeouts **(FREE SELF)** [Gitaly](../../../administration/gitaly/index.md) timeouts are configurable. The timeouts can be configured to make sure that long running Gitaly calls don't needlessly take up resources. diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 9a661fa9716..89c804ae88b 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index --- -# Admin Area settings **(CORE ONLY)** +# Admin Area settings **(FREE SELF)** As an administrator of a GitLab self-managed instance, you can manage the behavior of your deployment. To do so, select **Admin Area > Settings**. @@ -36,7 +36,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | [Elasticsearch](../../../integration/elasticsearch.md#enabling-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. | | [Kroki](../../../administration/integration/kroki.md#enable-kroki-in-gitlab) | Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). | | [PlantUML](../../../administration/integration/plantuml.md#gitlab) | Allow rendering of PlantUML diagrams in AsciiDoc and Markdown documents. | -| [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) **(FREE ONLY)** | Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). | +| [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) **(FREE SAAS)** | Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). | | [Third party offers](third_party_offers.md) | Control the display of third party offers. | | [Snowplow](../../../development/snowplow.md) | Configure the Snowplow integration. | | [Google GKE](../../project/clusters/add_gke_clusters.md) | Google GKE integration allows you to provision GKE clusters from GitLab. | @@ -52,7 +52,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | Repository maintenance | ([Repository checks](../../../administration/repository_checks.md) and [Housekeeping](../../../administration/housekeeping.md)). Configure automatic Git checks and housekeeping on repositories. | | [Repository static objects](../../../administration/static_objects_external_storage.md) | Serve repository static objects (for example, archives, blobs, ...) from an external storage (for example, a CDN). | -## Templates **(PREMIUM ONLY)** +## Templates **(PREMIUM SELF)** | Option | Description | | ------ | ----------- | @@ -64,7 +64,7 @@ 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)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/README.md). This pipeline configuration is run after the project's own configuration. | +| [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration) **(PREMIUM SELF)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/README.md). This pipeline configuration is run after the project's own configuration. | | [Package Registry](continuous_integration.md#package-registry-configuration) | Settings related to the use and experience of using the GitLab Package Registry. Note there are [risks involved](../../packages/container_registry/index.md#use-with-external-container-registries) in enabling some of these settings. | ## Reporting diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 42fa7fe6f54..0b40e513133 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Instance template repository **(PREMIUM ONLY)** +# Instance template repository **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index adb192f5b4a..18491f92650 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -17,7 +17,7 @@ for all projects that didn't have it already enabled. Only the complete settings for an integration can be inherited. Per-field inheritance is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). -## Manage instance-level default settings for a project integration **(CORE ONLY)** +## Manage instance-level default settings for a project integration **(FREE SELF)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2137) in GitLab 13.3 for project-level integrations. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6 for group-level integrations. diff --git a/doc/user/admin_area/settings/protected_paths.md b/doc/user/admin_area/settings/protected_paths.md index a03156511e2..061e9fa05d3 100644 --- a/doc/user/admin_area/settings/protected_paths.md +++ b/doc/user/admin_area/settings/protected_paths.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Protected paths **(CORE ONLY)** +# Protected paths **(FREE SELF)** Rate limiting is a common technique used to improve the security and durability of a web application. For more details, see diff --git a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md index 9ffd46e9ba6..a9b23b3dc50 100644 --- a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md +++ b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Rate limits on raw endpoints **(CORE ONLY)** +# Rate limits on raw endpoints **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30829) in GitLab 12.2. diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 92ad8eced95..a34a63f4543 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Sign-in restrictions **(CORE ONLY)** +# Sign-in restrictions **(FREE SELF)** You can use **Sign-in restrictions** to customize authentication restrictions for web interfaces as well as Git over HTTP(S). @@ -27,7 +27,7 @@ You can restrict the password authentication for web interface and Git over HTTP When this feature enabled, all users must use the [two-factor authentication](../../profile/account/two_factor_authentication.md). -Once the two-factor authentication is configured as mandatory, the users are allowed +After the two-factor authentication is configured as mandatory, users are allowed to skip forced configuration of two-factor authentication for the configurable grace period in hours. diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index ddd3dbda9cc..2eaf18febff 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Sign-up restrictions **(CORE ONLY)** +# Sign-up restrictions **(FREE SELF)** You can enforce the following restrictions on sign ups: @@ -50,12 +50,12 @@ To enforce confirmation of the email address used for new sign ups: 1. Go to **Admin Area > Settings > General** and expand **Sign-up restrictions**. 1. Select the **Enable email restrictions for sign ups** checkbox, then select **Save changes**. -## User cap **(CORE ONLY)** +## User cap **(FREE SELF)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4315) in GitLab 13.7. > - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-user-cap). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-user-cap). **(FREE SELF)** When the number of billable users reaches the user cap, any user who is added or requests access must be [approved](../approving_users.md#approving-a-user) by an administrator before they can start using @@ -64,7 +64,7 @@ their account. If an administrator increases or removes the user cap, the users in pending approval state are automatically approved in a background job. -### Enable or disable User cap **(CORE ONLY)** +### Enable or disable User cap **(FREE SELF)** User cap is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. @@ -86,7 +86,7 @@ Feature.enable(:admin_new_user_signups_cap) ## Soft email confirmation > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47003) in GitLab 12.2. -> - It's [deployed behind a feature flag](../../..//user/feature_flags.md), disabled by default. +> - It's [deployed behind a feature flag](../../../user/feature_flags.md), 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](#enable-or-disable-soft-email-confirmation). @@ -94,7 +94,7 @@ Feature.enable(:admin_new_user_signups_cap) WARNING: This feature might not be available to you. Check the **version history** note above for details. -The soft email confirmation improves the signup experience for new users by allowing +The soft email confirmation improves the sign-up experience for new users by allowing them to sign in without an immediate confirmation when an email confirmation is required. GitLab shows the user a reminder to confirm their email address, and the user can't create or update pipelines until their email address is confirmed. diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index b6826035116..3e0636ef7ac 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -5,9 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Enforce accepting Terms of Service **(CORE ONLY)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18570) in [GitLab Core](https://about.gitlab.com/pricing/) 10.8. +# Enforce accepting Terms of Service **(FREE SELF)** An admin can enforce acceptance of a terms of service and privacy policy. When this option is enabled, new and existing users must accept the terms. diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 84511339842..59845a8d0d8 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -5,9 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Third party offers **(CORE ONLY)** +# Third party offers **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20379) in [GitLab Core](https://about.gitlab.com/pricing/) 11.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20379) in GitLab Free 11.1. Within GitLab, we inform users of available third-party offers they might find valuable in order to enhance the development of their projects. An example is the Google Cloud Platform free credit diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 06b39d67228..2bb6adbc32b 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Usage statistics **(CORE ONLY)** +# Usage statistics **(FREE SELF)** GitLab Inc. periodically collects information about your instance in order to perform various actions. @@ -20,7 +20,7 @@ usage statistics to GitLab Inc. If your GitLab instance is behind a proxy, set the appropriate [proxy configuration variables](https://docs.gitlab.com/omnibus/settings/environment-variables.html). -## Version Check **(CORE ONLY)** +## Version Check **(FREE SELF)** If enabled, version check informs you if a new version is available and the importance of it through a status. This is shown on the help page (i.e. `/help`) @@ -59,7 +59,7 @@ sequenceDiagram Version Application->>GitLab instance: Response (PNG/SVG) ``` -## Usage Ping **(CORE ONLY)** +## Usage Ping **(FREE SELF)** See [Usage Ping guide](../../../development/usage_ping.md). diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index e2040ef19d6..ba4ef890caa 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# User and IP rate limits **(CORE ONLY)** +# User and IP rate limits **(FREE SELF)** Rate limiting is a common technique used to improve the security and durability of a web application. For more details, see 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 fe1841e7020..5296e70651a 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -5,20 +5,20 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Visibility and access controls **(CORE ONLY)** +# Visibility and access controls **(FREE SELF)** GitLab allows administrators to enforce specific controls. To access the visibility and access control options: -1. Log in to GitLab as an admin. +1. Sign in to GitLab as a user with Administrator [permissions](../../permissions.md). 1. Go to **Admin Area > Settings > General**. 1. Expand the **Visibility and access controls** section. ## Default branch protection This global option defines the branch protection that applies to every repository's default branch. [Branch protection](../../project/protected_branches.md) specifies which roles can push to branches and which roles can delete -branches. In this case _Default_ refers to a repository's default branch, which in most cases is _master_. +branches. In this case _Default_ refers to a repository's default branch, which in most cases is `master`. This setting applies only to each repositories' default branch. To protect other branches, you must configure branch protection in repository. For details, see [Protected Branches](../../project/protected_branches.md). @@ -31,7 +31,7 @@ For more details, see [Protected branches](../../project/protected_branches.md). To change this setting for a specific group, see [Default branch protection for groups](../../group/index.md#changing-the-default-branch-protection-of-a-group) -### Disable group owners from updating default branch protection **(PREMIUM ONLY)** +### Disable group owners from updating default branch protection **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211944) in GitLab 13.0. @@ -57,30 +57,30 @@ To change the default project creation protection: For more details, see [Default project-creation level](../../group/index.md#default-project-creation-level). -## Default project deletion protection **(PREMIUM ONLY)** +## Default project deletion protection **(PREMIUM SELF)** By default, a project can be deleted by anyone with the **Owner** role, either at the project or group level. -To ensure only admin users can delete projects: +To ensure only Administrator users can delete projects: 1. Check the **Default project deletion protection** checkbox. 1. Click **Save changes**. -## Default deletion delay **(PREMIUM ONLY)** +## Default deletion delay **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. -By default, a project marked for deletion will be permanently removed with immediate effect. -By default, a group marked for deletion will be permanently removed after 7 days. +By default, a project marked for deletion is permanently removed with immediate effect. +By default, a group marked for deletion is permanently removed after seven days. 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 (but not a personal namespace) 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 +Projects in a group (but not a personal namespace) can be deleted after a delayed period, by +[configuring in Group Settings](../../group/index.md#enabling-delayed-project-removal). +The default period is seven days, and can be changed. Setting this period to `0` enables immediate removal of projects or groups. To change this period: @@ -149,13 +149,11 @@ For more details, see [Exporting a project and its data](../../../user/project/s ## Enabled Git access protocols -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4696) in GitLab 8.10. - With GitLab access restrictions, you can select with which protocols users can communicate with GitLab. -Disabling an access protocol does not block access to the server itself via those ports. The ports -used for the protocol, SSH or HTTP(S), will still be accessible. The GitLab restrictions apply at the +Disabling an access protocol does not block access to the server itself by using those ports. The ports +used for the protocol, SSH or HTTP(S), are still accessible. The GitLab restrictions apply at the application level. To specify the enabled Git access protocols: @@ -170,26 +168,26 @@ When both SSH and HTTP(S) are enabled, users can choose either protocol. When only one protocol is enabled: -- The project page will only show the allowed protocol's URL, with no option to +- The project page shows only the allowed protocol's URL, with no option to change it. -- A tooltip will be shown when you hover over the URL's protocol, if an action - on the user's part is required, e.g. adding an SSH key, or setting a password. +- A tooltip is shown when you hover over the URL's protocol, if an action + on the user's part is required. For example, adding an SSH key or setting a password.  -On top of these UI restrictions, GitLab will deny all Git actions on the protocol +On top of these UI restrictions, GitLab denies all Git actions on the protocol not selected. WARNING: -Starting with [GitLab 10.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18021), -HTTP(S) protocol will be allowed for Git clone or fetch requests done by GitLab Runner -from CI/CD jobs, even if _Only SSH_ was selected. +GitLab versions [10.7 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18021), +allow the HTTP(S) protocol for Git clone or fetch requests done by GitLab Runner +from CI/CD jobs, even if **Only SSH** was selected. ## Custom Git clone URL for HTTP(S) > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18422) in GitLab 12.4. -You can customize project Git clone URLs for HTTP(S). This will affect the clone +You can customize project Git clone URLs for HTTP(S), which affects the clone panel:  @@ -225,10 +223,9 @@ For more details, see [SSH key restrictions](../../../security/ssh_keys_restrict ## Allow mirrors to be set up for projects -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3586) in GitLab 10.3. - -This option is enabled by default. By disabling it, both [pull and push mirroring](../../project/repository/repository_mirroring.md) will no longer -work in every repository and can only be re-enabled by an admin on a per-project basis. +This option is enabled by default. By disabling it, both +[pull and push mirroring](../../project/repository/repository_mirroring.md) no longer +work in every repository. They can only be re-enabled by an administrator user on a per-project basis.  diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md deleted file mode 100644 index a95501c0bde..00000000000 --- a/doc/user/admin_area/user_cohorts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'analytics/user_cohorts.md' ---- - -This document was moved to [another location](analytics/user_cohorts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index beb2cbfdc58..3b357ffd642 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # CI/CD Analytics -## Pipeline success and duration charts **(CORE)** +## Pipeline success and duration charts **(FREE)** > - Introduced in GitLab 3.1.1 as Commit Stats, and later renamed to Pipeline Charts. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/38318) to CI/CD Analytics in GitLab 12.8. @@ -22,6 +22,29 @@ View pipeline duration history:  +## DORA4 Metrics + +Customer experience is a key metric. Users want to measure platform stability and other +post-deployment performance KPIs, and set targets for customer behavior, experience, and financial +impact. Tracking and measuring these indicators solves an important pain point. Similarly, creating +views that manage products, not projects or repositories, provides users with a more relevant data set. +Since GitLab is a tool for the entire DevOps life-cycle, information from different workflows is +integrated and can be used to measure the success of the teams. + +The DevOps Research and Assessment ([DORA](https://cloud.google.com/blog/products/devops-sre/the-2019-accelerate-state-of-devops-elite-performance-productivity-and-scaling)) +team developed four key metrics that the industry has widely adopted. You can use these metrics as +performance indicators for software development teams: + +- Deployment frequency: How often an organization successfully releases to production. +- Lead time for changes: The amount of time it takes for code to reach production. +- Change failure rate: The percentage of deployments that cause a failure in production. +- Time to restore service: How long it takes an organization to recover from a failure in + production. + +GitLab plans to add support for all the DORA4 metrics at the project and group levels. GitLab added +the first metric, deployment frequency, at the project level for [CI/CD charts](ci_cd_analytics.md#deployment-frequency-charts) +and the [API]( ../../api/project_analytics.md). + ## Deployment frequency charts **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.8. diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 745774480b0..7f052aec9cd 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w --- -# Code Review Analytics **(STARTER)** +# Code Review Analytics **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38062) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.7. diff --git a/doc/user/analytics/cycle_analytics.md b/doc/user/analytics/cycle_analytics.md deleted file mode 100644 index 5c235f6708b..00000000000 --- a/doc/user/analytics/cycle_analytics.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../analytics/value_stream_analytics.md' ---- - -This document was moved to [another location](../analytics/value_stream_analytics.md) - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index caa8972b220..a186009cc15 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -6,6 +6,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Analytics +## Definitions + +When we describe GitLab analytics, we use the following terms: + +- Cycle time: The duration of your value stream, from start to finish. Often displayed in combination with "lead time." GitLab measures cycle time from issue creation to issue close. GitLab displays cycle time in [Value Stream Analytics](value_stream_analytics.md). +- DORA (DevOps Research and Assessment) ["Four Keys"](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance): + - Speed + - Deployment Frequency: How often an organization successfully releases to production. + - Lead Time for Changes: The time it takes for a commit to get into production. This differs from ordinary "lead time" as it "focuses on measuring only the time to deliver a feature once it has been developed", +as described in ([Measuring DevOps Performance](https://devops.com/measuring-devops-performance/)). + - Stability + - Change Failure Rate: The percentage of deployments causing a failure in production. + - Time to Restore Service: How long it takes an organization to recover from a failure in production. +- MTTC (Mean Time to Change): The average duration between idea and delivery. GitLab measures MTTC from issue creation to the issue's latest related merge request's deployment to production. +- MTTD (Mean Time to Detect): The average duration that a bug goes undetected in production. GitLab measures MTTD from deployment of bug to issue creation. +- MTTM (Mean Time To Merge): The average lifespan of a merge request. GitLab measures MTTM from merge request creation to merge request merge (and closed/un-merged merge requests are excluded). For more information, see [Merge Request Analytics](merge_request_analytics.md). +- MTTR (Mean Time to Recover/Repair/Resolution/Resolve/Restore): The average duration that a bug is not fixed in production. GitLab measures MTTR from deployment of bug to deployment of fix. +- Lead time: The duration of the work itself. Often displayed in combination with "cycle time." GitLab measures from issue first merge request creation to issue close. Note: Obviously work started before the creation of the first merge request. We plan to start measuring from "issue first commit" as a better proxy, although still imperfect. GitLab displays lead time in [Value Stream Analytics](value_stream_analytics.md). +- Throughput: The number of issues closed or merge requests merged (not closed) in some period of time. Often measured per sprint. GitLab displays merge request throughput in [Merge Request Analytics](merge_request_analytics.md). +- Value Stream: The entire work process that is followed to deliver value to customers. For example, the [DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/) is a value stream that starts with "plan" and ends with "monitor". GitLab helps you track your value stream using [Value Stream Analytics](value_stream_analytics.md). +- Velocity: The total issue burden completed in some period of time. The burden is usually measured in points or weight, often per sprint. For example, your velocity may be "30 points per sprint". GitLab measures velocity as the total points/weight of issues closed in a given period of time. + ## Instance-level analytics > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in GitLab 12.2. @@ -27,17 +49,17 @@ The following analytics features are available at the group level: - [Issue](../group/issues_analytics/index.md). **(PREMIUM)** - [Productivity](productivity_analytics.md) **(PREMIUM)** - [Repositories](../group/repositories_analytics/index.md) **(PREMIUM)** -- [Value Stream](value_stream_analytics.md). **(PREMIUM)** +- [Value Stream](../group/value_stream_analytics/index.md). **(PREMIUM)** ## Project-level analytics The following analytics features are available at the project level: -- [CI/CD](ci_cd_analytics.md). **(CORE)** +- [CI/CD](ci_cd_analytics.md). **(FREE)** - [Code Review](code_review_analytics.md). **(STARTER)** - [Insights](../project/insights/index.md). **(ULTIMATE)** - [Issue](../group/issues_analytics/index.md). **(PREMIUM)** - [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). **(CORE)** -- [Value Stream](value_stream_analytics.md). **(CORE)** +- [Repository](repository_analytics.md). **(FREE)** +- [Value Stream](value_stream_analytics.md). **(FREE)** diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index 0aa135ab88d..6c6911ff4f4 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. Issue Analytics is a bar graph which illustrates the number of issues created each month. -The default timespan is 13 months, which includes the current month, and the 12 months +The default time span is 13 months, which includes the current month, and the 12 months prior. To access the chart, navigate to your project sidebar and select **{chart}** **Analytics > Issue Analytics**. diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index c0fe19f1f16..6dd50a3be80 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -5,7 +5,7 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Merge Request Analytics **(STARTER)** +# Merge Request Analytics **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229045) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3. diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index 633d7b35087..a06d94caf69 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -16,7 +16,7 @@ long, on average, it takes to deliver features is an enormous endeavor. While [Value Stream Analytics](../analytics/value_stream_analytics.md) focuses on the entire Software Development Life Cycle (SDLC) process, Productivity Analytics provides a way for Engineering Management to drill down in a systematic way to uncover patterns and causes for success or failure at an individual, project, or group level. -Productivity can slow down for many reasons ranging from degrading code base to quickly growing teams. In order to investigate, department or team leaders can start by visualizing the time it takes for merge requests to be merged. +Productivity can slow down for many reasons ranging from degrading codebase to quickly growing teams. In order to investigate, department or team leaders can start by visualizing the time it takes for merge requests to be merged. ## Supported features @@ -60,5 +60,5 @@ GitLab has the ability to filter analytics based on a date range. To filter resu The **Productivity Analytics** dashboard can be accessed only: -- On [Premium or Silver tier](https://about.gitlab.com/pricing/) and above. +- On the [Premium tier](https://about.gitlab.com/pricing/) and above. - By users with [Reporter access](../permissions.md) and above. diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index b5aecff5180..6c41d93d51f 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -4,7 +4,7 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Value Stream Analytics **(CORE)** +# Value Stream Analytics **(FREE)** > - Introduced as Cycle Analytics prior to GitLab 12.3 at the project level. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3 at the group level. diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 674afcb29ee..04ad7852771 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -69,7 +69,7 @@ Examples of both configurations can be found here: 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. +are provided as a file system resource or URL. Follow these steps to configure API fuzzing in GitLab with an OpenAPI specification: @@ -519,7 +519,7 @@ increases as the numbers go up. To use a configuration file, add it to your repo ### 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 +made. You can use this to inject semantic version 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: diff --git a/doc/user/application_security/compliance_dashboard/index.md b/doc/user/application_security/compliance_dashboard/index.md deleted file mode 100644 index 383d2bf2df7..00000000000 --- a/doc/user/application_security/compliance_dashboard/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../compliance/compliance_dashboard/index.md' ---- - -This document was moved to [another location](../../compliance/compliance_dashboard/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 9bde2c28972..5541044fdae 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -182,7 +182,7 @@ scanning by using the following environment variables: | `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_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. | @@ -192,7 +192,7 @@ scanning by using the following environment variables: | `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. | +| `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. | diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 469945246c1..09f17f24470 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -27,12 +27,12 @@ Docker image with the fuzz engine to run your app. |----------|----------------|---------| | 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) | +| 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 | [javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | +| Java | [Javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | | Java | [JQF](https://github.com/rohanpadhye/JQF) (not preferred) | [jqf-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | -| JavaScript | [jsfuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/jsfuzz)| [jsfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/jsfuzz-fuzzing-example) | -| Python | [pythonfuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/pythonfuzz)| [pythonfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/pythonfuzz-fuzzing-example) | +| JavaScript | [`jsfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/jsfuzz)| [jsfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/jsfuzz-fuzzing-example) | +| Python | [`pythonfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/pythonfuzz)| [pythonfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/pythonfuzz-fuzzing-example) | ## Configuration @@ -44,8 +44,18 @@ provided as part of your GitLab installation. To do so, add the following to your `.gitlab-ci.yml` file: ```yaml +stages: + - fuzz + include: - template: Coverage-Fuzzing.gitlab-ci.yml + +my_fuzz_target: + extends: .fuzz_base + script: + # Build your fuzz target binary in these steps, then run it with gitlab-cov-fuzz> + # See our example repos for how you could do this with any of our supported languages + - ./gitlab-cov-fuzz run --regression=$REGRESSION -- <your fuzz target> ``` The included template makes available the [hidden job](../../../ci/yaml/README.md#hide-jobs) @@ -97,7 +107,7 @@ There are two types of jobs: Here's our current suggestion for configuring your fuzz target's timeout: -- Set `COVFUZZ_BRANCH` to the branch where you want to run long-running (async) fuzzing +- Set `COVFUZZ_BRANCH` to the branch where you want to run long-running (asynchronous) fuzzing jobs. This is `master` by default. - Use regression or short-running fuzzing jobs for other branches or merge requests. @@ -178,20 +188,20 @@ To use coverage fuzzing in an offline environment, follow these steps: `NEW_URL_GITLAB_COV_FUZ` is the URL of the private `gitlab-cov-fuzz` clone that you set up in the first step. -### Continuous fuzzing (long-running async fuzzing jobs) +### Continuous fuzzing (long-running asynchronous fuzzing jobs) It's also possible to run the fuzzing jobs longer and without blocking your main pipeline. This configuration uses the GitLab [parent-child pipelines](../../../ci/parent_child_pipelines.md). The full example is available in the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing#running-go-fuzz-from-ci). This example uses Go, but is applicable for any other supported languages. -The suggested workflow in this scenario is to have long-running, async fuzzing jobs on a +The suggested workflow in this scenario is to have long-running, asynchronous fuzzing jobs on a main/development branch, and short, blocking sync fuzzing jobs on all other branches and MRs. This is a good way to balance the needs of letting a developer's per-commit pipeline complete quickly, and also giving the fuzzer a large amount of time to fully explore and test the app. Long-running fuzzing jobs are usually necessary for the coverage guided fuzzer to find deeper bugs -in your latest code base. THe following is an example of what `.gitlab-ci.yml` looks like in this +in your latest codebase. THe following is an example of what `.gitlab-ci.yml` looks like in this workflow (for the full example, see the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing)): ```yaml @@ -207,7 +217,7 @@ sync_fuzzing: async_fuzzing: variables: - COVFUZZ_ADDITIONAL_ARGS: '-max_total_time=3600' + COVFUZZ_ADDITIONAL_ARGS: '-max_total_time=3600' trigger: include: .covfuzz-ci.yml rules: @@ -242,9 +252,9 @@ vulnerability: vulnerability can be Detected, Confirmed, Dismissed, or Resolved. - Project: The project in which the vulnerability exists. - Crash type: The type of crash or weakness in the code. This typically maps to a [CWE](https://cwe.mitre.org/). -- Crash state: A normalized version of the stacktrace, containing the last three functions of the +- Crash state: A normalized version of the stack trace, containing the last three functions of the crash (without random addresses). -- Stacktrace snippet: The last few lines of the stacktrace, which shows details about the crash. +- Stack trace snippet: The last few lines of the stack trace, which shows details about the crash. - Identifier: The vulnerability's identifier. This maps to either a [CVE](https://cve.mitre.org/) or [CWE](https://cwe.mitre.org/). - Severity: The vulnerability's severity. This can be Critical, High, Medium, Low, Info, or Unknown. diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 395a8702d1b..3ce60aa31e8 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -570,7 +570,7 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `DAST_PASSWORD_FIELD` | string | The name of password field at the sign-in HTML form. | | `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | | `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_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. In [GitLab 13.7 and earlier](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/367), was `DAST_AUTH_EXCLUDE_URLS` (which we plan to support until GitLab 14.0). | +| `DAST_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` | @@ -590,6 +590,7 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `DAST_FIRST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | | `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `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` | +| `DAST_AUTH_EXCLUDE_URLS` | URLs | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/289959) in GitLab 13.8, to be removed in 14.0, and replaced by `DAST_EXCLUDE_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 command-line options diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index cecf818edfc..277b20fb37b 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -67,7 +67,7 @@ The following languages and dependency managers are supported: | [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package.json` | [Retire.js](https://retirejs.github.io/retire.js/) | | [NuGet](https://www.nuget.org/) 4.9+ | .NET, C# | [`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) | -| [setuptools](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) (*1*) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile`, `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [`setuptools`](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) (*1*) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile`, `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [sbt](https://www.scala-sbt.org/) 1.2 and below ([Ivy](http://ant.apache.org/ivy/)) | Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | 1. [Pipenv](https://pipenv.pypa.io/en/latest/) projects are scanned when a `Pipfile` is present. @@ -188,7 +188,7 @@ The following variables are used for configuring specific analyzers (used for a | `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) | | `DS_PYTHON_VERSION` | `retire.js` | | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12296) in GitLab 12.1, [removed](https://www.python.org/doc/sunset-python-2/) in GitLab 13.7)| | `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`. Maven and Gradle use the Java version specified by this value. | -| `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repos). | +| `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repositories). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | | `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | | `BUNDLER_AUDIT_UPDATE_DISABLED` | `bundler-audit` | `"false"` | Disable automatic updates for the `bundler-audit` analyzer. Useful if you're running dependency scanning in an offline, air-gapped environment.| @@ -198,12 +198,12 @@ The following variables are used for configuring specific analyzers (used for a | `RETIREJS_NODE_ADVISORY_DB` | `retire.js` | `https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/npmrepository.json` | Path or URL to `retire.js` node vulnerability data file. Note that if the URL hosting the data file uses a custom SSL certificate, for example in an offline installation, you can pass the certificate in the `ADDITIONAL_CA_CERT_BUNDLE` environment variable. | | `RETIREJS_ADVISORY_DB_INSECURE` | `retire.js` | `false` | Enable fetching remote JS and Node vulnerability data files (defined by the `RETIREJS_JS_ADVISORY_DB` and `RETIREJS_NODE_ADVISORY_DB` variables) from hosts using an insecure or self-signed SSL (TLS) certificate. | -### Using private Maven repos +### Using private Maven repositories If your private Maven repository requires login credentials, you can use the `MAVEN_CLI_OPTS` environment variable. -Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos). +Read more on [how to use private Maven repositories](../index.md#using-private-maven-repositories). ## Interacting with the vulnerabilities @@ -375,7 +375,7 @@ Here are the requirements for using dependency scanning in an offline environmen This advisory database is constantly being updated, so you must periodically sync your local copy with GitLab. - _Only if scanning Ruby projects_: Host an offline Git copy of the [advisory database](https://github.com/rubysec/ruby-advisory-db). -- _Only if scanning npm/yarn projects_: Host an offline copy of the [retire.js](https://github.com/RetireJS/retire.js/) [node](https://github.com/RetireJS/retire.js/blob/master/repository/npmrepository.json) and [js](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json) advisory databases. +- _Only if scanning npm/yarn projects_: Host an offline copy of the [`retire.js`](https://github.com/RetireJS/retire.js/) [node](https://github.com/RetireJS/retire.js/blob/master/repository/npmrepository.json) and [`js`](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json) advisory databases. Note that 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 @@ -460,7 +460,7 @@ BUNDLER_AUDIT_ADVISORY_DB_REF_NAME: "master" BUNDLER_AUDIT_ADVISORY_DB_URL: "gitlab.example.com/ruby-advisory-db.git" ``` -#### Python (setuptools) +#### Python (setup tools) When using self-signed certificates for your private PyPi repository, no extra job configuration (aside from the template `.gitlab-ci.yml` above) is needed. However, you must update your `setup.py` to @@ -526,5 +526,9 @@ scanning job might be triggered even if the scanner doesn't support your project ### Issues building projects with npm or yarn packages relying on Python 2 -Python 2 was removed (see: [Python 2 sunsetting](https://www.python.org/doc/sunset-python-2/)) from the `retire.js` analyzer in GitLab 13.7 (analyzer version 2.10.1). Projects using packages +[Python 2 was removed](https://www.python.org/doc/sunset-python-2/) from the `retire.js` analyzer in GitLab 13.7 (analyzer version 2.10.1). Projects using packages with a dependency on this version of Python should use `retire.js` version 2.10.0 or lower (for example, `registry.gitlab.com/gitlab-org/security-products/analyzers/retire.js:2.10.0`). + +### Error: `dependency_scanning is used for configuration only, and its script should not be executed` + +For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 417ce70665c..b7ee256c3d6 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -123,19 +123,12 @@ latest versions of the scanning tools without having to do anything. There are s with this approach, however, and there is a [plan to resolve them](https://gitlab.com/gitlab-org/gitlab/-/issues/9725). -## Viewing security scan information in merge requests **(CORE)** +## Viewing security scan information in merge requests **(FREE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Core 13.5. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Free 13.5. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/273205) in 13.6. > - Report download dropdown [added](https://gitlab.com/gitlab-org/gitlab/-/issues/273418) in 13.7. -> - It's [deployed behind a feature flag](../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It can be enabled or disabled for a single project. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-the-basic-security-widget). **(CORE ONLY)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/249550) in GitLab 13.9. Merge requests which have run security scans let you know that the generated reports are available to download. To download a report, click on the @@ -261,13 +254,13 @@ vulnerability as you learn more over time. #### Dismissing multiple vulnerabilities -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. You can dismiss multiple vulnerabilities at once, providing an optional reason. Selecting the checkboxes on the side of each vulnerability in the list selects that individual vulnerability. Alternatively, you can select all the vulnerabilities in the list by selecting the checkbox in the table header. Deselecting the checkbox in the header deselects all the vulnerabilities in the list. -Once you have selected some vulnerabilities, a menu appears at the top of the table that allows you to select a dismissal reason. +After you have selected some vulnerabilities, a menu appears at the top of the table that allows you to select a dismissal reason. Pressing the "Dismiss Selected" button dismisses all the selected vulnerabilities at once, with the reason you chose.  @@ -281,7 +274,7 @@ You can create an issue for a vulnerability by visiting the vulnerability's page 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 +report. After 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 @@ -395,11 +388,11 @@ must be created. A [security scanner job](#security-scanning-tools) must be enab 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 can enable the `Vulnerability-Check` approval rule. If a license scanning job is enabled, you can 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) @@ -446,7 +439,7 @@ environment. Read how to [operate the Secure scanners in an offline environment](offline_deployments/index.md). -## Using private Maven repos +## Using private Maven repositories If you have a private Apache Maven repository that requires login credentials, you can use the `MAVEN_CLI_OPTS` environment variable @@ -522,13 +515,28 @@ This error appears when the included job's stage (named `test`) isn't declared i To fix this issue, you can either: - Add a `test` stage in your `.gitlab-ci.yml`. -- Change the default stage of the included security jobs. For example, with SpotBugs (SAST): +- Override the default stage of each security job. For example, to use a pre-defined stage name `unit-tests`: ```yaml include: - template: Security/SAST.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml + + stages: + - unit-tests + + dependency_scanning: + stage: unit-tests + + license_scanning: + stage: unit-tests - spotbugs-sast: + sast: + stage: unit-tests + + .secret-analyzer: stage: unit-tests ``` @@ -652,27 +660,16 @@ Analyzer results are displayed in the [job logs](../../ci/jobs/index.md#expand-a or [Security Dashboard](security_dashboard/index.md). There is [an open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/235772) in which changes to this behavior are being discussed. -### Enable or disable the basic security widget **(CORE ONLY)** - -The basic security widget 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](../feature_flags.md) -can opt to disable it. +### Error: job `is used for configuration only, and its script should not be executed` -To enable it: +[Changes made in GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41260) +to the `Security/Dependency-Scanning.gitlab-ci.yml` and `Security/SAST.gitlab-ci.yml` +templates mean that if you enable the `sast` or `dependency_scanning` jobs by setting the `rules` attribute, +they will fail with the error `(job) is used for configuration only, and its script should not be executed`. -```ruby -# For the instance -Feature.enable(:core_security_mr_widget) -# For a single project -Feature.enable(:core_security_mr_widget, Project.find(<project id>)) -``` - -To disable it: +The `sast` or `dependency_scanning` stanzas can be used to make changes to all SAST or Dependency Scanning, +such as changing `variables` or the `stage`, but they cannot be used to define shared `rules`. -```ruby -# For the instance -Feature.disable(:core_security_mr_widget) -# For a single project -Feature.disable(:core_security_mr_widget, Project.find(<project id>)) -``` +There [is an issue open to improve extendability](https://gitlab.com/gitlab-org/gitlab/-/issues/218444). +Please upvote the issue to help with prioritization, and +[contributions are welcomed](https://about.gitlab.com/community/contribute/). diff --git a/doc/user/application_security/license_compliance/index.md b/doc/user/application_security/license_compliance/index.md deleted file mode 100644 index 4c598d851a9..00000000000 --- a/doc/user/application_security/license_compliance/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../compliance/license_compliance/index.md' ---- - -This document was moved to [another location](../../compliance/license_compliance/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/license_management/index.md b/doc/user/application_security/license_management/index.md deleted file mode 100644 index bd67fca529f..00000000000 --- a/doc/user/application_security/license_management/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: ../../compliance/license_compliance/index.md ---- - -This document was moved to [another location](../../compliance/license_compliance/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 14ca27cdabe..9ccb0341a05 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -53,7 +53,7 @@ internally-hosted registry or provide access to the individual scanner images. You must also ensure that your app has access to common package repositories that are not hosted on GitLab.com, such as npm, yarn, or Ruby gems. Packages -from these repos can be obtained by temporarily connecting to a network or by +from these repositories can be obtained by temporarily connecting to a network or by mirroring the packages inside your own offline network. ### Interacting with the vulnerabilities @@ -132,7 +132,7 @@ a bastion, and used only for this specific project. #### Scheduling the updates By default, this project's pipeline runs only once, when the `.gitlab-ci.yml` is added to the -repo. To update the GitLab security scanners and signatures, it's necessary to run this pipeline +repository. To update the GitLab security scanners and signatures, it's necessary to run this pipeline regularly. GitLab provides a way to [schedule pipelines](../../../ci/pipelines/schedules.md). For example, you can set this up to download and store the Docker images every week. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 1f0b461c91b..88bcca5b594 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -4,10 +4,10 @@ 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/#assignments --- -# SAST Analyzers **(CORE)** +# SAST Analyzers **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. -> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to GitLab Free in 13.3. SAST relies on underlying third party tools that are wrapped into what we call "Analyzers". An analyzer is a diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 59887c95c67..b4497a1bde4 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -8,7 +8,7 @@ type: reference, howto # Static Application Security Testing (SAST) > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. -> - All open source (OSS) analyzers were moved to GitLab Core in GitLab 13.3. +> - All open source (OSS) analyzers were moved to GitLab Free in GitLab 13.3. NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) @@ -117,18 +117,18 @@ The following analyzers have multi-project support: #### Enable multi-project support for Security Code Scan Multi-project support in the Security Code Scan requires a Solution (`.sln`) file in the root of -the repository. For details on the Solution format, see the Microsoft reference [Solution (.sln) file](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). +the repository. For details on the Solution format, see the Microsoft reference [Solution (`.sln`) file](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). ### Making SAST analyzers available to all GitLab tiers -All open source (OSS) analyzers have been moved to the GitLab Core tier as of GitLab 13.3. +All open source (OSS) analyzers have been moved to the GitLab Free tier as of GitLab 13.3. #### Summary of features per tier Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Core | In Ultimate | +| Capability | In Free | In Ultimate | |:-----------------------------------------------------------------------------------|:--------------------|:-------------------| | [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | @@ -335,7 +335,7 @@ it via [custom environment variables](#custom-environment-variables). If your private Maven repository requires login credentials, you can use the `MAVEN_CLI_OPTS` environment variable. -Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos). +Read more on [how to use private Maven repositories](../index.md#using-private-maven-repositories). ### Enabling Kubesec analyzer @@ -720,6 +720,10 @@ affected. Read more in For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). +### Error: `sast is used for configuration only, and its script should not be executed` + +For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). + ### Limitation when using rules:exists The [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) @@ -750,3 +754,7 @@ For Maven builds, add the following to your `pom.xml` file: <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> ``` + +### Flawfinder encoding error + +This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/README.md#before_script) feature. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 0ae038924ec..254cfeca326 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -86,7 +86,7 @@ However not all features are available on every tier. See the breakdown below fo Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Core | In Ultimate | +| Capability | In Free | In Ultimate | |:--------------------------------------------------------------------------|:--------------------|:-------------------| | [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | @@ -156,6 +156,19 @@ To override a job definition, (for example, change properties like `variables` o declare a job with the same name as the SAST job to override. Place this new job after the template inclusion and specify any additional keys under it. +WARNING: +Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) +is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. + +#### GIT_DEPTH + +The [`GIT_DEPTH` variable](../../../ci/runners/README.md#shallow-cloning) affects Secret Detection. +The Secret Detection analyzer relies on generating patches between commits to scan content for +secrets. If you override the default, ensure the value is greater than 1. If the number of commits +in an MR is greater than the GIT_DEPTH value, Secret Detection will [fail to detect secrets](#error-couldnt-run-the-gitleaks-command-exit-status-2). + +#### Custom settings example + In the following example, we include the Secret Detection template and at the same time we override the `secret_detection` job with the `SECRET_DETECTION_HISTORIC_SCAN` variable to `true`: @@ -171,10 +184,6 @@ secret_detection: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable takes precedence. -WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. - #### Available variables Secret Detection can be customized by defining available variables: @@ -331,11 +340,15 @@ For information on this, see the [general Application Security troubleshooting s ### Error: `Couldn't run the gitleaks command: exit status 2` -This error is usually caused by the `GIT_DEPTH` value of 50 that is set for all [projects by default](../../../ci/pipelines/settings.md#git-shallow-clone). - -For example, if a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` is set to 50, the Secret Detection job fails as the clone is not deep enough to contain all of the relevant commits. +If a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` variable +is set to 50 (a [project default](../../../ci/pipelines/settings.md#git-shallow-clone)), +the Secret Detection job fails as the clone is not deep enough to contain all of the +relevant commits. -You can confirm this to be the cause of the error by implementing a [logging level](../../application_security/secret_detection/index.md#logging-level) of `debug`. Once implemented, the logs should look similar to the following example, wherein an "object not found" error can be seen: +To confirm this as the cause of the error, set the +[logging level](../../application_security/secret_detection/index.md#logging-level) to `debug`, then +rerun the pipeline. The logs should look similar to the following example. The text "object not +found" is a symptom of this error. ```plaintext ERRO[2020-11-18T18:05:52Z] object not found @@ -343,7 +356,9 @@ ERRO[2020-11-18T18:05:52Z] object not found [ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Gitleaks analysis failed: exit status 2 ``` -If this is the case, we can resolve the issue by setting the [`GIT_DEPTH` variable](../../../ci/runners/README.md#shallow-cloning) to a higher value. In order to apply this only to the Secret Detection job, the following can be added to your `.gitlab-ci.yml`: +To resolve the issue, set the [`GIT_DEPTH` variable](../../../ci/runners/README.md#shallow-cloning) +to a higher value. To apply this only to the Secret Detection job, the following can be added to +your `.gitlab-ci.yml` file: ```yaml secret_detection: diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 10bf6202a92..08faf9bf885 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -5,13 +5,13 @@ 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/#assignments --- -# GitLab Security Dashboard, Security Center, and Vulnerability Reports **(ULTIMATE)** +# GitLab Security Dashboards and Security Center **(ULTIMATE)** GitLab provides a comprehensive set of features for viewing and managing vulnerabilities: - Security dashboards: An overview of the security status in your instance, [groups](#group-security-dashboard), and [projects](#project-security-dashboard). -- [Vulnerability reports](#vulnerability-report): Detailed lists of all vulnerabilities for the instance, group, project, or +- [Vulnerability reports](../vulnerability_report/index.md): Detailed lists of all vulnerabilities for the instance, group, project, or pipeline. This is where you triage and manage vulnerabilities. - [Security Center](#instance-security-center): A dedicated area for vulnerability management at the instance level. This includes a security dashboard, vulnerability report, and settings. @@ -27,7 +27,7 @@ To benefit from these features, you must first configure one of the ## Supported reports -The vulnerability report displays vulnerabilities detected by scanners such as: +The security dashboard and vulnerability report displays information about vulnerabilities detected by scanners such as: - [Container Scanning](../container_scanning/index.md) - [Dynamic Application Security Testing](../dast/index.md) @@ -68,7 +68,7 @@ the analyzer outputs an > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. At the project level, the Security Dashboard displays a chart with the number of vulnerabilities over time. -Access it by navigating to **Security & Compliance > Security Dashboard**. Currently, we display historical +Access it by navigating to **Security & Compliance > Security Dashboard**. We display historical data up to 365 days.  @@ -76,43 +76,6 @@ data up to 365 days. Filter the historical data by clicking on the corresponding legend name. The image above, for example, shows only the graph for vulnerabilities with **high** severity. -### Vulnerability Report - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. - -The vulnerabilities that exist in your project's -[default branch](../../project/repository/branches/index.md#default-branch) are accessed by navigating to -**Security & Compliance > Vulnerability Report**. By default, the Vulnerability Report is filtered to -display all detected and confirmed vulnerabilities. - -The Vulnerability Report first displays the time at which the last pipeline completed on the project's -default branch. There's also a link to view this in more detail. In the case of any pipeline failures, -the number of failures is indicated. The failure notification takes you directly to -the **Failed jobs** tab of the pipeline page. - -The Vulnerability Report next displays the total number of vulnerabilities by severity (for example, -Critical, High, Medium, Low, Info, Unknown). Below this, a table shows each vulnerability's status, severity, -description and if there is a Merge Request related to it. Clicking a vulnerability takes you to its -[Vulnerability Details](../vulnerabilities) -page to view more information about that vulnerability. - - - -You can filter the vulnerabilities by one or more of the following: - -| Filter | Available Options | -| --- | --- | -| Status | Detected, Confirmed, Dismissed, Resolved | -| Severity | Critical, High, Medium, Low, Info, Unknown | -| Scanner | [Available Scanners](../index.md#security-scanning-tools) | - -You can also dismiss vulnerabilities in the table: - -1. Select the checkbox for each vulnerability you want to dismiss. -1. In the menu that appears, select the reason for dismissal and click **Dismiss Selected**. - - - ## Group Security Dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. @@ -146,7 +109,7 @@ Next to the timeline chart is a list of projects, grouped and sorted by the seve Projects with no vulnerability tests configured don't appear in the list. Additionally, dismissed vulnerabilities are excluded. -Navigate to the group's [vulnerability report](#vulnerability-report-1) to view the vulnerabilities found. +Navigate to the group's [vulnerability report](../vulnerability_report/index.md) to view the vulnerabilities found. ## Instance Security Center @@ -157,7 +120,7 @@ vulnerabilities present in the default branches of all the projects you configur following: - The [group security dashboard's](#group-security-dashboard) features. -- A [vulnerability report](#vulnerability-report). +- A [vulnerability report](../vulnerability_report/index.md). - A dedicated settings area to configure which projects to display.  @@ -184,36 +147,6 @@ To add projects to the Security Center: After you add projects, the security dashboard and vulnerability report display 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. - -You can export all your vulnerabilities in CSV (comma separated values) format by clicking the -**{upload}** **Export** button located at top right of the Security Dashboard. When the report is -ready, the CSV report downloads to your local machine. The report contains all vulnerabilities for -the projects defined in the Security Dashboard, as filters don't apply to the export function. - -NOTE: -It may take several minutes for the download to start if your project contains -thousands of vulnerabilities. Don't close the page until the download finishes. - -The fields in the export include: - -- Group Name -- Project Name -- Scanner Type -- Scanner Name -- Status -- Vulnerability -- Details -- Additional Info -- Severity -- [CVE](https://cve.mitre.org/) (Common Vulnerabilities and Exposures) -- [CWE](https://cwe.mitre.org/) (Common Weakness Enumeration) -- Other Identifiers - - - ## Keeping the dashboards up to date The Security Dashboard displays information from the results of the most recent @@ -245,35 +178,6 @@ When using [Auto DevOps](../../../topics/autodevops/index.md), use [special environment variables](../../../topics/autodevops/customize.md#environment-variables) to configure daily security scans. -## Vulnerability report - -Each vulnerability report contains vulnerabilities from the latest scans that were merged -into the default branch. - - - -You can filter which vulnerabilities the vulnerability report displays by: - -| Filter | Available Options | -| --- | --- | -| Status | Detected, Confirmed, Dismissed, Resolved | -| Severity | Critical, High, Medium, Low, Info, Unknown | -| Scanner | [Available Scanners](../index.md#security-scanning-tools) | -| Project | Projects configured in the Security Center settings | - -Clicking any vulnerability in the table takes you to its -[Vulnerability Details](../vulnerabilities) page to see more information on that vulnerability. -To create an issue associated with the vulnerability, click the **Create Issue** button. - - - -Once you create the issue, the linked issue icon in the vulnerability list: - -- Indicates that an issue has been created for that vulnerability. -- Shows a tooltip that contains a link to the issue. - - - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index ce2297f7a1a..40b8f418737 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -37,33 +37,33 @@ the following tables: | GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | |--------------------------------------------------------------------------------------------------------|--------------------------|----------------------------|------------------------------------| -| [security-code-scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | **{dotted-circle}** No | N/A | N/A | -| [brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | **{dotted-circle}** No | N/A | N/A | -| [sobelow](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Unknown` | -| [nodejs-scan](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) | **{check-circle}** Yes | String | `INFO`, `WARNING`, `ERROR` | -| [flawfinder](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) | **{check-circle}** Yes | Integer | `0`, `1`, `2`, `3`, `4`, `5` | -| [eslint](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Unknown` | -| [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `11`, `12`, `18` | -| [gosec](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | -| [bandit](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | -| [phpcs-security-audit](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) | **{check-circle}** Yes | String | `ERROR`, `WARNING` | -| [pmd-apex](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `4`, `5` | -| [kubesec](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | **{check-circle}** Yes | String | `CriticalSeverity`, `InfoSeverity` | -| [secrets](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Critical` | +| [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | **{dotted-circle}** No | N/A | N/A | +| [`brakeman`](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | **{dotted-circle}** No | N/A | N/A | +| [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Unknown` | +| [`nodejs-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) | **{check-circle}** Yes | String | `INFO`, `WARNING`, `ERROR` | +| [`flawfinder`](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) | **{check-circle}** Yes | Integer | `0`, `1`, `2`, `3`, `4`, `5` | +| [`eslint`](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Unknown` | +| [`SpotBugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `11`, `12`, `18` | +| [`gosec`](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | +| [`bandit`](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | +| [`phpcs-security-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) | **{check-circle}** Yes | String | `ERROR`, `WARNING` | +| [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `4`, `5` | +| [`kubesec`](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | **{check-circle}** Yes | String | `CriticalSeverity`, `InfoSeverity` | +| [`secrets`](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Critical` | ## Dependency Scanning | GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | |------------------------------------------------------------------------------------------|------------------------------|----------------------------|-------------------------------------| -| [bundler-audit](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit) | **{check-circle}** Yes | String | `low`, `medium`, `high`, `critical` | -| [retire.js](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js) | **{check-circle}** Yes | String | `low`, `medium`, `high`, `critical` | -| [gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | **{check-circle}** Yes | CVSS v2.0 Rating and CVSS v3.1 Qualitative Severity Rating | `(AV:N/AC:L/Au:S/C:P/I:P/A:N)`, `CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H` | +| [`bundler-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit) | **{check-circle}** Yes | String | `low`, `medium`, `high`, `critical` | +| [`retire.js`](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js) | **{check-circle}** Yes | String | `low`, `medium`, `high`, `critical` | +| [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | **{check-circle}** Yes | CVSS v2.0 Rating and CVSS v3.1 Qualitative Severity Rating | `(AV:N/AC:L/Au:S/C:P/I:P/A:N)`, `CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H` | ## Container Scanning | GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | |------------------------------------------------------------------------|--------------------------|----------------------------|--------------------------------------------------------------| -| [klar](https://gitlab.com/gitlab-org/security-products/analyzers/klar) | **{check-circle}** Yes | String | `Negligible`, `Low`, `Medium`, `High`, `Critical`, `Defcon1` | +| [`klar`](https://gitlab.com/gitlab-org/security-products/analyzers/klar) | **{check-circle}** Yes | String | `Negligible`, `Low`, `Medium`, `High`, `Critical`, `Defcon1` | ## Fuzz Testing diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v13_7.png Binary files differindex cd8dbed48fc..cd8dbed48fc 100644 --- a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png +++ b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v13_7.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png b/doc/user/application_security/vulnerability_report/img/instance_security_dashboard_export_csv_v13_4.png Binary files differindex 9ade24be16f..9ade24be16f 100644 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png +++ b/doc/user/application_security/vulnerability_report/img/instance_security_dashboard_export_csv_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_4.png Binary files differindex eb1dfe6c6f4..eb1dfe6c6f4 100644 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_v13_5.png Binary files differindex c46a8295a53..c46a8295a53 100644 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_v13_5.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png b/doc/user/application_security/vulnerability_report/img/vulnerability_details_create_issue_v13_7.png Binary files differindex 5184ad85fa9..5184ad85fa9 100644 --- a/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png +++ b/doc/user/application_security/vulnerability_report/img/vulnerability_details_create_issue_v13_7.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png b/doc/user/application_security/vulnerability_report/img/vulnerability_list_table_v13_4.png Binary files differindex 760942c3239..760942c3239 100644 --- a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png +++ b/doc/user/application_security/vulnerability_report/img/vulnerability_list_table_v13_4.png diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md new file mode 100644 index 00000000000..2f5435ec75f --- /dev/null +++ b/doc/user/application_security/vulnerability_report/index.md @@ -0,0 +1,92 @@ +--- +type: reference, howto +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/#assignments +--- + +# GitLab Vulnerability Reports **(ULTIMATE)** + +Each vulnerability report contains vulnerabilities from the scans of the most recent branch merged into the default branch. + +The vulnerability reports display the total number of vulnerabilities by severity (for example, +Critical, High, Medium, Low, Info, Unknown). Below this, a table shows each vulnerability's detected date, status, severity, description, identifier, the scanner where it was detected, and activity (including related issues or available solutions). By default, the vulnerability report is filtered to display all detected and confirmed vulnerabilities. + + + +You can filter which vulnerabilities display by: + +| Filter | Available Options | +| --- | --- | +| Status | Detected, Confirmed, Dismissed, Resolved | +| Severity | Critical, High, Medium, Low, Info, Unknown | +| Scanner | [Available Scanners](../index.md#security-scanning-tools) | +| Project | Projects configured in the Security Center settings, or all projects in the group for the group level report. This filter is not displayed on the project level vulnerability report | + +Clicking any vulnerability in the table takes you to its +[vulnerability details](../vulnerabilities) page to see more information on that vulnerability. + +To create an issue associated with the vulnerability, click the **Create Issue** button. + + + +After you create the issue, the linked issue icon in the vulnerability list: + +- Indicates that an issue has been created for that vulnerability. +- Shows a tooltip that contains a link to the issue. + + + +Contents of the unfiltered vulnerability report can be exported using our [export feature](#export-vulnerabilities) + +You can also dismiss vulnerabilities in the table: + +1. Select the checkbox for each vulnerability you want to dismiss. +1. In the menu that appears, select the reason for dismissal and click **Dismiss Selected**. + + + +## Project Vulnerability Report + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. + +The vulnerabilities that exist in your project's +[default branch](../../project/repository/branches/index.md#default-branch) are accessed by navigating to +**Security & Compliance > Vulnerability Report**. + +The project vulnerability report first displays the time at which the last pipeline completed on the project's +default branch. There's also a link to view this in more detail. In the case of any pipeline failures, +the number of failures is indicated. The failure notification takes you directly to +the **Failed jobs** tab of the pipeline page. + + + +## Export vulnerabilities + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. + +You can export all your vulnerabilities in CSV (comma separated values) format by clicking the +**{upload}** **Export** button located at top right of the Security Dashboard. When the report is +ready, the CSV report downloads to your local machine. The report contains all vulnerabilities for +the projects defined in the Security Dashboard, as filters don't apply to the export function. + +NOTE: +It may take several minutes for the download to start if your project contains +thousands of vulnerabilities. Don't close the page until the download finishes. + +The fields in the export include: + +- Group Name +- Project Name +- Scanner Type +- Scanner Name +- Status +- Vulnerability +- Details +- Additional Information +- Severity +- [CVE](https://cve.mitre.org/) (Common Vulnerabilities and Exposures) +- [CWE](https://cwe.mitre.org/) (Common Weakness Enumeration) +- Other Identifiers + + diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index 546746af535..e0128edf317 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -40,7 +40,7 @@ Notice how line breaks are now preserved. An indented (literal) paragraph disables text formatting, preserves spaces and line breaks, and is displayed in a -monospaced font: +fixed-width font: ```plaintext This literal paragraph is indented with one space. @@ -186,8 +186,12 @@ Attach a block or paragraph to a list item using a list continuation (which you * [ ] not checked ``` +<!-- vale gitlab.Spelling = NO --> + #### Callout +<!-- vale gitlab.Spelling = YES --> + ```plaintext // enable callout bubbles by adding `:icons: font` to the document header [,ruby] diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index 4ece94447bc..de250bc5fb4 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Award emoji **(CORE)** +# Award emoji **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/1825) in GitLab 8.2. > - GitLab 9.0 [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9570) the usage of native emoji if the platform diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 2c0d9b6c9ce..6f3d1e197f5 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# GitLab Kubernetes Agent **(PREMIUM ONLY)** +# GitLab Kubernetes Agent **(PREMIUM SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. > - It's disabled on GitLab.com. Rolling this feature out to GitLab.com is [planned](https://gitlab.com/groups/gitlab-org/-/epics/3834). @@ -190,7 +190,7 @@ the Agent in subsequent steps. You can create an Agent record either: For full details, read [Starting a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). -- Through GraphQL: **(PREMIUM ONLY)** +- Through GraphQL: **(PREMIUM SELF)** ```graphql mutation createAgent { @@ -439,49 +439,23 @@ The following example projects can help you get started with the Kubernetes Agen - [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) - This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) -- [Install GitLab Runner](runner.md) ### Deploying GitLab Runner with the Agent -These instructions assume that the Agent is already set up as described in the -[Get started with GitOps](#get-started-with-gitops-and-the-gitlab-agent): +You can use the Kubernetes Agent to +[deploy GitLab Runner in a Kubernetes cluster](http://docs.gitlab.com/runner/install/kubernetes-agent.html). -1. Check the possible - [Runner chart YAML values](https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/master/values.yaml) - on the Runner chart documentation, and create a `runner-chart-values.yaml` file - with the configuration that fits your needs, such as: +## Management interfaces - ```yaml - ## The GitLab Server URL (with protocol) that want to register the runner against - ## ref: https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-register - ## - gitlabUrl: https://gitlab.my.domain.com/ +Users with at least the [Developer](../../permissions.md) can access the user interface +for the GitLab Kubernetes agent at **Operations > Kubernetes** and selecting the +**GitLab Agent managed clusters** tab. This page lists all registered agents for +the current project, and the configuration directory for each agent: - ## The Registration Token for adding new Runners to the GitLab Server. This must - ## be retrieved from your GitLab Instance. - ## ref: https://docs.gitlab.com/ce/ci/runners/README.html - ## - runnerRegistrationToken: "XXXXXXYYYYYYZZZZZZ" + - ## For RBAC support: - rbac: - create: true - - ## Run all containers with the privileged flag enabled - ## This will allow the docker:dind image to run if you need to run Docker - ## commands. Please read the docs before turning this on: - ## ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-dockerdind - runners: - privileged: true - ``` - -1. Create a single manifest file to install the Runner chart with your cluster agent: - - ```shell - helm template --namespace gitlab gitlab-runner -f runner-chart-values.yaml gitlab/gitlab-runner > manifest.yaml - ``` - -1. Push your `manifest.yaml` to your manifest repository. +Additional management interfaces are planned for the GitLab Kubernetes Agent. +[Provide more feedback in the related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739). ## Troubleshooting diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index b71bbc29ef9..60d8cd352fc 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -4,7 +4,7 @@ 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 --- -# Kubernetes Agent configuration repository **(PREMIUM ONLY)** +# Kubernetes Agent configuration repository **(PREMIUM SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. > - It's disabled on GitLab.com. Rolling this feature out to GitLab.com is [planned](https://gitlab.com/groups/gitlab-org/-/epics/3834). diff --git a/doc/user/clusters/agent/runner.md b/doc/user/clusters/agent/runner.md index 715b27f951a..bbf07d4ea84 100644 --- a/doc/user/clusters/agent/runner.md +++ b/doc/user/clusters/agent/runner.md @@ -1,452 +1,8 @@ --- -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/#assignments +redirect_to: 'https://docs.gitlab.com/runner/install/kubernetes-agent.html' --- -# Install GitLab Runner with Kubernetes Agent **(PREMIUM ONLY)** +This document was moved to [another location](https://docs.gitlab.com/runner/install/kubernetes-agent.html). -These instructions to install the GitLab Runner assume the -[GitLab Kubernetes Agent](index.md) is already configured. - -1. Review the possible [Runner chart YAML values](https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/master/values.yaml) in the Runner chart documentation, - and create a `runner-chart-values.yaml` file with the configuration that fits - your needs, such as: - - ```yaml - # The GitLab Server URL (with protocol) that want to register the runner against - # ref: https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-register - # - gitlabUrl: https://gitlab.my.domain.example.com/ - - # The Registration Token for adding new Runners to the GitLab Server. This must - # be retrieved from your GitLab Instance. - # ref: https://docs.gitlab.com/ce/ci/runners/README.html - # - runnerRegistrationToken: "yrnZW46BrtBFqM7xDzE7dddd" - - # For RBAC support: - rbac: - create: true - - # Run all containers with the privileged flag enabled - # This will allow the docker:dind image to run if you need to run Docker - # commands. Please read the docs before turning this on: - # ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-dockerdind - runners: - privileged: true - ``` - -1. Create a single manifest file to install the Runner chart with your cluster agent, - replacing `GITLAB GITLAB-RUNNER` with your namespace: - - ```shell - helm template --namespace GITLAB GITLAB-RUNNER -f runner-chart-values.yaml gitlab/gitlab-runner > runner-manifest.yaml - ``` - - An [example file is available](#example-runner-manifest). - -1. Push your `runner-manifest.yaml` to your manifest repository. - -## Example Runner manifest - -```yaml -# This code is an example of a runner manifest looks like. -# Create your own manifest.yaml file to meet your project's needs. - ---- -# Source: gitlab-runner/templates/service-account.yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - annotations: - name: gitlab-runner-gitlab-runner - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" ---- -# Source: gitlab-runner/templates/secrets.yaml -apiVersion: v1 -kind: Secret -metadata: - name: "gitlab-runner-gitlab-runner" - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" -type: Opaque -data: - runner-registration-token: "FAKE-TOKEN" - runner-token: "" ---- -# Source: gitlab-runner/templates/configmap.yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: gitlab-runner-gitlab-runner - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" -data: - entrypoint: | - #!/bin/bash - set -e - mkdir -p /home/gitlab-runner/.gitlab-runner/ - cp /scripts/config.toml /home/gitlab-runner/.gitlab-runner/ - - # Register the runner - if [[ -f /secrets/accesskey && -f /secrets/secretkey ]]; then - export CACHE_S3_ACCESS_KEY=$(cat /secrets/accesskey) - export CACHE_S3_SECRET_KEY=$(cat /secrets/secretkey) - fi - - if [[ -f /secrets/gcs-applicaton-credentials-file ]]; then - export GOOGLE_APPLICATION_CREDENTIALS="/secrets/gcs-applicaton-credentials-file" - elif [[ -f /secrets/gcs-application-credentials-file ]]; then - export GOOGLE_APPLICATION_CREDENTIALS="/secrets/gcs-application-credentials-file" - else - if [[ -f /secrets/gcs-access-id && -f /secrets/gcs-private-key ]]; then - export CACHE_GCS_ACCESS_ID=$(cat /secrets/gcs-access-id) - # echo -e used to make private key multiline (in google json auth key private key is oneline with \n) - export CACHE_GCS_PRIVATE_KEY=$(echo -e $(cat /secrets/gcs-private-key)) - fi - fi - - if [[ -f /secrets/runner-registration-token ]]; then - export REGISTRATION_TOKEN=$(cat /secrets/runner-registration-token) - fi - - if [[ -f /secrets/runner-token ]]; then - export CI_SERVER_TOKEN=$(cat /secrets/runner-token) - fi - - if ! sh /scripts/register-the-runner; then - exit 1 - fi - - # Run pre-entrypoint-script - if ! bash /scripts/pre-entrypoint-script; then - exit 1 - fi - - # Start the runner - exec /entrypoint run --user=gitlab-runner \ - --working-directory=/home/gitlab-runner - - config.toml: | - concurrent = 10 - check_interval = 30 - log_level = "info" - listen_address = ':9252' - configure: | - set -e - cp /init-secrets/* /secrets - register-the-runner: | - #!/bin/bash - MAX_REGISTER_ATTEMPTS=30 - - for i in $(seq 1 "${MAX_REGISTER_ATTEMPTS}"); do - echo "Registration attempt ${i} of ${MAX_REGISTER_ATTEMPTS}" - /entrypoint register \ - --non-interactive - - retval=$? - - if [ ${retval} = 0 ]; then - break - elif [ ${i} = ${MAX_REGISTER_ATTEMPTS} ]; then - exit 1 - fi - - sleep 5 - done - - exit 0 - - check-live: | - #!/bin/bash - if /usr/bin/pgrep -f .*register-the-runner; then - exit 0 - elif /usr/bin/pgrep gitlab.*runner; then - exit 0 - else - exit 1 - fi - - pre-entrypoint-script: | ---- -# Source: gitlab-runner/templates/role.yaml -apiVersion: rbac.authorization.k8s.io/v1 -kind: "Role" -metadata: - name: gitlab-runner-gitlab-runner - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" -rules: -- apiGroups: [""] - resources: ["*"] - verbs: ["*"] ---- -# Source: gitlab-runner/templates/role-binding.yaml -apiVersion: rbac.authorization.k8s.io/v1 -kind: "RoleBinding" -metadata: - name: gitlab-runner-gitlab-runner - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: "Role" - name: gitlab-runner-gitlab-runner -subjects: -- kind: ServiceAccount - name: gitlab-runner-gitlab-runner - namespace: "gitlab" ---- -# Source: gitlab-runner/templates/deployment.yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: gitlab-runner-gitlab-runner - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" -spec: - replicas: 1 - selector: - matchLabels: - app: gitlab-runner-gitlab-runner - template: - metadata: - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" - annotations: - checksum/configmap: a6623303f6fcc3a043e87ea937bb8399d2d0068a901aa9c3419ed5c7a5afa9db - checksum/secrets: 32c7d2c16918961b7b84a005680f748e774f61c6f4e4da30650d400d781bbb30 - prometheus.io/scrape: 'true' - prometheus.io/port: '9252' - spec: - securityContext: - runAsUser: 100 - fsGroup: 65533 - terminationGracePeriodSeconds: 3600 - initContainers: - - name: configure - command: ['sh', '/config/configure'] - image: gitlab/gitlab-runner:alpine-v13.4.1 - imagePullPolicy: "IfNotPresent" - env: - - - name: CI_SERVER_URL - value: "https://gitlab.qa.joaocunha.eu/" - - name: CLONE_URL - value: "" - - name: RUNNER_REQUEST_CONCURRENCY - value: "1" - - name: RUNNER_EXECUTOR - value: "kubernetes" - - name: REGISTER_LOCKED - value: "true" - - name: RUNNER_TAG_LIST - value: "" - - name: RUNNER_OUTPUT_LIMIT - value: "4096" - - name: KUBERNETES_IMAGE - value: "ubuntu:16.04" - - - name: KUBERNETES_PRIVILEGED - value: "true" - - - name: KUBERNETES_NAMESPACE - value: "gitlab" - - name: KUBERNETES_POLL_TIMEOUT - value: "180" - - name: KUBERNETES_CPU_LIMIT - value: "" - - name: KUBERNETES_CPU_LIMIT_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_MEMORY_LIMIT - value: "" - - name: KUBERNETES_MEMORY_LIMIT_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_CPU_REQUEST - value: "" - - name: KUBERNETES_CPU_REQUEST_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_MEMORY_REQUEST - value: "" - - name: KUBERNETES_MEMORY_REQUEST_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_SERVICE_ACCOUNT - value: "" - - name: KUBERNETES_SERVICE_CPU_LIMIT - value: "" - - name: KUBERNETES_SERVICE_MEMORY_LIMIT - value: "" - - name: KUBERNETES_SERVICE_CPU_REQUEST - value: "" - - name: KUBERNETES_SERVICE_MEMORY_REQUEST - value: "" - - name: KUBERNETES_HELPER_CPU_LIMIT - value: "" - - name: KUBERNETES_HELPER_MEMORY_LIMIT - value: "" - - name: KUBERNETES_HELPER_CPU_REQUEST - value: "" - - name: KUBERNETES_HELPER_MEMORY_REQUEST - value: "" - - name: KUBERNETES_HELPER_IMAGE - value: "" - - name: KUBERNETES_PULL_POLICY - value: "" - volumeMounts: - - name: runner-secrets - mountPath: /secrets - readOnly: false - - name: scripts - mountPath: /config - readOnly: true - - name: init-runner-secrets - mountPath: /init-secrets - readOnly: true - resources: - {} - serviceAccountName: gitlab-runner-gitlab-runner - containers: - - name: gitlab-runner-gitlab-runner - image: gitlab/gitlab-runner:alpine-v13.4.1 - imagePullPolicy: "IfNotPresent" - lifecycle: - preStop: - exec: - command: ["/entrypoint", "unregister", "--all-runners"] - command: ["/bin/bash", "/scripts/entrypoint"] - env: - - - name: CI_SERVER_URL - value: "https://gitlab.qa.joaocunha.eu/" - - name: CLONE_URL - value: "" - - name: RUNNER_REQUEST_CONCURRENCY - value: "1" - - name: RUNNER_EXECUTOR - value: "kubernetes" - - name: REGISTER_LOCKED - value: "true" - - name: RUNNER_TAG_LIST - value: "" - - name: RUNNER_OUTPUT_LIMIT - value: "4096" - - name: KUBERNETES_IMAGE - value: "ubuntu:16.04" - - - name: KUBERNETES_PRIVILEGED - value: "true" - - - name: KUBERNETES_NAMESPACE - value: "gitlab" - - name: KUBERNETES_POLL_TIMEOUT - value: "180" - - name: KUBERNETES_CPU_LIMIT - value: "" - - name: KUBERNETES_CPU_LIMIT_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_MEMORY_LIMIT - value: "" - - name: KUBERNETES_MEMORY_LIMIT_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_CPU_REQUEST - value: "" - - name: KUBERNETES_CPU_REQUEST_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_MEMORY_REQUEST - value: "" - - name: KUBERNETES_MEMORY_REQUEST_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_SERVICE_ACCOUNT - value: "" - - name: KUBERNETES_SERVICE_CPU_LIMIT - value: "" - - name: KUBERNETES_SERVICE_MEMORY_LIMIT - value: "" - - name: KUBERNETES_SERVICE_CPU_REQUEST - value: "" - - name: KUBERNETES_SERVICE_MEMORY_REQUEST - value: "" - - name: KUBERNETES_HELPER_CPU_LIMIT - value: "" - - name: KUBERNETES_HELPER_MEMORY_LIMIT - value: "" - - name: KUBERNETES_HELPER_CPU_REQUEST - value: "" - - name: KUBERNETES_HELPER_MEMORY_REQUEST - value: "" - - name: KUBERNETES_HELPER_IMAGE - value: "" - - name: KUBERNETES_PULL_POLICY - value: "" - livenessProbe: - exec: - command: ["/bin/bash", "/scripts/check-live"] - initialDelaySeconds: 60 - timeoutSeconds: 1 - periodSeconds: 10 - successThreshold: 1 - failureThreshold: 3 - readinessProbe: - exec: - command: ["/usr/bin/pgrep","gitlab.*runner"] - initialDelaySeconds: 10 - timeoutSeconds: 1 - periodSeconds: 10 - successThreshold: 1 - failureThreshold: 3 - ports: - - name: metrics - containerPort: 9252 - volumeMounts: - - name: runner-secrets - mountPath: /secrets - - name: etc-gitlab-runner - mountPath: /home/gitlab-runner/.gitlab-runner - - name: scripts - mountPath: /scripts - resources: - {} - volumes: - - name: runner-secrets - emptyDir: - medium: "Memory" - - name: etc-gitlab-runner - emptyDir: - medium: "Memory" - - name: init-runner-secrets - projected: - sources: - - secret: - name: "gitlab-runner-gitlab-runner" - items: - - key: runner-registration-token - path: runner-registration-token - - key: runner-token - path: runner-token - - name: scripts - configMap: - name: gitlab-runner-gitlab-runner -``` +<!-- This redirect file can be deleted after <2022-02-01>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
\ No newline at end of file diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index b03dfb79ae0..25c50af84e1 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -4,7 +4,7 @@ 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/#assignments --- -# GitLab Managed Apps +# GitLab Managed Apps **(CORE)** GitLab provides **GitLab Managed Apps** for various applications which can be added directly to your configured cluster. These @@ -20,10 +20,9 @@ have been deprecated, and are scheduled for removal in GitLab 14.0. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20822) in GitLab 12.6. WARNING: -This is an _alpha_ feature, and is subject to change at any time without -prior notice. +This is a _beta_ feature, and some applications might miss features to provide full integration with GitLab. -This alternative method allows users to install GitLab-managed +This primary method for installing applications to clusters allows users to install GitLab-managed applications using GitLab CI/CD. It also allows customization of the install using Helm `values.yaml` files. @@ -1199,53 +1198,8 @@ determine the endpoint of your Ingress or Knative application, you can #### Determining the external endpoint manually -If the cluster is on GKE, click the **Google Kubernetes Engine** link in the -**Advanced settings**, or go directly to the -[Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/) -and select the proper project and cluster. Then click **Connect** and execute -the `gcloud` command in a local terminal or using the **Cloud Shell**. - -If the cluster is not on GKE, follow the specific instructions for your -Kubernetes provider to configure `kubectl` with the right credentials. -The output of the following examples show the external endpoint of your -cluster. This information can then be used to set up DNS entries and forwarding -rules that allow external access to your deployed applications. - -- If you installed Ingress using the **Applications**, run the following - command: - - ```shell - kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' - ``` - -- Some Kubernetes clusters return a hostname instead, like - [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: - - ```shell - kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' - ``` - - If EKS is used, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) - is also created, which incurs additional AWS costs. - -- For Istio/Knative, the command is different: - - ```shell - kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' - ``` - -- Otherwise, you can list the IP addresses of all load balancers: - - ```shell - kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' - ``` - -You may see a trailing `%` on some Kubernetes versions. Do not include it. - -The Ingress is now available at this address, and routes incoming requests to -the proper service based on the DNS name in the request. To support this, create -a wildcard DNS CNAME record for the desired domain name. For example, -`*.myekscluster.com` would point to the Ingress hostname obtained earlier. +See the [Base domain section](../project/clusters/index.md#base-domain) for a +guide on how to determine the external endpoint manually. #### Using a static IP diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md index c1ef798f5a8..2d185798317 100644 --- a/doc/user/clusters/crossplane.md +++ b/doc/user/clusters/crossplane.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Crossplane configuration +# Crossplane configuration **(CORE)** After [installing](applications.md#crossplane) Crossplane, you must configure it for use. The process of configuring Crossplane includes: diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index be4ac8151e4..cb721115e76 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Cluster Environments **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13392) for group-level clusters in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14809) for instance-level clusters in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13392) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3 for group-level clusters. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14809) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4 for instance-level clusters. Cluster environments provide a consolidated view of which CI [environments](../../ci/environments/index.md) are deployed to the Kubernetes cluster and it: @@ -38,7 +38,7 @@ In order to: - Show pod usage correctly, you must [enable Deploy Boards](../project/deploy_boards.md#enabling-deploy-boards). -Once you have successful deployments to your group-level or instance-level cluster: +After you have successful deployments to your group-level or instance-level cluster: 1. Navigate to your group's **Kubernetes** page. 1. Click on the **Environments** tab. diff --git a/doc/user/clusters/img/kubernetes-agent-ui-list_v13_8.png b/doc/user/clusters/img/kubernetes-agent-ui-list_v13_8.png Binary files differnew file mode 100644 index 00000000000..3f9cc41838a --- /dev/null +++ b/doc/user/clusters/img/kubernetes-agent-ui-list_v13_8.png diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 55f507fb318..b0aa402de78 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Cluster management project +# Cluster management project **(CORE)** WARNING: This is an _alpha_ feature, and it is subject to change at any time without diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 1428a0d4e80..7a0ed708d9b 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -58,7 +58,7 @@ Java 8 and Gradle 1.x projects are not supported. The minimum supported version | JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) | | | Go | [Godep](https://github.com/tools/godep), [go mod](https://github.com/golang/go/wiki/Modules) | | | Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | | -| .NET | [Nuget](https://www.nuget.org/) | The .NET Framework is supported via the [mono project](https://www.mono-project.com/). There are, however, some limitations. The scanner doesn't support Windows-specific dependencies and doesn't report dependencies of your project's listed dependencies. Also, the scanner always marks detected licenses for all dependencies as `unknown`. | +| .NET | [NuGet](https://www.nuget.org/) | The .NET Framework is supported via the [mono project](https://www.mono-project.com/). There are, however, some limitations. The scanner doesn't support Windows-specific dependencies and doesn't report dependencies of your project's listed dependencies. Also, the scanner always marks detected licenses for all dependencies as `unknown`. | | Python | [pip](https://pip.pypa.io/en/stable/) | Python is supported through [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files) and [Pipfile.lock](https://github.com/pypa/pipfile#pipfilelock). | | Ruby | [gem](https://rubygems.org/) | | @@ -70,7 +70,7 @@ The reported licenses might be incomplete or inaccurate. | Language | Package managers | |------------|---------------------------------------------------------------------------------------------------------------| | JavaScript | [Yarn](https://yarnpkg.com/) | -| Go | go get, gvt, glide, dep, trash, govendor | +| Go | `go get`, `gvt`, `glide`, `dep`, `trash`, `govendor` | | Erlang | [Rebar](https://www.rebar3.org/) | | Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage), [CocoaPods](https://cocoapods.org/) v0.39 and below | | Elixir | [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) | @@ -137,11 +137,11 @@ License Compliance can be configured using environment variables. | `ASDF_NODEJS_VERSION` | no | Version of Node.js to use for the scan. | | `ASDF_PYTHON_VERSION` | no | Version of Python to use for the scan. | | `ASDF_RUBY_VERSION` | no | Version of Ruby to use for the scan. | -| `GRADLE_CLI_OPTS` | no | Additional arguments for the gradle executable. If not supplied, defaults to `--exclude-task=test`. | +| `GRADLE_CLI_OPTS` | no | Additional arguments for the Gradle executable. If not supplied, defaults to `--exclude-task=test`. | | `LICENSE_FINDER_CLI_OPTS` | no | Additional arguments for the `license_finder` executable. For example, if you have multiple projects in nested directories, you can update your `.gitlab-ci-yml` template to specify a recursive scan, like `LICENSE_FINDER_CLI_OPTS: '--recursive'`. | | `LM_JAVA_VERSION` | no | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. | | `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. | -| `MAVEN_CLI_OPTS` | no | Additional arguments for the mvn executable. If not supplied, defaults to `-DskipTests`. | +| `MAVEN_CLI_OPTS` | no | Additional arguments for the `mvn` executable. If not supplied, defaults to `-DskipTests`. | | `PIP_INDEX_URL` | no | Base URL of Python Package Index (default: `https://pypi.org/simple/`). | | `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address to download the analyzer from. | | `SETUP_CMD` | no | Custom setup for the dependency installation (experimental). | @@ -217,12 +217,12 @@ to explicitly add `-DskipTests` to your options. If you still need to run tests during `mvn install`, add `-DskipTests=false` to `MAVEN_CLI_OPTS`. -#### Using private Maven repos +#### Using private Maven repositories If you have a private Maven repository which requires login credentials, you can use the `MAVEN_CLI_OPTS` environment variable. -Read more on [how to use private Maven repos](../../application_security/index.md#using-private-maven-repos). +Read more on [how to use private Maven repositories](../../application_security/index.md#using-private-maven-repositories). You can also use `MAVEN_CLI_OPTS` to connect to a trusted Maven repository that uses a self-signed or internally trusted certificate. For example: @@ -264,7 +264,7 @@ license_scanning: You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). -#### Using private Python repos +#### Using private Python repositories If you have a private Python repository you can use the `PIP_INDEX_URL` [environment variable](#available-variables) to specify its location. @@ -560,11 +560,11 @@ You can supply a custom root certificate to complete TLS verification by using t In GitLab 12.8 a new name for `license_management` job was introduced. This change was made to improve clarity around the purpose of the scan, which is to scan and collect the types of licenses present in a projects dependencies. GitLab 13.0 drops support for `license_management`. If you're using a custom setup for License Compliance, you're required -to update your CI config accordingly: +to update your CI configuration accordingly: 1. Change the CI template to `License-Scanning.gitlab-ci.yml`. 1. Change the job name to `license_scanning` (if you mention it in `.gitlab-ci.yml`). -1. Change the artifact name to `license_scanning`, and the file name to `gl-license-scanning-report.json` (if you mention it in `.gitlab-ci.yml`). +1. Change the artifact name to `license_scanning`, and the filename to `gl-license-scanning-report.json` (if you mention it in `.gitlab-ci.yml`). For example, the following `.gitlab-ci.yml`: @@ -662,9 +662,9 @@ Additional configuration may be needed for connecting to [private Bundler registries](#using-private-bundler-registries), [private Conan registries](#using-private-bower-registries), [private Go registries](#using-private-go-registries), -[private Maven repositories](#using-private-maven-repos), +[private Maven repositories](#using-private-maven-repositories), [private NPM registries](#using-private-npm-registries), -[private Python repositories](#using-private-python-repos), +[private Python repositories](#using-private-python-repositories), and [private Yarn registries](#using-private-yarn-registries). ### SPDX license list name matching diff --git a/doc/user/discussions/img/apply_suggestion_v12_7.png b/doc/user/discussions/img/apply_suggestion_v12_7.png Binary files differdeleted file mode 100644 index c8c44149fd0..00000000000 --- a/doc/user/discussions/img/apply_suggestion_v12_7.png +++ /dev/null diff --git a/doc/user/discussions/img/apply_suggestion_v13_9.png b/doc/user/discussions/img/apply_suggestion_v13_9.png Binary files differnew file mode 100644 index 00000000000..932855a8c97 --- /dev/null +++ b/doc/user/discussions/img/apply_suggestion_v13_9.png diff --git a/doc/user/discussions/img/custom_commit_v13_9.png b/doc/user/discussions/img/custom_commit_v13_9.png Binary files differnew file mode 100644 index 00000000000..547a6534ea1 --- /dev/null +++ b/doc/user/discussions/img/custom_commit_v13_9.png diff --git a/doc/user/discussions/img/make_suggestion_v12_7.png b/doc/user/discussions/img/make_suggestion_v12_7.png Binary files differdeleted file mode 100644 index 7eb84186b0a..00000000000 --- a/doc/user/discussions/img/make_suggestion_v12_7.png +++ /dev/null diff --git a/doc/user/discussions/img/make_suggestion_v13_9.png b/doc/user/discussions/img/make_suggestion_v13_9.png Binary files differnew file mode 100644 index 00000000000..dc6889cfcd6 --- /dev/null +++ b/doc/user/discussions/img/make_suggestion_v13_9.png diff --git a/doc/user/discussions/img/resolve_thread_open_issue.png b/doc/user/discussions/img/resolve_thread_open_issue.png Binary files differdeleted file mode 100644 index 2dd4ea3cb1b..00000000000 --- a/doc/user/discussions/img/resolve_thread_open_issue.png +++ /dev/null diff --git a/doc/user/discussions/img/resolve_thread_open_issue_v13_9.png b/doc/user/discussions/img/resolve_thread_open_issue_v13_9.png Binary files differnew file mode 100644 index 00000000000..6611ca7b1ff --- /dev/null +++ b/doc/user/discussions/img/resolve_thread_open_issue_v13_9.png diff --git a/doc/user/discussions/img/suggestion_button_v12_7.png b/doc/user/discussions/img/suggestion_button_v12_7.png Binary files differdeleted file mode 100644 index 3b7a4d625a3..00000000000 --- a/doc/user/discussions/img/suggestion_button_v12_7.png +++ /dev/null diff --git a/doc/user/discussions/img/suggestion_button_v13_9.png b/doc/user/discussions/img/suggestion_button_v13_9.png Binary files differnew file mode 100644 index 00000000000..4fbdac4f66d --- /dev/null +++ b/doc/user/discussions/img/suggestion_button_v13_9.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index bf3e907bd24..7d0413a1f1b 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -44,7 +44,7 @@ Thread resolution helps keep track of progress during planning or code review. Every standard comment or thread in merge requests, commits, commit diffs, and snippets is initially displayed as unresolved. They can then be individually resolved by anyone with at least Developer access to the project or by the author of the change being reviewed. -If the thread has been resolved and a non-member unresolves their own response, +If the thread has been resolved and a non-member un-resolves their own response, this will also unresolve the discussion thread. If the non-member then resolves this same response, this will resolve the discussion thread. @@ -115,7 +115,7 @@ are resolved](#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolve there will be an **open an issue to resolve them later** link in the merge request widget. - + This will prepare an issue with its content referring to the merge request and the unresolved threads. @@ -161,7 +161,7 @@ box and hit **Save** for the changes to take effect. From now on, you will not be able to merge from the UI until all threads are resolved. - + ### Automatically resolve merge request diff threads when they become outdated @@ -284,7 +284,7 @@ Additionally, locked issues and merge requests can not be reopened. ## Merge Request Reviews > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Core in 13.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Free in 13.1. When looking at a Merge Request diff, you are able to start a review. This allows you to create comments inside a Merge Request that are **only visible to you** until published, @@ -370,13 +370,17 @@ From a merge request's **Discussion** tab, or from an epic/issue overview, find  -Once you select one of the filters in a given issue or MR, GitLab will save +After you select one of the filters in a given issue or MR, GitLab will save your preference, so that it will persist when you visit the same page again from any device you're logged into. ## Suggest Changes -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. +> - Custom commit messages for suggestions were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9. +> - Custom commit messages for suggestions is disabled on GitLab.com and not recommended for production use. +> - Custom commit messages for suggestions was deployed behind a [feature flag](../feature_flags.md), disabled by default. +> - To use custom commit messages for suggestions in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-custom-commit-messages-for-suggestions). **(FREE SELF)** As a reviewer, you're able to suggest code changes with a simple Markdown syntax in Merge Request Diff threads. Then, the @@ -388,24 +392,50 @@ the merge request authored by the user that applied them. 1. Choose a line of code to be changed, add a new comment, then click on the **Insert suggestion** icon in the toolbar: -  +  1. In the comment, add your suggestion to the pre-populated code block: -  +  1. Click either **Start a review** or **Add to review** to add your comment to a [review](#merge-request-reviews), or **Add comment now** to add the comment to the thread immediately. The Suggestion in the comment can be applied by the merge request author directly from the merge request: -  +  -Once the author applies a Suggestion, it will be marked with the **Applied** label, +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9, + you can opt to add a custom commit message to describe your change. If you don't + specify it, the default commit message will be used. Note that [this feature may not be available to you](#enable-or-disable-custom-commit-messages-for-suggestions). + Also, it is not supported for [batch suggestions](#batch-suggestions). + +  + +After the author applies a Suggestion, it will be marked with the **Applied** label, the thread will be automatically resolved, and GitLab will create a new commit and push the suggested change directly into the codebase in the merge request's branch. [Developer permission](../permissions.md) is required to do so. +### Enable or disable Custom commit messages for suggestions **(FREE SELF)** + +Custom commit messages for suggestions 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 custom commit messages for suggestions: + +```ruby +Feature.enable(:suggestions_custom_commit) +``` + +To disable custom commit messages for suggestions: + +```ruby +Feature.disable(:suggestions_custom_commit) +``` + ### Multi-line Suggestions > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. @@ -501,7 +531,7 @@ to your branch to address your reviewers' requests.  -#### Enable or disable Batch Suggestions **(CORE ONLY)** +#### Enable or disable Batch Suggestions **(FREE SELF)** Batch Suggestions is deployed behind a feature flag that is **enabled by default**. @@ -537,7 +567,7 @@ Clicking on the **Reply to comment** button will bring the reply area into focus  Replying to a non-thread comment will convert the non-thread comment to a -thread once the reply is submitted. This conversion is considered an edit +thread after the reply is submitted. This conversion is considered an edit to the original comment, so a note about when it was last edited will appear underneath it. This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff threads are diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md index 9a601871349..a6be4c69f81 100644 --- a/doc/user/feature_flags.md +++ b/doc/user/feature_flags.md @@ -29,11 +29,11 @@ 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), diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 611c1105961..d474392b52a 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -97,7 +97,7 @@ Any settings or feature limits not listed here are using the defaults listed in | ----------- | ----------------- | ------------- | | 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 * * * *` | +| Scheduled Pipeline Cron | `*/5 * * * *` | `3-59/10 * * * *` | | [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 | @@ -114,7 +114,7 @@ or over the repository size limit, you can [reduce your repository size with Git | Setting | GitLab.com | Default | | ----------- | ----------- | ------------- | | [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md) | 10 GB | Unlimited | -| Maximum import size | 5 GB | Unlimited | +| Maximum import size | 5 GB | Unlimited ([Modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to unlimited in GitLab 13.8. | 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. @@ -170,7 +170,7 @@ Linux shared runners on GitLab.com run in autoscale mode and are powered by Goog Autoscaling means reduced queue times to spin up CI/CD jobs, and isolated VMs for each project, thus maximizing security. These shared runners are available for users and customers on GitLab.com. -GitLab offers Gold tier capabilities and included CI/CD minutes per group per month for our [Open Source](https://about.gitlab.com/solutions/open-source/join/), [Education](https://about.gitlab.com/solutions/education/), and [Startups](https://about.gitlab.com/solutions/startups/) programs. For private projects, GitLab offers various [plans](https://about.gitlab.com/pricing/), starting with a Free tier. +GitLab offers Ultimate tier capabilities and included CI/CD minutes per group per month for our [Open Source](https://about.gitlab.com/solutions/open-source/join/), [Education](https://about.gitlab.com/solutions/education/), and [Startups](https://about.gitlab.com/solutions/startups/) programs. For private projects, GitLab offers various [plans](https://about.gitlab.com/pricing/), starting with a Free tier. 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 installed. Instances provide 1 vCPU and 25GB of HDD disk space. The default @@ -622,13 +622,6 @@ dropped and users get To help avoid abuse, project and group imports, exports, and export downloads are rate limited. See [Project import/export rate limits](../../user/project/settings/import_export.md#rate-limits) and [Group import/export rate limits](../../user/group/settings/import_export.md#rate-limits) for details. -GitLab.com Import/Export Rate Limits are set to the default except: - -| Setting | GitLab.com | Default | -|:-------------------------------------------------|:-----------|:--------| -| Max Project Export requests per minute per user | 1 | 6 | -| Max Group Export requests per minute per user | 1 | 6 | - ### Non-configurable limits See [non-configurable limits](../../security/rate_limits.md#non-configurable-limits) for information on @@ -639,7 +632,7 @@ rate limits that are not configurable, and therefore also used on GitLab.com. We use [Fluentd](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#fluentd) to parse our logs. Fluentd sends our logs to [Stackdriver Logging](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#stackdriver) and [Cloud Pub/Sub](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#cloud-pubsub). Stackdriver is used for storing logs long-term in Google Cold Storage (GCS). Cloud Pub/Sub -is used to forward logs to an [Elastic cluster](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#elastic) using [pubsubbeat](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#pubsubbeat-vms). +is used to forward logs to an [Elastic cluster](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#elastic) using [`pubsubbeat`](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#pubsubbeat-vms). You can view more information in our runbooks such as: diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md index 8db9c7fd76c..22001b317f7 100644 --- a/doc/user/group/bulk_editing/index.md +++ b/doc/user/group/bulk_editing/index.md @@ -20,19 +20,21 @@ Only the items visible on the current page are selected for bulk editing (up to ## Bulk edit issues at the group level -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in GitLab 12.1. +> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. +> - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. +> - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. NOTE: You need a permission level of [Reporter or higher](../../permissions.md) to manage issues. When bulk editing issues in a group, you can edit the following attributes: -- Epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in - [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.) **(PREMIUM)** -- Milestone -- Labels -- Health status ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in - [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2.) **(ULTIMATE)** +- [Epic](../epics/index.md) +- [Milestone](../../project/milestones/index.md) +- [Labels](../../project/labels.md) +- [Health status](../../project/issues/index.md#health-status) +- [Iteration](../iterations/index.md) To update multiple project issues at the same time: diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index ea7629d1f10..fa334310868 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Group-level Kubernetes clusters +# Group-level Kubernetes clusters **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in GitLab 11.6. @@ -43,7 +43,7 @@ to the project, provided the cluster is not disabled. ## Multiple Kubernetes clusters -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Core in 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) in GitLab Free 13.2. You can associate more than one Kubernetes cluster to your group, and maintain different clusters for different environments, such as development, staging, and production. diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 0dbd7af1214..09e899a61ba 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -4,7 +4,7 @@ stage: Manage group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Contribution Analytics **(STARTER)** +# Contribution Analytics **(PREMIUM)** > - Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3090) for subgroups in GitLab 12.2. diff --git a/doc/user/group/dependency_proxy/index.md b/doc/user/group/dependency_proxy/index.md deleted file mode 100644 index c4feed24132..00000000000 --- a/doc/user/group/dependency_proxy/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/dependency_proxy/index.md' ---- - -This document was moved to [another location](../../packages/dependency_proxy/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 9cc7a35bc32..d4c1a5fc768 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -16,13 +16,15 @@ to them. > - The New Epic form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. > - In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/229621) and later, the New Epic button on the Epics list opens the New Epic form. +> - In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45948) and later, you can create a new epic from an empty Roadmap. To create an epic in the group you're in: 1. Get to the New Epic form: - - From the **Epics** list in your group, select the **New Epic** button. - - From an epic in your group, select the **New Epic** button. + - From the **Epics** list in your group, select **New epic**. + - From an epic in your group, select **New epic**. - From anywhere, in the top menu, select **New...** (**{plus-square}**) **> New epic**. + - In an empty [roadmap](../roadmap/index.md), select **New epic**.  @@ -39,7 +41,7 @@ To create an epic in the group you're in: ## Edit an epic -After you create an epic, you can edit change the following details: +After you create an epic, you can edit the following details: - Title - Description @@ -152,6 +154,9 @@ To make an epic confidential: ## Manage issues assigned to an epic +This section collects instructions for all the things you can do with [issues](../../project/issues/index.md) +in relation to epics. + ### Add a new issue to an epic You can add an existing issue to an epic, or create a new issue that's @@ -176,7 +181,7 @@ To add a new issue to an epic: - Search for the desired issue by entering part of the issue's title, then selecting the desired match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/9126)). - If there are multiple issues to be added, press <kbd>Spacebar</kbd> and repeat this step. + If there are multiple issues to be added, press <kbd>Space</kbd> and repeat this step. 1. Select **Add**. #### Create an issue from an epic @@ -278,7 +283,7 @@ To add a child epic to an epic: - Search for the desired issue by entering part of the epic's title, then selecting the desired match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/9126)). - If there are multiple epics to be added, press <kbd>Spacebar</kbd> and repeat this step. + If there are multiple epics to be added, press <kbd>Space</kbd> and repeat this step. 1. Select **Add**. ### Move child epics between epics diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index d051a134af1..a217175df1a 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import groups from another instance of GitLab **(CORE)** +# Import groups from another instance of GitLab **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7. > - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 069dea40ba5..208c64d0406 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -301,7 +301,7 @@ There are two different ways to add a new project to a group: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. > - Brought to [GitLab Starter](https://about.gitlab.com/pricing/) in 10.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) to [GitLab Free](https://about.gitlab.com/pricing/) in 11.10. By default, [Developers and Maintainers](../permissions.md#group-members-permissions) can create projects under a group. @@ -327,7 +327,7 @@ A group's **Details** page includes tabs for: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab [Starter](https://about.gitlab.com/pricing/) 12.10 as a [beta feature](https://about.gitlab.com/handbook/product/#beta) -The group details view also shows the number of the following items created in the last 90 days: **(STARTER)** +The group details view also shows the number of the following items created in the last 90 days: **(PREMIUM)** - Merge requests. - Issues. @@ -389,7 +389,7 @@ To share a given group, for example, 'Frontend' with another group, for example, All the members of the 'Engineering' group will have been added to 'Frontend'. -## Manage group memberships via LDAP **(STARTER ONLY)** +## Manage group memberships via LDAP **(PREMIUM SELF)** Group syncing allows LDAP groups to be mapped to GitLab groups. This provides more control over per-group user management. To configure group syncing edit the `group_base` **DN** (`'OU=Global Groups,OU=GitLab INT,DC=GitLab,DC=org'`). This **OU** contains all groups that will be associated with GitLab groups. @@ -400,10 +400,12 @@ For more information on the administration of LDAP and group sync, refer to the 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. -### Creating group links via CN **(STARTER ONLY)** +### Creating group links via CN **(PREMIUM SELF)** To create group links via CN: +<!-- vale gitlab.Spelling = NO --> + 1. Select the **LDAP Server** for the link. 1. Select `LDAP Group cn` as the **Sync method**. 1. In the **LDAP Group cn** text input box, begin typing the CN of the group. There will be a dropdown menu with matching CNs within the configured `group_base`. Select your CN from this list. @@ -412,7 +414,9 @@ To create group links via CN:  -### Creating group links via filter **(PREMIUM ONLY)** +<!-- vale gitlab.Spelling = YES --> + +### Creating group links via filter **(PREMIUM SELF)** To create group links via filter: @@ -424,7 +428,7 @@ To create group links via filter:  -### Overriding user permissions **(STARTER ONLY)** +### Overriding user permissions **(PREMIUM SELF)** In GitLab [8.15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/822) and later, LDAP user permissions can now be manually overridden by an admin user. To override a user's permissions: @@ -551,12 +555,12 @@ username, you can create a new group and transfer projects to it. You can change settings that are specific to repositories in your group. -#### Custom initial branch name **(CORE ONLY)** +#### Custom initial branch name **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43290) in GitLab 13.6. By default, when you create a new project in GitLab, the initial branch is called `master`. -For groups, a group administrator can customize the initial branch name to something +For groups, a group owner can customize the initial branch name to something else. This way, every new project created under that group from then on will start from the custom branch name rather than `master`. To do so: 1. Go to the **Group page > Settings > Repository** and expand **Default initial @@ -576,7 +580,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, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium](https://about.gitlab.com/pricing/premium/) or higher tiers, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). Since [GitLab 13.6](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), if the user who sets up the deletion leaves or is otherwise removed from the group before the actual deletion happens, the job is cancelled, and the group is no longer scheduled for deletion. @@ -612,7 +616,7 @@ To enable this feature, navigate to the group settings page. Select  -#### Member Lock **(STARTER)** +#### Member Lock **(PREMIUM)** Member lock lets a group owner prevent any new project membership to all of the projects within a group, allowing tighter control over project membership. @@ -634,8 +638,8 @@ request to add a new user to a project through API will not be possible. #### IP access restriction **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in [GitLab Ultimate and Gold](https://about.gitlab.com/pricing/) 12.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) to [GitLab Premium and Silver](https://about.gitlab.com/pricing/) in 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) to [GitLab Premium](https://about.gitlab.com/pricing/) in 13.1. NOTE: IP Access Restrictions are currently not functioning as expected on GitLab.com. Some users @@ -645,9 +649,9 @@ more information. To make sure only people from within your organization can access particular resources, you have the option to restrict access to groups and their -underlying projects, issues, etc, by IP address. This can help ensure that +underlying subgroups, projects, issues, and so on, by IP address. This can help ensure that particular content doesn't leave the premises, while not blocking off access to -the entire instance. +the entire instance. IP access restrictions can only be configured at the group level. Add one or more allowed IP subnets using CIDR notation to the group settings and anyone coming from a different IP address won't be able to access the restricted @@ -672,7 +676,7 @@ To enable this feature: #### Allowed domain restriction **(PREMIUM)** ->- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in [GitLab Premium and Silver](https://about.gitlab.com/pricing/) 12.2. +>- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. >- Support for specifying multiple email domains [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) in GitLab 13.1 You can restrict access to groups by allowing only users with email addresses in particular domains to be added to the group. @@ -702,6 +706,9 @@ To enable this feature: This will enable the domain-checking for all new users added to the group from this moment on. +NOTE: +Domain restrictions only apply to groups and do not prevent users from being added as members of projects owned by the restricted group. + #### Group file templates **(PREMIUM)** Group file templates allow you to share a set of templates for common file @@ -726,6 +733,9 @@ To enable this feature, navigate to the group settings page, expand the  +To learn how to create templates for issues and merge requests, visit +[Description templates](../project/description_templates.md). + #### Group-level project templates **(PREMIUM)** Define project templates at a group level by setting a group as the template source. @@ -765,7 +775,7 @@ To enable this feature: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. By default, projects within a group are deleted immediately. -Optionally, on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, +Optionally, on [Premium](https://about.gitlab.com/pricing/) or higher tiers, 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. @@ -785,7 +795,7 @@ The group setting for delayed deletion is not inherited by sub-groups and has to > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216987) in GitLab 13.3. By default, projects within a group can be forked. -Optionally, on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, +Optionally, on [Premium](https://about.gitlab.com/pricing/) or higher tiers, you can prevent the projects within a group from being forked outside of the current top-level group. Previously this setting was available only for groups enforcing group managed account. This setting will be @@ -804,11 +814,11 @@ To enable prevent project forking: - **Webhooks**: Configure [webhooks](../project/integrations/webhooks.md) for your group. - **Kubernetes cluster integration**: Connect your GitLab group with [Kubernetes clusters](clusters/index.md). - **Audit Events**: View [Audit Events](../../administration/audit_events.md) - for the group. **(STARTER ONLY)** + for the group. **(PREMIUM SELF)** - **Pipelines quota**: Keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group. - **Integrations**: Configure [integrations](../admin_area/settings/project_integration_management.md) for your group. -#### Group push rules **(STARTER)** +#### Group push rules **(PREMIUM)** > - [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. @@ -824,12 +834,12 @@ 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. -### Maximum artifacts size **(CORE ONLY)** +### Maximum artifacts size **(FREE SELF)** For information about setting a maximum artifact size for a group, see [Maximum artifacts size](../admin_area/settings/continuous_integration.md#maximum-artifacts-size). -## User contribution analysis **(STARTER)** +## User contribution analysis **(PREMIUM)** With [GitLab Contribution Analytics](contribution_analytics/index.md), you have an overview of the contributions (pushes, merge requests, diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 269be19f759..97f62becdb6 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. Issue Analytics is a bar graph which illustrates the number of issues created each month. -The default timespan is 13 months, which includes the current month, and the 12 months +The default time span is 13 months, which includes the current month, and the 12 months prior. To access the chart, navigate to your group sidebar and select **{chart}** **Analytics > Issue Analytics**. diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index fc4fb0236de..3204292160c 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -30,10 +30,10 @@ You can get a CSV of the code coverage data for all of the projects in your grou To get the report: 1. Go to your group's **Analytics > Repositories** page -1. Click **Download historic test coverage data (.csv)**, +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)**. +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). diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index f3b7be536ae..e2c01987e36 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -40,7 +40,8 @@ toggle the list of the milestone bars. > - Filtering roadmaps by milestone is [deployed behind a feature flag](../../feature_flags.md), enabled by default. > - Filtering roadmaps by milestone is enabled on GitLab.com. > - Filtering roadmaps by milestone is recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-filtering-roadmaps-by-milestone). **(PREMIUM ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-filtering-roadmaps-by-milestone). **(PREMIUM SELF)** +> - Filtering by epic confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218624) in GitLab 13.8. WARNING: Filtering roadmaps by milestone might not be available to you. Check the **version history** note above for details. @@ -62,18 +63,18 @@ You can sort epics in the Roadmap view by: Each option contains a button that toggles the sort order between **ascending** and **descending**. The sort option and order persist when browsing Epics, including the [epics list view](../epics/index.md). -You can also filter epics in the Roadmap view by: +You can also filter epics in the Roadmap view by the epics': - Author - Label - Milestone -- Confidentiality of epics +- Confidentiality  Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics). -### Enable or disable filtering roadmaps by milestone **(PREMIUM ONLY)** +### Enable or disable filtering roadmaps by milestone **(PREMIUM SELF)** Filtering roadmaps by milestone is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index 7158b7bc86b..aee491fa47b 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: 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/groups/gitlab-org/-/epics/4345) that does not require separate accounts. -We recommend that group administrators who haven't yet implemented this feature wait for +We recommend that group owners who haven't yet implemented this feature wait for the new solution. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/709) in GitLab 12.1. @@ -50,7 +50,7 @@ assertions to be able to create a user. | First Name | `first_name`, `firstname`, `firstName` | | Last Name | `last_name`, `lastname`, `lastName` | -## Feature flag **(PREMIUM ONLY)** +## Feature flag **(PREMIUM SELF)** The group-managed accounts feature is behind these feature flags: `group_managed_accounts`, `sign_up_on_sso` and `convert_user_to_group_managed_accounts`. The flags are disabled by default. To activate the feature, ask a GitLab administrator with Rails console access to run: diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 0ce92eac1a3..10344c60e7e 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -5,7 +5,7 @@ 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/#assignments --- -# SAML SSO for GitLab.com groups **(SILVER ONLY)** +# SAML SSO for GitLab.com groups **(PREMIUM SAAS)** > Introduced in GitLab 11.0. @@ -26,6 +26,7 @@ SAML SSO is not supported at the subgroup level. 1. Configure your SAML server using the **Assertion consumer service URL**, **Identifier**, and **GitLab single sign-on URL**. Alternatively GitLab provides [metadata XML configuration](#metadata-configuration). See [specific identity provider documentation](#providers) for more details. 1. Configure the SAML response to include a NameID that uniquely identifies each user. 1. Configure [required assertions](group_managed_accounts.md#assertions) if using [Group Managed Accounts](group_managed_accounts.md). +1. While the default is enabled for most SAML providers, please ensure the app is set to have [Service Provider](#glossary) initiated calls in order to link existing GitLab accounts. 1. Once the identity provider is set up, move on to [configuring GitLab](#configuring-gitlab).  @@ -110,7 +111,8 @@ When [configuring your identify provider](#configuring-your-identity-provider), ### Azure setup notes <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). Please note that the video is outdated in regards to objectID mapping and the [SCIM documentation should be followed](scim_setup.md#azure-configuration-steps). +For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). Please note that the video is outdated in regard to +objectID mapping and the [SCIM documentation should be followed](scim_setup.md#azure-configuration-steps). | GitLab Setting | Azure Field | |--------------|----------------| @@ -280,7 +282,7 @@ If a user is already a member of the group, linking the SAML identity does not c To rescind access to the group, perform the following steps, in order: -1. Remove the user from the user datastore on the identity provider or the list of users on the specific app. +1. Remove the user from the user data store on the identity provider or the list of users on the specific app. 1. Remove the user from the GitLab.com group. ### Unlinking accounts @@ -292,7 +294,7 @@ Users can unlink SAML for a group from their profile page. This can be helpful i WARNING: Unlinking an account removes all roles assigned to that user within the group. -If a user relinks their account, roles need to be reassigned. +If a user re-links their account, roles need to be reassigned. For example, to unlink the `MyOrg` account, the following **Disconnect** button is available under **Profile > Accounts**: @@ -341,9 +343,9 @@ access. | Term | Description | |------|-------------| -| Identity Provider | The service which manages your user identities such as ADFS, Okta, Onelogin, or Ping Identity. | +| Identity Provider | The service which manages your user identities such as ADFS, Okta, OneLogin, or Ping Identity. | | Service Provider | SAML considers GitLab to be a service provider. | -| Assertion | A piece of information about a user's identity, such as their name or role. Also know as claims or attributes. | +| Assertion | A piece of information about a user's identity, such as their name or role. Also known as claims or attributes. | | SSO | Single Sign On. | | Assertion consumer service URL | The callback on GitLab where users are redirected after successfully authenticating with the identity provider. | | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | @@ -376,7 +378,7 @@ For convenience, we've included some [example resources](../../../administration ### Verifying NameID -In troubleshooting the Group SAML setup, any authenticated user can use the API to verify the NameID GitLab already has linked to the user by visiting [https://gitlab.com/api/v4/user](https://gitlab.com/api/v4/user) and checking the `extern_uid` under identities. +In troubleshooting the Group SAML setup, any authenticated user can use the API to verify the NameID GitLab already has linked to the user by visiting [`https://gitlab.com/api/v4/user`](https://gitlab.com/api/v4/user) and checking the `extern_uid` under identities. Similarly, group members of a role with the appropriate permissions can make use of the [members API](../../../api/members.md) to view group SAML identity information for members of the group. @@ -387,7 +389,7 @@ This can then be compared to the [NameID](#nameid) being sent by the Identity Pr If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](#configuring-your-identity-provider), they may see a 404. As outlined in the [user access section](#linking-saml-to-your-existing-gitlabcom-account), a group Owner will need to provide the URL to users. -### Message: "SAML authentication failed: Extern uid has already been taken" +### Message: "SAML authentication failed: Extern UID has already been taken" This error suggests you are signed in as a GitLab user but have already linked your SAML identity to a different GitLab user. Sign out and then try to sign in again using the SSO SAML link, which should log you into GitLab with the linked user account. @@ -408,7 +410,7 @@ Here are possible causes and solutions: |------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| | When a user account with the email address already exists in GitLab, but the user does not have the SAML identity tied to their account. | The user will need to [link their account](#user-access-and-management). | -### Message: "SAML authentication failed: Extern uid has already been taken, User has already been taken" +### Message: "SAML authentication failed: Extern UID has already been taken, User has already been taken" 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. @@ -418,6 +420,11 @@ This can be prevented by configuring the [NameID](#nameid) to return a consisten Ensure that the user who is trying to link their GitLab account has been added as a user within the identity provider's SAML app. +Alternatively, the SAML response may be missing the `InResponseTo` attribute in the +`samlp:Response` tag, which is [expected by the SAML gem](https://github.com/onelogin/ruby-saml/blob/9f710c5028b069bfab4b9e2b66891e0549765af5/lib/onelogin/ruby-saml/response.rb#L307-L316). +The [Identity Provider](#glossary) administrator should ensure that the login is +initiated by the Service Provider (typically GitLab) and not the Identity Provider. + ### Stuck in a login "loop" Ensure that the **GitLab single sign-on URL** has been configured as "Login URL" (or similarly named field) in the identity provider's SAML app. @@ -446,3 +453,25 @@ However, self-managed GitLab instances use a configuration file that supports mo Internally that uses the [`ruby-saml` library](https://github.com/onelogin/ruby-saml), so we sometimes check there to verify low level details of less commonly used options. It can also help to compare the XML response from your provider with our [example XML used for internal testing](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/spec/fixtures/saml/response.xml). + +### Searching Rails log + +With access to the rails log or `production_json.log` (available only to GitLab team members for GitLab.com), +you should be able to find the base64 encoded SAML response by searching with the following filters: + +- `json.meta.caller_id`: `Groups::OmniauthCallbacksController#group_saml` +- `json.meta.user` or `json.username`: `username` +- `json.method`: `POST` +- `json.path`: `/groups/GROUP-PATH/-/saml/callback` + +In a relevant log entry, the `json.params` should provide a valid response with: + +- `"key": "SAMLResponse"` and the `"value": (full SAML response)`, +- `"key": "RelayState"` with `"value": "/group-path"`, and +- `"key": "group_id"` with `"value": "group-path"`. + +In some cases, if the SAML response is lengthy, you may receive a `"key": "truncated"` with `"value":"..."`. +In these cases, please ask a group owner for a copy of the SAML response from when they select +the "Verify SAML Configuration" button on the group SSO Settings page. + +Use a base64 decoder to see a human-readable version of the SAML response. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index cd3e99ae541..3a34a4b0599 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -5,9 +5,9 @@ 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/#assignments --- -# SCIM provisioning using SAML SSO for GitLab.com groups **(SILVER ONLY)** +# SCIM provisioning using SAML SSO for GitLab.com groups **(PREMIUM SAAS)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab Premium 11.10. System for Cross-domain Identity Management (SCIM), is an open standard that enables the automation of user provisioning. When SCIM is provisioned for a GitLab group, membership of @@ -260,7 +260,7 @@ It is important not to update these to incorrect values, since this will cause u Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](index.md#i-need-to-change-my-saml-app) section. -Alternatively, users can be removed from the SCIM app which will delink all removed users. Sync can then be turned on for the new SCIM app to [link existing users](#user-access-and-linking-setup). +Alternatively, users can be removed from the SCIM app which de-links all removed users. Sync can then be turned on for the new SCIM app to [link existing users](#user-access-and-linking-setup). ### The SCIM app is throwing `"User has already been taken","status":409` error message diff --git a/doc/user/group/security_dashboard/index.md b/doc/user/group/security_dashboard/index.md deleted file mode 100644 index 3feccf2e342..00000000000 --- a/doc/user/group/security_dashboard/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/security_dashboard/index.md' ---- - -This document was moved to [another location](../../application_security/security_dashboard/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 6b95388bf2e..6ad550d77c3 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -69,7 +69,7 @@ For more details on the specific data persisted in a group export, see the  -1. Once the export is generated, you should receive an e-mail with a link to the [exported contents](#exported-contents) +1. After the export is generated, you should receive an e-mail with a link to the [exported contents](#exported-contents) in a compressed tar archive, with contents in JSON format. 1. Alternatively, you can come back to the project settings and download the @@ -77,7 +77,7 @@ For more details on the specific data persisted in a group export, see the NOTE: The maximum import file size can be set by the Administrator, default is `0` (unlimited). -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin UI](../../admin_area/settings/account_and_limit_settings.md). +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin UI](../../admin_area/settings/account_and_limit_settings.md). Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. ### Between CE and EE diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 438769872c0..4fcef07a04e 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -324,7 +324,7 @@ To delete a custom value stream: This chart visually depicts the total number of days it takes for cycles to be completed. (Totals are being replaced with averages in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/262070).) This chart uses the global page filters for displaying data based on the selected -group, projects, and timeframe. In addition, specific stages can be selected +group, projects, and time frame. In addition, specific stages can be selected from within the chart itself. The chart data is limited to the last 500 items. @@ -345,7 +345,7 @@ Feature.disable(:cycle_analytics_scatterplot_enabled) This chart shows a cumulative count of issues and merge requests per day. This chart uses the global page filters for displaying data based on the selected -group, projects, and timeframe. The chart defaults to showing counts for issues but can be +group, projects, and time frame. The chart defaults to showing counts for issues but can be toggled to show data for merge requests and further refined for specific group-level labels. By default the top group-level labels (max. 10) are pre-selected, with the ability to diff --git a/doc/user/incident_management/index.md b/doc/user/incident_management/index.md deleted file mode 100644 index ed3516df168..00000000000 --- a/doc/user/incident_management/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../operations/incident_management/index.md' ---- - -This document was moved to [../../operations/incident_management/index.md](../../operations/incident_management/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/index.md b/doc/user/index.md index 3b2acfab34c..598c47963b5 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -43,7 +43,7 @@ GitLab is a Git-based platform that integrates a great number of essential tools - Hosting code in repositories with version control. - Tracking proposals for new implementations, bug reports, and feedback with a fully featured [Issue Tracker](project/issues/index.md#issues-list). -- Organizing and prioritizing with [Issue Boards](project/issues/index.md#issue-boards). +- Organizing and prioritizing with [Issue Boards](project/issue_board.md). - Reviewing code in [Merge Requests](project/merge_requests/index.md) with live-preview changes per branch with [Review Apps](../ci/review_apps/index.md). - Building, testing, and deploying with built-in [Continuous Integration](../ci/README.md). diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 60453b007ba..bab61402909 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Infrastructure as code with Terraform and GitLab +# Infrastructure as code with Terraform and GitLab **(CORE)** ## Motivation @@ -26,6 +26,8 @@ variables: # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables TF_STATE_NAME: default TF_CACHE_KEY: default + # If your terraform files are in a subdirectory, set TF_ROOT accordingly + # TF_ROOT: terraform/production ``` This template uses `.latest.`, instead of stable, and may include breaking changes. @@ -39,6 +41,15 @@ This template also includes some opinionated decisions, which you can override: [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml) `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on `master`. +This video from January 2021 walks you through all the GitLab Terraform integration features: + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=iGXjUrkkzDI">Terraform with GitLab</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/iGXjUrkkzDI" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + ## GitLab Managed Terraform state [Terraform remote backends](https://www.terraform.io/docs/backends/index.html) diff --git a/doc/user/infrastructure/mr_integration.md b/doc/user/infrastructure/mr_integration.md index 2704e7b7c8d..c9c29405ee9 100644 --- a/doc/user/infrastructure/mr_integration.md +++ b/doc/user/infrastructure/mr_integration.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Terraform integration in Merge Requests +# Terraform integration in Merge Requests **(CORE)** Collaborating around Infrastructure as Code (IaC) changes requires both code changes and expected infrastructure changes to be checked and approved. GitLab provides a solution to help collaboration around Terraform code changes and their expected effects using the Merge Request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows. diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md index 30838b1cabd..c1b09b2f03b 100644 --- a/doc/user/infrastructure/terraform_state.md +++ b/doc/user/infrastructure/terraform_state.md @@ -4,7 +4,7 @@ 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/#assignments --- -# GitLab managed Terraform State +# GitLab managed Terraform State **(CORE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. @@ -16,8 +16,10 @@ to securely store the state files in local storage (the default) or The GitLab managed Terraform state backend can store your Terraform state easily and securely, and spares you from setting up additional remote resources like -Amazon S3 or Google Cloud Storage. Its features include: +Amazon S3 or Google Cloud Storage. After the GitLab administrator +[sets it up](../../administration/terraform_state.md), its features include: +- Versioning of Terraform state files. - Supporting encryption of the state file both in transit and at rest. - Locking and unlocking state. - Remote Terraform plan and apply execution. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index be6e483aa54..ff796409ada 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -21,7 +21,7 @@ We encourage you to view this document as [rendered by GitLab itself](https://gi ## GitLab Flavored Markdown (GFM) GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification](https://spec.commonmark.org/current/) -(which is based on standard Markdown) in several ways to add additional useful functionality. +(which is based on standard Markdown) in several ways to add more features. It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/free-pro-team@latest/github/writing-on-github/basic-writing-and-formatting-syntax). You can use GFM in the following areas: @@ -41,20 +41,23 @@ for more information. ### Transition from Redcarpet to CommonMark -Since 11.1, GitLab uses the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker) -for Markdown processing of all new issues, merge requests, comments, and other Markdown -content in the GitLab system. Since 11.3, wiki pages and Markdown files (`*.md`) in -repositories are also processed with CommonMark. As of 11.8, the [Redcarpet Ruby library](https://github.com/vmg/redcarpet) -has been removed and all issues and comments, including those from pre-11.1, are now processed -using the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker). - -The documentation website had its [Markdown engine migrated from Redcarpet to Kramdown](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/108) +- In GitLab version 11.8, the [Redcarpet Ruby library](https://github.com/vmg/redcarpet) + was removed. All issues and comments, including those from pre-11.1, are now processed + using the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker). +- GitLab versions 11.3 and greater use CommonMark to process wiki pages and Markdown + files (`*.md`) in repositories. +- GitLab versions 11.1 and greater use the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker) + for Markdown processing of all new issues, merge requests, comments, and other Markdown + content in the GitLab system. + +The documentation website migrated its Markdown engine +[from Redcarpet to Kramdown](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/108) in October 2018. You may have older issues, merge requests, or Markdown documents in your -repository that were written using some of the nuances of the GitLab RedCarpet version -of Markdown. Since CommonMark uses slightly stricter syntax, these documents -might now appear a little differently since we have transitioned to CommonMark. +repository that relied upon nuances of the GitLab RedCarpet version +of Markdown. Because CommonMark uses slightly stricter syntax, these documents +may now appear differently after the transition to CommonMark. For example, numbered lists with nested lists may render incorrectly: @@ -80,23 +83,24 @@ character of the top list item (`C` in this case): We flag any significant differences between Redcarpet and CommonMark Markdown in this document. -If you have a large volume of Markdown files, it can be tedious to determine +If you have many Markdown files, it can be tedious to determine if they display correctly or not. You can use the [`diff_redcarpet_cmark`](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) -tool (not an officially supported product) to generate a list of files and the -differences between how RedCarpet and CommonMark render the files. It gives -an indication if anything needs to be changed - often nothing needs -to change. +tool to generate a list of files and the +differences between how RedCarpet and CommonMark render the files. It indicates +if any changes are needed. + +`diff_redcarpet_cmark` is not an officially supported product. ### GFM extends standard Markdown -GitLab makes full use of the standard (CommonMark) formatting, but also includes additional -functionality useful for GitLab users. +GitLab makes full use of the standard (CommonMark) formatting, but also includes more +helpful features for GitLab users. It makes use of [new Markdown features](#new-gfm-markdown-extensions), not found in standard Markdown: -- [Color "chips" written in HEX, RGB or HSL](#colors) +- [Color chips written in HEX, RGB or HSL](#colors) - [Diagrams and flowcharts](#diagrams-and-flowcharts) - [Emoji](#emoji) - [Front matter](#front-matter) @@ -124,7 +128,7 @@ changing how standard Markdown is used: ### Colors -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colors). +If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colors). It's possible to have color written in HEX, RGB, or HSL format rendered with a color indicator. @@ -168,9 +172,12 @@ It's also possible to use [Kroki](https://kroki.io) to create a wide variety of > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15107) in GitLab 10.3. -Visit the [official page](https://mermaidjs.github.io/) for more details. If you're new to using Mermaid or need help identifying issues in your Mermaid code, the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) is a helpful tool for creating and resolving issues within Mermaid diagrams. +Visit the [official page](https://mermaidjs.github.io/) for more details. The +[Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) helps you +learn Mermaid and debug issues in your Mermaid code. Use it to identify and resolve +issues in your diagrams. -In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block: +To generate a diagram or flowchart, write your text inside the `mermaid` block: ````markdown ```mermaid @@ -239,42 +246,46 @@ Read more in the [Kroki integration](../administration/integration/kroki.md) pag ### Emoji -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#emoji). +If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#emoji). ```markdown Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: :zap: You can use emoji anywhere GFM is supported. :v: -You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. +You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People :heart: you for that. If you're new to this, don't be :fearful:. You can join the emoji :family:. All you need to do is to look up one of the supported codes. Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: ``` -Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px" style="display:inline;margin:0"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px" style="display:inline;margin:0"> to your <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0">. Well we have a gift for you: +Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> to your <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. Well we have a gift for you: -<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px" style="display:inline;margin:0">You can use emoji anywhere GFM is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px" style="display:inline;margin:0"> +<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">You can use emoji anywhere GFM is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> -You can use it to point out a <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/bug.png" width="20px" height="20px" style="display:inline;margin:0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0"> patches. And if someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/snail.png" width="20px" height="20px" style="display:inline;margin:0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/birthday.png" width="20px" height="20px" style="display:inline;margin:0">. People will <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0"> you for that. +You can use it to point out a<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/bug.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> patches. If someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/snail.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/birthday.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. People <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> you for that. -If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0">. You can join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0">. All you need to do is to look up one of the supported codes. +If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. You can join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. All you need to do is to look up one of the supported codes. -Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0"> +Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> #### Emoji and your OS -The emoji example above uses hard-coded images for this documentation. The emoji, -when rendered within GitLab, may appear different depending on the OS and browser used. +The emoji example above uses hard-coded images for this documentation. Rendered emoji +in GitLab may appear different depending on the OS and browser used. Most emoji are natively supported on macOS, Windows, iOS, Android, and fall back on image-based emoji where there is no support. +<!-- vale gitlab.Spelling = NO --> + On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. Ubuntu 18.04 (like many modern Linux distributions) has this font installed by default. +<!-- vale gitlab.Spelling = YES --> + ### Front matter > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23331) in GitLab 11.6. @@ -284,8 +295,9 @@ its content. This data can be used by static site generators such as [Jekyll](ht [Hugo](https://gohugo.io/content-management/front-matter/), and many other applications. When you view a Markdown file rendered by GitLab, any front matter is displayed as-is, -in a box at the top of the document, before the rendered HTML content. To view an example, -you can toggle between the source and rendered version of a [GitLab documentation file](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/README.md). +in a box at the top of the document. The HTML content displays after the front matter. To view an example, +you can toggle between the source and rendered version of a +[GitLab documentation file](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/README.md). In GitLab, front matter is only used in Markdown files and wiki pages, not the other places where Markdown formatting is supported. It must be at the very top of the document @@ -340,7 +352,7 @@ $example = array( ### Inline diff -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-diff). +If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-diff). With inline diff tags you can display `{+ additions +}` or `[- deletions -]`. @@ -413,7 +425,7 @@ the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activati ### Special GitLab references GFM recognizes special GitLab related references. For example, you can reference -an issue, a commit, a team member, or even the whole team within a project. GFM turns +an issue, a commit, a team member, or even an entire project team. GFM turns that reference into a link so you can navigate between them. Additionally, GFM recognizes certain cross-project references and also has a shorthand @@ -421,7 +433,7 @@ version to reference other projects from the same namespace. GFM recognizes the following: -| references | input | cross-project reference | shortcut within same namespace | +| references | input | cross-project reference | shortcut inside same namespace | | :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- | | specific user | `@user_name` | | | | specific group | `@group_name` | | | @@ -447,8 +459,8 @@ GFM recognizes the following: 1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7. -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 +For example, referencing an issue by using `#123` formats the output as a link +to issue number 123 with text `#123`. Likewise, a link to issue number 123 is recognized and formatted with text `#123`. In addition to this, links to some objects are also recognized and formatted. Some examples of these are: @@ -459,12 +471,12 @@ In addition to this, links to some objects are also recognized and formatted. So ### Task lists -If this section is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#task-lists). +If this section isn't rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#task-lists). -You can add task lists anywhere Markdown is supported, but you can only "click" -to toggle the boxes if they are in issues, merge requests, or comments. In other -places you must edit the Markdown manually to change the status by adding or -removing an `x` within the square brackets. +You can add task lists anywhere Markdown is supported, but only issues, merge requests, and +comments support clicking to toggle the boxes. In other +places, you must edit the Markdown manually to change the status by adding or +removing an `x` inside the square brackets. To create a task list, add a specially-formatted Markdown list. You can use either unordered or ordered lists: @@ -482,13 +494,13 @@ unordered or ordered lists: 1. [x] Sub-task 2 ``` - + ### Table of contents -You can add a table of contents to a Markdown file, wiki page, or issue/merge request -description, by adding the tag `[[_TOC_]]` on its own line. -It appears as an unordered list that links to the various headers. +Add a table of contents to a Markdown file, wiki page, issue request, or merge request +description by adding the tag `[[_TOC_]]` on its own line. +It displays an unordered list that links to subheadings in the document. ```markdown This is an intro sentence to my Wiki page. @@ -504,7 +516,7 @@ First section content. Second section content. ``` - + ### Wiki-specific Markdown @@ -583,38 +595,39 @@ This snippet links to `<wiki_root>/miscellaneous.md`: ### Embedding metrics in GitLab Flavored Markdown -Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab flavored Markdown](../operations/metrics/embed.md) for more details. +Metric charts can be embedded in GitLab Flavored Markdown. Read +[Embedding Metrics in GitLab flavored Markdown](../operations/metrics/embed.md) for more details. ## Standard Markdown and extensions in GitLab -All standard Markdown formatting should work as expected within GitLab. Some standard +All standard Markdown formatting should work as expected in GitLab. Some standard functionality is extended with additional features, without affecting the standard usage. If a functionality is extended, the new option is listed as a sub-section. ### Blockquotes -Blockquotes are useful to highlight information, such as a side-note. It's generated +Use a blockquote to highlight information, such as a side note. It's generated by starting the lines of the blockquote with `>`: ```markdown -> Blockquotes are very handy to emulate reply text. +> Blockquotes help you emulate reply text. > This line is part of the same quote. Quote break. -> This is a very long line that is still quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. +> This is a very long line that is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote. ``` -> Blockquotes are very handy to emulate reply text. +> Blockquotes help you emulate reply text. > This line is part of the same quote. Quote break. -> This is a very long line that is still quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. +> This is a very long line that is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote. #### Multiline blockquote -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiline-blockquote). +If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiline-blockquote). GFM extends the standard Markdown by also supporting multi-line blockquotes fenced by `>>>`: @@ -639,9 +652,9 @@ you can quote that without having to manually prepend `>` to every line! ### Code spans and blocks -You can highlight anything that should be viewed as code and not simple text. +You can highlight anything that should be viewed as code and not standard text. -Simple inline code is highlighted with single backticks `` ` ``: +Inline code is highlighted with single backticks `` ` ``: ```markdown Inline `code` has `back-ticks around` it. @@ -651,9 +664,11 @@ Inline `code` has `back-ticks around` it. --- -Similarly, a whole block of code can be fenced with triple backticks (```` ``` ````), -triple tildes (`~~~`), or indented 4 or more spaces to achieve a similar effect for -a larger body of code. +To achieve a similar effect for a larger code example, you can: + +- Fence an entire block of code with triple backticks (```` ``` ````). +- Fence an entire block of code with triple tildes (`~~~`). +- Indent it four or more spaces. ````markdown ```python @@ -695,16 +710,16 @@ Tildes are OK too. #### Colored code and syntax highlighting -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting). +If this section isn't rendered correctly, +[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting). GitLab uses the [Rouge Ruby library](http://rouge.jneen.net/) for more colorful syntax highlighting in code blocks. For a list of supported languages visit the [Rouge project wiki](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers). -Syntax highlighting is only supported in code blocks, so it's not possible to highlight -code when it's inline. +Syntax highlighting is supported only in code blocks, so you can't highlight inline code. -Blocks of code are fenced by lines with three back-ticks (```` ``` ````) or three tildes (`~~~`), and have -the language identified at the end of the first fence: +To fence and apply syntax highlighting to a block of code, append the code language +to the opening code declaration, three back-ticks (```` ``` ````) or three tildes (`~~~`): ````markdown ```javascript @@ -761,7 +776,7 @@ But let's throw in a <b>tag</b>. ### Emphasis There are multiple ways to emphasize text in Markdown. You can italicize, bold, strikethrough, -as well as combine these emphasis styles together. +and combine these emphasis styles together. Strikethrough is not part of the core Markdown standard, but is part of GFM. Examples: @@ -786,10 +801,11 @@ Strikethrough uses two tildes. ~~Scratch this.~~ #### Multiple underscores in words and mid-word emphasis -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiple-underscores-in-words). +If this section isn't rendered correctly, +[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiple-underscores-in-words). -It's not usually useful to italicize just _part_ of a word, especially when you're -dealing with code and names that often appear with multiple underscores. As a result, +Avoid italicizing a portion of a word, especially when you're +dealing with code and names that often appear with multiple underscores. GFM extends the standard Markdown standard by ignoring multiple underlines in words, to allow better rendering of Markdown documents discussing code: @@ -922,8 +938,7 @@ emoji is converted to an image which is then removed from the ID. ### Horizontal Rule -It's very simple to create a horizontal rule, by using three or more hyphens, asterisks, -or underscores: +Create a horizontal rule by using three or more hyphens, asterisks, or underscores: ```markdown Three or more hyphens, @@ -978,7 +993,7 @@ Do not change to a reference style link. #### Videos -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#videos). +If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#videos). Image tags that link to files with a video extension are automatically converted to a video player. The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`: @@ -995,7 +1010,7 @@ Here's a sample video: #### Audio -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#audio). +If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#audio). Similar to videos, link tags for files with an audio extension are automatically converted to an audio player. The valid audio extensions are `.mp3`, `.oga`, `.ogg`, `.spx`, and `.wav`: @@ -1012,7 +1027,8 @@ Here's a sample audio clip: ### Inline HTML -To see the Markdown rendered within HTML in the second example, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-html). +To see the second example of Markdown rendered in HTML, +[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-html). You can also use raw HTML in your Markdown, and it usually works pretty well. @@ -1076,11 +1092,12 @@ Markdown is fine in GitLab. #### Details and summary -To see the Markdown rendered within HTML in the second example, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#details-and-summary). +To see the second Markdown example rendered in HTML, +[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#details-and-summary). Content can be collapsed using HTML's [`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) and [`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) -tags. This is especially useful for collapsing long logs so they take up less screen space. +tags. For example, collapse a long log file so it takes up less screen space. ```html <p> @@ -1108,7 +1125,7 @@ These details <em>remain</em> <strong>hidden</strong> until expanded. --- -Markdown inside these tags is supported as well. +Markdown inside these tags is also supported. NOTE: If your Markdown isn't rendering correctly, try adding @@ -1150,7 +1167,7 @@ These details <em>remain</em> <b>hidden</b> until expanded. A line break is inserted (a new paragraph starts) if the previous text is ended with two newlines, like when you hit <kbd>Enter</kbd> twice in a row. If you only use one newline (hit <kbd>Enter</kbd> once), the next sentence remains part of the -same paragraph. This is useful if you want to keep long lines from wrapping, and keep +same paragraph. Use this approach if you want to keep long lines from wrapping, and keep them editable: ```markdown @@ -1180,7 +1197,7 @@ GFM adheres to the Markdown specification in how [paragraphs and line breaks are A paragraph is one or more consecutive lines of text, separated by one or more blank lines (two newlines at the end of the first paragraph), as [explained above](#line-breaks). -If you need more control over line breaks or soft returns, you can add a single line break +Need more control over line breaks or soft returns? Add a single line break by ending a line with a backslash, or two or more spaces. Two newlines in a row create a new paragraph, with a blank line in between: @@ -1268,6 +1285,8 @@ GFM auto-links almost any URL you put into your text: - http://localhost:3000 ``` +<!-- vale gitlab.Spelling = NO --> + - <https://www.google.com> - <https://www.google.com> - <ftp://ftp.us.debian.org/debian/> @@ -1275,6 +1294,7 @@ GFM auto-links almost any URL you put into your text: - <irc://irc.freenode.net/> - <http://localhost:3000> +<!-- vale gitlab.Spelling = YES --> ### Lists Ordered and unordered lists can be created. @@ -1397,17 +1417,21 @@ Example: ### Superscripts / Subscripts -Currently, CommonMark and GFM don't support the superscript syntax ( `x^2` ) that -Redcarpet does. You can use the standard HTML syntax for superscripts and subscripts: +CommonMark and GFM don't support the Redcarpet superscript syntax ( `x^2` ). +Use the standard HTML syntax for superscripts and subscripts: ```html The formula for water is H<sub>2</sub>O while the equation for the theory of relativity is E = mc<sup>2</sup>. ``` +<!-- vale gitlab.Spelling = NO --> + The formula for water is H<sub>2</sub>O while the equation for the theory of relativity is E = mc<sup>2</sup>. +<!-- vale gitlab.Spelling = YES --> + ### Tables Tables are not part of the core Markdown spec, but they are part of GFM. @@ -1437,7 +1461,7 @@ Example: | 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 9 | -Additionally, you can choose the alignment of text within columns by adding colons (`:`) +Additionally, you can choose the alignment of text in columns by adding colons (`:`) to the sides of the "dash" lines in the second row. This affects every cell in the column: ```markdown @@ -1452,7 +1476,7 @@ to the sides of the "dash" lines in the second row. This affects every cell in t | Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | | Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | -[Within GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#tables), +[In GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#tables), the headers are always left-aligned in Chrome and Firefox, and centered in Safari. You can use HTML formatting to adjust the rendering of tables. For example, you can @@ -1470,7 +1494,7 @@ use `<br>` tags to force a cell to have multiple lines: | Item1 | This is on one line | | Item2 | This item has:<br>- Multiple items<br>- That we want listed separately | -You can use HTML formatting within GitLab itself to add [task lists](#task-lists) with checkboxes, +You can use HTML formatting in GitLab itself to add [task lists](#task-lists) with checkboxes, but they do not render properly on `docs.gitlab.com`: ```markdown @@ -1485,8 +1509,8 @@ but they do not render properly on `docs.gitlab.com`: [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27205) in GitLab 12.7. If you're working in spreadsheet software (for example, Microsoft Excel, Google -Sheets, or Apple Numbers), you can copy from a spreadsheet, and GitLab -pastes it as a Markdown table. For example, suppose you have the +Sheets, or Apple Numbers), GitLab creates a Markdown table when you copy-and-paste +from a spreadsheet. For example, suppose you have the following spreadsheet:  @@ -1502,4 +1526,4 @@ entry and paste the spreadsheet: - The original [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard Markdown. - You can find the detailed specification for CommonMark in the [CommonMark Spec](https://spec.commonmark.org/current/). -- The [CommonMark Dingus](https://spec.commonmark.org/dingus/) is a handy tool for testing CommonMark syntax. +- The [CommonMark Dingus](https://spec.commonmark.org/dingus/) helps you test CommonMark syntax. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index bef768cad4e..be3454dbd02 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -6,23 +6,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Operations Dashboard **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5781) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/9218) to [GitLab Premium](https://about.gitlab.com/pricing/) in 11.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5781) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/9218) to [GitLab Premium](https://about.gitlab.com/pricing/) in 11.10. The Operations Dashboard provides a summary of each project's operational health, including pipeline and alert status. -The dashboard can be accessed via the top bar, by clicking **More > Operations**. +The dashboard can be accessed from the top bar, by clicking **More > Operations**. ## Adding a project to the dashboard NOTE: For GitLab.com, you can add your project to the Operations Dashboard for free if your project is public. If your project is private, the group it belongs to must -have a [Silver](https://about.gitlab.com/pricing/) plan. +have a [GitLab Premium](https://about.gitlab.com/pricing/) plan. To add a project to the dashboard: -1. Click the **Add projects** button in the homescreen of the dashboard. +1. Ensure your alerts + [populate the `gitlab_environment_name` field](../../operations/metrics/alerts.md#external-prometheus-instances). + In GitLab 13.9, you can display alerts for the `production` environment only. +1. Click the **Add projects** button in the home screen of the dashboard. 1. Search and add one or more projects using the **Search your projects** field. 1. Click the **Add projects** button. diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 6159ea395fa..c7245a0fd19 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Composer packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. Publish [Composer](https://getcomposer.org/) packages in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index f90c220a622..0f4ed62d265 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -7,9 +7,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Conan packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. -Publish Conan packages in your project’s Package Registry. Then install the +Publish Conan packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. To publish Conan packages to the Package Registry, add the Package Registry as a @@ -98,7 +98,8 @@ For more details about creating and managing Conan packages, see the ## Add the Package Registry as a Conan remote To run `conan` commands, you must add the Package Registry as a Conan remote for -your project or instance. +your project or instance. Then you can publish packages to +and install packages from the Package Registry. ### Add a remote for your project @@ -170,13 +171,13 @@ convention. ## Authenticate to the Package Registry -To authenticate to the Package Registry, you need either a personal access token -or deploy token. +To authenticate to the Package Registry, you need one of the following: -- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), - set the scope to `api`. -- If you use a [deploy token](../../project/deploy_tokens/index.md), set the - scope to `read_package_registry`, `write_package_registry`, or both. +- A [personal access token](../../../user/profile/personal_access_tokens.md) + with the scope set to `api`. +- A [deploy token](../../project/deploy_tokens/index.md) with the + scope set to `read_package_registry`, `write_package_registry`, or both. +- A [CI job token](#publish-a-conan-package-by-using-cicd). ### Add your credentials to the GitLab remote @@ -278,10 +279,19 @@ create_package: Additional Conan images to use as the basis of your CI file are available in the [Conan docs](https://docs.conan.io/en/latest/howtos/run_conan_in_docker.html#available-docker-images). +### Re-publishing a package with the same recipe + +When you publish a package that has the same recipe (`package-name/version@user/channel`) +as an existing package, the duplicate files are uploaded successfully and +are accessible through the UI. However, when the package is installed, +only the most recently-published package is returned. + ## Install a Conan package Install a Conan package from the Package Registry so you can use it as a -dependency. +dependency. You can install a package from the scope of your instance or your project. +If multiple packages have the same recipe, when you install +a package, the most recently-published package is retrieved. WARNING: Project-level packages [cannot be downloaded currently](https://gitlab.com/gitlab-org/gitlab/-/issues/270129). diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 8c284ccb9a3..b19be5f6bdc 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -571,6 +571,52 @@ Here are examples of regex patterns you may want to use: (?:v.+|master|release) ``` +### Set cleanup limits to conserve resources + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/288812) in GitLab 13.9. +> - It's [deployed behind a feature flag](../../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-cleanup-policy-limits). + +Cleanup policies are executed as a background process. This process is complex, and depending on the number of tags to delete, +the process can take time to finish. + +To prevent server resource starvation, the following application settings are available: + +- `container_registry_expiration_policies_worker_capacity`. The maximum number of cleanup workers running concurrently. This must be greater than `1`. + We recommend starting with a low number and increasing it after monitoring the resources used by the background workers. +- `container_registry_delete_tags_service_timeout`. The maximum time, in seconds, that the cleanup process can take to delete a batch of tags. +- `container_registry_cleanup_tags_service_max_list_size`. The maximum number of tags that can be deleted in a single execution. Additional tags must be deleted in another execution. + We recommend starting with a low number, like `100`, and increasing it after monitoring that container images are properly deleted. + +For self-managed instances, those settings can be updated in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + + ```ruby + ApplicationSetting.last.update(container_registry_expiration_policies_worker_capacity: 3) + ``` + +Alternatively, once the limits are [enabled](#enable-or-disable-cleanup-policy-limits), they are available in the [admin area](../../admin_area/index.md) **Settings > CI/CD > Container Registry**. + +#### Enable or disable cleanup policy limits + +The cleanup policies limits are under development and not ready for production use. They are +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(:container_registry_expiration_policies_throttling) +``` + +To disable it: + +```ruby +Feature.disable(:container_registry_expiration_policies_throttling) +``` + ### Use the cleanup policy API You can set, update, and disable the cleanup policies using the GitLab API. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 5e5aadfae2b..fd75df513c7 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -7,9 +7,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Proxy > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 13.6. -> - [Support for private groups](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. -> - Anonymous access to images in public groups is no longer available starting in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Free](https://about.gitlab.com/pricing/) in GitLab 13.6. +> - [Support for private groups](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Free](https://about.gitlab.com/pricing/) 13.7. +> - Anonymous access to images in public groups is no longer available starting in [GitLab Free](https://about.gitlab.com/pricing/) 13.7. +> - [Support for pull-by-digest and Docker version 20.x](https://gitlab.com/gitlab-org/gitlab/-/issues/290944) in [GitLab Free](https://about.gitlab.com/pricing/) 13.9. The GitLab Dependency Proxy is a local proxy you can use for your frequently-accessed upstream images. @@ -17,11 +18,6 @@ upstream images. In the case of CI/CD, the Dependency Proxy receives a request and returns the upstream image from a registry, acting as a pull-through cache. -NOTE: -The Dependency Proxy is not compatible with Docker version 20.x and later. -If you are using the Dependency Proxy, Docker version 19.x.x is recommended until -[issue #290944](https://gitlab.com/gitlab-org/gitlab/-/issues/290944) is resolved. - ## Prerequisites The Dependency Proxy must be [enabled by an administrator](../../../administration/packages/dependency_proxy.md). @@ -60,11 +56,11 @@ Prerequisites: ### Authenticate with the Dependency Proxy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Free](https://about.gitlab.com/pricing/) 13.7. > - 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](../../../administration/packages/dependency_proxy.md#disabling-authentication). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](../../../administration/packages/dependency_proxy.md#disabling-authentication). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -91,33 +87,29 @@ You can authenticate using: #### Authenticate within CI/CD -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280582) in GitLab 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280582) in GitLab 13.7. +> - Automatic runner authentication [added](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27302) in GitLab 13.9. -To work with the Dependency Proxy in [GitLab CI/CD](../../../ci/README.md), you can use: +Runners log in to the Dependency Proxy automatically. To pull through +the Dependency Proxy, use the `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` +environment variable: + +```yaml +# .gitlab-ci.yml +image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:latest +``` + +There are other additional predefined environment variables you can also use: - `CI_DEPENDENCY_PROXY_USER`: A CI user for logging in to the Dependency Proxy. - `CI_DEPENDENCY_PROXY_PASSWORD`: A CI password for logging in to the Dependency Proxy. - `CI_DEPENDENCY_PROXY_SERVER`: The server for logging in to the Dependency Proxy. - `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`: The image prefix for pulling images through the Dependency Proxy. -This script shows how to use these variables to log in and pull an image from the Dependency Proxy: - -```yaml -# .gitlab-ci.yml - -dependency-proxy-pull-master: - # Official docker image. - image: docker:latest - stage: build - services: - - docker:dind - before_script: - - docker login -u "$CI_DEPENDENCY_PROXY_USER" -p "$CI_DEPENDENCY_PROXY_PASSWORD" "$CI_DEPENDENCY_PROXY_SERVER" - script: - - docker pull "$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX"/alpine:latest -``` - -`CI_DEPENDENCY_PROXY_SERVER` and `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` include the server port. So if you use `CI_DEPENDENCY_PROXY_SERVER` to log in, for example, you must explicitly include the port in your pull command and vice-versa: +`CI_DEPENDENCY_PROXY_SERVER` and `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` +include the server port. If you explicitly include the Dependency Proxy +path, the port must be included, unless you have logged into the Dependency +Proxy manually without including the port: ```shell docker pull gitlab.example.com:443/my-group/dependency_proxy/containers/alpine:latest @@ -125,61 +117,6 @@ docker pull gitlab.example.com:443/my-group/dependency_proxy/containers/alpine:l You can also use [custom environment variables](../../../ci/variables/README.md#custom-environment-variables) to store and access your personal access token or other valid credentials. -##### Authenticate with `DOCKER_AUTH_CONFIG` - -You can use the Dependency Proxy to pull your base image. - -1. [Create a `DOCKER_AUTH_CONFIG` environment variable](../../../ci/docker/using_docker_images.md#define-an-image-from-a-private-container-registry). -1. Get credentials that allow you to log into the Dependency Proxy. -1. Generate the version of these credentials that will be used by Docker: - - ```shell - # The use of "-n" - prevents encoding a newline in the password. - echo -n "my_username:my_password" | base64 - - # Example output to copy - bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= - ``` - - This can also be a [personal access token](../../../user/profile/personal_access_tokens.md) such as: - - ```shell - echo -n "my_username:personal_access_token" | base64 - ``` - -1. Create a [custom environment variables](../../../ci/variables/README.md#custom-environment-variables) -named `DOCKER_AUTH_CONFIG` with a value of: - - ```json - { - "auths": { - "https://gitlab.example.com": { - "auth": "(Base64 content from above)" - } - } - } - ``` - - To use `$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` when referencing images, you must explicitly include the port in your `DOCKER_AUTH_CONFIG` value: - - ```json - { - "auths": { - "https://gitlab.example.com:443": { - "auth": "(Base64 content from above)" - } - } - } - ``` - -1. Now reference the Dependency Proxy in your base image: - - ```yaml - # .gitlab-ci.yml - image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:latest - ... - ``` - ### Store a Docker image in Dependency Proxy cache To store a Docker image in Dependency Proxy storage: @@ -221,7 +158,7 @@ the [Dependency Proxy API](../../../api/dependency_proxy.md). ## Docker Hub rate limits and the Dependency Proxy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) in [GitLab Free](https://about.gitlab.com/pricing/) 13.7. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch how to [use the Dependency Proxy to help avoid Docker Hub rate limits](https://youtu.be/Nc4nUo7Pq08). diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 82c72481984..11af10bf8a0 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Generic Packages Repository **(CORE)** +# GitLab Generic Packages Repository **(FREE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4209) in GitLab 13.5. > - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. @@ -48,7 +48,7 @@ PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/README.md#namespaced-path-encoding). | | `package_name` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). | `package_version` | string | yes | The package version. It can contain only numbers (`0-9`), and dots (`.`). Must be in the format of `X.Y.Z`, i.e. should match `/\A\d+\.\d+\.\d+\z/` regular expression. -| `file_name` | string | yes | The file name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). +| `file_name` | string | yes | The filename. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). Provide the file context in the request body. @@ -87,7 +87,7 @@ GET /projects/:id/packages/generic/:package_name/:package_version/:file_name | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/README.md#namespaced-path-encoding). | | `package_name` | string | yes | The package name. | | `package_version` | string | yes | The package version. | -| `file_name` | string | yes | The file name. | +| `file_name` | string | yes | The filename. | The file context is served in the response body. The response content type is `application/octet-stream`. diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index 87cd4a4a9a6..d84e629b60c 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - It's disabled for 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-the-go-proxy). -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. With the Go proxy for GitLab, every project in GitLab can be fetched with the [Go proxy protocol](https://proxy.golang.org/). diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 9da14842845..b8efbdb71c1 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -35,6 +35,8 @@ You can also use the [API](../../api/packages.md) to administer the Package Regi The below table lists formats that are not supported, but are accepting Community contributions for. Consider contributing to GitLab. This [development documentation](../../development/packages.md) guides you through the process. +<!-- vale gitlab.Spelling = NO --> + | Format | Status | | ------ | ------ | | Chef | [#36889](https://gitlab.com/gitlab-org/gitlab/-/issues/36889) | @@ -51,6 +53,7 @@ guides you through the process. | Terraform | [WIP: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) | | Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | +<!-- vale gitlab.Spelling = YES --> ## Container Registry The GitLab [Container Registry](container_registry/index.md) is a secure and private registry for container images. It's built on open source software and completely integrated within GitLab. Use GitLab CI/CD to create and publish images. Use the GitLab [API](../../api/container_registry.md) to manage the registry across groups and projects. diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index e0f5a400977..c6bf62dfc9a 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Maven packages in the Package Repository > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. Publish [Maven](https://maven.apache.org) artifacts in your project’s Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -186,10 +186,11 @@ published to the GitLab Package Registry. ## Authenticate to the Package Registry with Maven -To authenticate to the Package Registry, you need either a personal access token or deploy token. +To authenticate to the Package Registry, you need one of the following: -- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), set the scope to `api`. -- If you use a [deploy token](../../project/deploy_tokens/index.md), set the scope to `read_package_registry`, `write_package_registry`, or both. +- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`. +- A [deploy token](../../project/deploy_tokens/index.md) with the scope set to `read_package_registry`, `write_package_registry`, or both. +- A [CI_JOB_TOKEN](#authenticate-with-a-ci-job-token-in-maven). ### Authenticate with a personal access token in Maven @@ -219,7 +220,7 @@ The `name` must be `Private-Token`. ### Authenticate with a deploy token in Maven > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) deploy token authentication in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. To use a deploy token, add this section to your [`settings.xml`](https://maven.apache.org/settings.html) file. @@ -354,12 +355,13 @@ repositories { To use the GitLab endpoint for Maven packages, choose an option: -- **Project-level**: Use when you have few Maven packages and they are not in - the same GitLab group. -- **Group-level**: Use when you have many Maven packages in the same GitLab - group. -- **Instance-level**: Use when you have many Maven packages in different - GitLab groups or in their own namespace. +- **Project-level**: To publish Maven packages to a project, use a project-level endpoint. + To install Maven packages, use a project-level endpoint when you have few Maven packages + and they are not in the same GitLab group. +- **Group-level**: Use a group-level endpoint when you want to install packages from + many different projects in the same GitLab group. +- **Instance-level**: Use an instance-level endpoint when you want to install many + packages from different GitLab groups or in their own namespace. The option you choose determines the settings you add to your `pom.xml` file. @@ -414,7 +416,7 @@ repositories { ### Group-level Maven endpoint > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. 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 @@ -462,7 +464,7 @@ repositories { ``` - For the `id`, use what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). -- For `my-group`, use your group name. +- For `GROUP_ID`, use your group ID, which you can view on your group's home page. - For `PROJECT_ID`, use your project ID, which you can view on your project's home page. - Replace `gitlab.example.com` with your domain name. - For retrieving artifacts, use either the @@ -472,7 +474,7 @@ repositories { ### Instance-level Maven endpoint > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. 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 @@ -533,7 +535,7 @@ repositories { After you have set up the [remote and authentication](#authenticate-to-the-package-registry-with-maven) and [configured your project](#use-the-gitlab-endpoint-for-maven-packages), -publish a Maven artifact from your project. +publish a Maven package to your project. ### Publish by using Maven @@ -604,11 +606,20 @@ To publish a package by using Gradle: Now navigate to your project's **Packages & Registries** page and view the published artifacts. +### Publishing a package with the same name or version + +When you publish a package with the same name or version as an existing package, +the existing package is overwritten. + ## Install a package To install a package from the GitLab Package Registry, you must configure the [remote and authenticate](#authenticate-to-the-package-registry-with-maven). -When this is completed, there are two ways to install a package. +When this is completed, you can install a package from a project, +group, or namespace. + +If multiple packages have the same name and version, when you install +a package, the most recently-published package is retrieved. ### Use Maven with `mvn install` diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index c16fea1d00a..18d0c26f973 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # NPM packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. Publish NPM packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. @@ -159,7 +159,7 @@ If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view ### Authenticate with a CI job token > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. If you're using NPM with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. The token inherits the permissions of the user that generates the pipeline. @@ -244,7 +244,9 @@ Prerequisites: - [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. - Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages). -- Your NPM package name must be in the format of [@scope/package-name](#package-naming-convention). It must match exactly, including the case. +- Your NPM package name must be in the format of [@scope/package-name](#package-naming-convention). + It must match exactly, including the case. This is different than the + NPM naming convention, but it is required to work with the GitLab Package Registry. To upload an NPM package to your project, run this command: @@ -263,6 +265,9 @@ Prerequisites: - [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. - Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages). +- Your NPM package name must be in the format of [@scope/package-name](#package-naming-convention). + It must match exactly, including the case. This is different than the + NPM naming convention, but it is required to work with the GitLab Package Registry. To work with NPM 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. @@ -297,7 +302,8 @@ the same version more than once, even if it has been deleted. ## Install a package NPM packages are commonly-installed by using the `npm` or `yarn` commands -in a JavaScript project. +in a JavaScript project. You can install a package from the scope of a project, group, +or instance. 1. Set the URL for scoped packages by running: @@ -309,16 +315,16 @@ in a JavaScript project. 1. Ensure [authentication](#authenticate-to-the-package-registry) is configured. -1. In your project, to install a package, run: +1. To install a package in your project, run: ```shell - npm install @my-project-scope/my-package + npm install @my-scope/my-package ``` Or if you're using Yarn: ```shell - yarn add @my-project-scope/my-package + yarn add @my-scope/my-package ``` In [GitLab 12.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/55344), @@ -346,7 +352,7 @@ and use your organization's URL. The name is case-sensitive and must match the n ### NPM dependencies metadata > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab Premium 12.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. In GitLab 12.6 and later, packages published to the Package Registry expose the following attributes to the NPM client: @@ -363,7 +369,7 @@ In GitLab 12.6 and later, packages published to the Package Registry expose the ## Add NPM distribution tags > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) in GitLab Premium 12.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag/) to newly-published packages. Tags are optional and can be assigned to only one package at a time. @@ -456,7 +462,7 @@ If you get this error, ensure that: - Your token is not expired and has appropriate permissions. - [Your token does not begin with `-`](https://gitlab.com/gitlab-org/gitlab/-/issues/235473). -- A package with the same name doesn't already exist within the given scope. +- A package with the same name or version doesn't already exist within the given scope. - The scoped packages URL includes a trailing slash: - Correct: `//gitlab.example.com/api/v4/packages/npm/` - Incorrect: `//gitlab.example.com/api/v4/packages/npm` diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 35172663cc1..5805fb29931 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # NuGet packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. Publish NuGet packages in your project’s Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -62,11 +62,13 @@ NuGet CLI. ## Use the GitLab endpoint for NuGet Packages +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36423) group-level endpoint in GitLab 13.8. + To use the GitLab endpoint for NuGet Packages, choose an option: - **Project-level**: Use when you have few NuGet packages and they are not in the same GitLab group. -- **Group-level**: Use when you have many NuGet packages in different within the +- **Group-level**: Use when you have many NuGet packages in different projects within the same GitLab group. Some features such as [publishing](#publish-a-nuget-package) a package are only available on the project-level endpoint. @@ -104,6 +106,9 @@ You can now add a new source to NuGet with: #### Project-level endpoint +A project-level endpoint is required to publish NuGet packages to the Package Registry. +A project-level endpoint is also required to install NuGet packages from a project. + To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with `nuget`: ```shell @@ -120,6 +125,8 @@ nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/proje #### Group-level endpoint +To install a NuGet package from a group, use a group-level endpoint. + To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with `nuget`: ```shell @@ -138,6 +145,9 @@ nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/group #### Project-level endpoint +A project-level endpoint is required to publish NuGet packages to the Package Registry. +A project-level endpoint is also required to install NuGet packages from a project. + To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with Visual Studio: 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). @@ -165,6 +175,8 @@ If you get a warning, ensure that the **Location**, **Username**, and #### Group-level endpoint +To install a package from a group, use a group-level endpoint. + To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with Visual Studio: 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). @@ -194,6 +206,9 @@ If you get a warning, ensure that the **Location**, **Username**, and #### Project-level endpoint +A project-level endpoint is required to publish NuGet packages to the Package Registry. +A project-level endpoint is also required to install NuGet packages from a project. + To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for .NET: 1. In the root of your project, create a file named `nuget.config`. @@ -217,6 +232,8 @@ To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package #### Group-level endpoint +To install a package from a group, use a group-level endpoint. + To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for .NET: 1. In the root of your project, create a file named `nuget.config`. @@ -324,8 +341,19 @@ updated: 1. Commit the changes and push it to your GitLab repository to trigger a new CI/CD build. +### Publishing a package with the same name or version + +When you publish a package with the same name or version as an existing package, +the existing package is overwritten. + ## Install packages +To install a NuGet package from the Package Registry, you must first +[add a project-level or group-level endpoint](#add-the-package-registry-as-a-source-for-nuget-packages). + +If multiple packages have the same name and version, when you install +a package, the most recently-published package is retrieved. + ### Install a package with the NuGet CLI WARNING: diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 5876ef19ad9..1ad0ad9bb1f 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Package Registry -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. With the GitLab Package Registry, you can use GitLab as a private or public registry for a variety of common package managers. You can publish and share @@ -21,6 +21,12 @@ You can view packages for your project or group. You can search, sort, and filter packages on this page. +When you view packages in a group: + +- All projects published to the group and its projects are displayed. +- Only the projects you can access are displayed. +- If a project is private, or you are not a member of the project, it is not displayed. + For information on how to create and upload a package, view the GitLab documentation for your package type. ## Use GitLab CI/CD to build packages @@ -29,7 +35,7 @@ You can use [GitLab CI/CD](../../../ci/README.md) to build packages. 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). +CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). Learn more about using CI/CD to build: diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 376c0439f32..3357d776f27 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # PyPI packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. Publish PyPI packages in your project’s Package Registry. Then install the packages whenever you need to use them as a dependency. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 3dbae78ccc4..cc1106fe84f 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -142,13 +142,13 @@ The following table depicts the various user permission levels in a project. | Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | | Run CI/CD pipeline against a protected branch | | | ✓ (*5*) | ✓ | ✓ | | Delete [packages](packages/index.md) | | | | ✓ | ✓ | -| Request a CVE ID **(FREE ONLY)** | | | | ✓ | ✓ | +| Request a CVE ID **(FREE SAAS)** | | | | ✓ | ✓ | | Use environment terminals | | | | ✓ | ✓ | -| Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | +| Run Web IDE's Interactive Web Terminals **(ULTIMATE SELF)** | | | | ✓ | ✓ | | Add new team members | | | | ✓ | ✓ | | Enable/disable branch protection | | | | ✓ | ✓ | | Push to protected branches | | | | ✓ | ✓ | -| Turn on/off protected branch push for devs | | | | ✓ | ✓ | +| Turn on/off protected branch push for developers | | | | ✓ | ✓ | | Enable/disable tag protections | | | | ✓ | ✓ | | Edit project settings | | | | ✓ | ✓ | | Edit project badges | | | | ✓ | ✓ | @@ -172,7 +172,7 @@ The following table depicts the various user permission levels in a project. | Delete wiki pages | | | | ✓ | ✓ | | View project Audit Events | | | ✓ (*12*) | ✓ | ✓ | | Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | -| Manage [project access tokens](project/settings/project_access_tokens.md) **(CORE ONLY)** | | | | ✓ | ✓ | +| Manage [project access tokens](project/settings/project_access_tokens.md) **(FREE SELF)** | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | | Transfer project to another namespace | | | | | ✓ | | Rename project | | | | | ✓ | @@ -282,7 +282,7 @@ group. | Manage group members | | | | | ✓ | | Delete group | | | | | ✓ | | Delete group epic **(PREMIUM)** | | | | | ✓ | -| Edit SAML SSO Billing **(SILVER ONLY)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | +| Edit SAML SSO Billing **(PREMIUM SAAS)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | | View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | | Disable notification emails | | | | | ✓ | | View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -290,8 +290,8 @@ group. | View Issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Productivity analytics **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | | View Value Stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Billing **(FREE ONLY)** | | | | | ✓ (4) | -| View Usage Quotas **(FREE ONLY)** | | | | | ✓ (4) | +| View Billing **(FREE SAAS)** | | | | | ✓ (4) | +| View Usage Quotas **(FREE SAAS)** | | | | | ✓ (4) | | Filter members by 2FA status | | | | | ✓ | 1. Groups can be set to [allow either Owners or Owners and @@ -314,7 +314,7 @@ nested groups if you have membership in one of its parents. To learn more, read through the documentation on [subgroups memberships](group/subgroups/index.md#membership). -## External users **(CORE ONLY)** +## External users **(FREE SELF)** In cases where it is desired that a user has access only to some internal or private projects, there is the option of creating **External Users**. This @@ -352,6 +352,9 @@ An administrator can flag a user as external by either of the following methods: or edit an existing one. There, you can find the option to flag the user as external. +Additionally users can be set as external users using [SAML groups](../integration/saml.md#external-groups) +and [LDAP groups](../administration/auth/ldap/index.md#external-groups). + ### Setting new users to external By default, new users are not set as external users. This behavior can be changed @@ -396,7 +399,7 @@ 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. -## Auditor users **(PREMIUM ONLY)** +## Auditor users **(PREMIUM SELF)** >[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/998) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.17. @@ -421,7 +424,8 @@ details such as projects or subgroups. They do not have access to the group's pa ### Minimal access users take license seats Users with even a "minimal access" role are counted against your number of license seats. This -requirement does not apply for [GitLab Gold/Ultimate](https://about.gitlab.com/pricing/) subscriptions. +requirement does not apply for [GitLab Ultimate](https://about.gitlab.com/pricing/) +subscriptions. ## Project features diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index cdf80f722f7..6f5ddf1d9bd 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Creating users **(CORE ONLY)** +# Creating users **(FREE SELF)** You can create users: diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 6cdd2d6f161..5f468f81e0c 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -240,7 +240,7 @@ following desktop browsers: NOTE: For Firefox 47-66, you can enable the FIDO U2F API in -[about:config](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). +[`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). Search for `security.webauth.u2f` and double click on it to toggle to `true`. To set up 2FA with a U2F device: @@ -262,7 +262,7 @@ Click on **Register U2F Device** to complete the process. > - It's [deployed behind a feature flag](../../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-webauthn). **(CORE ONLY)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-webauthn). **(FREE SELF)** The WebAuthn workflow is [supported by](https://caniuse.com/#search=webauthn) the following desktop browsers: @@ -384,7 +384,7 @@ codes. If you saved these codes, you can use one of them to sign in. To use a recovery code, enter your username/email and password on the GitLab sign-in page. When prompted for a two-factor code, enter the recovery code. -Once you use a recovery code, you cannot re-use it. You can still use the other +After you use a recovery code, you cannot re-use it. You can still use the other recovery codes you saved. ### Generate new recovery codes using SSH @@ -479,7 +479,7 @@ Sign in and re-enable two-factor authentication as soon as possible. - To enforce 2FA at the system or group levels see [Enforce Two-factor Authentication](../../../security/two_factor_authentication.md). -## Enable or disable WebAuthn **(CORE ONLY)** +## Enable or disable WebAuthn **(FREE SELF)** Support for WebAuthn is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default**. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index ae672d8414f..5d5168b477a 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -173,7 +173,7 @@ In most of the below cases, the notification is sent to: - Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below NOTE: -To minimize the number of notifications that do not require any action, from [GitLab 12.9 onwards](https://gitlab.com/gitlab-org/gitlab/-/issues/616), eligible approvers are no longer notified for all the activities in their projects. To receive them they have to change their user notification settings to **Watch** instead. +To minimize the number of notifications that do not require any action, in [GitLab versions 12.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/616), eligible approvers are no longer notified for all the activities in their projects. To receive them they have to change their user notification settings to **Watch** instead. | Event | Sent to | |------------------------|---------| diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index af7bfb80cac..fc42ad47d5a 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -76,12 +76,16 @@ syntax highlighted code on GitLab. The default syntax theme is White, and you can choose among 5 different themes: +<!-- vale gitlab.Spelling = NO --> + - White - Dark - Solarized light - Solarized dark - Monokai +<!-- vale gitlab.Spelling = YES --> +  [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in 13.0, the theme diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index 1aa040c9cb8..e3b52e99a89 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -57,4 +57,4 @@ If you continue to type, `@le`, the popup list changes to the following. The popup now only includes users where `le` appears in their username, or a word in their name. - + diff --git a/doc/user/project/builds/artifacts.md b/doc/user/project/builds/artifacts.md deleted file mode 100644 index e7572b4ff1f..00000000000 --- a/doc/user/project/builds/artifacts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../pipelines/job_artifacts.md' ---- - -This document was moved to [pipelines/job_artifacts](../pipelines/job_artifacts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index a29c0754d31..19f17ad91d7 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -21,6 +21,10 @@ Only the items visible on the current page are selected for bulk editing (up to ## Bulk edit issues at the project level +> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. +> - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. +> - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. + NOTE: You need a permission level of [Reporter or higher](../permissions.md) to manage issues. @@ -28,13 +32,12 @@ When bulk editing issues in a project, you can edit the following attributes: - Status (open/closed) - Assignee -- Epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in - [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.) **(PREMIUM)** -- Milestone -- Labels -- Health status ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in - [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2.) **(ULTIMATE)** -- Subscriptions +- [Epic](../group/epics/index.md) +- [Milestone](milestones/index.md) +- [Labels](labels.md) +- [Health status](issues/index.md#health-status) +- Notification subscription +- [Iteration](../group/iterations/index.md) To update multiple project issues at the same time: diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 85ac641f6e4..f7394093a3a 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -4,10 +4,10 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Canary Deployments **(CORE)** +# Canary Deployments **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Core in 13.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Free in 13.8. A popular [Continuous Deployment](https://en.wikipedia.org/wiki/Continuous_deployment) strategy, where a small portion of the fleet is updated to the new version of @@ -72,7 +72,7 @@ can easily notice them. ### Advanced traffic control with Canary Ingress > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Core in GitLab 13.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Free in GitLab 13.8. Canary deployments can be more strategic with [Canary Ingress](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#canary), which is an advanced traffic routing service that controls incoming HTTP diff --git a/doc/user/project/ci_cd_for_external_repo.md b/doc/user/project/ci_cd_for_external_repo.md deleted file mode 100644 index 57747be3859..00000000000 --- a/doc/user/project/ci_cd_for_external_repo.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../ci/ci_cd_for_external_repos/index.md' ---- - -This document was moved to [another location](../../ci/ci_cd_for_external_repos/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 9047e564598..94aedb1cdab 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Adding EKS clusters +# Adding EKS clusters **(CORE)** GitLab supports adding new and existing EKS clusters. @@ -20,7 +20,7 @@ requirements are met: - `kubectl` [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) for access to the EKS cluster. -### Additional requirements for self-managed instances **(CORE ONLY)** +### Additional requirements for self-managed instances **(FREE SELF)** If you are using a self-managed GitLab instance, GitLab must first be configured with a set of Amazon credentials. These credentials are used to assume an Amazon IAM role provided by the user diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index e3e6efc887f..421a59db92c 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Adding GKE clusters +# Adding GKE clusters **(CORE)** GitLab supports adding new and existing GKE clusters. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index beb8b71b917..7f4d25b7eca 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Adding and removing Kubernetes clusters +# Adding and removing Kubernetes clusters **(CORE)** GitLab offers integrated cluster creation for the following Kubernetes providers: @@ -40,7 +40,7 @@ Before [adding a Kubernetes cluster](#create-new-cluster) using GitLab, you need - [Maintainer access to a group](../../permissions.md#group-members-permissions) for a group-level cluster. - [Admin Area access](../../admin_area/index.md) for a self-managed instance-level - cluster. **(CORE ONLY)** + cluster. **(FREE SELF)** ## Access controls diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md deleted file mode 100644 index e38fbb871c1..00000000000 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../add_eks_clusters.md#existing-eks-cluster' ---- - -This document was moved to [another location](../add_eks_clusters.md#existing-eks-cluster). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index a06846e33a6..ab83da3a975 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Kubernetes clusters +# Kubernetes clusters **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1 for projects. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in @@ -33,8 +33,10 @@ integrated at the [group level](../../group/clusters/index.md) or To view your project level Kubernetes clusters, navigate to **Operations > Kubernetes** from your project. On this page, you can [add a new cluster](#adding-and-removing-clusters) -and view information about your existing clusters, such as nodes count and rough estimates -of memory and CPU usage. +and view information about your existing clusters, such as: + +- Nodes count. +- Rough estimates of memory and CPU usage. ## Setting up @@ -72,13 +74,12 @@ to: ### Multiple Kubernetes clusters > - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3 -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Core in 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Free in 13.2. You can associate more than one Kubernetes cluster to your project. That way you can have different clusters for different environments, -like dev, staging, production, and so on. - -Simply add another cluster, like you did the first time, and make sure to +like development, staging, production, and so on. +Add another cluster, like you did the first time, and make sure to [set an environment scope](#setting-the-environment-scope) that differentiates the new cluster from the rest. @@ -165,7 +166,7 @@ details about the created resources. If you choose to manage your own cluster, project-specific resources aren't created automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you must explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) -for your deployment jobs to use; otherwise a namespace is created for you. +for your deployment jobs to use. Otherwise, a namespace is created for you. #### Important notes @@ -182,10 +183,10 @@ Note the following with GitLab and clusters: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31759) in GitLab 12.6. -If you choose to allow GitLab to manage your cluster for you, GitLab stores a cached +If you allow GitLab to manage your cluster, GitLab stores a cached version of the namespaces and service accounts it creates for your projects. If you modify these resources in your cluster manually, this cache can fall out of sync with -your cluster, which can cause deployment jobs to fail. +your cluster. This can cause deployment jobs to fail. To clear the cache: @@ -204,12 +205,61 @@ Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an env If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain is used for the different stages. For example, Auto Review Apps and Auto Deploy. -The domain should have a wildcard DNS configured to the Ingress IP address. After Ingress has been installed (see [Installing Applications](#installing-applications)), +The domain should have a wildcard DNS configured to the Ingress IP address. +After Ingress has been installed (see [Installing Applications](#installing-applications)), you can either: - Create an `A` record that points to the Ingress IP address with your domain provider. - Enter a wildcard DNS address using a service such as nip.io or xip.io. For example, `192.168.1.1.xip.io`. +To determine the external Ingress IP address, or external Ingress hostname: + +- *If the cluster is on GKE*: + 1. Click the **Google Kubernetes Engine** link in the **Advanced settings**, + or go directly to the [Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/). + 1. Select the proper project and cluster. + 1. Click **Connect** + 1. Execute the `gcloud` command in a local terminal or using the **Cloud Shell**. + +- *If the cluster is not on GKE*: Follow the specific instructions for your + Kubernetes provider to configure `kubectl` with the right credentials. + The output of the following examples show the external endpoint of your + cluster. This information can then be used to set up DNS entries and forwarding + rules that allow external access to your deployed applications. + +Depending an your Ingress, the external IP address can be retrieved in various ways. +This list provides a generic solution, and some GitLab-specific approaches: + +- In general, you can list the IP addresses of all load balancers by running: + + ```shell + kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' + ``` + +- If you installed Ingress using the **Applications**, run: + + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' + ``` + +- Some Kubernetes clusters return a hostname instead, like + [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: + + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' + ``` + + If you use EKS, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) + is also created, which incurs additional AWS costs. + +- Istio/Knative uses a different command. Run: + + ```shell + kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' + ``` + +If you see a trailing `%` on some Kubernetes versions, do not include it. + ## Installing applications GitLab can install and manage some applications like Helm, GitLab Runner, Ingress, @@ -224,10 +274,10 @@ Auto DevOps automatically detects, builds, tests, deploys, and monitors your applications. To make full use of Auto DevOps (Auto Deploy, Auto Review Apps, and -Auto Monitoring) the Kubernetes project integration must be enabled, but +Auto Monitoring) the Kubernetes project integration must be enabled. However, Kubernetes clusters can be used without Auto DevOps. -[Read more about Auto DevOps](../../../topics/autodevops/index.md) +[Read more about Auto DevOps](../../../topics/autodevops/index.md). ## Deploying to a Kubernetes cluster @@ -260,9 +310,9 @@ following command in your deployment job script, for Kubernetes to access the re kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run | kubectl apply -f - ``` -The Kubernetes cluster integration exposes the following +The Kubernetes cluster integration exposes these [deployment variables](../../../ci/variables/README.md#deployment-environment-variables) in the -GitLab CI/CD build environment to deployment jobs, which are jobs that have +GitLab CI/CD build environment to deployment jobs. Deployment jobs have [defined a target environment](../../../ci/environments/index.md#defining-environments). | Variable | Description | @@ -303,7 +353,7 @@ When you customize the namespace, existing environments remain linked to their c namespaces until you [clear the cluster cache](#clearing-the-cluster-cache). WARNING: -By default, anyone who can create a deployment job can access any CI variable within +By default, anyone who can create a deployment job can access any CI variable in an environment's deployment job. This includes `KUBECONFIG`, which gives access to any secret available to the associated service account in your cluster. To keep your production credentials safe, consider using @@ -327,8 +377,8 @@ the need to leave GitLab. #### Deploy Boards GitLab Deploy Boards offer a consolidated view of the current health and -status of each CI [environment](../../../ci/environments/index.md) running on Kubernetes, -displaying the status of the pods in the deployment. Developers and other +status of each CI [environment](../../../ci/environments/index.md) running on Kubernetes. +They display the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use without any need to access Kubernetes. @@ -336,7 +386,7 @@ workflow they already use without any need to access Kubernetes. #### Viewing pod logs -GitLab makes it easy to view the logs of running pods in connected Kubernetes +GitLab enables you to view the logs of running pods in connected Kubernetes clusters. By displaying the logs directly in GitLab, developers can avoid having to manage console tools or jump to a different interface. @@ -349,7 +399,7 @@ to manage console tools or jump to a different interface. When enabled, the Kubernetes integration adds [web terminal](../../../ci/environments/index.md#web-terminals) support to your [environments](../../../ci/environments/index.md). This is based on the `exec` functionality found in Docker and Kubernetes, so you get a new -shell session within your existing containers. To use this integration, you +shell session in your existing containers. To use this integration, you should deploy to Kubernetes using the deployment variables above, ensuring any deployments, replica sets, and pods are annotated with: @@ -402,7 +452,7 @@ Automatically detect and monitor Kubernetes metrics. Automatic monitoring of ### Visualizing cluster health > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Core in 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Free in 13.2. When [Prometheus is deployed](#installing-applications), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 2523dc3e0a2..349040e0bf6 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -4,10 +4,10 @@ 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/#assignments --- -# Kubernetes Logs +# Kubernetes Logs **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) to [GitLab Core](https://about.gitlab.com/pricing/) 12.9. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) to [GitLab Free](https://about.gitlab.com/pricing/) 12.9. GitLab makes it easy to view the logs of running pods or managed applications in [connected Kubernetes clusters](index.md). By displaying the logs directly in GitLab diff --git a/doc/user/project/clusters/protect/container_network_security/index.md b/doc/user/project/clusters/protect/container_network_security/index.md index 8299844e511..a7cdd73acd7 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -28,10 +28,9 @@ chart. - GitLab managed installation of Cilium. - Support for L3, L4, and L7 policies. - Ability to export logs to a SIEM. -- Statistics page showing volume of packets processed and dropped over time (Gold/Ultimate users - only). +- Statistics page showing volume of packets processed and dropped over time (Ultimate users only). - Management of NetworkPolicies through code in a project (Available for auto DevOps users only). -- Management of CiliumNetworkPolicies through a UI policy manager (Gold/Ultimate users only). +- Management of CiliumNetworkPolicies through a UI policy manager (Ultimate users only). ## Supported container orchestrators diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index 10f9380a1f2..e530f0dfcda 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -46,11 +46,11 @@ Network Policies can be managed through GitLab in one of two ways: - Management through a YAML file in each application's project (for projects using Auto DevOps). For more information, see the [Network Policy documentation](../../../../../topics/autodevops/stages.md#network-policy). - Management through the GitLab Policy management UI (for projects not using Auto DevOps). For more - information, see the [Container Network Policy documentation](../../../../application_security/threat_monitoring/index.md#container-network-policy-management) (Ultimate/Gold only). + information, see the [Container Network Policy documentation](../../../../application_security/threat_monitoring/index.md#container-network-policy-management) (Ultimate only). Each method has benefits and drawbacks: -| | YAML method | UI method (Ultimate/Gold only) | +| | YAML method | UI method (Ultimate only) | |--|:------------|:-------------------------------| | **Benefits** | A change control process is possible by requiring [MR Approvals](../../../merge_requests/merge_request_approvals.md). All changes are fully tracked and audited in the same way that Git tracks the history of any file in its repository. | The UI provides a simple rules editor for users who are less familiar with the YAML syntax of NetworkPolicies. This view is a live representation of the policies currently deployed in the Kubernetes cluster. The UI also allows for multiple network policies to be created per environment. | | **Drawbacks** | Only one network policy can be deployed per environment (although that policy can be as detailed as needed). Also, if changes were made in Kubernetes directly rather than through the `auto-deploy-values.yaml` file, the YAML file's contents don't represent the actual state of policies deployed in Kubernetes. | Policy changes aren't audited and a change control process isn't available. | diff --git a/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md b/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md index e9a05b58fec..e7d8d591510 100644 --- a/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md +++ b/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md @@ -43,7 +43,7 @@ Google Kubernetes Engine integration. All you have to do is [follow this link](h ## Creating a new project from a template We use a GitLab project templates to get started. As the name suggests, -those projects provide a barebones application built on some well-known frameworks. +those projects provide a bare-bones application built on some well-known frameworks. 1. In GitLab, click the plus icon (**+**) at the top of the navigation bar and select **New project**. @@ -55,7 +55,7 @@ those projects provide a barebones application built on some well-known framewor 1. Give your project a name, optionally a description, and make it public so that you can take advantage of the features available in the - [GitLab Gold plan](https://about.gitlab.com/pricing/#gitlab-com). + [GitLab Ultimate plan](https://about.gitlab.com/pricing/).  diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 8572ab850e4..18c8ba9626f 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Runbooks +# Runbooks **(CORE)** Runbooks are a collection of documented procedures that explain how to carry out a particular process, be it starting, stopping, debugging, diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index a52d3400aa2..2d0ed3cd207 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Deploying AWS Lambda function using GitLab CI/CD +# Deploying AWS Lambda function using GitLab CI/CD **(CORE)** GitLab allows users to easily deploy AWS Lambda functions and create rich serverless applications. @@ -74,7 +74,7 @@ Place this code in the file `src/handler.js`. In our case, `module.exports.hello` defines the `hello` handler to reference later in the `serverless.yml`. -You can learn more about the AWS Lambda Node.js function handler and all its various options here: <https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html> +You can learn more about the [AWS Lambda Node.js function handler](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html) and all its various options in its documentation. #### Creating a `serverless.yml` file diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 043c5e4ca79..336813b5ba5 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Serverless +# Serverless **(CORE)** > Introduced in GitLab 11.5. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 63ea84e42c9..1e1938854df 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -5,11 +5,11 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Code Owners **(STARTER)** +# Code Owners **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) -in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. -> - 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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in GitLab 11.3. +> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9. +> - Moved to GitLab Premium in 13.9. ## Introduction @@ -18,7 +18,7 @@ to find out who should review or approve merge requests. Additionally, if you have a question over a specific file or code block, it may be difficult to know who to find the answer from. -GitLab Code Owners is a feature to define who owns specific +The GitLab Code Owners feature defines who owns specific files or paths in a repository, allowing other users to understand who is responsible for each file or path. @@ -32,7 +32,7 @@ the process of finding the right reviewers and approvers for a given merge request. In larger organizations or popular open source projects, Code Owners -can also be useful to understand who to contact if you have +can help you understand who to contact if you have a question that may not be related to code review or a merge request approval. @@ -49,12 +49,12 @@ You can choose to add the `CODEOWNERS` file in three places: - Inside the `docs/` directory The `CODEOWNERS` file is valid for the branch where it lives. For example, if you change the code owners -in a feature branch, they won't be valid in the main branch until the feature branch is merged. +in a feature branch, the changes aren't valid in the main branch until the feature branch is merged. If you introduce new files to your repository and you want to identify the code owners for that file, -you have to update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same -branch), GitLab will count the owners as soon as the branch is merged. If -you don't, you can do that later, but your new files will not belong to anyone until you update your +you must update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same +branch), GitLab counts the owners as soon as the branch is merged. If +you don't, you can do that later, but your new files don't belong to anyone until you update your `CODEOWNERS` file in the TARGET branch. When a file matches multiple entries in the `CODEOWNERS` file, @@ -73,29 +73,32 @@ The user that would show for `README.md` would be `@user2`. ## Approvals by Code Owners -Once you've added Code Owners to a project, you can configure it to +After 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)** -Developer or higher [permissions](../permissions.md) are required in order to +Developer or higher [permissions](../permissions.md) are required to approve a merge request. -Once set, Code Owners are displayed in merge requests widgets: +After it's set, Code Owners are displayed in merge request widgets:  -While the `CODEOWNERS` file can be used in addition to Merge Request [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules), -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). -Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) -to specify the actual owners and granular permissions. +While you can use the `CODEOWNERS` file in addition to Merge Request +[Approval Rules](merge_requests/merge_request_approvals.md#approval-rules), +you can also use it as the sole driver of merge request approvals +without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules): + +1. Create the file in one of the three locations specified above. +1. Set the code owners as required approvers for + [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). +1. 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) -will prevent any user who is not specified in the `CODEOWNERS` file from pushing +prevents any user who is not specified in the `CODEOWNERS` file from pushing changes for the specified files/paths, except those included in the **Allowed to push** column. This allows for a more inclusive push strategy, as administrators don't have to restrict developers from pushing directly to the @@ -114,13 +117,13 @@ in the `.gitignore` file followed by one or more of: - The `@name` of one or more groups that should be owners of the file. - Lines starting with `#` are 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. +The path definition order is significant: the last pattern +matching a given path is used to find the code owners. ### Groups as Code Owners -> - [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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1. +> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. Groups and subgroups members are inherited as eligible Code Owners to a project, as long as the hierarchy is respected. @@ -131,7 +134,7 @@ suppose you have a project called "Project A" within the group and a "Project B" within the subgroup. 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 +the Subgroup Y. 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:  @@ -142,9 +145,9 @@ Code Owners:  -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: +After being invited, any member (`@user`) of the group or subgroup can be set +as Code Owner to files of the Project A or B, and the entire Group X +(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as follows: ```plaintext # A member of the group or subgroup as Code Owner to a file @@ -162,7 +165,7 @@ 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 behind a feature flag, enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab Premium 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 @@ -185,8 +188,8 @@ changes, to set their own independent patterns by specifying discrete sections i teams can be added as reviewers. Sections can be added to `CODEOWNERS` files as a new line with the name of the -section inside square brackets. Every entry following it is assigned to that -section. The following example would create 2 Code Owner rules for the "README +section inside square brackets. Every entry following is assigned to that +section. The following example would create two Code Owner rules for the "README Owners" section: ```plaintext @@ -196,7 +199,7 @@ internal/README.md @user2 ``` Multiple sections can be used, even with matching file or directory patterns. -Reusing the same section name will group the results together under the same +Reusing the same section name groups the results together under the same section, with the most specific rule or last matching pattern being used. For example, consider the following entries in a `CODEOWNERS` file: @@ -213,7 +216,7 @@ model/db @gl-database README.md @gl-docs ``` -This will result in 3 entries under the "Documentation" section header, and 2 +This results in three entries under the "Documentation" section header, and two entries under "Database". Case is not considered when combining sections, so in this example, entries defined under the sections "Documentation" and "DOCUMENTATION" would be combined into one, using the case of the first instance @@ -227,9 +230,11 @@ the rules for "Groups" and "Documentation" sections: #### Optional Code Owners Sections **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.8 behind a feature flag, enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8 behind a feature flag, enabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53227) in GitLab 13.9. -When you want to make a certain section optional, you can do so by adding a code owners section prepended with the caret `^` character. Approvals from owners listed in the section will **not** be required. For example: +To make a certain section optional, add a code owners section prepended with the +caret `^` character. Approvals from owners listed in the section are **not** required. For example: ```plaintext [Documentation] @@ -242,13 +247,13 @@ When you want to make a certain section optional, you can do so by adding a code *.go @root ``` -The optional code owners section will be displayed in merge requests under the **Approval Rules** area: +The optional code owners section displays in merge requests under the **Approval Rules** area:  -If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails. +If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails. -For example, the code owners of the "Documentation" section below will still be required to approve merge requests: +For example, the code owners of the "Documentation" section below is still required to approve merge requests: ```plaintext [Documentation] @@ -264,12 +269,12 @@ For example, the code owners of the "Documentation" section below will still be *.txt @root ``` -Optional sections in the code owners file are currently treated as optional only -when changes are submitted via merge requests. If a change is submitted directly -to the protected branch, approval from code owners will still be required, even if the -section is marked as optional. We plan to change this in a +Optional sections in the code owners file are treated as optional only +when changes are submitted by using merge requests. If a change is submitted directly +to the protected branch, approval from code owners is still required, even if the +section is marked as optional. We plan to change this behavior in a [future release](https://gitlab.com/gitlab-org/gitlab/-/issues/297638), -where direct pushes to the protected branch will be allowed for sections marked as optional. +and allow direct pushes to the protected branch for sections marked as optional. ## Example `CODEOWNERS` file diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md deleted file mode 100644 index 17e86b6d7e8..00000000000 --- a/doc/user/project/container_registry.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../packages/container_registry/index.md' ---- - -This document was moved to [another location](../packages/container_registry/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md deleted file mode 100644 index 5c235f6708b..00000000000 --- a/doc/user/project/cycle_analytics.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../analytics/value_stream_analytics.md' ---- - -This document was moved to [another location](../analytics/value_stream_analytics.md) - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 831a8803622..72695580d9d 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -5,10 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy Boards **(CORE)** +# Deploy Boards **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. -> - [Moved](<https://gitlab.com/gitlab-org/gitlab/-/issues/212320>) to GitLab Core in 13.8. +> - [Moved](<https://gitlab.com/gitlab-org/gitlab/-/issues/212320>) to GitLab Free in 13.8. GitLab Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status @@ -93,7 +93,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ `$CI_PROJECT_PATH_SLUG` are the values of the CI variables. This is so we can lookup the proper environment in a cluster/namespace which may have more than one. These resources should be contained in the namespace defined in - the Kubernetes service setting. You can use an [Autodeploy](../../topics/autodevops/stages.md#auto-deploy) `.gitlab-ci.yml` + the Kubernetes service setting. You can use an [Auto deploy](../../topics/autodevops/stages.md#auto-deploy) `.gitlab-ci.yml` template which has predefined stages and commands to use, and automatically applies the annotations. Each project must have a unique namespace in Kubernetes as well. The image below demonstrates how this is shown inside @@ -158,7 +158,7 @@ version of your application. ## Further reading -- [GitLab Autodeploy](../../topics/autodevops/stages.md#auto-deploy) +- [GitLab Auto deploy](../../topics/autodevops/stages.md#auto-deploy) - [GitLab CI/CD environment variables](../../ci/variables/README.md) - [Environments and deployments](../../ci/environments/index.md) - [Kubernetes deploy example](https://gitlab.com/gitlab-examples/kubernetes-deploy) diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 93ed1030e1f..1bd68fc5c1e 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -7,10 +7,10 @@ type: howto, reference # Deploy Keys -Deploy keys allow read-only or read-write (if enabled) access to one or -more repositories, by importing an SSH public key to your GitLab instance. +Deploy keys allow read-only or read-write access to your +repositories by importing an SSH public key into your GitLab instance. -This is useful for cloning repositories to your Continuous +This is useful, for example, for cloning repositories to your Continuous Integration (CI) server. By using deploy keys, you don't have to set up a fake user account. @@ -82,7 +82,7 @@ can add or enable a deploy key for a project repository: 1. Navigate to the project's **Settings > Repository** page. 1. Expand the **Deploy Keys** section. 1. Specify a title for the new deploy key and paste your public SSH key. -1. (Optional) Check **Write access allowed** to allow `read-write` access. Leave it unchecked for `read-only` access. +1. (Optional) Check **Grant write permissions to this key** to allow `read-write` access. Leave it unchecked for `read-only` access. There are three lists of Project Deploy Keys: diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 5a62730d989..6f05c40eefc 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -67,7 +67,7 @@ following table along with GitLab version it was introduced in: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29639) in GitLab 12.1. -The default username format is `gitlab+deploy-token-#{n}`. Some tools or +The default username format is `gitlab+deploy-token-{n}`. Some tools or platforms may not support this format; in this case you can specify a custom username to be used when creating the deploy token. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 3108bdda7a0..a7ce48b6487 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -6,16 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Description templates ->[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4981) in GitLab 8.11. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4981) in GitLab 8.11. We all know that a properly submitted issue is more likely to be addressed in a timely manner by the developers of a project. -Description templates allow you to define context-specific templates for issue -and merge request description fields for your project, as well as help filter -out a lot of unnecessary noise from issues. - -## Overview +With description templates, you can define context-specific templates for issue and merge request +description fields for your project, and filter out unnecessary noise from issues. By using the description templates, users that create a new issue or merge request can select a description template to help them communicate with other @@ -28,7 +25,10 @@ Description templates must be written in [Markdown](../markdown.md) and stored in your project's repository under a directory named `.gitlab`. Only the templates of the default branch are taken into account. -## Use-cases +To learn how to create templates for various file types in groups, visit +[Group file templates](../group/index.md#group-file-templates). + +## Use cases - Add a template to be used in every issue for a specific project, giving instructions and guidelines, requiring for information specific to that subject. @@ -39,6 +39,8 @@ templates of the default branch are taken into account. images guidelines, link to the related issue, reviewer name, and so on. - You can also create issues and merge request templates for different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. +- You can use an [issue description template](#creating-issue-templates) as a + [Service Desk email template](service_desk.md#new-service-desk-issues). ## Creating issue templates @@ -47,20 +49,20 @@ directory in your repository. Commit and push to your default branch. To create a Markdown file: - 1. Click the `+` button next to `master` and click **New file**. - 1. Add the name of your issue template to the **File name** text field next to `master`. - Make sure that your file has the `.md` extension, for - example `feature_request.md` or `Feature Request.md`. - 1. Commit and push to your default branch. +1. Click the `+` button next to `master` and click **New file**. +1. Add the name of your issue template to the **File name** text field next to `master`. + Make sure that your file has the `.md` extension, for + example `feature_request.md` or `Feature Request.md`. +1. Commit and push to your default branch. If you don't have a `.gitlab/issue_templates` directory in your repository, you need to create it. To create the `.gitlab/issue_templates` directory: - 1. Click the `+` button next to `master` and select **New directory**. - 1. Name this new directory `.gitlab` and commit to your default branch. - 1. Click the `+` button next to `master` again and select **New directory**.This time, n - 1. Name your directory `issue_templates` and commit to your default branch. +1. Click the `+` button next to `master` and select **New directory**. +1. Name this new directory `.gitlab` and commit to your default branch. +1. Click the `+` button next to `master` again and select **New directory**. +1. Name your directory `issue_templates` and commit to your default branch. To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue) and see if you can choose a description template. @@ -80,17 +82,17 @@ to the issue description field. The **Reset template** button discards any changes you made after picking the template and returns it to its initial status. NOTE: -You can create short-cut links to create an issue using a designated template. For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. +You can create shortcut links to create an issue using a designated template. +For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`.  ## Setting a default template for merge requests and issues **(STARTER)** -> - This feature was introduced before [description templates](#overview) and is available in [GitLab Starter](https://about.gitlab.com/pricing/). It can be enabled in the project's settings. -> - Templates for issues were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28) in GitLab EE 8.1. -> - Templates for merge requests were [introduced](https://gitlab.com/gitlab-org/gitlab/commit/7478ece8b48e80782b5465b96c79f85cc91d391b) in GitLab EE 6.9. +> - Templates for merge requests [introduced](https://gitlab.com/gitlab-org/gitlab/commit/7478ece8b48e80782b5465b96c79f85cc91d391b) in GitLab 6.9. +> - Templates for issues [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28) in GitLab 8.1. -The visibility of issues and/or merge requests should be set to either "Everyone +The visibility of issues or merge requests should be set to either "Everyone with access" or "Only Project Members" in your project's **Settings / Visibility, project features, permissions** section, otherwise the template text areas don't show. This is the default behavior, so in most cases you should be fine. @@ -113,52 +115,46 @@ pre-filled with the text you entered in the template(s). ## Description template example -We make use of Description Templates for Issues and Merge Requests within the GitLab Community -Edition project. Please refer to the [`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab) -for some examples. +We make use of description templates for issues and merge requests in the GitLab project. +For some examples, refer to the [`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab). NOTE: -It's possible to use [quick actions](quick_actions.md) within description templates to quickly add +It's possible to use [quick actions](quick_actions.md) in description templates to quickly add labels, assignees, and milestones. The quick actions are only executed if the user submitting the issue or merge request has the permissions to perform the relevant actions. Here is an example of a Bug report template: -```plaintext -Summary +```markdown +## Summary (Summarize the bug encountered concisely) - -Steps to reproduce +## Steps to reproduce (How one can reproduce the issue - this is very important) +## Example Project -Example Project - -(If possible, please create an example project here on GitLab.com that exhibits the problematic behaviour, and link to it here in the bug report) - -(If you are using an older version of GitLab, this will also determine whether the bug has been fixed in a more recent version) +(If possible, please create an example project here on GitLab.com that exhibits the problematic +behavior, and link to it here in the bug report. +If you are using an older version of GitLab, this will also determine whether the bug has been fixed +in a more recent version) - -What is the current bug behavior? +## What is the current bug behavior? (What actually happens) - -What is the expected correct behavior? +## What is the expected correct behavior? (What you should see instead) +## Relevant logs and/or screenshots -Relevant logs and/or screenshots - -(Paste any relevant logs - please use code blocks (```) to format console output, -logs, and code as it's very hard to read otherwise.) - +(Paste any relevant logs - please use code blocks (```) to format console output, logs, and code, as +it's very hard to read otherwise.) -Possible fixes +## Possible fixes (If you can, link to the line of code that might be responsible for the problem) diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 49918b8f023..5c24ec6caf6 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# File Locking **(CORE)** +# File Locking **(FREE)** Preventing wasted work caused by unresolvable merge conflicts requires a different way of working. This means explicitly requesting write permissions, @@ -26,7 +26,7 @@ GitLab supports two different modes of file locking: - [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)** + files from being modified on any branch. **(FREE)** - [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)** @@ -41,7 +41,7 @@ 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`. -## Exclusive file locks +## Exclusive file locks **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35856) in GitLab 10.5. @@ -198,7 +198,8 @@ Suggested workflow for shared projects: > [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. +requires access to [GitLab Premium](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`). diff --git a/doc/user/project/gpg_signed_commits/index.md b/doc/user/project/gpg_signed_commits/index.md deleted file mode 100644 index 206013210a0..00000000000 --- a/doc/user/project/gpg_signed_commits/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../repository/gpg_signed_commits/index.md' ---- - -This document was moved to [another location](../repository/gpg_signed_commits/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index 1d92e32e071..5ffc2878269 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -7,22 +7,28 @@ type: reference # Syntax Highlighting -GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It will try to guess what language to use based on the file extension, which most of the time is sufficient. +GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language to use based on the file extension, which most of the time is sufficient. NOTE: The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/) for text editing, which internally uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for syntax highlighting. -If GitLab is guessing wrong, you can override its choice of language using the `gitlab-language` attribute in `.gitattributes`. For example, if you are working in a Prolog project and using the `.pl` file extension (which would normally be highlighted as Perl), you can add the following to your `.gitattributes` file: +If GitLab is guessing wrong, you can override its choice of language using the +`gitlab-language` attribute in `.gitattributes`. For example, if you are working in a +<!-- vale gitlab.Spelling = NO --> Prolog <!-- vale gitlab.Spelling = YES --> +project and using the `.pl` file extension (which would normally be highlighted as Perl), +you can add the following to your `.gitattributes` file: ``` conf *.pl gitlab-language=prolog ``` -When you check in and push that change, all `*.pl` files in your project will be highlighted as Prolog. +<!-- vale gitlab.Spelling = NO --> +When you check in and push that change, all `*.pl` files in your project are highlighted as Prolog. +<!-- vale gitlab.Spelling = YES --> -The paths here are simply Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is: +The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is: ``` conf /Nicefile gitlab-language=ruby @@ -38,7 +44,8 @@ To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shen /other-file gitlab-language=text?token=Error ``` -Please note that these configurations will only take effect when the `.gitattributes` file is in your default branch (usually `master`). +Please note that these configurations only take effect when the `.gitattributes` +file is in your default branch (usually `master`). NOTE: The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 82ff889c043..61d4d29aa4d 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -62,7 +62,7 @@ Migrating to Git/GitLab will benefit you: an open source end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more. - **Support for many network protocols**. Git supports SSH, HTTP/HTTPS and rsync - among others, whereas CVS supports only SSH and its own insecure pserver + among others, whereas CVS supports only SSH and its own insecure `pserver` protocol with no user authentication. ## How to migrate @@ -70,7 +70,7 @@ Migrating to Git/GitLab will benefit you: Here's a few links to get you started with the migration: - [Migrate using the `cvs-fast-export` tool](https://gitlab.com/esr/cvs-fast-export) -- [Stack Overflow post on importing the CVS repo](https://stackoverflow.com/a/11490134/974710) +- [Stack Overflow post on importing the CVS repository](https://stackoverflow.com/a/11490134/974710) - [Convert a CVS repository to Git](https://www.techrepublic.com/blog/linux-and-open-source/convert-cvs-repositories-to-git/) - [Man page of the `git-cvsimport` tool](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-cvsimport.html) - [Migrate using `reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html#conversion) diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index 38679914a9d..bac10cb0948 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -29,7 +29,8 @@ If you want to continue monitoring your dependencies, see the ## What happened to my account? Your account has been automatically closed on May 15th, 2018. If you had a paid -subscription at that time, your card will be refunded on a pro rata temporis basis. +subscription at that time, your card will be refunded on a +<!-- vale gitlab.Spelling = NO --> pro rata temporis <!-- vale gitlab.Spelling = YES --> basis. You may contact `gemnasium@gitlab.com` regarding your closed account. ## Will my account/data be transferred to GitLab Inc.? @@ -66,15 +67,18 @@ GitHub.com or GitHub Enterprise repository. This will automatically prompt GitLab CI/CD to run whenever code is pushed to GitHub and post CI/CD results back to both GitLab and GitHub when completed. -1. Create a new project, and select "CI/CD for external repo": +<!-- vale gitlab.Spelling = NO --> + +1. Create a new project, and select **CI/CD for external repo**:  + <!-- vale gitlab.Spelling = YES --> -1. Use the "GitHub" button to connect your repositories. +1. Use the **GitHub** button to connect your repositories.  -1. Select the project(s) to be set up with GitLab CI/CD and chose "Connect". +1. Select the project(s) to be set up with GitLab CI/CD and choose **Connect**.  diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 0e8cc159aec..3ff612c51a7 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -9,11 +9,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can import your existing repositories by providing the Git URL: -1. From your GitLab dashboard click **New project** -1. Switch to the **Import project** tab -1. Click on the **Repo by URL** button -1. Fill in the "Git repository URL" and the remaining project fields -1. Click **Create project** to begin the import process -1. Once complete, you will be redirected to your newly created project +<!-- vale gitlab.Spelling = NO --> +<!-- vale gitlab.SubstitutionWarning = NO --> + +1. From your GitLab dashboard click **New project**. +1. Switch to the **Import project** tab. +1. Click on the **Repo by URL** button. +1. Fill in the "Git repository URL" and the remaining project fields. +1. Click **Create project** to begin the import process. +1. Once complete, you will be redirected to your newly created project. + +<!-- vale gitlab.Spelling = YES --> +<!-- vale gitlab.SubstitutionWarning = YES -->  diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index 3642d07106c..a816dca59bc 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -30,7 +30,7 @@ There are two approaches to SVN to Git migration: migration. It creates a writable Git mirror of a local or remote Subversion repository and that way you can use both Subversion and Git as long as you like. It requires access to your GitLab server as it talks with the Git repositories -directly in a filesystem level. +directly in a file system level. ### SubGit prerequisites diff --git a/doc/user/project/import/tfs.md b/doc/user/project/import/tfs.md deleted file mode 100644 index 31f9b200558..00000000000 --- a/doc/user/project/import/tfs.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'tfvc.md' ---- - -This document was moved to [another location](tfvc.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/index.md b/doc/user/project/index.md index e3079c3731d..607049b512e 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -17,12 +17,12 @@ the number of private projects you create. ## Project features -When you create a project in GitLab, you'll have access to a large number of +When you create a project in GitLab, you receive access to a large number of [features](https://about.gitlab.com/features/): **Repositories:** -- [Issue tracker](issues/index.md): Discuss implementations with your team within issues +- [Issue tracker](issues/index.md): Discuss implementations with your team in issues - [Issue Boards](issue_board.md): Organize and prioritize your workflow - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project - [Repositories](repository/index.md): Host your code in a fully @@ -42,13 +42,13 @@ When you create a project in GitLab, you'll have access to a large number of **Issues and merge requests:** -- [Issue tracker](issues/index.md): Discuss implementations with your team within issues +- [Issue tracker](issues/index.md): Discuss implementations with your team in issues - [Issue Boards](issue_board.md): Organize and prioritize your workflow - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project - [Merge Requests](merge_requests/index.md): Apply your branching strategy and get reviewed by your team - [Merge Request Approvals](merge_requests/merge_request_approvals.md): Ask for approval before - implementing a change **(STARTER)** + implementing a change - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): Your Git diff tool right from the GitLab UI - [Review Apps](../../ci/review_apps/index.md): Live preview the results @@ -108,7 +108,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Conan packages](../packages/conan_repository/index.md): your private Conan repository in GitLab. - [Maven packages](../packages/maven_repository/index.md): your private Maven repository in GitLab. - [NPM packages](../packages/npm_registry/index.md): your private NPM package registry in GitLab. -- [Code owners](code_owners.md): specify code owners for certain files **(STARTER)** +- [Code owners](code_owners.md): specify code owners for certain files - [License Compliance](../compliance/license_compliance/index.md): approve and deny licenses for projects. **(ULTIMATE)** - [Dependency List](../application_security/dependency_list/index.md): view project dependencies. **(ULTIMATE)** - [Requirements](requirements/index.md): Requirements allow you to create criteria to check your products against. **(ULTIMATE)** @@ -192,7 +192,7 @@ To delete a project, first navigate to the home page for that project. 1. Click **Delete project** 1. Confirm this action by typing in the expected text. -Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects within a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). +Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects in a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). ## CI/CD for external repositories **(PREMIUM)** @@ -214,11 +214,11 @@ filtered by **Push events**, **Merge events**, **Issue events**, **Comments**, ### Leave a project -**Leave project** will only display on the project's dashboard +**Leave project** only displays on the project's dashboard when a project is part of a group (under a [group namespace](../group/index.md#namespaces)). -If you choose to leave a project you will no longer be a project -member, therefore, unable to contribute. +If you choose to leave a project you are no longer a project +member, and cannot contribute. ## Project's landing page @@ -230,15 +230,15 @@ with [permissions to view the project's code](../permissions.md#project-members- - The content of a [`README` or an index file](repository/#repository-readme-and-index-files) - is displayed (if any), followed by the list of directories within the + is displayed (if any), followed by the list of directories in the project's repository. - If the project doesn't contain either of these files, the - visitor will see the list of files and directories of the repository. + visitor sees the list of files and directories of the repository. -For users without permissions to view the project's code: +For users without permissions to view the project's code, GitLab displays: -- The wiki homepage is displayed, if any. -- The list of issues within the project is displayed. +- The wiki homepage, if any. +- The list of issues in the project. ## GitLab Workflow - VS Code extension @@ -259,15 +259,15 @@ Depending on the situation, different things apply. When [renaming a user](../profile/index.md#changing-your-username), [changing a group path](../group/index.md#changing-a-groups-path) or [renaming a repository](settings/index.md#renaming-a-repository): -- Existing web URLs for the namespace and anything under it (e.g., projects) will +- Existing web URLs for the namespace and anything under it (such as projects) will redirect to the new URLs. - Starting with GitLab 10.3, existing Git remote URLs for projects under the - namespace will redirect to the new remote URL. Every time you push/pull to a + namespace redirect to the new remote URL. Every time you push/pull to a repository that has changed its location, a warning message to update - your remote will be displayed instead of rejecting your action. - This means that any automation scripts, or Git clients will continue to + your remote is displayed instead of rejecting your action. + This means that any automation scripts, or Git clients continue to work after a rename, making any transition a lot smoother. -- The redirects will be available as long as the original path is not claimed by +- The redirects are available as long as the original path is not claimed by another group, user or project. ## Use your project as a Go package @@ -278,11 +278,11 @@ and `godoc.org` discovery requests, including the [`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) meta tags. Private projects, including projects in subgroups, can be used as a Go package, -but may require configuration to work correctly. GitLab will respond correctly +but may require configuration to work correctly. GitLab responds correctly to `go get` discovery requests for projects that *are not* in subgroups, regardless of authentication or authorization. [Authentication](#authenticate-go-requests) is required to use a private project -in a subgroup as a Go package. Otherwise, GitLab will truncate the path for +in a subgroup as a Go package. Otherwise, GitLab truncates the path for private projects in subgroups to the first two segments, causing `go get` to fail. @@ -302,10 +302,10 @@ queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching) `GOPRIVATE`, `GONOPROXY`, and `GONOSUMDB` are comma-separated lists of Go modules and Go module prefixes. For example, -`GOPRIVATE=gitlab.example.com/my/private/project` will disable queries for that -one project, but `GOPRIVATE=gitlab.example.com` will disable queries for *all* -projects on GitLab.com. Go will not query module proxies if the module name or a -prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go will not query checksum +`GOPRIVATE=gitlab.example.com/my/private/project` disables queries for that +one project, but `GOPRIVATE=gitlab.example.com` disables queries for *all* +projects on GitLab.com. Go does not query module proxies if the module name or a +prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go does not query checksum databases if the module name or a prefix of it appears in `GONOPRIVATE` or `GONOSUMDB`. @@ -315,8 +315,8 @@ To authenticate requests to private projects made by Go, use a [`.netrc` file](https://ec.haxx.se/usingcurl-netrc.html) and a [personal access token](../profile/personal_access_tokens.md) in the password field. **This only works if your GitLab instance can be accessed with HTTPS.** The `go` command -will not transmit credentials over insecure connections. This will authenticate -all HTTPS requests made directly by Go but will not authenticate requests made +does not transmit credentials over insecure connections. This authenticates +all HTTPS requests made directly by Go, but does not authenticate requests made through Git. For example: @@ -332,16 +332,18 @@ On Windows, Go reads `~/_netrc` instead of `~/.netrc`. ### Authenticate Git fetches -If a module cannot be fetched from a proxy, Go will fall back to using Git (for -GitLab projects). Git will use `.netrc` to authenticate requests. Alternatively, -Git can be configured to embed specific credentials in the request URL, or to -use SSH instead of HTTPS (as Go always uses HTTPS to fetch Git repositories): +If a module cannot be fetched from a proxy, Go falls back to using Git (for +GitLab projects). Git uses `.netrc` to authenticate requests. You can also +configure Git to either: + +- Embed specific credentials in the request URL. +- Use SSH instead of HTTPS, as Go always uses HTTPS to fetch Git repositories. ```shell -# embed credentials in any request to GitLab.com: +# Embed credentials in any request to GitLab.com: git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" -# use SSH instead of HTTPS: +# Use SSH instead of HTTPS: git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" ``` @@ -352,9 +354,9 @@ git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.examp To quickly access a project from the GitLab UI using the project ID, visit the `/projects/:id` URL in your browser or other tool accessing the project. -## Project aliases **(PREMIUM ONLY)** +## Project aliases **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab Premium 12.1. When migrating repositories to GitLab and they are being accessed by other systems, it's very useful to be able to access them using the same name especially when @@ -369,12 +371,12 @@ A project alias can be only created via API and only by GitLab administrators. Follow the [Project Aliases API documentation](../../api/project_aliases.md) for more details. -Once an alias has been created for a project (e.g., an alias `gitlab` for the -project `https://gitlab.com/gitlab-org/gitlab`), the repository can be cloned -using the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of +After an alias has been created for a project (such as an alias `gitlab` for the +project `https://gitlab.com/gitlab-org/gitlab`), you can clone the repository +with the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of `git clone git@gitlab.com:gitlab-org/gitlab.git`). -## Project activity analytics overview **(ULTIMATE ONLY)** +## Project activity analytics overview **(ULTIMATE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab [Ultimate](https://about.gitlab.com/pricing/) 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 434ae760aff..d63599d02bc 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -4,7 +4,7 @@ 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/#assignments --- -# IBM Engineering Workflow Management (EWM) Integration **(CORE)** +# IBM Engineering Workflow Management (EWM) Integration **(FREE)** 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. diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md deleted file mode 100644 index 1fbbee36173..00000000000 --- a/doc/user/project/integrations/generic_alerts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/incident_management/generic_alerts.md' ---- - -This document was moved to [another location](../../../operations/incident_management/generic_alerts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index ccf4b6cb303..ef8c9d59132 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -4,7 +4,7 @@ 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/#assignments --- -# GitLab Slack application **(FREE ONLY)** +# GitLab Slack application **(FREE SAAS)** > - Introduced in GitLab 9.4. > - Distributed to Slack App Directory in GitLab 10.2. diff --git a/doc/user/project/integrations/img/mattermost_configuration.png b/doc/user/project/integrations/img/mattermost_configuration.png Binary files differdeleted file mode 100644 index 18c0036846d..00000000000 --- a/doc/user/project/integrations/img/mattermost_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_configuration_v2.png b/doc/user/project/integrations/img/mattermost_configuration_v2.png Binary files differnew file mode 100644 index 00000000000..e05b34fd77a --- /dev/null +++ b/doc/user/project/integrations/img/mattermost_configuration_v2.png diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 8dd7e4309b4..58f7ea3279f 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -10,7 +10,7 @@ GitLab provides a way to push update messages to an Irker server. When configured, pushes to a project trigger the service to send data directly to the Irker server. -See the project homepage for further information: <https://gitlab.com/esr/irker> +See the [project homepage](https://gitlab.com/esr/irker) for further information. ## Needed setup diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 306a16bd873..aa5d11282d9 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -6,57 +6,82 @@ 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, Jira integrations with GitLab make the process of working across systems more efficient. +You can use Jira to track work implemented in GitLab. The Jira integration with GitLab makes the +process of working across these 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). +The GitLab Jira integration, available in every GitLab project by default, allows you to connect +to any Jira instance, whether on Atlassian cloud or self-managed. -After you set up this integration, you can cross-reference activity in the GitLab project with any of your projects in Jira. This includes the ability to close or transition Jira issues when work is completed in GitLab. +You can also install the [Jira Development Panel integration](../../../integration/jira_development_panel.md). +For more information about the differences between the two integrations, see +[Jira integrations](jira_integrations.md). -Features include: +After you set up this integration, you can cross-reference activity in the GitLab project with any +of your projects in Jira. This includes the ability to close or transition Jira issues when work is +completed in GitLab and: -- **Mention a Jira issue ID** in a commit message or MR (merge request) and +- Mention a Jira issue ID in a commit message or MR (merge request) and: - GitLab links to the Jira issue. - The Jira issue adds a comment with details and a link back to the activity in GitLab. -- **Mention that a commit or MR resolves or closes a specific Jira issue** and when it's merged to the default branch: +- Mention that a commit or MR resolves or closes a specific Jira issue and when it's merged to the default branch: - The GitLab MR displays a note that it closed the Jira issue. Prior to the merge, MRs indicate which issue they close. - 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)** +- Run a pipeline on an MR linked to a Jira issue: + - The Jira issue shows the current pipeline status (in the sidebar as "builds"). +- Deploy to an environment from an MR linked to a Jira issue: + - The Jira issue shows the status of the deployment (in the sidebar as "deployments"). +- Create or modify a feature flag that mentions a Jira issue in its description: + - The Jira issue shows the details of the feature-flag (in the sidebar as "feature flags"). +- 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: +Additional features provided by the Jira Development Panel integration include: - 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. - -See the [feature comparison](jira_integrations.md#feature-comparison) for more details. +- Showing pipeline, deployment, and feature flags in Jira issues. ## Configuration <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be). -Each GitLab project can be configured to connect to an entire Jira instance. That -means one GitLab project can interact with _all_ Jira projects in that instance, once -configured. Therefore, you do not have to explicitly associate -a GitLab project with any single Jira project. +Each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab +project can interact with _all_ Jira projects in that instance, once configured. For: + +- The [view Jira issues](#view-jira-issues) feature, you must associate a GitLab project with a + specific Jira project. +- Other features, you do not have to explicitly associate a GitLab project with any single Jira + project. + +If you have one Jira instance, you can pre-fill the settings. For more information, see the +documentation for: + +- [Project integration management](../../admin_area/settings/project_integration_management.md). +- [Services Templates](services_templates.md). + +To enable the Jira service in GitLab, you must: -If you have one Jira instance, you can pre-fill the settings page with a default -template. See the [Services Templates](services_templates.md) docs. +1. Configure the project in Jira. +1. Enter the correct values in GitLab. -In order to enable the Jira service in GitLab, you need to first configure the project in Jira and then enter the correct values in GitLab. +### Configure Jira -### Configuring Jira +The process for configuring Jira depends on whether you host Jira on your own server or on +[Atlassian cloud](https://www.atlassian.com/cloud). #### Jira Server -**Jira Server** supports basic authentication. When connecting, a **username and password** are required. Note that connecting to Jira Server via CAS is not possible. [Set up a user in Jira Server](jira_server_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab). +Jira Server supports basic authentication. When connecting, a **username and password** are +required. Connecting to Jira Server via CAS is not possible. For more information, see +[set up a user in Jira Server](jira_server_configuration.md). -#### Jira Cloud +#### Jira on Atlassian cloud -**Jira Cloud** supports authentication through an API token. When connecting to **Jira Cloud**, an **email and API token** are required. [Set up a user in Jira Cloud](jira_cloud_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab). +Jira on Atlassian cloud supports authentication through an API token. When connecting to Jira on +Atlassian cloud, an **email and API token** are required. For more information, see +[set up a user in Jira on Atlassian cloud](jira_cloud_configuration.md). -### Configuring GitLab +### Configure GitLab > **Notes:** > @@ -79,10 +104,10 @@ Enter the further details on the page as described in the following table. | Field | Description | | ----- | ----------- | -| `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. E.g., `https://jira.example.com`. | -| `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira Cloud**. | -| `Username or Email` | Created in [configuring Jira](#configuring-jira) step. Use `username` for **Jira Server** or `email` for **Jira Cloud**. | -| `Password/API token` |Created in [configuring Jira](#configuring-jira) step. Use `password` for **Jira Server** or `API token` for **Jira Cloud**. | +| `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. For example, `https://jira.example.com`. | +| `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira on Atlassian cloud**. | +| `Username or Email` | Created in [configure Jira](#configure-jira) step. Use `username` for **Jira Server** or `email` for **Jira on Atlassian cloud**. | +| `Password/API token` |Created in [configure Jira](#configure-jira) step. Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. | | `Jira workflow transition IDs` | Required for closing Jira issues via commits or merge requests. These are the IDs of transitions in Jira that move issues to a particular state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. In GitLab 13.6 and earlier, field was called `Transition ID`. | To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. **(PREMIUM)** @@ -107,19 +132,19 @@ administration UI. You can get the ID you need in either of the following ways: 1. By mousing over the link for the transition you want and looking for the "action" parameter in the URL -Note that the transition ID may vary between workflows (e.g., bug vs. story), +Note that the transition ID may vary between workflows (for example, bug vs. story), even if the status you are changing to is the same. #### Disabling comments on Jira issues You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue. -See the [Configuring GitLab](#configuring-gitlab) section and uncheck the **Enable comments** setting. +See the [Configure GitLab](#configure-gitlab) section and uncheck the **Enable comments** setting. ## Jira issues -By now you should have [configured Jira](#configuring-jira) and enabled the -[Jira service in GitLab](#configuring-gitlab). If everything is set up correctly +By now you should have [configured Jira](#configure-jira) and enabled the +[Jira service in GitLab](#configure-gitlab). If everything is set up correctly you should be able to reference and close Jira issues by just mentioning their ID in GitLab commits and merge requests. @@ -201,7 +226,7 @@ with a link to the commit that resolved the issue. > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. -You can browse and search issues from a selected Jira project directly in GitLab. This requires [configuration](#configuring-gitlab) in GitLab by an administrator. +You can browse and search issues from a selected Jira project directly in GitLab. This requires [configuration](#configure-gitlab) in GitLab by an administrator.  diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index b8eebef8e42..e9f30f32308 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -4,10 +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/#assignments --- -# Creating an API token in Jira Cloud +# Create an API token in Jira on Atlassian cloud -An API token is needed when integrating with Jira Cloud, follow the steps -below to create one: +For [integrations with Jira](jira.md), an API token is needed when integrating with Jira +on Atlassian cloud. To create an API token: 1. Log in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address. @@ -17,10 +17,11 @@ below to create one: 1. Click **Create API token**. - +  - +1. Click **Copy**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configure-gitlab). -1. Click **Copy**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configuring-gitlab). +  -The Jira configuration is complete. You need the newly created token, and the associated email address, when [configuring GitLab](jira.md#configuring-gitlab) in the next section. +The Jira configuration is complete. You need the newly created token, and the associated email +address, when [configuring GitLab](jira.md#configure-gitlab). diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 3c91fd3549f..3daea250aac 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -6,26 +6,46 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Jira integrations -## Introduction +GitLab can be integrated with [Jira](https://www.atlassian.com/software/jira). -GitLab Issues are a tool for discussing ideas and planning and tracking work. However, your organization may already use Jira for these purposes, with -extensive, established data and business processes they rely on. +[Issues](../issues/index.md) are a tool for discussing ideas, and planning and tracking work. +However, your organization may already use Jira for these purposes, with extensive, established data +and business processes they rely on. -Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work exclusively in GitLab, you also have the option of continuing to use Jira by using the GitLab Jira integrations. +Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work +exclusively in GitLab, you can also continue to use Jira by using the GitLab Jira integrations. -## Integrations +## Integration types -The following Jira integrations allow different types of cross-referencing between GitLab activity and Jira issues, with additional features: +There are two different Jira integrations that 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) - 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-com-for-jira-cloud) 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). +- [Jira integration](jira.md), built in to GitLab. In a given GitLab project, it can be configured + to connect to any Jira instance, either hosted by you or hosted in + [Atlassian cloud](https://www.atlassian.com/cloud). +- [Jira development panel integration](../../../integration/jira_development_panel.md). Connects all + GitLab projects under a specified group or personal namespace. -### Feature comparison +Jira development panel integration configuration depends on whether: + +- You're using GitLab.com or a self-managed GitLab instance. +- You're using Jira on [Atlassian cloud](https://www.atlassian.com/cloud) or on your own server. + +| You use Jira on: | For the Jira development panel integration, GitLab.com customers need: | For the Jira development panel integration, GitLab self-managed customers need: | +|:-------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Atlassian cloud | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See a [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/268278) for more information. | +| Your own server | The [Jira DVCS connector](../../../integration/jira_development_panel.md). | The [Jira DVCS connector](../../../integration/jira_development_panel.md). | + +NOTE: +DVCS means distributed version control system. + +## Feature comparison + +The integration to use depends on the capabilities your require. You can install both at the same +time. | Capability | Jira integration | Jira Development Panel integration | -|-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| +|:----------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------| | Mention of Jira issue ID in GitLab is automatically linked to that issue | Yes | No | | Mention of Jira issue ID in GitLab issue/MR is reflected in the Jira issue | Yes, as a Jira comment with the GitLab issue/MR title and a link back to it. Its first mention also adds the GitLab page to the Jira issue under “Web links”. | Yes, in the issue’s Development panel | | Mention of Jira issue ID in GitLab commit message is reflected in the issue | Yes. The entire commit message is added to the Jira issue as a comment and under “Web links”, each with a link back to the commit in GitLab. | Yes, in the issue’s Development panel and optionally with a custom comment on the Jira issue using Jira Smart Commits. | diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index d2a42c0535e..5bb17388a1e 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -4,61 +4,65 @@ 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/#assignments --- -# Creating a username and password for Jira Server +# Create Jira Server username and password -We need to create a user in Jira to have access to all projects that need to integrate with GitLab. +For [integrations with Jira](jira.md), you must create a user account in Jira to have access to +all projects that need to integrate with GitLab. -As an example, we create a user named `gitlab` and add it to a new group -named `gitlab-developers`. +The Jira user account created for the integration must have write access to +your Jira projects. -NOTE: -It is important that the Jira user created for the integration is given 'write' -access to your Jira projects. This is covered in the process below. +As an example, the following process creates a user named `gitlab` and that's a +member of a new group named `gitlab-developers`: -1. Log in to your Jira instance as an administrator and under **Jira Administration** - go to **User Management** to create a new user. +1. Sign in to your Jira instance as an administrator, and + then go to the gear icon and select **User Management**.  -1. The next step is to create a new user (e.g., `gitlab`) who has write access - to projects in Jira. Enter the user's name and a _valid_ e-mail address - since Jira sends a verification e-mail to set up the password. +1. Create a new user account (for example, `gitlab`) with write access to + projects in Jira. Enter the user account's name and a valid e-mail address, + because Jira sends a verification email to set up the password. - Jira creates the username automatically by using the e-mail - prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You - need to create an HTTP basic authentication password. You can do this by visiting the user - profile, looking up the username, and setting a password. + Jira creates the username by using the email prefix. You can change the + username later, if needed. The GitLab integration doesn't support SSO (such + as SAML). You need to create an HTTP basic authentication password. You can + do this by visiting the user profile, looking up the username, and setting a + password.  -1. Create a `gitlab-developers` group (we give this group write access to Jira - projects in a later step.) Go to the **Groups** tab on the left, and select **Add group**. +1. From the sidebar, select **Groups**.  - Give it a name and click **Add group**. +1. In the **Add group** section, enter a **Name** for the group (for example, + `gitlab-developers`), and then select **Add group**. -1. Add the `gitlab` user to the `gitlab-developers` group by clicking **Edit members**. - The `gitlab-developers` group should be listed in the leftmost box as a selected group. - Under **Add members to selected group(s)**, enter `gitlab`. +1. Add the `gitlab` user to the `gitlab-developers` group by selecting **Edit members**. + The `gitlab-developers` group should be listed in the leftmost box as a + selected group. In the **Add members to selected group(s)** area, enter `gitlab`.  - Click **Add selected users** and `gitlab` should appear in the **Group member(s)** box. - This membership is saved automatically. + Select **Add selected users**, and `gitlab` should appear in the **Group member(s)** + area. This membership is saved automatically.  -1. To give the newly-created group 'write' access, you need to create a **Permission Scheme**. - To do this, click the gear icon and select **Issues**. Then click **Permission Schemes**. - Click **Add Permission Scheme** and enter a **Name** and, optionally, a **Description**. +1. To give the newly-created group 'write' access, you must create a permission + scheme. To do this, in the admin menu, go to the gear icon and select **Issues**. -1. Once your permission scheme is created, you are taken back to the permissions scheme list. - Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, - click **Edit**. In the resulting dialog box, select **Group** and select `gitlab-developers` - from the dropdown. +1. From the sidebar, select **Permission Schemes**. + +1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a + **Description**, and then select **Add**. + +1. In the permissions scheme list, locate your new permissions scheme, and + select **Permissions**. Next to **Administer Projects**, select **Edit**. In + the **Group** list, select `gitlab-developers`.  The Jira configuration is complete. Write down the new Jira username and its -password as they are needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). +password, as you need them when [configuring GitLab](jira.md#configure-gitlab). diff --git a/doc/user/project/integrations/kubernetes.md b/doc/user/project/integrations/kubernetes.md deleted file mode 100644 index 646c9ed66d5..00000000000 --- a/doc/user/project/integrations/kubernetes.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../clusters/index.md' ---- - -This document was moved to [another location](../clusters/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index e80f672d05d..db190f47b01 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -58,5 +58,7 @@ At the end, fill in your Mattermost details: | **Webhook** | The incoming webhook URL which you have to set up on Mattermost, similar to: `http://mattermost.example/hooks/5xo…` | | **Username** | Optional username which can be on messages sent to Mattermost. Fill this in if you want to change the username of the bot. | | **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | +| **Branches to be notified** | Select which types of branches to send notifications for. | +| **Labels to be notified** | Optional labels that the issue or merge request must have in order to trigger a notification. Leave blank to get all notifications. | - + diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index c391877be20..840f46be97b 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](../../../operations/incident_management/alert_integrations.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | +| [Generic alerts](../../../operations/incident_management/integrations.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 | @@ -53,8 +53,8 @@ Click on the service links to see further configuration instructions and details | Packagist | Update your projects on Packagist, the main Composer repository | Yes | | Pipelines emails | Email the pipeline status to a list of recipients | No | | [Slack Notifications](slack.md) | Send GitLab events (for example, an issue was created) to Slack as notifications | No | -| [Slack slash commands](slack_slash_commands.md) **(CORE ONLY)** | Use slash commands in Slack to control GitLab | No | -| [GitLab Slack application](gitlab_slack_application.md) **(FREE ONLY)** | Use Slack's official application | No | +| [Slack slash commands](slack_slash_commands.md) **(FREE SELF)** | Use slash commands in Slack to control GitLab | No | +| [GitLab Slack application](gitlab_slack_application.md) **(FREE SAAS)** | Use Slack's official application | No | | PivotalTracker | Project Management Software (Source Commits Endpoint) | No | | [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 | diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md deleted file mode 100644 index 69e2ea2856c..00000000000 --- a/doc/user/project/integrations/project_services.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'overview.md' ---- - -This document was moved to [Integrations](overview.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 959c4cc623b..d40c638105e 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -4,22 +4,25 @@ 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/#assignments --- -# Prometheus integration +# Prometheus integration **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. -GitLab offers powerful integration with [Prometheus](https://prometheus.io) for monitoring key metrics of your apps, directly within GitLab. +GitLab offers powerful integration with [Prometheus](https://prometheus.io) for +monitoring key metrics of your apps, directly in GitLab. Metrics for each environment are retrieved from Prometheus, and then displayed -within the GitLab interface. +in the GitLab interface.  There are two ways to set up Prometheus integration, depending on where your apps are running: - For deployments on Kubernetes, GitLab can automatically [deploy and manage Prometheus](#managed-prometheus-on-kubernetes). -- For other deployment targets, simply [specify the Prometheus server](#manual-configuration-of-prometheus). +- For other deployment targets, [specify the Prometheus server](#manual-configuration-of-prometheus). -Once enabled, GitLab detects metrics from known services in the [metric library](prometheus_library/index.md). You can also [add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create +Once enabled, GitLab detects metrics from known services in the +[metric library](prometheus_library/index.md). You can also +[add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create [custom dashboards](../../../operations/metrics/dashboards/index.md). ## Enabling Prometheus Integration @@ -28,7 +31,8 @@ Once enabled, GitLab detects metrics from known services in the [metric library] > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28916) in GitLab 10.5. -GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cluster](../clusters/index.md), making monitoring of your apps easy. +GitLab can seamlessly deploy and manage Prometheus on a +[connected Kubernetes cluster](../clusters/index.md), to help you monitor your apps. #### Requirements @@ -36,7 +40,7 @@ GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cl #### Getting started -Once you have a connected Kubernetes cluster, deploying a managed Prometheus is as easy as a single click. +After you have a connected Kubernetes cluster, you can deploy a managed Prometheus with a single click. 1. Go to the **Operations > Kubernetes** page to view your connected clusters 1. Select the cluster you would like to deploy Prometheus to @@ -46,17 +50,28 @@ Once you have a connected Kubernetes cluster, deploying a managed Prometheus is #### About managed Prometheus deployments -Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). +Prometheus is deployed into the `gitlab-managed-apps` namespace, using the +[official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). +Prometheus is only accessible in the cluster, with GitLab communicating through the +[Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). -The Prometheus server [automatically detects and monitors](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): +The Prometheus server +[automatically detects and monitors](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) +nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, +set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): - `prometheus.io/scrape` to `true` to enable monitoring of the resource. - `prometheus.io/port` to define the port of the metrics endpoint. - `prometheus.io/path` to define the path of the metrics endpoint. Defaults to `/metrics`. -CPU and Memory consumption is monitored, but requires [naming conventions](prometheus_library/kubernetes.md#specifying-the-environment) in order to determine the environment. If you are using [Auto DevOps](../../../topics/autodevops/index.md), this is handled automatically. +CPU and Memory consumption is monitored, but requires +[naming conventions](prometheus_library/kubernetes.md#specifying-the-environment) +to determine the environment. If you are using +[Auto DevOps](../../../topics/autodevops/index.md), this is handled automatically. -The [NGINX Ingress](../clusters/index.md#installing-applications) that is deployed by GitLab to clusters, is automatically annotated for monitoring providing key response metrics: latency, throughput, and error rates. +The [NGINX Ingress](../clusters/index.md#installing-applications) that is deployed +by GitLab to clusters, is automatically annotated for monitoring providing key +response metrics: latency, throughput, and error rates. ##### Example of Kubernetes service annotations and labels @@ -161,15 +176,16 @@ Installing and configuring Prometheus to monitor applications is fairly straight 1. [Install Prometheus](https://prometheus.io/docs/prometheus/latest/installation/) 1. Set up one of the [supported monitoring targets](prometheus_library/index.md) -1. Configure the Prometheus server to [collect their metrics](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) +1. Configure the Prometheus server to + [collect their metrics](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) #### Configuration in GitLab -The actual configuration of Prometheus integration within GitLab +The actual configuration of Prometheus integration in GitLab requires the domain name or IP address of the Prometheus server you'd like to integrate with. If the Prometheus resource is secured with Google's Identity-Aware Proxy (IAP), -additional information like Client ID and Service Account credentials can be passed which -GitLab can use to access the resource. More information about authentication from a +you can pass information like Client ID and Service Account credentials. +GitLab can use these to access the resource. More information about authentication from a service account can be found at Google's documentation for [Authenticating from a service account](https://cloud.google.com/iap/docs/authentication-howto#authenticating_from_a_service_account). @@ -189,12 +205,13 @@ service account can be found at Google's documentation for #### Thanos configuration in GitLab You can configure [Thanos](https://thanos.io/) as a drop-in replacement for Prometheus -with GitLab, using the domain name or IP address of the Thanos server you'd like +with GitLab. Use the domain name or IP address of the Thanos server you'd like to integrate with. 1. Navigate to the [Integrations page](overview.md#accessing-integrations). 1. Click the **Prometheus** service. -1. Provide the domain name or IP address of your server, for example `http://thanos.example.com/` or `http://192.0.2.1/`. +1. Provide the domain name or IP address of your server, for example + `http://thanos.example.com/` or `http://192.0.2.1/`. 1. Click **Save changes**. ### Precedence with multiple Prometheus configurations @@ -221,7 +238,7 @@ can use only one: > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10408) in GitLab 9.2. > - GitLab 9.3 added the [numeric comparison](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/27439) of the 30 minute averages. -Developers can view the performance impact of their changes within the merge +Developers can view the performance impact of their changes in the merge request workflow. This feature requires [Kubernetes](prometheus_library/kubernetes.md) metrics. When a source branch has been deployed to an environment, a sparkline and diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index b563dd34896..4a88010a343 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Monitoring AWS resources +# Monitoring AWS resources **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index c14c14658b7..290313ac1af 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Monitoring HAProxy +# Monitoring HAProxy **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 501e8ba7c1d..e10da8c6ebe 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Prometheus Metrics library +# Prometheus Metrics library **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index ae330158a58..ed1949536a3 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Monitoring Kubernetes +# Monitoring Kubernetes **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. diff --git a/doc/user/project/integrations/prometheus_library/metrics.md b/doc/user/project/integrations/prometheus_library/metrics.md deleted file mode 100644 index a275efce5bb..00000000000 --- a/doc/user/project/integrations/prometheus_library/metrics.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'index.md' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 4cb827b3b4a..dcaef1e2ae6 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Monitoring NGINX +# Monitoring NGINX **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index f7542ec78f7..f7e6b6e76d6 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Monitoring NGINX Ingress Controller +# Monitoring NGINX Ingress Controller **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22133) in GitLab 11.7. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index c855e564753..0c86c4921b3 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Monitoring NGINX Ingress Controller with VTS metrics +# Monitoring NGINX Ingress Controller with VTS metrics **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13438) in GitLab 9.5. diff --git a/doc/user/project/integrations/prometheus_units.md b/doc/user/project/integrations/prometheus_units.md deleted file mode 100644 index 0c2ce3002ee..00000000000 --- a/doc/user/project/integrations/prometheus_units.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/metrics/dashboards/yaml_number_format.md' ---- - -This document was moved to [another location](../../../operations/metrics/dashboards/yaml_number_format.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 9e9f5b8297f..ab798675278 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -45,6 +45,7 @@ separately configured [Slack slash commands](slack_slash_commands.md). 1. Select the **Notify only broken pipelines** check box to only notify on failures. 1. In the **Branches to be notified** select box, choose which types of branches to send notifications for. +1. Leave the **Labels to be notified** field blank to get all notifications or add labels that the issue or merge request must have in order to trigger a notification. 1. Click **Test settings and save changes**. Your Slack team now starts receiving GitLab event notifications as configured. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 1e4577fb88e..4f206cd3e45 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Slack slash commands **(CORE ONLY)** +# Slack slash commands **(FREE SELF)** > Introduced in GitLab 8.15. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 47a44e53b47..27c2cb08d10 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -31,7 +31,7 @@ update a backup mirror, or even deploy to your production server. Webhooks are available: -- Per project, at a project's **Settings > Webhooks** menu. **(CORE)** +- Per project, at a project's **Settings > Webhooks** menu. **(FREE)** - Additionally per group, at a group's **Settings > Webhooks** menu. **(PREMIUM)** NOTE: @@ -1151,10 +1151,15 @@ X-Gitlab-Event: Pipeline Hook "email": "admin@example.com" }, "runner": { - "id":380987, - "description":"shared-runners-manager-6.gitlab.com", - "active":true, - "is_shared":true + "id": 380987, + "description": "shared-runners-manager-6.gitlab.com", + "active": true, + "is_shared": true, + "tags": [ + "linux", + "docker", + "shared-runner" + ] }, "artifacts_file":{ "filename": null, @@ -1183,7 +1188,11 @@ X-Gitlab-Event: Pipeline Hook "id":380987, "description":"shared-runners-manager-6.gitlab.com", "active":true, - "is_shared":true + "is_shared":true, + "tags": [ + "linux", + "docker" + ] }, "artifacts_file":{ "filename": null, @@ -1209,10 +1218,14 @@ X-Gitlab-Event: Pipeline Hook "email": "admin@example.com" }, "runner": { - "id":380987, - "description":"shared-runners-manager-6.gitlab.com", - "active":true, - "is_shared":true + "id": 380987, + "description": "shared-runners-manager-6.gitlab.com", + "active": true, + "is_shared": true, + "tags": [ + "linux", + "docker" + ] }, "artifacts_file":{ "filename": null, @@ -1308,7 +1321,11 @@ X-Gitlab-Event: Job Hook "active": true, "is_shared": false, "id": 380987, - "description": "shared-runners-manager-6.gitlab.com" + "description": "shared-runners-manager-6.gitlab.com", + "tags": [ + "linux", + "docker" + ] } } ``` @@ -1468,6 +1485,74 @@ X-Gitlab-Event: Member Hook } ``` +### Subgroup events **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260419) in GitLab 13.9. + +Subgroup events are triggered when: + +- A [subgroup is created in a group](#subgroup-created-in-a-group) +- A [subgroup is removed from a group](#subgroup-removed-from-a-group) + +#### Subgroup created in a group + +**Request Header**: + +```plaintext +X-Gitlab-Event: Subgroup Hook +``` + +**Request Body**: + +```json +{ + + "created_at": "2021-01-20T09:40:12Z", + "updated_at": "2021-01-20T09:40:12Z", + "event_name": "subgroup_create", + "name": "subgroup1", + "path": "subgroup1", + "full_path": "group1/subgroup1", + "group_id": 10, + "parent_group_id": 7, + "parent_name": "group1", + "parent_path": "group1", + "parent_full_path": "group1" + +} +``` + +#### Subgroup removed from a group + +**Request Header**: + +```plaintext +X-Gitlab-Event: Subgroup Hook +``` + +**Request Body**: + +```json +{ + + "created_at": "2021-01-20T09:40:12Z", + "updated_at": "2021-01-20T09:40:12Z", + "event_name": "subgroup_destroy", + "name": "subgroup1", + "path": "subgroup1", + "full_path": "group1/subgroup1", + "group_id": 10, + "parent_group_id": 7, + "parent_name": "group1", + "parent_path": "group1", + "parent_full_path": "group1" + +} +``` + +NOTE: +Webhooks for when a [subgroup is removed from a group](#subgroup-removed-from-a-group) are not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transferring-groups) + ### Feature Flag events Triggered when a feature flag is turned on or off. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 7119970fca0..d2f73a88eae 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Issue Boards **(CORE)** +# Issue Boards **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5554) in [GitLab 8.11](https://about.gitlab.com/releases/2016/08/22/gitlab-8-11-released/#issue-board). @@ -38,10 +38,9 @@ as shown in the following table: | 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 | +| Free | Multiple | 1 | No | No | +| Premium | Multiple | Multiple | Yes | Yes | +| Ultimate | Multiple | Multiple | Yes | Yes | To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards) below. @@ -54,10 +53,10 @@ the Issue Board feature. ## Multiple issue boards > - [Introduced](https://about.gitlab.com/releases/2016/10/22/gitlab-8-13-released/) in GitLab 8.13. -> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. +> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to [GitLab Free](https://about.gitlab.com/pricing/) in GitLab 12.1. > - Multiple issue boards per group are available in [GitLab Premium](https://about.gitlab.com/pricing/). -Multiple issue boards allow for more than one issue board for a given project **(CORE)** or group **(PREMIUM)**. +Multiple issue boards allow for more than one issue board for a given project **(FREE)** or group **(PREMIUM)**. This is great for large projects with more than one team or when a repository hosts the code of multiple products. Using the search box at the top of the menu, you can filter the listed boards. @@ -228,7 +227,7 @@ and vice versa. ## GitLab Enterprise features for issue boards -GitLab issue boards are available on GitLab Core and GitLab.com Free tiers, but some +GitLab issue boards are available on the GitLab Free tier, but some advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/). ### Configurable issue boards **(STARTER)** @@ -258,8 +257,8 @@ 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. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28597) to the Free tier of GitLab.com in 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212331) to GitLab Core in 13.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28597) to the Free tier of GitLab SaaS in 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212331) to GitLab Free self-managed in 13.0. To enable or disable focus mode, select the **Toggle focus mode** button (**{maximize}**) at the top right. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. @@ -435,13 +434,13 @@ To remove a list from an issue board: 1. Select **Remove list**. A confirmation dialog appears. 1. Select **OK**. -### Add issues to a list **(CORE ONLY)** +### Add issues to a list **(FREE SELF)** > - Feature flag [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47898) in GitLab 13.7. > - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. > - It's disabled on GitLab.com. > - It's recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-adding-issues-to-the-list). **(CORE ONLY)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-adding-issues-to-the-list). **(FREE SELF)** You can add issues to a list in a project issue board by clicking the **Add issues** button in the top right corner of the issue board. This opens up a modal @@ -461,7 +460,7 @@ the list by filtering by the following: - Release - Weight -#### Enable or disable adding issues to the list **(CORE ONLY)** +#### Enable or disable adding issues to the list **(FREE SELF)** Adding issues to the list is deployed behind a feature flag that is **disabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) @@ -563,7 +562,7 @@ another list. This makes it faster to reorder many issues at once. To select and move multiple cards: -1. Select each card with <kbd>Ctrl</kbd>+`Click` on Windows or Linux, or <kbd>Cmd</kbd>+`Click` on MacOS. +1. Select each card with <kbd>Control</kbd>+`Click` on Windows or Linux, or <kbd>Command</kbd>+`Click` on MacOS. 1. Drag one of the selected cards to another position or list and all selected cards are moved.  diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md deleted file mode 100644 index 6fa2822aa9a..00000000000 --- a/doc/user/project/issues/automatic_issue_closing.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#closing-issues-automatically' ---- - -This document was moved to [another location](managing_issues.md#closing-issues-automatically). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/closing_issues.md b/doc/user/project/issues/closing_issues.md deleted file mode 100644 index 45b905f2fb5..00000000000 --- a/doc/user/project/issues/closing_issues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#closing-issues' ---- - -This document was moved to [another location](managing_issues.md#closing-issues). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md deleted file mode 100644 index 53648b53ea3..00000000000 --- a/doc/user/project/issues/create_new_issue.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#create-a-new-issue' ---- - -This document was moved to [another location](managing_issues.md#create-a-new-issue). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index e7cd1377603..4fa7bef4fb2 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Export Issues to CSV > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1126) in [GitLab Starter 9.0](https://about.gitlab.com/releases/2017/03/22/gitlab-9-0-released/#export-issues-ees-eep). -> - Moved to GitLab Core in GitLab 12.10. +> - Moved to GitLab Free in GitLab 12.10. Issues can be exported as CSV from GitLab and are sent to your default notification email as an attachment. @@ -20,7 +20,7 @@ which stores tabular data in plain text. > _CSVs are a handy way of getting data from one program to another where one program cannot read the other ones normal output._ [Ref](https://www.quora.com/What-is-a-CSV-file-and-its-uses) CSV files can be used with any plotter or spreadsheet-based program, such as Microsoft Excel, -Open Office Calc, or Google Spreadsheets. +Open Office <!-- vale gitlab.Spelling = NO --> Calc, <!-- vale gitlab.Spelling = NO --> or Google Spreadsheets. ## Use cases diff --git a/doc/user/project/issues/deleting_issues.md b/doc/user/project/issues/deleting_issues.md deleted file mode 100644 index d8e1485a2dc..00000000000 --- a/doc/user/project/issues/deleting_issues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#deleting-issues' ---- - -This document was moved to [another location](managing_issues.md#deleting-issues). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 3739070be01..8dc5c3396ae 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -1,14 +1,14 @@ --- -stage: Create -group: Knowledge +stage: Plan +group: Product Planning info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" --- -# Design Management **(CORE)** +# Design Management **(FREE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. > - Support for SVGs was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. -> - Design Management was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Core in 13.0. +> - Design Management was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. Design Management allows you to upload design assets (wireframes, mockups, etc.) to GitLab issues and keep them stored in one single place, accessed by the Design @@ -46,7 +46,7 @@ If the requirements are not met, the **Designs** tab displays a message to the u ## Supported files Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, -`gif`, `bmp`, `tiff`, `ico`, or `svg`. +`gif`, `bmp`, `tiff`, `ico`, `webp`, or `svg`. Support for [PDF](https://gitlab.com/gitlab-org/gitlab/issues/32811) is planned for a future release. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 34e9340067c..909a20f0e2f 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -41,7 +41,7 @@ You can see issues with their due dates in the [issues list](index.md#issues-lis Overdue issues have their icon and date colored red. To sort issues by their due dates, select **Due date** from the dropdown menu on the right. Issues are then sorted from the earliest due date to the latest. -To display isses with the latest due dates at the top, select **Sort direction** (**{sort-lowest}**). +To display issues with the latest due dates at the top, select **Sort direction** (**{sort-lowest}**). Due dates also appear in your [to-do list](../../todos.md). diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 74311eefd83..e398c6f86d0 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -4,35 +4,29 @@ 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/#assignments --- -# Issues **(CORE)** +# Issues **(FREE)** -Issues are the fundamental medium for collaborating on ideas and planning work in GitLab. +Issues are the fundamental mechanism in GitLab to collaborate on ideas, solve +problems, and plan work. -## Overview +Using issues, you can share and discuss proposals (both before and during their +implementation) between you and your team, and outside collaborators. -The GitLab issue tracker is an advanced tool for collaboratively developing ideas, solving problems, -and planning work. +You can use issues for many purposes, customized to your needs and workflow. +Common use cases include: -Issues can allow sharing and discussion of proposals before, and during, -their implementation between: +- Discussing the implementation of a new idea. +- Tracking tasks and work status. +- Accepting feature proposals, questions, support requests, or bug reports. +- Elaborating on new code implementations. -- You and your team. -- Outside collaborators. +For more information about using issues, see the +[Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/) +GitLab blog post. -They can also be used for a variety of other purposes, customized to your -needs and workflow. - -Issues are always associated with a specific project. If you have multiple projects in a group, -you can view all of the issues collectively at the group level. - -**Common use cases include:** - -- Discussing the implementation of a new idea -- Tracking tasks and work status -- Accepting feature proposals, questions, support requests, or bug reports -- Elaborating on new code implementations - -See also [Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/). +Issues are always associated with a specific project. If you have multiple +projects in a group, you can view all of the issues collectively at the group +level. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> To learn how our Strategic Marketing department uses GitLab issues with [labels](../labels.md) and @@ -41,63 +35,30 @@ To learn how our Strategic Marketing department uses GitLab issues with [labels] ## Parts of an issue -Issues contain a variety of content and metadata, enabling a large range of flexibility -in how they are used. Each issue can contain the following attributes, though not all items -must be set. - -<table class="borderless-table fixed-table"> -<tr> - <td> - <ul> - <li>Content</li> - <ul> - <li>Title</li> - <li>Description and tasks</li> - <li>Comments and other activity</li> - </ul> - <li>People</li> - <ul> - <li>Author</li> - <li>Assignee(s)</li> - </ul> - <li>State</li> - <ul> - <li>State (open or closed)</li> - <li>Health status (on track, needs attention, or at risk)</li> - <li>Confidentiality</li> - <li>Tasks (completed vs. outstanding)</li> - </ul> - </ul> - </td> - <td> - <ul> - <li>Planning and tracking</li> - <ul> - <li>Milestone</li> - <li>Due date</li> - <li>Weight</li> - <li>Time tracking</li> - <li>Labels</li> - <li>Votes</li> - <li>Reaction emoji</li> - <li>Linked issues</li> - <li>Assigned epic</li> - <li>Unique issue number and URL</li> - </ul> - </ul> - </td> -</tr> -</table> - -## Viewing and managing issues - -While you can view and manage details of an issue on the [issue page](#issue-page), -you can also work with multiple issues at a time using: - -- [Issues List](#issues-list). -- [Issue Boards](#issue-boards). -- Issue references. -- [Epics](#epics) **(PREMIUM)**. +Issues have a flexible content and metadata structure. Here are some of the +elements you can provide in an issue: + +- Title +- Description and tasks +- Comments and other activity +- Author +- Assignees +- State (open or closed) +- Health status (on track, needs attention, or at risk) +- Confidentiality +- Tasks (completed vs. outstanding) +- Milestone +- Due date +- Weight +- Time tracking +- Labels +- Votes +- Reaction emoji +- Linked issues +- Assigned epic +- Unique issue number and URL + +## View and manage issues Key actions for issues include: @@ -105,7 +66,17 @@ Key actions for issues include: - [Moving issues](managing_issues.md#moving-issues) - [Closing issues](managing_issues.md#closing-issues) - [Deleting issues](managing_issues.md#deleting-issues) -- [Promoting issues](managing_issues.md#promote-an-issue-to-an-epic) **(PREMIUM)** +- [Promoting issues](managing_issues.md#promote-an-issue-to-an-epic) + +Although you can view and manage details of an issue on the [issue page](#issue-page), +you can also work with several issues at a time by using these features: + +- [Issues List](#issues-list): View a list of issues in a project or group. +- [Issue Boards](../issue_board.md): Organize issues with a project management + workflow for a feature or product release. +- Issue references +- [Epics](../../group/epics/index.md): Manage your portfolio of projects by + tracking groups of issues with a shared theme. ### Issue page @@ -114,18 +85,18 @@ Key actions for issues include: On an issue's page, you can view [all aspects of the issue](issue_data_and_actions.md), and modify them if you have the necessary [permissions](../../permissions.md). -#### Real-time sidebar **(CORE ONLY)** +#### Real-time sidebar **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. 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). +To enable it, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). ### Issues List  -On the Issues List, you can: +In the Issues List, you can: - View all issues in a project when opening the Issues List from a project context. - View all issues in a groups's projects when opening the Issues List from a group context. @@ -137,20 +108,22 @@ view, you can also make certain changes [in bulk](../bulk_editing.md) to the dis For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page for a rundown of all the fields and information in an issue. -You can sort a list of issues in several ways, for example by issue creation date, milestone due date. For more information, see the [Sorting and Ordering Issue Lists](sorting_issue_lists.md) page. +You can sort a list of issues in several ways, for example by issue creation date, milestone due date. +For more information, see the [Sorting and ordering issue lists](sorting_issue_lists.md) page. -### Issue boards +#### Cached issue count - +> - [Introduced]([link-to-issue](https://gitlab.com/gitlab-org/gitlab/-/issues/243753)) in GitLab 13.9. +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use this feature in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cached-issue-count) **(FREE SELF)** -[Issue boards](../issue_board.md) are Kanban boards with columns that display issues based on their -labels or their assignees**(PREMIUM)**. They offer the flexibility to manage issues using -highly customizable workflows. +WARNING: +This feature might not be available to you. Check the **version history** note above for details. -You can reorder issues in the column. If you drag an issue card to another column, its -associated label or assignee is changed to match that of the new column. The entire -board can also be filtered to only include issues from a certain milestone or an overarching -label. +In a group, the sidebar displays the total count of open issues and this value is cached if higher +than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. ### Design Management @@ -158,12 +131,6 @@ With [Design Management](design_management.md), you can upload design assets to issues and view them all together for sharing and collaboration with your team. -### Epics **(PREMIUM)** - -[Epics](../../group/epics/index.md) let you manage your portfolio of projects more -efficiently and with less effort. Epics track groups of issues that share a theme, across -projects and milestones. - ### Related issues You can mark two issues as related, so that when viewing one, the other is always @@ -226,3 +193,22 @@ You can then see issue statuses in the [issue list](#issues-list) and the - [Issues API](../../../api/issues.md) - Configure an [external issue tracker](../../../integration/external-issue-tracker.md) such as Jira, Redmine, Bugzilla, or EWM. + +## Enable or disable cached issue count **(FREE SELF)** + +Cached issue count in the left sidebar 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(:cached_sidebar_open_issues_count) +``` + +To disable it: + +```ruby +Feature.disable(:cached_sidebar_open_issues_count) +``` diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 4c8630581f5..5218bb57bca 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -129,7 +129,7 @@ element. Due dates can be changed as many times as needed. ### Labels Categorize issues by giving them [labels](../labels.md). They help to organize workflows, -and they enable you to work with the [GitLab Issue Board](index.md#issue-boards). +and they enable you to work with the [GitLab Issue Board](../issue_board.md). Group Labels, which allow you to use the same labels for all projects in the same group, can also be given to issues. They work exactly the same, but are immediately @@ -291,7 +291,7 @@ supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-g After you write a comment, you can: -- Click **Comment** and to publish your comment. +- Click **Comment** to publish your comment. - Choose **Start thread** from the dropdown list and start a new [thread](../../discussions/index.md#threaded-discussions) in that issue's main thread to discuss specific points. This invites other participants to reply directly to your thread, keeping related comments grouped together. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index ef860df054e..7ca0556dff4 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -270,7 +270,7 @@ closed issues remain as-is. Disabling automatic issue closing only affects merge requests *in* the project and does not prevent other projects from closing it via cross-project issues. -#### Customizing the issue closing pattern **(CORE ONLY)** +#### Customizing the issue closing pattern **(FREE SELF)** In order to change the default issue closing pattern, GitLab administrators must edit the [`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) diff --git a/doc/user/project/issues/moving_issues.md b/doc/user/project/issues/moving_issues.md deleted file mode 100644 index 3b40affcdc3..00000000000 --- a/doc/user/project/issues/moving_issues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#moving-issues' ---- - -This document was moved to [another location](managing_issues.md#moving-issues). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 82b2d4fde52..91c26d49532 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -4,10 +4,10 @@ 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/#assignments --- -# Related issues **(CORE)** +# Related issues **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1797) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.4. -> - The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4. +> - The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.4. Related issues are a bi-directional relationship between any two issues and appear in a block below the issue description. Issues can be across groups diff --git a/doc/user/project/issues/similar_issues.md b/doc/user/project/issues/similar_issues.md deleted file mode 100644 index 79a50d5f812..00000000000 --- a/doc/user/project/issues/similar_issues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'index.md#similar-issues' ---- - -This document was moved to [another location](index.md#similar-issues). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index b4cb1c383ba..3a393b18579 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Sorting and ordering issue lists **(CORE)** +# Sorting and ordering issue lists **(FREE)** You can sort a list of issues several ways, including by: diff --git a/doc/user/project/maven_packages.md b/doc/user/project/maven_packages.md deleted file mode 100644 index 5bfa08de2ed..00000000000 --- a/doc/user/project/maven_packages.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../packages/maven_repository/index.md' ---- - -This document was moved to [another location](../packages/maven_repository/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/members/img/access_requests_management_13_8.png b/doc/user/project/members/img/access_requests_management_13_8.png Binary files differdeleted file mode 100644 index 950ef4dec01..00000000000 --- a/doc/user/project/members/img/access_requests_management_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/access_requests_management_v13_9.png b/doc/user/project/members/img/access_requests_management_v13_9.png Binary files differnew file mode 100644 index 00000000000..b7883e9d134 --- /dev/null +++ b/doc/user/project/members/img/access_requests_management_v13_9.png diff --git a/doc/user/project/members/img/add_user_email_accept_13_8.png b/doc/user/project/members/img/add_user_email_accept_13_8.png Binary files differdeleted file mode 100644 index ed980036af5..00000000000 --- a/doc/user/project/members/img/add_user_email_accept_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_email_accept_v13_9.png b/doc/user/project/members/img/add_user_email_accept_v13_9.png Binary files differnew file mode 100644 index 00000000000..a6b303e05ca --- /dev/null +++ b/doc/user/project/members/img/add_user_email_accept_v13_9.png diff --git a/doc/user/project/members/img/add_user_email_ready_13_8.png b/doc/user/project/members/img/add_user_email_ready_v13_8.png Binary files differindex a610b46a176..a610b46a176 100644 --- a/doc/user/project/members/img/add_user_email_ready_13_8.png +++ b/doc/user/project/members/img/add_user_email_ready_v13_8.png diff --git a/doc/user/project/members/img/add_user_email_search_13_8.png b/doc/user/project/members/img/add_user_email_search_v13_8.png Binary files differindex 934cf19bd3d..934cf19bd3d 100644 --- a/doc/user/project/members/img/add_user_email_search_13_8.png +++ b/doc/user/project/members/img/add_user_email_search_v13_8.png diff --git a/doc/user/project/members/img/add_user_give_permissions_13_8.png b/doc/user/project/members/img/add_user_give_permissions_v13_8.png Binary files differindex 1916d056a52..1916d056a52 100644 --- a/doc/user/project/members/img/add_user_give_permissions_13_8.png +++ b/doc/user/project/members/img/add_user_give_permissions_v13_8.png diff --git a/doc/user/project/members/img/add_user_import_members_from_another_project_13_8.png b/doc/user/project/members/img/add_user_import_members_from_another_project_v13_8.png Binary files differindex a6dddec3fb7..a6dddec3fb7 100644 --- a/doc/user/project/members/img/add_user_import_members_from_another_project_13_8.png +++ b/doc/user/project/members/img/add_user_import_members_from_another_project_v13_8.png diff --git a/doc/user/project/members/img/add_user_imported_members_13_8.png b/doc/user/project/members/img/add_user_imported_members_13_8.png Binary files differdeleted file mode 100644 index 725e447604f..00000000000 --- a/doc/user/project/members/img/add_user_imported_members_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_imported_members_v13_9.png b/doc/user/project/members/img/add_user_imported_members_v13_9.png Binary files differnew file mode 100644 index 00000000000..e40240df2b2 --- /dev/null +++ b/doc/user/project/members/img/add_user_imported_members_v13_9.png diff --git a/doc/user/project/members/img/add_user_list_members_13_8.png b/doc/user/project/members/img/add_user_list_members_13_8.png Binary files differdeleted file mode 100644 index b8c0160c6d8..00000000000 --- a/doc/user/project/members/img/add_user_list_members_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_list_members_v13_9.png b/doc/user/project/members/img/add_user_list_members_v13_9.png Binary files differnew file mode 100644 index 00000000000..7a07ea01d14 --- /dev/null +++ b/doc/user/project/members/img/add_user_list_members_v13_9.png diff --git a/doc/user/project/members/img/add_user_search_people_13_8.png b/doc/user/project/members/img/add_user_search_people_v13_8.png Binary files differindex e9aa58512ab..e9aa58512ab 100644 --- a/doc/user/project/members/img/add_user_search_people_13_8.png +++ b/doc/user/project/members/img/add_user_search_people_v13_8.png diff --git a/doc/user/project/members/img/project_groups_tab_13_8.png b/doc/user/project/members/img/project_groups_tab_13_8.png Binary files differdeleted file mode 100644 index 5d7948f0761..00000000000 --- a/doc/user/project/members/img/project_groups_tab_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/project_groups_tab_v13_9.png b/doc/user/project/members/img/project_groups_tab_v13_9.png Binary files differnew file mode 100644 index 00000000000..d1b6a640341 --- /dev/null +++ b/doc/user/project/members/img/project_groups_tab_v13_9.png diff --git a/doc/user/project/members/img/project_members_13_8.png b/doc/user/project/members/img/project_members_13_8.png Binary files differdeleted file mode 100644 index 9120d471b3b..00000000000 --- a/doc/user/project/members/img/project_members_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_filter_direct_v13_9.png b/doc/user/project/members/img/project_members_filter_direct_v13_9.png Binary files differnew file mode 100644 index 00000000000..50115ee4052 --- /dev/null +++ b/doc/user/project/members/img/project_members_filter_direct_v13_9.png diff --git a/doc/user/project/members/img/project_members_filter_inherited_v13_9.png b/doc/user/project/members/img/project_members_filter_inherited_v13_9.png Binary files differnew file mode 100644 index 00000000000..433003fe58b --- /dev/null +++ b/doc/user/project/members/img/project_members_filter_inherited_v13_9.png diff --git a/doc/user/project/members/img/project_members_search_v13_9.png b/doc/user/project/members/img/project_members_search_v13_9.png Binary files differnew file mode 100644 index 00000000000..67280d11dca --- /dev/null +++ b/doc/user/project/members/img/project_members_search_v13_9.png diff --git a/doc/user/project/members/img/project_members_sort_v13_9.png b/doc/user/project/members/img/project_members_sort_v13_9.png Binary files differnew file mode 100644 index 00000000000..47abe18ba49 --- /dev/null +++ b/doc/user/project/members/img/project_members_sort_v13_9.png diff --git a/doc/user/project/members/img/project_members_v13_9.png b/doc/user/project/members/img/project_members_v13_9.png Binary files differnew file mode 100644 index 00000000000..3b48c752c6a --- /dev/null +++ b/doc/user/project/members/img/project_members_v13_9.png diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_8.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_8.png Binary files differdeleted file mode 100644 index 6cbbb386396..00000000000 --- a/doc/user/project/members/img/share_project_with_groups_tab_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png Binary files differnew file mode 100644 index 00000000000..99be996c03e --- /dev/null +++ b/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index cccb998fc31..00474098487 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -21,42 +21,74 @@ project's **Members**. When your project belongs to the group, group members inherit the membership and permission level for the project from the group. - + From the image above, we can deduce the following things: - There are 3 members that have access to the project. - User0 is a Reporter and has inherited their permissions from group `demo` which contains current project. -- For User1 there is no indication of a group, therefore they belong directly +- User1 is shown as a **Direct member** in the **Source** column, therefore they belong directly to the project we're inspecting. - Administrator is the Owner and member of **all** groups and for that reason, there is an indication of an ancestor group and inherited Owner permissions. -[From GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/21727), you can filter this list -using the dropdown on the right side: +## Filter and sort members - +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. +> - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/4901) in GitLab 13.9. +> - Improvements are [deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - Improvements are enabled on GitLab.com. +> - Improvements are recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable improvements](#enable-or-disable-improvements-to-project-member-management). **(FREE SELF)** -- **Show only direct members** displays only User1. -- **Show only inherited members** displays User0 and Administrator. +The following sections illustrate how you can filter and sort members in a project. To view these options, +navigate to your desired project, go to **Members**, and include the noted search terms. + +### Membership filter + +By default, inherited and direct members are displayed. The membership filter can be used to display only inherited or only direct members. + +#### Display inherited members + +To display inherited members, include `Membership` `=` `Inherited` in the search text box. + + + +#### Display direct members + +To display direct members, include `Membership` `=` `Direct` in the search text box. + + + +### Search + +You can search for members by name, username, or email. + + + +### Sort + +You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in** in ascending or descending order. + + ## Add a user Right next to **People**, start typing the name or username of the user you want to add. - + Select the user and the [permission level](../../permissions.md) that you'd like to give the user. Note that you can select more than one user. - + Once done, select **Add users to project** and they are immediately added to your project with the permissions you gave them above. - + From there on, you can either remove an existing user or change their access level to the project. @@ -68,14 +100,14 @@ You can import another project's users in your own project by hitting the In the dropdown menu, you can see only the projects you are Maintainer on. - + Select the one you want and hit **Import project members**. A flash message displays, notifying you that the import was successful, and the new members are now in the project's members list. Notice that the permissions that they had on the project you imported from are retained. - + ## Invite people using their e-mail address @@ -83,18 +115,18 @@ If a user you want to give access to doesn't have an account on your GitLab instance, you can invite them just by typing their e-mail address in the user search field. - + As you can imagine, you can mix inviting multiple people and adding existing GitLab users to the project. - + Once done, hit **Add users to project** and watch that there is a new member with the e-mail address we used above. From there on, you can resend the invitation, change their access level, or even delete them. - + While unaccepted, the system automatically sends reminder emails on the second, fifth, and tenth day after the invitation was initially sent. @@ -130,7 +162,7 @@ NOTE: If a project does not have any maintainers, the notification is sent to the most recently active owners of the project's group. - + If you change your mind before your request is approved, just click the **Withdraw Access Request** button. @@ -167,3 +199,27 @@ To remove a member from a project: A **Remove member** modal appears. 1. (Optional) Select the **Also unassign this user from related issues and merge requests** checkbox. 1. Click **Remove member**. + +## Enable or disable improvements to project member management **(FREE SELF)** + +Project member management improvements are 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 the improvements. + +To disable them: + +```ruby +# For the instance +Feature.disable(:vue_project_members_list) +# For a single project +Feature.disable(:vue_project_members_list, Project.find(<project id>)) +``` + +To enable them: + +```ruby +# For the instance +Feature.enable(:vue_project_members_list) +# For a single project +Feature.enable(:vue_project_members_list, Project.find(<project id>)) +``` diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index d17717fb29c..7000988d9bf 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -26,7 +26,7 @@ To share 'Project Acme' with the 'Engineering' group: 1. For 'Project Acme' use the left navigation menu to go to **Members**. -  +  1. Select the **Invite group** tab. 1. Add the 'Engineering' group with the maximum access level of your choice. @@ -35,7 +35,7 @@ To share 'Project Acme' with the 'Engineering' group: 1. After sharing 'Project Acme' with 'Engineering': - The group is listed in the **Groups** tab. -  +  - The project is listed on the group dashboard. diff --git a/doc/user/project/merge_requests.md b/doc/user/project/merge_requests.md deleted file mode 100644 index 5762177882e..00000000000 --- a/doc/user/project/merge_requests.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'merge_requests/index.md' ---- - -This document was moved to [merge_requests/index.md](merge_requests/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 8adaae3b2ef..89fbc4cd89e 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -23,7 +23,7 @@ of the merge request. ## Enabling commit edits from upstream members -From [GitLab 13.7 onwards](https://gitlab.com/gitlab-org/gitlab/-/issues/23308), +In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308), this setting is enabled by default. It can be changed by users with Developer permissions to the source project. Once enabled, upstream members will also be able to retry the pipelines and jobs of the merge request: diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 4e87876b036..36fb5cea4b0 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -13,12 +13,13 @@ with introducing a **Cherry-pick** button in merge requests and commit details. ## Cherry-picking a merge request -After the merge request has been merged, a **Cherry-pick** button will be available +After the merge request has been merged, a **Cherry-pick** button displays to cherry-pick the changes introduced by that merge request.  -After you click that button, a modal will appear showing a [branch filter search box](../repository/branches/index.md#branch-filter-search-box) +After you click that button, a modal displays a +[branch filter search box](../repository/branches/index.md#branch-filter-search-box) where you can choose to either: - Cherry-pick the changes directly into the selected branch. @@ -28,12 +29,12 @@ where you can choose to either: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2675) in GitLab 12.9. -When you cherry-pick a merge commit, GitLab will output a system note to the related merge -request thread crosslinking the new commit and the existing merge request. +When you cherry-pick a merge commit, GitLab displays a system note to the related merge +request thread. It crosslinks the new commit and the existing merge request.  -Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) will include cherry-picked merge commits. +Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. NOTE: We only track cherry-pick executed from GitLab (both UI and API). Support for [tracking cherry-picked commits through the command line](https://gitlab.com/gitlab-org/gitlab/-/issues/202215) is planned for a future release. @@ -44,15 +45,15 @@ You can cherry-pick a commit from the commit details page:  -Similar to cherry-picking a merge request, you can opt to cherry-pick the changes +Similar to cherry-picking a merge request, you can cherry-pick the changes directly into the target branch or create a new merge request to cherry-pick the changes. -Please note that when cherry-picking merge commits, the mainline will always be the -first parent. If you want to use a different mainline then you need to do that +When cherry-picking merge commits, the mainline is always the +first parent. If you want to use a different mainline, you need to do that from the command line. -Here is a quick example to cherry-pick a merge commit using the second parent as the +Here's a quick example to cherry-pick a merge commit using the second parent as the mainline: ```shell diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index ca15ec154fc..0fb53884ea2 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -5,9 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Code Quality +# Code Quality **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. Ensuring your project's code stays simple, readable and easy to contribute to can be problematic. With the help of [GitLab CI/CD](../../../ci/README.md), you can analyze your @@ -28,7 +28,7 @@ Code Quality: ## Code Quality Widget -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. Going a step further, GitLab can show the Code Quality report right @@ -75,7 +75,7 @@ GitLab 11.4 or earlier, you can view the deprecated job definitions in the - Using shared runners, the job should be configured For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). - Using private runners, there is an [alternative configuration](#set-up-a-private-runner-for-code-quality-without-docker-in-docker) recommended for running CodeQuality analysis more efficiently. -In either configuration, the runner mmust have 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. +In either configuration, the runner must have 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 GitLab Runner, include the Code Quality template in your CI configuration: @@ -219,8 +219,8 @@ The end result is that: - Docker images, including all CodeClimate images, are cached, and not re-fetched for subsequent jobs. With this configuration, the run time for a second pipeline is much shorter. For example -this [small change](https://gitlab.com/drewcimino/test-code-quality-template/-/merge_requests/4/diffs?commit_id=1e705607aef7236c1b20bb6f637965f3f3e53a46) -to an [open merge request](https://gitlab.com/drewcimino/test-code-quality-template/-/merge_requests/4/pipelines) +this [small change](https://gitlab.com/drew/test-code-quality-template/-/merge_requests/4/diffs?commit_id=1e705607aef7236c1b20bb6f637965f3f3e53a46) +to an [open merge request](https://gitlab.com/drew/test-code-quality-template/-/merge_requests/4/pipelines) running Code Quality analysis ran significantly faster the second time:  @@ -358,7 +358,7 @@ After the Code Quality job completes: [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts) for the `code_quality` job. - The full list of code quality violations generated by a pipeline is shown in the - Code Quality tab of the Pipeline Details page. **(STARTER)** + Code Quality tab of the Pipeline Details page. **(PREMIUM)** ### Generating an HTML report @@ -411,7 +411,7 @@ plugins: enabled: true ``` -This adds SonarJava to the `plugins:` section of the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml) +This adds SonarJava to the `plugins:` section of the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) included in your project. Changes to the `plugins:` section do not affect the `exclude_patterns` section of the @@ -428,7 +428,7 @@ Here's [an example project](https://gitlab.com/jheimbuck_gl/jh_java_example_proj A common issue is that the terms `Code Quality` (GitLab specific) and `Code Climate` (Engine used by GitLab) are very similar. You must add a **`.codeclimate.yml`** file to change the default configuration, **not** a `.codequality.yml` file. If you use -the wrong filename, the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml) +the wrong filename, the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) is still used. ### No Code Quality report is displayed in a Merge Request @@ -444,15 +444,15 @@ This can be due to multiple reasons: - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifact(s) to expire faster than desired. - If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. -- Large `codeclimate.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). +- Large `gl-code-quality-report.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). As a work-around, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) that are [ignored by GitLab](#implementing-a-custom-tool). You can: - Configure the Code Quality tool to not output those types. - Use `sed`, `awk` or similar commands in the `.gitlab-ci.yml` script to - edit the `codeclimate.json` before the job completes. + edit the `gl-code-quality-report.json` before the job completes. ### Only a single Code Quality report is displayed, but more are defined GitLab only uses the Code Quality artifact from the latest created job (with the largest job ID). If multiple jobs in a pipeline generate a code quality artifact, those of earlier jobs are ignored. -To avoid confusion, configure only one job to generate a `codeclimate.json`. +To avoid confusion, configure only one job to generate a `gl-code-quality-report.json`. diff --git a/doc/user/project/merge_requests/code_quality_diff.md b/doc/user/project/merge_requests/code_quality_diff.md deleted file mode 100644 index 2b7b2574ef7..00000000000 --- a/doc/user/project/merge_requests/code_quality_diff.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'code_quality.md' ---- - -This document was moved to [another location](code_quality.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/container_scanning.md b/doc/user/project/merge_requests/container_scanning.md deleted file mode 100644 index 5d61f2b36e8..00000000000 --- a/doc/user/project/merge_requests/container_scanning.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/container_scanning/index.md' ---- - -This document was moved to [another location](../../application_security/container_scanning/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 5adc4ab6b6e..e5d3954cb41 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -178,7 +178,7 @@ fork from its upstream project in the **Settings > Advanced Settings** section b For further details, [see the forking workflow documentation](../repository/forking_workflow.md). -## New merge request by email **(CORE ONLY)** +## New merge request by email **(FREE SELF)** _This feature needs [incoming email](../../../administration/incoming_email.md) to be configured by a GitLab administrator to be available._ It isn't diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 0de9f246ceb..f4843b96c99 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Export Merge Requests to CSV **(CORE)** +# Export Merge Requests to CSV **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3619) in GitLab 13.6. diff --git a/doc/user/project/merge_requests/dast.md b/doc/user/project/merge_requests/dast.md deleted file mode 100644 index 37c0d5b4e37..00000000000 --- a/doc/user/project/merge_requests/dast.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/dast/index.md' ---- - -This document was moved to [another location](../../application_security/dast/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/dependency_scanning.md b/doc/user/project/merge_requests/dependency_scanning.md deleted file mode 100644 index dd5910121ed..00000000000 --- a/doc/user/project/merge_requests/dependency_scanning.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/dependency_scanning/index.md' ---- - -This document was moved to [another location](../../application_security/dependency_scanning/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index dc5e1f81a63..5be277c2f29 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -53,10 +53,10 @@ 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). +- [Assign](#assignee) the merge request to a colleague for review. With [multiple assignees](#multiple-assignees), you can assign it to more than one person at a time. - 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)** +- Require [approval](merge_request_approvals.md) from your team. **(PREMIUM)** - [Close issues automatically](#merge-requests-to-close-issues) when they are merged. - Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option to keep your repository clean. - Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. @@ -87,9 +87,10 @@ Open the drop down box to search for the user you wish to assign, and the merge request will be added to their [assigned merge request list](../../search/index.md#issues-and-merge-requests). -#### Multiple assignees **(STARTER)** +#### Multiple assignees **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2004) in [GitLab Starter 11.11](https://about.gitlab.com/pricing/). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2004) in GitLab 11.11. +> - Moved to GitLab Premium in 13.9 Multiple people often review merge requests at the same time. GitLab allows you to have multiple assignees for merge requests @@ -119,7 +120,7 @@ It is also possible to manage multiple assignees: > - It's enabled on GitLab.com. > - It's recommended for production use. > - It can be enabled or disabled for a single project. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-merge-request-reviewers). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-merge-request-reviewers). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -136,7 +137,7 @@ This makes it easy to determine the relevant roles for the users involved in the To request it, open the **Reviewers** drop-down box to search for the user you wish to get a review from. -#### Enable or disable Merge Request Reviewers **(CORE ONLY)** +#### Enable or disable Merge Request Reviewers **(FREE SELF)** Merge Request Reviewers is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. @@ -161,23 +162,23 @@ Feature.disable(:merge_request_reviewers) Feature.disable(:merge_request_reviewers, Project.find(<project id>)) ``` -#### Approval Rule information for Reviewers **(STARTER)** +#### Approval Rule information for Reviewers **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. +> - Moved to GitLab Premium in 13.9. > - It was [deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51183) in GitLab 13.8. > - It's enabled on GitLab.com. > - It's recommended for production use. > - It can be enabled or disabled for a single project. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-approval-rule-information-for-reviewers). **(STARTER ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-approval-rule-information-for-reviewers). **(PREMIUM SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. When editing the **Reviewers** field in a new or existing merge request, GitLab displays the name of the matching [approval rule](merge_request_approvals.md#approval-rules) -below the name of each suggested reviewer. [Code Owners](../code_owners.md) are displayed as **Code Owner** without group detail. -We intend to iterate on this feature in future releases. +below the name of each suggested reviewer. [Code Owners](../code_owners.md) are displayed as `Codeowner` without group detail. This example shows reviewers and approval rules when creating a new merge request: @@ -187,7 +188,7 @@ This example shows reviewers and approval rules in a merge request sidebar:  -##### Enable or disable Approval Rule information for Reviewers **(STARTER ONLY)** +##### Enable or disable Approval Rule information for Reviewers **(PREMIUM SELF)** Merge Request Reviewers is under development and ready for production use. It is deployed behind a feature flag that is **enabled by default**. diff --git a/doc/user/project/merge_requests/license_management.md b/doc/user/project/merge_requests/license_management.md deleted file mode 100644 index 4c598d851a9..00000000000 --- a/doc/user/project/merge_requests/license_management.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../compliance/license_compliance/index.md' ---- - -This document was moved to [another location](../../compliance/license_compliance/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/maintainer_access.md b/doc/user/project/merge_requests/maintainer_access.md deleted file mode 100644 index 29afff289fd..00000000000 --- a/doc/user/project/merge_requests/maintainer_access.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'allow_collaboration.md' ---- - -This document was moved to [another location](allow_collaboration.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 887f563be51..36f5c5aed5f 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -5,27 +5,28 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge Request Approvals **(CORE)** +# Merge Request Approvals **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580) in GitLab Enterprise Edition 7.2. Available in GitLab Core and higher tiers. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580) in GitLab Enterprise Edition 7.2. Available in GitLab Free and higher tiers. > - Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. -Code review is an essential practice of every successful project, and giving your -approval once a merge request is in good shape is an important part of the review +Code review is an essential practice of every successful project. Approving a +merge request is an important part of the review process, as it clearly communicates the ability to merge the change. ## Optional Approvals > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. -Any user with Developer or greater [permissions](../../permissions.md) can approve a merge request in GitLab Core and higher tiers. -This provides a consistent mechanism for reviewers to approve merge requests, and makes it easy for -maintainers to know when a change is ready to merge. Approvals in Core are optional and do +Any user with Developer or greater [permissions](../../permissions.md) can approve a merge request in GitLab Free and higher tiers. +This provides a consistent mechanism for reviewers to approve merge requests, and ensures +maintainers know a change is ready to merge. Approvals in Free are optional, and do not prevent a merge request from being merged when there is no approval. -## Required Approvals **(STARTER)** +## Required Approvals **(PREMIUM)** -> [Introduced](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only) in GitLab Enterprise Edition 7.12. Available in [GitLab Starter](https://about.gitlab.com/pricing/) and higher tiers. +> - [Introduced](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only) in GitLab Enterprise Edition 7.12. +> - Moved to GitLab Premium in 13.9. Required approvals enable enforced code review by requiring specified people to approve a merge request before it can be merged. @@ -50,13 +51,12 @@ be merged, and optionally which users should do the approving. Approvals can be - [As project defaults](#adding--editing-a-default-approval-rule). - [Per merge request](#editing--overriding-approval-rules-per-merge-request). -If no approval rules are defined, any user can approve a merge request, though the default -minimum number of required approvers can still be set in the [project settings for merge request approvals](#merge-request-approvals-project-settings). +If no approval rules are defined, any user can approve a merge request. However, the default +minimum number of required approvers can still be set in the +[project settings for merge request approvals](#merge-request-approvals-project-settings). 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) are available in -[GitLab Premium](https://about.gitlab.com/pricing/) and above. +or choose more than one with [multiple approval rules](#multiple-approval-rules). NOTE: On GitLab.com, you can add a group as an approver if you're a member of that group or the @@ -64,7 +64,7 @@ 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. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 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: @@ -83,29 +83,31 @@ A group of users can also be added as approvers. In the future, group approvers [restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). If a user is added as an individual approver and is also part of a group approver, -then that user is just counted once. The merge request author, as well as users who have committed +then that user is just counted once. The merge request author, and users who have committed to the merge request, do not count as eligible approvers, if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) (enabled by default) and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default) are enabled on the project settings. -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. +When an eligible approver comments on a merge request, it displays in the +**Commented by** column of the Approvals widget. It indicates who participated in +the merge request review. Authors and reviewers can also identify who they should reach out +to if they have any questions about the content of the merge request. ##### Implicit Approvers If the number of required approvals is greater than the number of assigned approvers, -approvals from other users will count towards meeting the requirement. These would be +approvals from other users counts towards meeting the requirement. These would be users with developer [permissions](../../permissions.md) or higher in the project who were not explicitly listed in the approval rules. ##### Code Owners as eligible approvers -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. +> - Moved to GitLab Premium in 13.9. If you add [Code Owners](../code_owners.md) to your repository, the owners to the -corresponding files will become eligible approvers, together with members with Developer +corresponding files become eligible approvers, together with members with Developer or higher [permissions](../../permissions.md). To enable this merge request approval rule: @@ -117,7 +119,7 @@ To enable this merge request approval rule:  Once set, merge requests can only be merged once approved by the -number of approvals you've set. GitLab will accept approvals from +number of approvals you've set. GitLab accepts approvals from users with Developer or higher permissions, as well as by Code Owners, indistinguishably. @@ -126,7 +128,8 @@ Alternatively, you can **require** #### 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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. +> - Moved to Premium in 13.9. Managers or operators with [Reporter permissions](../../permissions.md#project-members-permissions) to a project sometimes need to be required approvers of a merge request, @@ -156,27 +159,27 @@ To add or edit the default merge request approval rule: 1. Click **Add approval rule**, or **Edit**. - Add or change the **Rule name**. - Set the number of required approvals in **Approvals required**. The minimum value is `0`. - - (Optional) Search for users or groups that will be [eligible to approve](#eligible-approvers) + - (Optional) Search for users or groups that are [eligible to approve](#eligible-approvers) merge requests and click the **Add** button to add them as approvers. Before typing - in the search field, approvers will be suggested based on the previous authors of + in the search field, approvers are suggested based on the previous authors of the files being changed by the merge request. - (Optional) Click the **{remove}** **Remove** button next to a group or user to delete it from the rule. 1. Click **Add approval rule** or **Update approval rule**. When [approval rule overrides](#prevent-overriding-default-approvals) are allowed, -changes to these default rules will **not** be applied to existing merge +changes to these default rules are not applied to existing merge requests, except for changes to the [target branch](#scoped-to-protected-branch) of the rule. When approval rule overrides are not allowed, all changes to these default rules -will be applied to existing merge requests. Any approval rules that had previously been +are applied to existing merge requests. Any approval rules that had previously been manually [overridden](#editing--overriding-approval-rules-per-merge-request) during a -period when approval rule overrides where allowed, will not be modified. +period when approval rule overrides where allowed, are not modified. NOTE: If a merge request targets a different project, such as from a fork to the upstream project, -the default approval rules will be taken from the target (upstream) project, not the +the default approval rules are taken from the target (upstream) project, not the source (fork). ##### Editing / overriding approval rules per merge request @@ -195,8 +198,8 @@ the same steps as [Adding / editing a default approval rule](#adding--editing-a- #### Set up an optional approval rule -MR approvals can be configured to be optional. -This can be useful if you're working on a team where approvals are appreciated, but not required. +MR approvals can be configured to be optional, which can help if you're working +on a team where approvals are appreciated, but not required. To configure an approval to be optional, set the number of required approvals in **Approvals required** to `0`. @@ -211,16 +214,16 @@ as well as multiple default approval rules per project. Adding or editing multiple default rules is identical to [adding or editing a single default approval rule](#adding--editing-a-default-approval-rule), -except the **Add approval rule** button will be available to add more rules, even after +except the **Add approval rule** button is available to add more rules, even after a rule is already defined. Similarly, editing or overriding multiple approval rules per merge request is identical to [editing or overriding approval rules per merge request](#editing--overriding-approval-rules-per-merge-request), -except the **Add approval rule** button will be available to add more rules, even after +except the **Add approval rule** button is available to add more rules, even after a rule is already defined. -When an [eligible approver](#eligible-approvers) approves a merge request, it will -reduce the number of approvals left for all rules that the approver belongs to. +When an [eligible approver](#eligible-approvers) approves a merge request, it +reduces the number of approvals left for all rules that the approver belongs to.  @@ -269,7 +272,7 @@ The merge request author is not allowed to approve their own merge request if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) is enabled in the project settings. -Once the approval rules have been met, the merge request can be merged if there is nothing +After the approval rules have been met, the merge request can be merged if there is nothing else blocking it. Note that the merge request could still be blocked by other conditions, such as merge conflicts, [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). @@ -291,7 +294,7 @@ To prevent that from happening: #### Resetting approvals on push You can force all approvals on a merge request to be removed when new commits are -pushed to the source branch of the merge request. If disabled, approvals will persist +pushed to the source branch of the merge request. If disabled, approvals persist even if there are changes added to the merge request. To enable this feature: 1. Check the **Require new approvals when new commits are added to an MR.** @@ -300,11 +303,12 @@ even if there are changes added to the merge request. To enable this feature: NOTE: Approvals do not get reset when [rebasing a merge request](fast_forward_merge.md) -from the UI. However, approvals will be reset if the target branch is changed. +from the UI. However, approvals are reset if the target branch is changed. -#### Allowing merge request authors to approve their own merge requests +#### Allowing merge request authors to approve their own merge requests **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. +> - Moved to GitLab Premium in 13.9. By default, projects are configured to prevent merge requests from being approved by their own authors. To change this setting: @@ -315,9 +319,10 @@ their own authors. To change this setting: 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 +#### Prevent approval of merge requests by their committers **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. +> - Moved to GitLab Premium in 13.9. You can prevent users that have committed to a merge request from approving it. To enable this feature: @@ -327,12 +332,13 @@ enable this feature: #### Require authentication when approving a merge request -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0. +> - Moved to GitLab Premium in 13.9. NOTE: To require authentication when approving a merge request, you must enable **Password authentication enabled for web interface** under [sign-in restrictions](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). -in the Admin area. +in the Admin Area. You can force the approver to enter a password in order to authenticate before adding the approval. This enables an Electronic Signature for approvals such as the one defined diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 4a596ed6139..646d77391a3 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -17,7 +17,7 @@ then it cannot be merged until its dependency is itself merged. NOTE: Merge requests dependencies are a **PREMIUM** feature, but this restriction is -only enforced for the dependent merge request. A merge request in a **CORE** or +only enforced for the dependent merge request. A merge request in a **FREE** or **STARTER** project can be a dependency of a **PREMIUM** merge request, but not vice-versa. diff --git a/doc/user/project/merge_requests/merge_request_discussion_resolution.md b/doc/user/project/merge_requests/merge_request_discussion_resolution.md deleted file mode 100644 index f8d15f31875..00000000000 --- a/doc/user/project/merge_requests/merge_request_discussion_resolution.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../discussions/index.md' ---- - -This document was moved to [another location](../../discussions/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_when_build_succeeds.md b/doc/user/project/merge_requests/merge_when_build_succeeds.md deleted file mode 100644 index 48d32d2882f..00000000000 --- a/doc/user/project/merge_requests/merge_when_build_succeeds.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -redirect_to: 'merge_when_pipeline_succeeds.md' ---- - -This document was moved to [merge_when_pipeline_succeeds](merge_when_pipeline_succeeds.md). - ->[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7135) by the "Rename MWBS service to Merge When Pipeline Succeeds" change. - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index b813e4f7d28..5efb8d9ff40 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -42,8 +42,12 @@ complete, the merge is blocked until you resolve all existing threads. ## Only allow merge requests to be merged if the pipeline succeeds -You can prevent merge requests from being merged if their pipeline did not succeed -or if there are threads to be resolved. This works for both: +You can prevent merge requests from being merged if: + +- No pipeline ran. +- The pipeline did not succeed. + +This works for both: - GitLab CI/CD pipelines - Pipelines run from an [external CI integration](../integrations/overview.md#integrations-listing) @@ -58,6 +62,7 @@ CI providers with this feature. To enable it, you must: 1. Press **Save** for the changes to take effect. This setting also prevents merge requests from being merged if there is no pipeline. +You should be careful to configure CI/CD so that pipelines run for every merge request. ### Limitations diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index 99e70f35d6d..b2aedb7d95f 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -10,13 +10,13 @@ type: reference, concepts Merge conflicts occur when two branches have different changes that cannot be merged automatically. -Git is able to automatically merge changes between branches in most cases, but -there are situations where Git will require your assistance to resolve the +Git can merge changes between branches in most cases, but +occasionally Git requires your assistance to resolve the conflicts manually. Typically, this is necessary when people change the same parts of the same files. -GitLab will prevent merge requests from being merged until all conflicts are -resolved. Conflicts can be resolved locally, or in many cases within GitLab +GitLab prevents merge requests from being merged until all conflicts are +resolved. Conflicts can be resolved locally, or in many cases in GitLab (see [conflicts available for resolution](#conflicts-available-for-resolution) for information on when this is available). @@ -24,35 +24,30 @@ for information on when this is available). NOTE: GitLab resolves conflicts by creating a merge commit in the source branch that -is not automatically merged into the target branch. This allows the merge -commit to be reviewed and tested before the changes are merged, preventing +is not automatically merged into the target branch. The merge +commit can be reviewed and tested before the changes are merged. This prevents unintended changes entering the target branch without review or breaking the build. ## Resolve conflicts: interactive mode -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5479) in GitLab 8.11. - -Clicking this will show a list of files with conflicts, with conflict sections +Clicking **Resolve Conflicts** displays a list of files with conflicts, with conflict sections highlighted:  -Once all conflicts have been marked as using 'ours' or 'theirs', the conflict -can be resolved. This will perform a merge of the target branch of the merge -request into the source branch, resolving the conflicts using the options +After all conflicts have been marked as using 'ours' or 'theirs', the conflict +can be resolved. Resolving conflicts merges the target branch of the merge +request into the source branch, using the options chosen. If the source branch is `feature` and the target branch is `master`, this is similar to performing `git checkout feature; git merge master` locally. ## Resolve conflicts: inline editor -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6374) in GitLab 8.13. - -The merge conflict resolution editor allows for more complex merge conflicts, -which require the user to manually modify a file in order to resolve a conflict, -to be solved right form the GitLab interface. Use the **Edit inline** button -to open the editor. Once you're sure about your changes, hit the -**Commit to source branch** button. +Some merge conflicts are more complex, requiring you to manually modify a file to +resolve them. Use the merge conflict resolution editor to resolve complex +conflicts in the GitLab interface. Click **Edit inline** to open the editor. +After you're sure about your changes, click **Commit to source branch**.  @@ -66,13 +61,16 @@ GitLab allows resolving conflicts in a file where all of the below are true: - The file, with conflict markers added, is not over 200 KB in size - The file exists under the same path in both branches -If any file with conflicts in that merge request does not meet all of these -criteria, the conflicts for that merge request cannot be resolved in the UI. +If any file in your merge request containing conflicts can't meet all of these +criteria, you can't resolve the merge conflict in the UI. Additionally, GitLab does not detect conflicts in renames away from a path. For -example, this will not create a conflict: on branch `a`, doing `git mv file1 -file2`; on branch `b`, doing `git mv file1 file3`. Instead, both files will be -present in the branch after the merge request is merged. +example, this does not create a conflict: + +1. On branch `a`, doing `git mv file1 file2` +1. On branch `b`, doing `git mv file1 file3`. + +Instead, both files are present in the branch after the merge request is merged. <!-- ## Troubleshooting 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 e2d6ba9ea1c..4efeb3b7938 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 **(CORE)** +# Reviewing and managing merge requests **(FREE)** 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), @@ -13,10 +13,10 @@ which is then reviewed, and accepted (or rejected). ## View project merge requests -View all the merge requests within a project by navigating to **Project > Merge Requests**. +View all the merge requests in a project by navigating to **Project > Merge Requests**. -When you access your project's merge requests, GitLab will present them in a list, -and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists). +When you access your project's merge requests, GitLab displays them in a list. +Use the tabs to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists).  @@ -32,7 +32,7 @@ You can [search and filter the results](../../search/index.md#filtering-issue-an A merge commit is created for every merge, but the branch is only merged if a fast-forward merge is possible. This ensures that if the merge request build -succeeded, the target branch build will also succeed after merging. +succeeded, the target branch build also succeeds after the merge. Navigate to a project's settings, select the **Merge commit with semi-linear history** option under **Merge Requests: Merge method** and save your changes. @@ -80,16 +80,19 @@ Click **Expand file** on any file to view the changes for that file. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. -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 navigation bar, click **Settings**, and go to **Preferences** on the left -sidebar. Scroll down to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. -Click **Save changes** to apply. +For larger merge requests, consider reviewing one file at a time. To enable this feature: -From there, when reviewing merge requests' **Changes** tab, you will see only one file at a time. You can then click the buttons **Prev** and **Next** to view the other files changed. +1. In the top right corner of the navigation bar, click your user avatar. +1. Click **Settings**. +1. In the left sidebar, go to **Preferences**. +1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. +1. Click **Save changes** to apply. + +After you enable this setting, GitLab displays only one file at a time in the **Changes** tab when you review merge requests. You can click **Prev** and **Next** to view other changed files.  -From [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) onwards, if you want to change +In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) and later, if you want to change this behavior, you can do so from your **User preferences** (as explained above) or directly in a merge request: @@ -104,10 +107,14 @@ browser's cookies or change this behavior again. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. -To seamlessly navigate among commits in a merge request, from the **Commits** tab, click one of -the commits to open the single-commit view. From there, you can navigate among the commits -by clicking the **Prev** and **Next** buttons on the top-right of the page or by using the -<kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. +To seamlessly navigate among commits in a merge request: + +1. Click the **Commits** tab. +1. Click a commit to open it in the single-commit view. +1. Navigate through the commits by either: + + - Clicking **Prev** and **Next** buttons on the top-right of the page. + - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts.  @@ -120,7 +127,7 @@ to expand the entire file.  -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205401) in GitLab 13.1, when viewing a +In GitLab [versions 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205401), when viewing a merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the entire content by clicking **Show file contents**. @@ -136,12 +143,53 @@ NOTE: You can append `?w=1` while on the diffs page of a merge request to ignore any whitespace changes. +## Mark files as viewed + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. +> - 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-file-views). **(FREE SELF)** + +When reviewing a merge request with many files multiple times, it may be useful to the reviewer +to focus on new changes and ignore the files that they have already reviewed and don't want to +see anymore unless they are changed again. + +To mark a file as viewed: + +1. Go to the merge request's **Diffs** tab. +1. On the right-top of the file, locate the **Viewed** checkbox. +1. Check it to mark the file as viewed. + +Once checked, the file remains marked for that reviewer unless there are newly introduced +changes to its content or the checkbox is unchecked. + +### Enable or disable file views **(FREE SELF)** + +The file view feature 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 enable it for your instance. + +To enable it: + +```ruby +Feature.enable(:local_file_reviews) +``` + +To disable it: + +```ruby +Feature.disable(:local_file_reviews) +``` + ## Perform inline code reviews > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. -GitLab provides a way of leaving comments in any part of the file being changed -in a Merge Request. To do so, click the **{comment}** **comment** icon in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line. +In a merge request, you can leave comments in any part of the file being changed. +In the Merge Request Diff UI, click the **{comment}** **comment** icon in the gutter +to expand the diff lines and leave a comment, just as you would for a changed line.  @@ -153,7 +201,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)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-multiline-comments). **(FREE SELF)** 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. @@ -169,7 +217,7 @@ above it.  -### Enable or disable multiline comments **(CORE ONLY)** +### Enable or disable multiline comments **(FREE SELF)** The multiline comments feature is under development but ready for production use. It is deployed behind a feature flag that is **disabled by default**. @@ -191,31 +239,30 @@ Feature.enable(:multiline_comments) ## Pipeline status in merge requests widgets If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, -you will be able to see: +you can see: - Both pre-merge and post-merge pipelines and the environment information if any. - Which deployments are in progress. -If there's an [environment](../../../ci/environments/index.md) and the application is -successfully deployed to it, the deployed environment and the link to the -Review App will be shown as well. +If an application is successfully deployed to an +[environment](../../../ci/environments/index.md), the deployed environment and the link to the +Review App are both shown. 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. +When the pipeline fails in a merge request but it can still be merged, +the **Merge** button is colored red. ### Post-merge pipeline status When a merge request is merged, you can see the post-merge pipeline status of the branch the merge request was merged into. For example, when a merge request -is merged into the master branch and then triggers a deployment to the staging +is merged into the `master` branch and then triggers a deployment to the staging environment. -Deployments that are ongoing will be shown, as well as the deploying/deployed state +Ongoing deployments are shown, and the state (deploying or deployed) for environments. If it's the first time the branch is deployed, the link -will return a `404` error until done. During the deployment, the stop button will -be disabled. If the pipeline fails to deploy, the deployment information will be hidden. +returns a `404` error until done. During the deployment, the stop button is +disabled. If the pipeline fails to deploy, the deployment information is hidden.  @@ -223,14 +270,15 @@ For more information, [read about pipelines](../../../ci/pipelines/index.md). ### Merge when pipeline succeeds (MWPS) -Set a merge request that looks ready to merge to [merge automatically when CI pipeline succeeds](merge_when_pipeline_succeeds.md). +Set a merge request that looks ready to merge to +[merge automatically when CI pipeline succeeds](merge_when_pipeline_succeeds.md). ### Live preview with Review Apps If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, -you can preview the changes submitted to a feature-branch through a merge request -in a per-branch basis. No need to checkout the branch, install and preview locally; -all your changes will be available to preview by anyone with the Review Apps link. +you can preview the changes submitted to a feature branch through a merge request +on a per-branch basis. You don't need to checkout the branch, install, and preview locally. +All your changes are available to preview by anyone with the Review Apps link. With GitLab [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the merge request widget takes you directly to the pages changed, making it easier and @@ -240,21 +288,26 @@ faster to preview proposed modifications. ## Associated features -There is also a large number of features to associated to merge requests: - -| Feature | Description | -|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Bulk editing merge requests](../../project/bulk_editing.md) | Update the attributes of multiple merge requests simultaneously. | -| [Cherry-pick changes](cherry_pick_changes.md) | Cherry-pick any commit in the UI by simply clicking the **Cherry-pick** button in a merged merge requests or a commit. | -| [Fast-forward merge requests](fast_forward_merge.md) | For a linear Git history and a way to accept merge requests without creating merge commits | -| [Find the merge request that introduced a change](versions.md) | When viewing the commit details page, GitLab will link to the merge request(s) containing that commit. | -| [Merge requests versions](versions.md) | Select and compare the different versions of merge request diffs | -| [Resolve conflicts](resolve_conflicts.md) | GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. | -| [Revert changes](revert_changes.md) | Revert changes from any commit from within a merge request. | +These features are associated with merge requests: + +- [Bulk editing merge requests](../../project/bulk_editing.md): + Update the attributes of multiple merge requests simultaneously. +- [Cherry-pick changes](cherry_pick_changes.md): + Cherry-pick any commit in the UI by clicking the **Cherry-pick** button in a merged merge requests or a commit. +- [Fast-forward merge requests](fast_forward_merge.md): + For a linear Git history and a way to accept merge requests without creating merge commits +- [Find the merge request that introduced a change](versions.md): + When viewing the commit details page, GitLab links to the merge request(s) containing that commit. +- [Merge requests versions](versions.md): + Select and compare the different versions of merge request diffs +- [Resolve conflicts](resolve_conflicts.md): + GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. +- [Revert changes](revert_changes.md): + Revert changes from any commit from a merge request. ## Troubleshooting -Sometimes things don't go as expected in a merge request, here are some +Sometimes things don't go as expected in a merge request. Here are some troubleshooting steps. ### Merge request cannot retrieve the pipeline status @@ -264,7 +317,7 @@ This can occur if Sidekiq doesn't pick up the changes fast enough. #### Sidekiq Sidekiq didn't process the CI state change fast enough. Please wait a few -seconds and the status will update automatically. +seconds and the status should update automatically. #### Bug @@ -280,12 +333,9 @@ Merge Request again. ## Tips -Here are some tips that will help you be more efficient with merge requests in +Here are some tips to help you be more efficient with merge requests in the command line. -NOTE: -This section might move in its own document in the future. - ### Copy the branch name for local checkout > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. @@ -294,7 +344,7 @@ 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 +(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally via command line by running `git checkout <branch-name>`. ### Checkout merge requests locally through the `head` ref @@ -303,7 +353,7 @@ 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 ways to checkout a merge request locally. -Please note that you can checkout a merge request locally even if the source +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`) @@ -312,10 +362,10 @@ 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 +`head` ref is deleted. This means that the merge request is not 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. +can still be re-opened. If the merge request's branch +exists, you can still check out the branch, as it isn't affected. #### Checkout locally by adding a Git alias @@ -334,7 +384,7 @@ from the `origin` remote, do: git mr origin 5 ``` -This will fetch the merge request into a local `mr-origin-5` branch and check +This fetches the merge request into a local `mr-origin-5` branch and check it out. #### Checkout locally by modifying `.git/config` for a given repository diff --git a/doc/user/project/merge_requests/sast.md b/doc/user/project/merge_requests/sast.md deleted file mode 100644 index 11f85749fb7..00000000000 --- a/doc/user/project/merge_requests/sast.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/sast/index.md' ---- - -This document was moved to [another location](../../application_security/sast/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/sast_docker.md b/doc/user/project/merge_requests/sast_docker.md deleted file mode 100644 index 5d61f2b36e8..00000000000 --- a/doc/user/project/merge_requests/sast_docker.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/container_scanning/index.md' ---- - -This document was moved to [another location](../../application_security/container_scanning/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 93b85ce8669..5311d833aec 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -8,7 +8,7 @@ type: reference, concepts # Squash and merge > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1024) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.17. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from [GitLab Starter](https://about.gitlab.com/pricing/)to GitLab Core in 11.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from [GitLab Starter](https://about.gitlab.com/pricing/)to GitLab Free in 11.0. With squash and merge you can combine all your merge request's commits into one and retain a clean history. @@ -110,7 +110,6 @@ 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)** 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,31 +132,6 @@ NOTE: If your project is set to **Do not allow** Squash and Merge, the users still have the option to squash commits locally through the command line and force-push to their remote branch before merging. -### Enable or disable Squash Commit Options **(CORE ONLY)** - -Squash Commit Options 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 -# Instance-wide -Feature.enable(:squash_options) -# or by project -Feature.enable(:squash_options, Project.find(<project ID>)) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:squash_options) -# or by project -Feature.disable(:squash_options, Project.find(<project ID>)) -``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index 7417320eea0..43ab03114fa 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -5,12 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Draft merge requests **(CORE)** +# Draft merge requests **(FREE)** If a merge request is not yet ready to be merged, perhaps due to continued development or open threads, you can prevent it from being accepted before it's ready by flagging -it as a **Draft**. This will disable the "Merge" button, preventing it from -being merged, and it will stay disabled until the "Draft" flag has been removed. +it as a **Draft**. This disables the **Merge** button, preventing it from +being merged. It stays disabled until the **Draft** flag has been removed.  @@ -22,7 +22,7 @@ To run pipelines for merged results, you must [remove the draft status](#removin ## Adding the "Draft" flag to a merge request -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** will be removed in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** is scheduled for removal in GitLab 14.0. > - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. There are several ways to flag a merge request as a Draft: @@ -30,15 +30,15 @@ There are several ways to flag a merge request as a Draft: - Click the **Mark as draft** button on the top-right corner of the merge request's page. - Add `[Draft]`, `Draft:` or `(Draft)` to the start of the merge request's title. Clicking on **Start the title with Draft:**, under the title box, when editing the merge request's - description will have the same effect. + description has the same effect. - **Deprecated** Add `[WIP]` or `WIP:` to the start of the merge request's title. - **WIP** still works but was deprecated in favor of **Draft**. It will be removed in the next major version (GitLab 14.0). + **WIP** still works but was deprecated in favor of **Draft**. It is scheduled for removal in the next major version (GitLab 14.0). - Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) in a comment in the merge request. This is a toggle, and can be repeated - to change the status back. Note that any other text in the comment will be discarded. + to change the status back. Note that any other text in the comment is discarded. - Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the merge request's source branch. This is not a toggle, and doing it again in another - commit will have no effect. + commit has no effect. ## Removing the "Draft" flag from a merge request @@ -48,10 +48,10 @@ Similar to above, when a Merge Request is ready to be merged, you can remove the - Click the **Mark as ready** button on the top-right corner of the merge request's page. - Remove `[Draft]`, `Draft:` or `(Draft)` from the start of the merge request's title. Clicking on **Remove the Draft: prefix from the title**, under the title box, when editing the merge - request's description, will have the same effect. + request's description, has the same effect. - Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) in a comment in the merge request. This is a toggle, and can be repeated - to change the status back. Note that any other text in the comment will be discarded. + to change the status back. Note that any other text in the comment is discarded. - Click on the **Resolve Draft status** button near the bottom of the merge request description, next to the **Merge** button (see [image above](#draft-merge-requests)). Must have at least Developer level permissions on the project for the button to @@ -60,8 +60,8 @@ Similar to above, when a Merge Request is ready to be merged, you can remove the ## Including/excluding WIP merge requests when searching When viewing/searching the merge requests list, you can choose to include or exclude -WIP merge requests by adding a "WIP" filter in the search box, and choosing "Yes" -(to include) or "No" (to exclude). +WIP merge requests. Add a **WIP** filter in the search box, and choose **Yes** +to include, or **No** to exclude.  diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index acf32bb0f92..d7ca2eae831 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Milestones **(CORE)** +# Milestones **(FREE)** Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. diff --git a/doc/user/project/operations/alert_management.md b/doc/user/project/operations/alert_management.md deleted file mode 100644 index e60e7d93d12..00000000000 --- a/doc/user/project/operations/alert_management.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/incident_management/index.md' ---- - -This document was moved to [another location](../../../operations/incident_management/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/dashboard_settings.md b/doc/user/project/operations/dashboard_settings.md deleted file mode 100644 index ef106181acc..00000000000 --- a/doc/user/project/operations/dashboard_settings.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/metrics/dashboards/settings.md' ---- - -This document was moved to [another location](../../../operations/metrics/dashboards/settings.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md deleted file mode 100644 index 399ab0d53dc..00000000000 --- a/doc/user/project/operations/error_tracking.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/error_tracking.md' ---- - -This document was moved to [another location](../../../operations/error_tracking.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md deleted file mode 100644 index 03f2cad6d78..00000000000 --- a/doc/user/project/operations/feature_flags.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/feature_flags.md' ---- - -This document was moved to [another location](../../../operations/feature_flags.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md deleted file mode 100644 index d19cf393883..00000000000 --- a/doc/user/project/operations/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/index.md' ---- - -This document was moved to [another location](../../../operations/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/linking_to_an_external_dashboard.md b/doc/user/project/operations/linking_to_an_external_dashboard.md deleted file mode 100644 index ef106181acc..00000000000 --- a/doc/user/project/operations/linking_to_an_external_dashboard.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/metrics/dashboards/settings.md' ---- - -This document was moved to [another location](../../../operations/metrics/dashboards/settings.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/tracing.md b/doc/user/project/operations/tracing.md deleted file mode 100644 index dcf9894f9e1..00000000000 --- a/doc/user/project/operations/tracing.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/tracing.md' ---- - -This document was moved to [another location](../../../operations/tracing.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven.md b/doc/user/project/packages/maven.md deleted file mode 100644 index 13b5d69586a..00000000000 --- a/doc/user/project/packages/maven.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/maven_repository/index.md' ---- - -This document was moved to [another location](../../packages/maven_repository/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven_packages.md b/doc/user/project/packages/maven_packages.md deleted file mode 100644 index 13b5d69586a..00000000000 --- a/doc/user/project/packages/maven_packages.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/maven_repository/index.md' ---- - -This document was moved to [another location](../../packages/maven_repository/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md deleted file mode 100644 index 13b5d69586a..00000000000 --- a/doc/user/project/packages/maven_repository.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/maven_repository/index.md' ---- - -This document was moved to [another location](../../packages/maven_repository/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md deleted file mode 100644 index f874b05e7e2..00000000000 --- a/doc/user/project/packages/npm_registry.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/npm_registry/index.md' ---- - -This document was moved to [another location](../../packages/npm_registry/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index aa06a15a8c0..86e34842aaf 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -19,7 +19,7 @@ GitLab does it for you, out-of-the-box. open source Certificate Authority. WARNING: -This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3342). +This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(FREE SELF)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3342). ## Requirements @@ -28,7 +28,8 @@ Before you can enable automatic provisioning of an SSL certificate for your doma - Created a [project](../index.md#getting-started) in GitLab containing your website's source code. - Acquired a domain (`example.com`) and added a [DNS entry](index.md) - pointing it to your Pages website. + pointing it to your Pages website. The top-level domain (`.com`) must be a + [public suffix](https://publicsuffix.org/). - [Added your domain to your Pages project](index.md#1-add-a-custom-domain-to-pages) and verified your ownership. - Verified your website is up and running, accessible through your custom domain. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index e8c6305dbab..d9f57253396 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -32,7 +32,9 @@ nor credit card transactions, then why do we need secure connections? Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" security measure, necessary just for big companies like banks and shopping sites with financial transactions. +<!-- vale gitlab.Spelling = NO --> Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): +<!-- vale gitlab.rulename = YES --> > _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](https://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md deleted file mode 100644 index 2cf118c9066..00000000000 --- a/doc/user/project/pages/getting_started/fork_sample_project.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'pages_forked_sample_project.md' ---- - -This document was moved to [pages_forked_sample_project.md](pages_forked_sample_project.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/new_or_existing_website.md b/doc/user/project/pages/getting_started/new_or_existing_website.md deleted file mode 100644 index 2fc833fbd34..00000000000 --- a/doc/user/project/pages/getting_started/new_or_existing_website.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'pages_ci_cd_template.md' ---- - -This document was moved to [another location](pages_ci_cd_template.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/pages_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md deleted file mode 100644 index 0dab1f6ee19..00000000000 --- a/doc/user/project/pages/getting_started/pages_bundled_template.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'pages_new_project_template.md' ---- - -This document was moved to [pages_new_project_template.md](pages_new_project_template.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index c7916b7c01e..60f8533afc8 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -52,5 +52,5 @@ You can take some **optional** further steps:  - - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-baseurls) + - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-base-urls) from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the configuration file. diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md deleted file mode 100644 index 361323a9073..00000000000 --- a/doc/user/project/pages/getting_started_part_four.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'getting_started/pages_from_scratch.md' ---- - -This document was moved to [getting_started/pages_from_scratch.md](getting_started/pages_from_scratch.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 801fe0c7ef0..dee021b8225 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Pages domain names, URLs, and baseurls +# GitLab Pages domain names, URLs, and base URLs On this document, learn how to name your project for GitLab Pages according to your intended website's URL. @@ -78,7 +78,7 @@ To understand Pages domains clearly, read the examples below. - On your GitLab instance, replace `gitlab.io` above with your Pages server domain. Ask your sysadmin for this information. -## URLs and baseurls +## URLs and base URLs NOTE: The `baseurl` option might be called named differently in some static site generators. diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md deleted file mode 100644 index 9d7f401ca91..00000000000 --- a/doc/user/project/pages/getting_started_part_three.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'custom_domains_ssl_tls_certification/index.md' ---- - -This document was moved to [another location](custom_domains_ssl_tls_certification/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md deleted file mode 100644 index 4b2b186ca28..00000000000 --- a/doc/user/project/pages/getting_started_part_two.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'index.md' ---- - -This document was moved to [another location](index.md#getting-started). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index c9e28bf15c2..6eb06972945 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -103,7 +103,7 @@ optionally secure it with SSL/TLS certificates. If you're using GitLab.com, your website is publicly available to the internet. To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). -If you're using a self-managed instance (Core, Starter, Premium, or Ultimate), +If you're using a self-managed instance (Free, Premium, or Ultimate), your websites are published on your own server, according to the [Pages settings](../../../administration/pages/index.md) chosen by your sysadmin, who can make them public or internal. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 8380f367212..fbc86abbe66 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -63,7 +63,7 @@ If the case of `404.html`, there are different scenarios. For example: 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)** +## GitLab Pages Access Control **(FREE)** To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index a2a17a4f2ca..2e0fc87b3df 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -38,7 +38,9 @@ For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v - **Only project members**: Only project members are able to browse the website. - **Everyone with access**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. -1. Click **Save changes**. +1. Click **Save changes**. Note that your changes may not take effect immediately. GitLab Pages uses + a caching mechanism for efficiency. Your changes may not take effect until that cache is + invalidated, which usually takes less than a minute. The next time someone tries to access your website and the access control is enabled, they're presented with a page to sign into GitLab and verify they diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md deleted file mode 100644 index cf5f33534cd..00000000000 --- a/doc/user/project/pipelines/job_artifacts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../ci/pipelines/job_artifacts.md' ---- - -This document was moved to [another location](../../../ci/pipelines/job_artifacts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md deleted file mode 100644 index 52352a29c5a..00000000000 --- a/doc/user/project/pipelines/schedules.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../ci/pipelines/schedules.md' ---- - -This document was moved to [another location](../../../ci/pipelines/schedules.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md deleted file mode 100644 index f19f28743a8..00000000000 --- a/doc/user/project/pipelines/settings.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../ci/pipelines/settings.md' ---- - -This document was moved to [another location](../../../ci/pipelines/settings.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 5754a3b7a9d..37324b02437 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -13,7 +13,7 @@ further restrictions on certain branches, they can be protected. ## Overview -By default, a protected branch does four simple things: +By default, a protected branch does these things: - It prevents its creation, if not already created, from everybody except users with Maintainer permission. @@ -21,58 +21,60 @@ By default, a protected branch does four simple things: - It prevents **anyone** from force pushing to the branch. - It prevents **anyone** from deleting the branch. -NOTE: -A GitLab administrator is allowed to push to the protected branches. +**Permissions:** -See the [Changelog](#changelog) section for changes over time. +- GitLab administrators are allowed to push to the protected branches. +- Users with [Developer permissions](../permissions.md) are allowed to + create a project in a group, but might not be allowed to initially + push to the [default branch](repository/branches/index.md#default-branch). The default branch protection level is set in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). +See the [Changelog](#changelog) section for changes over time. + ## Configuring protected branches -To protect a branch, you need to have at least Maintainer permission level. Note -that the `master` branch is protected by default. +To protect a branch, you need to have at least Maintainer permission level. +The `master` branch is protected by default. -1. Navigate to your project's **Settings ➔ Repository** +1. In your project, go to **Settings > Repository**. 1. Scroll to find the **Protected branches** section. 1. From the **Branch** dropdown menu, select the branch you want to protect and click **Protect**. In the screenshot below, we chose the `develop` branch.  -1. Once done, the protected branch will appear in the "Protected branches" list. +1. Once done, the protected branch displays in the **Protected branches** list.  ## Using the Allowed to merge and Allowed to push settings -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in GitLab 8.11. - In GitLab 8.11 and later, we added another layer of branch protection which provides -more granular management of protected branches. The "Developers can push" -option was replaced by an "Allowed to push" setting which can be set to -allow/prohibit Maintainers and/or Developers to push to a protected branch. +more granular management of protected branches. The **Developers can push** +option was replaced by **Allowed to push**. You can set this value to allow +or prohibit Maintainers and/or Developers to push to a protected branch. -Using the "Allowed to push" and "Allowed to merge" settings, you can control +Using the **Allowed to push** and **Allowed to merge** settings, you can control the actions that different roles can perform with the protected branch. -For example, you could set "Allowed to push" to "No one", and "Allowed to merge" -to "Developers + Maintainers", to require _everyone_ to submit a merge request for +For example, you could set **Allowed to push** to "No one", and **Allowed to merge** +to "Developers + Maintainers", to require everyone to submit a merge request for changes going into the protected branch. This is compatible with workflows like the [GitLab workflow](../../topics/gitlab_flow.md). However, there are workflows where that is not needed, and only protecting from force pushes and branch removal is useful. For those workflows, you can allow everyone with write access to push to a protected branch by setting -"Allowed to push" to "Developers + Maintainers". +**Allowed to push** to "Developers + Maintainers". -You can set the "Allowed to push" and "Allowed to merge" options while creating +You can set the **Allowed to push** and **Allowed to merge** options while creating a protected branch or afterwards by selecting the option you want from the -dropdown list in the "Already protected" area. +dropdown list in the **Already protected** area.  If you don't choose any of those options while creating a protected branch, -they are set to "Maintainers" by default. +they are set to Maintainers by default. ### Allow Deploy Keys to push to a protected branch @@ -88,7 +90,7 @@ Deploy keys can be selected in the **Allowed to push** dropdown when: - Defining a protected branch. - Updating an existing branch. -Select a deploy key to allow the owner of the key to push to the chosen protected branch, +Select a deploy key to allow the key's owner to push to the chosen protected branch, even if they aren't a member of the related project. The owner of the selected deploy key must have at least read access to the given project. @@ -101,26 +103,22 @@ Deploy Keys are not available in the **Allowed to merge** dropdown.  -## Restricting push and merge access to certain users **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.11. +## Restricting push and merge access to certain users **(PREMIUM)** -With GitLab Enterprise Edition you can restrict access to protected branches -by choosing a role (Maintainers, Developers) as well as certain users. From the +With GitLab Premium you can restrict access to protected branches +by choosing a role (Maintainers, Developers) and certain users. From the dropdown menu select the role and/or the users you want to have merge or push access.  -Click **Protect** and the branch will appear in the "Protected branch" list. +Click **Protect** and the branch displays in the **Protected branch** list.  ## Wildcard protected branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4665) in GitLab 8.10. - -You can specify a wildcard protected branch, which will protect all branches +You can specify a wildcard protected branch, which protects all branches matching the wildcard. For example: | Wildcard Protected Branch | Matching Branches | @@ -129,15 +127,15 @@ matching the wildcard. For example: | `production/*` | `production/app-server`, `production/load-balancer` | | `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` | -Protected branch settings (like "Developers can push") apply to all matching +Protected branch settings, like **Developers can push**, apply to all matching branches. Two different wildcards can potentially match the same branch. For example, `*-stable` and `production-*` would both match a `production-stable` branch. In that case, if _any_ of these protected branches have a setting like -"Allowed to push", then `production-stable` will also inherit this setting. +"Allowed to push", then `production-stable` also inherit this setting. -If you click on a protected branch's name, you will be presented with a list of +If you click on a protected branch's name, GitLab displays a list of all matching branches:  @@ -151,41 +149,36 @@ When a protected branch or wildcard protected branches are set to Developers (and users with higher [permission levels](../permissions.md)) are allowed to create a new protected branch as long as they are [**Allowed to merge**](#using-the-allowed-to-merge-and-allowed-to-push-settings). -This can only be done via the UI or through the API (to avoid creating protected -branches accidentally from the command line or from a Git client application). +This can only be done by using the UI or through the API, to avoid creating protected +branches accidentally from the command line or from a Git client application. To create a new branch through the user interface: -1. Visit **Repository > Branches**. +1. Go to **Repository > Branches**. 1. Click on **New branch**. -1. Fill in the branch name and select an existing branch, tag, or commit that - the new branch will be based off. Only existing protected branches and commits - that are already in protected branches will be accepted. +1. Fill in the branch name and select an existing branch, tag, or commit to + base the new branch on. Only existing protected branches and commits + that are already in protected branches are accepted. ## Deleting a protected branch -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393) in GitLab 9.3. - -From time to time, it may be required to delete or clean up branches that are -protected. +From time to time, you may need to delete or clean up protected branches. +User with [Maintainer permissions](../permissions.md) and greater can manually delete protected +branches by using the GitLab web interface: -User with [Maintainer permissions](../permissions.md) and up can manually delete protected -branches via the GitLab web interface: - -1. Visit **Repository > Branches** -1. Click on the delete icon next to the branch you wish to delete -1. In order to prevent accidental deletion, an additional confirmation is - required +1. Go to **Repository > Branches**. +1. Click on the delete icon next to the branch you wish to delete. +1. To prevent accidental deletion, an additional confirmation is required.  -Deleting a protected branch is only allowed via the web interface, not via Git. +Deleting a protected branch is allowed only by using the web interface; not from Git. This means that you can't accidentally delete a protected branch from your command line or a Git client application. ## Protected Branches approval by Code Owners **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4. It is possible to require at least one approval by a [Code Owner](code_owners.md) to a file changed by the @@ -208,7 +201,7 @@ To enable Code Owner's approval to branches already protected:  -When enabled, all merge requests targeting these branches will require approval +When enabled, all merge requests targeting these branches require approval by a Code Owner per matched rule before they can be merged. Additionally, direct pushes to the protected branch are denied if a rule is matched. @@ -224,26 +217,9 @@ for details about the pipelines security model. ## Changelog -**13.5** - -- [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). - -**11.9** - -- [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) by Developers (and users with higher permission levels) through the API and the user interface. - -**9.2** - -- Allow deletion of protected branches via the web interface ([issue #21393](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393)). - -**8.11** - -- Allow creating protected branches that can't be pushed to ([merge request !5081](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081)). - -**8.10** - -- Allow developers without push access to merge into a protected branch ([merge request !4892](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4892)). -- Allow specifying protected branches using wildcards ([merge request !4665](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4665)). +- **13.5**: [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). +- **11.9**: [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) + by Developers (and users with higher permission levels) through the API and the user interface. <!-- ## Troubleshooting diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 7e09c526312..a6f2d645198 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -15,11 +15,13 @@ This feature evolved out of [protected branches](protected_branches.md) ## Overview -Protected tags will prevent anyone from updating or deleting the tag, and will prevent creation of matching tags based on the permissions you have selected. By default, anyone without Maintainer permission will be prevented from creating tags. +Protected tags prevent anyone from updating or deleting the tag, and prevent +creation of matching tags based on the permissions you have selected. By default, +anyone without Maintainer [permissions](../permissions.md) is prevented from creating tags. ## Configuring protected tags -To protect a tag, you need to have at least Maintainer permission level. +To protect a tag, you need to have at least Maintainer [permissions](../permissions.md). 1. Navigate to the project's **Settings > Repository**: @@ -29,17 +31,18 @@ To protect a tag, you need to have at least Maintainer permission level.  -1. From the **Allowed to create** dropdown, select who will have permission to create matching tags and then click **Protect**: +1. From the **Allowed to create** dropdown, select users with permission to create + matching tags, and click **Protect**:  -1. Once done, the protected tag will appear in the **Protected tags** list: +1. After done, the protected tag displays in the **Protected tags** list:  ## Wildcard protected tags -You can specify a wildcard protected tag, which will protect all tags +You can specify a wildcard protected tag, which protects all tags matching the wildcard. For example: | Wildcard Protected Tag | Matching Tags | @@ -52,9 +55,9 @@ matching the wildcard. For example: Two different wildcards can potentially match the same tag. For example, `*-stable` and `production-*` would both match a `production-stable` tag. In that case, if _any_ of these protected tags have a setting like -**Allowed to create**, then `production-stable` will also inherit this setting. +**Allowed to create**, then `production-stable` also inherit this setting. -If you click on a protected tag's name, you will be presented with a list of +If you click on a protected tag's name, GitLab displays a list of all matching tags:  diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 64be3182dab..ac65fabd6a7 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -34,9 +34,9 @@ The following quick actions are applicable to descriptions, discussions and thre | `/assign @user` | ✓ | ✓ | | Assign one user. | | `/assign @user1 @user2` | ✓ | ✓ | | Assign multiple users. **(STARTER)** | | `/assign me` | ✓ | ✓ | | Assign yourself. | -| `/assign_reviewer @user` | | ✓ | | Assign one user as a reviewer. | -| `/assign_reviewer @user1 @user2` | | ✓ | | Assign multiple users as reviewers. **(STARTER)** | -| `/assign_reviewer me` | | ✓ | | Assign yourself as a reviewer. | +| `/assign_reviewer @user` or `/reviewer @user` or `/request_review @user` | | ✓ | | Assign one user as a reviewer. | +| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | | ✓ | | Assign multiple users as reviewers. **(STARTER)** | +| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | | ✓ | | Assign yourself as a reviewer. | | `/award :emoji:` | ✓ | ✓ | ✓ | Toggle emoji award. | | `/child_epic <epic>` | | | ✓ | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | | `/clear_weight` | ✓ | | | Clear weight. **(STARTER)** | @@ -49,7 +49,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/done` | ✓ | ✓ | ✓ | Mark to do as done. | | `/draft` | | ✓ | | Toggle the draft status. | | `/due <date>` | ✓ | | | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | -| `/duplicate <#issue>` | ✓ | | | Close this issue and mark as a duplicate of another issue. **(CORE)** Also, mark both as related. **(STARTER)** | +| `/duplicate <#issue>` | ✓ | | | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. **(STARTER)** | | `/epic <epic>` | ✓ | | | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. **(PREMIUM)** | | `/estimate <<W>w <DD>d <hh>h <mm>m>` | ✓ | ✓ | | Set time estimate. For example, `/estimate 1w 3d 2h 14m`. | | `/iteration *iteration:"iteration name"` | ✓ | | | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). **(STARTER)** | @@ -62,7 +62,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/promote` | ✓ | | | Promote issue to epic. **(PREMIUM)** | | `/publish` | ✓ | | | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) **(ULTIMATE)** | | `/reassign @user1 @user2` | ✓ | ✓ | | Replace current assignees with those specified. **(STARTER)** | -| `/rebase` | | ✓ | | Rebase source branch. This will schedule a background task that attempt to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` will be ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab will display a message that a rebase cannot be scheduled. Rebase failures will be displayed with the merge request status. | +| `/rebase` | | ✓ | | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | | `/reassign_reviewer @user1 @user2` | | ✓ | | Replace current reviewers with those specified. **(STARTER)** | | `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace current labels with those specified. | | `/relate #issue1 #issue2` | ✓ | | | Mark issues as related. **(STARTER)** | @@ -87,8 +87,8 @@ The following quick actions are applicable to descriptions, discussions and thre | `/todo` | ✓ | ✓ | ✓ | Add a to-do item. | | `/unassign @user1 @user2` | ✓ | ✓ | | Remove specific assignees. **(STARTER)** | | `/unassign` | | ✓ | | Remove all assignees. | -| `/unassign_reviewer @user1 @user2` | | ✓ | | Remove specific reviewers. **(STARTER)** | -| `/unassign_reviewer` | | ✓ | | Remove all reviewers. | +| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | | ✓ | | Remove specific reviewers. **(STARTER)** | +| `/unassign_reviewer` or `/remove_reviewer` | | ✓ | | Remove all reviewers. | | `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove specified labels. | | `/unlabel` or `/remove_label` | ✓ | ✓ | ✓ | Remove all labels. | | `/unlock` | ✓ | ✓ | | Unlock the discussions. | diff --git a/doc/user/project/releases.md b/doc/user/project/releases.md deleted file mode 100644 index 6dd5a6f0b0d..00000000000 --- a/doc/user/project/releases.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'releases/index.md' ---- - -This document was moved to [another location](releases/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 90d7ac0a3c2..d03cc0495c1 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -407,7 +407,7 @@ Here is an example of a release evidence object: } ``` -### Collect release evidence **(PREMIUM ONLY)** +### Collect release evidence **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index ffd4b383bcb..abe533172b9 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -53,14 +53,14 @@ the target is the project's **default branch**. The default branch is also initially [protected](../../protected_branches.md#protected-branches) against accidental deletion and forced pushes. -### Custom initial branch name **(CORE ONLY)** +### Custom initial branch name **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2. > - It's 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-custom-initial-branch-name). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). **(FREE SELF)** 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 @@ -71,7 +71,7 @@ else. This way, every new project created from then on will start from the custo 1. Change the default initial branch to a custom name of your choice. 1. **Save Changes**. -#### Enable or disable custom initial branch name **(CORE ONLY)** +#### Enable or disable custom initial branch name **(FREE SELF)** Setting the default initial branch name is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 4f996df5fef..df3e24fbf30 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -17,8 +17,8 @@ project.  -For those who prefer to keep their fingers on the keyboard, there is a -[shortcut button](../../shortcuts.md) as well, which you can invoke from _anywhere_ +If you prefer to keep their fingers on the keyboard, use the +[shortcut button](../../shortcuts.md), which you can invoke from anywhere in a project. Press `t` to launch the File search function when in **Issues**, 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 fb798738160..7847930366a 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 @@ -23,107 +23,28 @@ Rewriting repository history is a destructive operation. Make sure to back up yo you begin. The best way back up a repository is to [export the project](../settings/import_export.md#exporting-a-project-and-its-data). -NOTE: -Git LFS files can only be removed by an Administrator using a -[Rake task](../../../raketasks/cleanup.md). Removal of this limitation -[is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/223621). - ## Purge files from repository history -To reduce the size of your repository in GitLab, you must remove references to large files from branches, tags, and +To reduce the size of your repository in GitLab, you must first remove references to large files from branches, tags, *and* other internal references (refs) that are automatically created by GitLab. These refs include: - `refs/merge-requests/*` for merge requests. - `refs/pipelines/*` for [pipelines](../../../ci/troubleshooting.md#fatal-reference-is-not-a-tree-error). - `refs/environments/*` for environments. +- `refs/keep-around/*` are created as hidden refs to prevent commits referenced in the database from being removed -Git doesn't usually download these refs to make cloning and fetch faster, but we can use the `--mirror` option to -download all the advertised refs. - -1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) - using a supported package manager or from source. - -1. Clone a fresh copy of the repository using `--bare` and `--mirror`: - - ```shell - 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. - - To purge large files, the `--strip-blobs-bigger-than` option can be used: - - ```shell - git filter-repo --strip-blobs-bigger-than 10M - ``` - - To purge large files stored using Git LFS, the `--blob--callback` option can - be used. The example below, uses the callback to read the file size from the - Git LFS pointer, and removes files larger than 10MB. - - ```shell - git filter-repo --blob-callback ' - if blob.data.startswith(b"version https://git-lfs.github.com/spec/v1"): - size_in_bytes = int.from_bytes(blob.data[124:], byteorder="big") - if size_in_bytes > 10*1000: - blob.skip() - ' - ``` - - To purge specific large files by path, the `--path` and `--invert-paths` options can be combined: - - ```shell - git filter-repo --path path/to/big/file.m4v --invert-paths - ``` - - See the - [`git filter-repo` documentation](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#EXAMPLES) - for more examples and the complete documentation. - -1. Force push your changes to overwrite all branches on GitLab: - - ```shell - git push origin --force 'refs/heads/*' - ``` - - [Protected branches](../protected_branches.md) cause this to fail. To proceed, you must - remove branch protection, push, and then re-enable protected branches. - -1. To remove large files from tagged releases, force push your changes to all tags on GitLab: - - ```shell - git push origin --force 'refs/tags/*' - ``` - - [Protected tags](../protected_tags.md) cause this to fail. To proceed, you must remove tag - protection, push, and then re-enable protected tags. - -1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. - - ```shell - git push origin --force 'refs/replace/*' - ``` - - Refer to the Git [`replace`](https://git-scm.com/book/en/v2/Git-Tools-Replace) documentation for information on how this works. - -1. Run a [repository cleanup](#repository-cleanup). - -NOTE: -Project statistics are cached for performance. You may need to wait 5-10 minutes -to see a reduction in storage utilization. - -## Purge files from GitLab storage - -In addition to the refs mentioned above, GitLab also creates hidden `refs/keep-around/*`to prevent commits being deleted. Hidden refs are not advertised, which means we can't download them using Git, but these refs are included in a project export. +These refs are not automatically downloaded and hidden refs are not advertised, but we can remove these refs using a project export. -To purge files from GitLab storage: +To purge files from a GitLab repository: 1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) using a supported package manager or from source. 1. Generate a fresh [export from the project](../settings/import_export.html#exporting-a-project-and-its-data) and download it. + This project export contains a backup copy of your repository *and* refs + we can use to purge files from your repository. 1. Decompress the backup using `tar`: @@ -134,7 +55,7 @@ To purge files from GitLab storage: This contains a `project.bundle` file, which was created by [`git bundle`](https://git-scm.com/docs/git-bundle). -1. Clone a fresh copy of the repository from the bundle: +1. Clone a fresh copy of the repository from the bundle using `--bare` and `--mirror` options: ```shell git clone --bare --mirror /path/to/project.bundle @@ -149,7 +70,7 @@ To purge files from GitLab storage: the previous run. You need this file from **every** run. Do the next step every time you run `git filter-repo`. - To purge all large files, the `--strip-blobs-bigger-than` option can be used: + To purge all files larger than 10M, the `--strip-blobs-bigger-than` option can be used: ```shell git filter-repo --strip-blobs-bigger-than 10M @@ -236,14 +157,14 @@ This: - Runs `git gc --prune=30.minutes.ago` against the repository to remove unreferenced objects. Repacking your repository temporarily causes the size of your repository to increase significantly, because the old pack files are not removed until the new pack files have been created. -- Unlinks any unused LFS objects currently attached to your project, freeing up storage space. +- Unlinks any unused LFS objects attached to your project, freeing up storage space. - Recalculates the size of your repository on disk. GitLab sends an email notification with the recalculated repository size after the cleanup has completed. If the repository size does not decrease, this may be caused by loose objects being kept around because they were referenced in a Git operation that happened -in the last 30 minutes. Try re-running these steps once the repository has been +in the last 30 minutes. Try re-running these steps after the repository has been dormant for at least 30 minutes. When using repository cleanup, note: @@ -263,7 +184,7 @@ When using repository cleanup, note: Repository size limits: - Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#account-and-limit-settings) - on self-managed instances. **(STARTER ONLY)** + on self-managed instances. **(PREMIUM SELF)** - Are [set for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). When a project has reached its size limit, you cannot: diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 4a7f75ba1ac..efd7353c883 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -16,8 +16,8 @@ at most once every 5 minutes on GitLab.com with [the limit set by the administra There are two kinds of repository mirroring supported by GitLab: -- [Push](#pushing-to-a-remote-repository): for mirroring a GitLab repository to another location. **(CORE)** -- [Pull](#pulling-from-a-remote-repository): for mirroring a repository from another location to GitLab. **(STARTER)** +- [Push](#pushing-to-a-remote-repository): for mirroring a GitLab repository to another location. **(FREE)** +- [Pull](#pulling-from-a-remote-repository): for mirroring a repository from another location to GitLab. **(PREMIUM)** When the mirror repository is updated, all new branches, tags, and commits will be visible in the project's activity feed. @@ -37,7 +37,7 @@ The following are some possible use cases for repository mirroring: - You migrated to GitLab but still need to keep your project in another source. In that case, you can simply set it up to mirror to GitLab (pull) and all the essential history of commits, tags, - and branches will be available in your GitLab instance. **(STARTER)** + and branches will be available in your GitLab instance. **(PREMIUM)** - 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. @@ -47,10 +47,10 @@ The following are some possible use cases for repository mirroring: 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)** +## Pushing to a remote repository **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249) in GitLab Enterprise Edition 8.7. -> - [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18715) in 10.8. +> - [Moved to GitLab Free](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18715) in 10.8. > - [LFS support over HTTPS added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in 13.5 For an existing project, you can set up push mirroring as follows: @@ -205,10 +205,11 @@ If it is not working correctly a red `error` tag appears and shows the error mes 1. Fill in the **Password** field with the GitLab personal access token created on the destination GitLab instance. 1. Click the **Mirror repository** button. -## Pulling from a remote repository **(STARTER)** +## Pulling from a remote repository **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51) in GitLab Enterprise Edition 8.2. -> - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/-/issues/10871) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.11. +> - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/-/issues/10871) in GitLab 11.11. +> - Moved to GitLab Premium in 13.9. You can set up a repository to automatically have its branches, tags, and commits updated from an upstream repository. @@ -262,9 +263,10 @@ Repository mirrors are updated as Sidekiq becomes available to process them. If - Fails (for example, a branch diverged from upstream), it will be attempted again later. Mirrors can fail up to 14 times before they will not be enqueued for update again. -### Overwrite diverged branches **(STARTER)** +### Overwrite diverged branches **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4559) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4559) in GitLab 10.6. +> - Moved to GitLab Premium in 13.9. You can choose to always update your local branches with remote versions, even if they have diverged from the remote. @@ -274,7 +276,9 @@ For mirrored branches, enabling this option results in the loss of local changes To use this option, check the **Overwrite diverged branches** box when creating a repository mirror. -### Trigger pipelines for mirror updates **(STARTER)** +### Trigger pipelines for mirror updates **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. If this option is enabled, pipelines will be triggered when branches or tags are updated from the remote repository. Depending on the activity of the remote @@ -282,9 +286,10 @@ repository, this may greatly increase the load on your CI runners. Only enable this if you know they can handle the load. CI will run using the credentials assigned when you set up pull mirroring. -### Hard failure **(STARTER)** +### Hard failure **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3117) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3117) in GitLab 10.2. +> - Moved to GitLab Premium in 13.9. Once the mirroring process is unsuccessfully retried 14 times in a row, it will get marked as hard failed. This will become visible in either the: @@ -295,9 +300,10 @@ failed. This will become visible in either the: When a project is hard failed, it will no longer get picked up for mirroring. You can resume the project mirroring again by [forcing an update](#forcing-an-update). -### Trigger an update using the API **(STARTER)** +### Trigger an update using the API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in GitLab 10.3. +> - Moved to GitLab Premium in 13.9. 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), @@ -305,19 +311,21 @@ 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). -## Mirror only protected branches **(STARTER)** +## Mirror only protected branches **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. Based on the mirror direction that you choose, you can opt to mirror only the [protected branches](../protected_branches.md) from/to your remote repository. For pull mirroring, non-protected branches are not mirrored and can diverge. To use this option, check the **Only mirror protected branches** box when -creating a repository mirror. +creating a repository mirror. **(PREMIUM)** ## SSH authentication -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2551) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5 for Pull mirroring. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in [GitLab Core](https://about.gitlab.com/pricing/) 11.6 for Push mirroring. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2551) in GitLab 9.5 for Pull mirroring. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in GitLab 11.6 for Push mirroring. SSH authentication is mutual: @@ -403,17 +411,19 @@ to generate a new key. You'll have to update the other repository with the new key to keep the mirror running. NOTE: -The generated keys are stored in the GitLab database, not in the filesystem. Therefore, +The generated keys are stored in the GitLab database, not in the file system. Therefore, SSH public key authentication for mirrors cannot be used in a pre-receive hook. -## Forcing an update **(CORE)** +## Forcing an update **(FREE)** While mirrors are scheduled to update automatically, you can always force an update by using the update button which is available on the **Mirroring repositories** section of the **Repository Settings** page.  -## Bidirectional mirroring **(STARTER)** +## Bidirectional mirroring **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. WARNING: Bidirectional mirroring may cause conflicts. @@ -536,7 +546,9 @@ Note that this sample has a few limitations: - The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` is seen as a ref update and Git will complain about it. -### Mirroring with Perforce Helix via Git Fusion **(STARTER)** +### Mirroring with Perforce Helix via Git Fusion **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. WARNING: Bidirectional mirroring should not be used as a permanent configuration. Refer to diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index b9477da3937..a9e249bb8c3 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -21,8 +21,8 @@ Choose **New file** from the dropdown. Enter a filename 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 +defaults to the branch you were viewing in the file browser. If you enter +a new branch name, a checkbox displays, 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. @@ -31,46 +31,45 @@ When you are satisfied with your new file, click **Commit Changes** at the botto ### Shortcuts -You can use handy shortcuts when editing a file through the Web Editor, which are the same as -the Web IDE's. For details, see the documentation for [Command Palette](../web_ide/index.md#command-palette). +You can use shortcuts when editing a file through the Web Editor. It uses the same shortcuts +as the Web IDE. For details, read the documentation for [Command Palette](../web_ide/index.md#command-palette). ### Template dropdowns 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. +might need. GitLab displays a message to help you:  -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. +When clicking on either `LICENSE` or `.gitignore` and so on, a dropdown displays +to provide you a template that may be suitable for your project:  -The license, changelog, contribution guide, or `.gitlab-ci.yml` file could also -be added through a button on the project page. In the example below, the license +The license, changelog, contribution guide, or `.gitlab-ci.yml` file can also +be added through a button on the project page. In this example, the license has already been created, which creates a link to the license itself.  NOTE: -The **Set up CI/CD** button will not appear on an empty repository. You have to at -least add a file in order for the button to show up. +The **Set up CI/CD** button does not appear on an empty repository. For the button +to display, add a file to your repository. ## 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 +doesn't work well for binary data such as images, PDFs, or other binary 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. +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 popup or use the **click to upload** link. A file -preview will appear once you have selected a file to upload. +After 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. After you +select a file to upload, a file preview displays. Enter a commit message, choose a branch, and click **Upload file** when you are ready. @@ -100,19 +99,22 @@ There are multiple ways to create a branch from the GitLab web interface. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2808) in GitLab 8.6. -If your development workflow dictates to have an issue for every merge -request, you can quickly create a branch directly from the issue to speed the process up. -The new branch, and later its merge request, will be marked as related to this issue. -Once merged, the MR will automatically close the issue. +If your development workflow requires an issue for every merge +request, you can create a branch directly from the issue to speed the process up. +The new branch, and later its merge request, are marked as related to this issue. +Once merged, the merge request closes the issue. You can see a **Create merge request** dropdown below the issue description. -NOTE: -You won't see the **Create merge request** button if there is already a branch with the same -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. This project will no longer be able to receive or send merge requests to the source project or other forks. +The **Create merge request** button doesn't display if: + +- A branch with the same name already exists. +- The branch already has a referenced merge request. +- Your project has an active fork relationship. + +To make this button appear, one possible workaround is to +[remove your project's fork relationship](../settings/index.md#removing-a-fork-relationship). +After removal, the fork relationship cannot be restored. This project can no longer +be able to receive or send merge requests to the source project, or other forks.  @@ -120,46 +122,47 @@ 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 -screenshot above will create a branch named +After selecting one of these options, a new branch or branch and merge request +is created based on your project's default branch. By default, this branch is `master`. +The branch name is based on an internal ID, and the issue title. The example +screenshot above creates a branch named `2-make-static-site-auto-deploy-and-serve`. When you click the **Create branch** button in an empty -repository project, GitLab automatically creates a `master` branch, commits -a blank `README.md` file to it, and creates and redirects you to a new branch -based on the issue title. -If your [project is already configured with a deployment service](../integrations/overview.md), -such as Kubernetes, GitLab takes one step further and prompts you to set up -[auto deploy](../../../topics/autodevops/stages.md#auto-deploy) -by helping you create a `.gitlab-ci.yml` file. +repository project, GitLab performs these actions: + +- Creates a `master` branch. +- Commits a blank `README.md` file to it. +- Creates and redirects you to a new branch based on the issue title. +- _If your project is [configured with a deployment service](../integrations/overview.md) like Kubernetes,_ + GitLab prompts you to set up [auto deploy](../../../topics/autodevops/stages.md#auto-deploy) + by helping you create a `.gitlab-ci.yml` file. After the branch is created, you can edit files in the repository to fix -the issue. When a merge request is created based on the newly created branch, -the description field will automatically display the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) -`Closes #ID`, where `ID` the ID of the issue. This will close the issue once the +the issue. When a merge request is created based on the newly-created branch, +the description field displays the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) +`Closes #ID`, where `ID` is the ID of the issue. This closes the issue when the 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 upfront. From a project's files page, -choose **New branch** from the dropdown. +request, you can create a new branch upfront. - +1. 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. -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. +  - +1. Enter a new **Branch name**. +1. (Optional) Change the **Create from** field to choose which branch, tag, or + commit SHA this new branch originates from. This field autocompletes if you + start typing an existing branch or tag. +1. Click **Create branch** to return to the file browser on this new 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. @@ -167,31 +170,35 @@ modify files. ## Create a new tag -Tags are useful for marking major milestones such as production releases, -release candidates, and more. You can create a tag from a branch or a commit -SHA. From a project's files page, choose **New tag** from the dropdown. +Tags help you mark major milestones such as production releases and +release candidates. You can create a tag from a branch or a commit +SHA: + +1. 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 -list page. +1. Give the tag a name such as `v1.0.0`. +1. Choose the branch or SHA from which you want to create this new tag. +1. (Optional) Add a message and release notes. The release notes section supports + Markdown format. +1. (Optional) Upload an attachment. +1. Click **Create tag**, and GitLab redirects you 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 -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. +trigger a new merge request rather than committing directly to `master`: + +1. Enter a new branch name in the **Target branch** field. +1. GitLab displays the **Start a new merge request with these changes** check box. +1. Commit your changes, and GitLab redirects you to a new merge request form. - +  -If you'd prefer _not_ to use your primary email address for commits created +If you'd prefer to not use your primary email address for commits created through the web editor, you can choose to use another of your linked email addresses from the **User Settings > Edit Profile** page. diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index c99b0d91523..4e239431d02 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -260,7 +260,8 @@ For GitLab.com, it is set to 10 MB. ## Export requirements to a CSV file -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290813) in GitLab 13.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290813) in GitLab 13.8. +> - Revised CSV column headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299247) in GitLab 13.9. You can export GitLab requirements to a [CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) sent to your default notification @@ -280,14 +281,29 @@ To export requirements: ### Exported CSV file format +<!-- vale gitlab.Spelling = NO --> You can preview the exported CSV file in a spreadsheet editor, such as Microsoft Excel, OpenOffice Calc, or Google Sheets. +<!-- vale gitlab.Spelling = YES --> -The exported CSV file contains the following columns: +The exported CSV file contains the following headers: -- Requirement ID -- Title -- Description -- Author Username -- Latest Test Report State -- Latest Test Report Created At (UTC) +- In GitLab 13.8: + + - Requirement ID + - Title + - Description + - Author Username + - Latest Test Report State + - Latest Test Report Created At (UTC) + +- In GitLab 13.9 and later: + + - Requirement ID + - Title + - Description + - Author + - Author Username + - Created At (UTC) + - State + - State Updated At (UTC) diff --git a/doc/user/project/security_dashboard.md b/doc/user/project/security_dashboard.md deleted file mode 100644 index d9440e8deea..00000000000 --- a/doc/user/project/security_dashboard.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../application_security/security_dashboard/index.md' ---- - -This document was moved to [another location](../application_security/security_dashboard/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 76156690fe7..7c66f078770 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -4,11 +4,11 @@ group: Certify info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Service Desk **(CORE)** +# Service Desk **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/149) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/214839) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215364) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215364) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.2. Service Desk is a module that allows your team to connect with any external party through email, without any external tools. @@ -34,7 +34,7 @@ It provides a unique email address for end users to create issues in a project. Follow-up notes can be sent either through the GitLab interface or by email. End users only see the thread through email. -For instance, let's assume you develop a game for iOS or Android. +For example, let's assume you develop a game for iOS or Android. The codebase is hosted in your GitLab instance, built and deployed with GitLab CI/CD. @@ -91,39 +91,59 @@ Service Desk is now enabled for this project! You should be able to access it fr > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/214839) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215364) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215364) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.2. An email is sent to the author when: - A user submits a new issue using Service Desk. - A new note is created on a Service Desk issue. -The body of these email messages can be customized by using templates. To create a new customized template, -create a new Markdown (`.md`) file inside the `.gitlab/service_desk_templates/` -directory in your repository. Commit and push to your default branch. +You can customize the body of these email messages with templates. +Save your templates in the `.gitlab/service_desk_templates/` +directory in your repository. + +With Service Desk, you can use templates for: + +- [Thank you emails](#thank-you-email) +- [New note emails](#new-note-email) +- [New Service Desk issues](#new-service-desk-issues) #### Thank you email -The **Thank you email** is the email sent to a user after they submit an issue. -The filename of the template has to be `thank_you.md`. -There are a few placeholders you can use which are automatically replaced in the email: +When a user submits an issue through Service Desk, GitLab sends a **thank you email**. +You must name the template file `thank_you.md`. + +You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID -As the Service Desk issues are created as confidential (only project members can see them) -the response email does not provide the issue link. +Because Service Desk issues are created as [confidential](issues/confidential_issues.md) (only project members can see them), +the response email does not contain the issue link. #### New note email -When a user-submitted issue receives a new comment, GitLab sends a **New note email** -to the user. The filename of this template must be `new_note.md`, and you can -use these placeholders in the email: +When a user-submitted issue receives a new comment, GitLab sends a **new note email**. +You must name the template file `new_note.md`. + +You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID - `%{NOTE_TEXT}`: note text +#### New Service Desk issues + +You can select one [issue description template](description_templates.md#creating-issue-templates) +**per project** to be appended to every new Service Desk issue's description. +Issue description templates should reside in your repository's `.gitlab/issue_templates/` directory. + +To use a custom issue template with Service Desk, in your project: + +1. [Create a description template](description_templates.md#creating-issue-templates) +1. Go to **Settings > General > Service Desk**. +1. From the dropdown **Template to append to all Service Desk issues**, select your template. + ### Using custom email display name > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7529) in GitLab 12.8. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 27727890383..6f230f1798a 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -18,7 +18,7 @@ The **GitLab import/export** button is displayed if the project import option is See also: - [Project import/export API](../../../api/project_import_export.md) -- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(CORE ONLY)** +- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(FREE SELF)** - [Group import/export](../../group/settings/import_export.md) - [Group import/export API](../../../api/group_import_export.md) @@ -180,14 +180,14 @@ all imported projects are given the visibility of `Private`. NOTE: The maximum import file size can be set by the Administrator, default is `0` (unlimited). -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. ### Project import status You can query an import through the [Project import/export API](../../../api/project_import_export.md#import-status). As described in the API documentation, the query may return an import error or exceptions. -### Import large projects **(CORE ONLY)** +### Import large projects **(FREE SELF)** If you have a larger project, consider using a Rake task, as described in our [developer documentation](../../../development/import_project.md#importing-via-a-rake-task). diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 26ef5e2260a..aa41f1c0233 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -40,6 +40,26 @@ You can select a framework label to identify that your project has certain compl NOTE: Compliance framework labels do not affect your project settings. +#### Custom compliance frameworks + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. +> - It's [deployed behind a feature flag](../../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-custom-compliance-frameworks). **(PREMIUM ONLY)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +GitLab 13.8 introduces custom compliance frameworks at the group-level. A group owner can create a compliance framework label +and assign it to any number of projects within that group or sub-groups. When this feature is enabled, projects can only +be assigned compliance framework labels that already exist within that group. + +If existing [Compliance frameworks](#compliance-framework) are not sufficient, you can now create +your own. + +New compliance framework labels can be created and updated using GraphQL. + ### Sharing and permissions For your repository, you can set up features such as public access, repository features, @@ -120,7 +140,7 @@ Set up your project's merge request settings: - Set up the merge request method (merge commit, [fast-forward merge](../merge_requests/fast_forward_merge.md)). - Add merge request [description templates](../description_templates.md#description-templates). -- Enable [merge request approvals](../merge_requests/merge_request_approvals.md). **(STARTER)** +- Enable [merge request approvals](../merge_requests/merge_request_approvals.md). - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). - Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved). - Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch) @@ -128,7 +148,7 @@ Set up your project's merge request settings:  -### Service Desk **(STARTER)** +### Service Desk Enable [Service Desk](../service_desk.md) for your project to offer customer support. @@ -245,8 +265,8 @@ To delete a project: 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 administrators can [configure](../../group/index.md#enabling-delayed-project-removal) projects within a group +- From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium](https://about.gitlab.com/pricing/) or higher tiers, +group owners 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). @@ -299,3 +319,22 @@ Add the URL of a Jaeger server to allow your users to [easily access the Jaeger [Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). + +### Enable or disable custom compliance frameworks **(PREMIUM ONLY)** + +Enabling or disabling custom compliance frameworks 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(:ff_custom_compliance_frameworks) +``` + +To disable it: + +```ruby +Feature.disable(:ff_custom_compliance_frameworks) +``` diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 39de9ab9ca2..590f549577e 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -8,13 +8,11 @@ type: reference, howto # Project access tokens NOTE: -Project access tokens are supported for self-managed instances on Core and above. They are also supported on GitLab.com Bronze and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). +Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. -> - It was [deployed](https://gitlab.com/groups/gitlab-org/-/epics/2587) behind a feature flag, disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/218722) in GitLab 13.3. -> - It's recommended for production use. -> - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in 13.5 for paid groups only. +> - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5 for paid groups only. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. WARNING: This feature might not be available to you. Check the **version history** note above for details. diff --git a/doc/user/project/slash_commands.md b/doc/user/project/slash_commands.md deleted file mode 100644 index 5844861c91e..00000000000 --- a/doc/user/project/slash_commands.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'quick_actions.md' ---- - -This document was moved to [user/project/quick_actions.md](quick_actions.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 07f122a7828..e4916d524e6 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -6,11 +6,11 @@ type: reference, how-to description: "The static site editor enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture or Git commands." --- -# Static Site Editor **(CORE)** +# Static Site Editor **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28758) in GitLab 12.10. > - WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214559) in GitLab 13.0. -> - Non-Markdown content blocks uneditable on the WYSIWYG mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216836) in GitLab 13.3. +> - Non-Markdown content blocks not editable on the WYSIWYG mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216836) in GitLab 13.3. > - Formatting Markdown [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49052) in GitLab 13.7. Static Site Editor (SSE) enables users to edit content on static websites without @@ -23,8 +23,8 @@ and submit the changes for review. The Static Site Editor allows collaborators to submit changes to static site files seamlessly. For example: -- Non-technical collaborators can easily edit a page directly from the browser; - they don't need to know Git and the details of your project to be able to contribute. +- Non-technical collaborators can edit a page directly from the browser. + They don't need to know Git and the details of your project to contribute. - Recently hired team members can quickly edit content. - Temporary collaborators can jump from project to project and quickly edit pages instead of having to clone or fork every single project they need to submit changes to. @@ -68,7 +68,7 @@ The editor can then navigate to the merge request to assign it to a colleague fo ## Set up your project First, set up the project. Once done, you can use the Static Site Editor to -easily [edit your content](#edit-content). +[edit your content](#edit-content). 1. To get started, create a new project from the [Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman) template. You can either [fork it](../repository/forking_workflow.md#creating-a-fork) @@ -101,7 +101,7 @@ To edit a file: wish to edit the raw Markdown instead, you can toggle the **Markdown** mode in the bottom-right corner. 1. When you're done, click **Submit changes...**. -1. (Optional) Adjust the default title and description of the merge request that will be submitted +1. (Optional) Adjust the default title and description of the merge request, to submit with your changes. Alternatively, select a [merge request template](../../../user/project/description_templates.md#creating-merge-request-templates) from the dropdown menu and edit it accordingly. 1. Click **Submit changes**. @@ -154,9 +154,9 @@ so you can verify the correct image is included and there aren't any references You can embed YouTube videos on the WYSIWYG mode by clicking the video icon (**{live-preview}**). The following URL/ID formats are supported: -- YouTube watch URL (e.g. `https://www.youtube.com/watch?v=0t1DgySidms`) -- YouTube embed URL (e.g. `https://www.youtube.com/embed/0t1DgySidms`) -- YouTube video ID (e.g. `0t1DgySidms`) +- **YouTube watch URLs**: `https://www.youtube.com/watch?v=0t1DgySidms` +- **YouTube embed URLs**: `https://www.youtube.com/embed/0t1DgySidms` +- **YouTube video IDs**: `0t1DgySidms` ### Front matter @@ -164,13 +164,13 @@ The following URL/ID formats are supported: > - Ability to edit page front matter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235921) in GitLab 13.5. Front matter is a flexible and convenient way to define page-specific variables in data files -intended to be parsed by a static site generator. It is commonly used for setting a page's -title, layout template, or author, but can be used to pass any kind of metadata to the +intended to be parsed by a static site generator. Use it to set a page's +title, layout template, or author. You can also pass any kind of metadata to the generator as the page renders out to HTML. Included at the very top of each data file, the -front matter is often formatted as YAML or JSON and requires consistent and accurate syntax. +front matter is often formatted as YAML or JSON, and requires consistent and accurate syntax. To edit the front matter from the Static Site Editor you can use the GitLab regular file editor, -the Web IDE, or easily update the data directly from the WYSIWYG editor: +the Web IDE, or update the data directly from the WYSIWYG editor: 1. Click the **Page settings** button on the bottom-right to reveal a web form with the data you have on the page's front matter. The form is populated with the current data: @@ -181,10 +181,16 @@ the Web IDE, or easily update the data directly from the WYSIWYG editor: 1. When you're done, click **Submit changes...**. 1. Describe your changes (add a commit message). 1. Click **Submit changes**. -1. Click **View merge request** and GitLab will take you there. +1. Click **View merge request** to view it. -Note that support for adding new attributes to the page's front matter from the form is not supported -yet. You can do so by editing the file locally, through the GitLab regular file editor, or through the Web IDE. Once added, the form will load the new fields. +Adding new attributes to the page's front matter from the form is not supported. +To add new attributes: + +- Edit the file locally +- Edit the file with the GitLab regular file editor. +- Edit the file with the Web IDE. + +After adding an attribute, the form loads the new fields. ## Configuration files @@ -206,8 +212,8 @@ use to customize behavior of the Static Site Editor (SSE). If the file does not default values which support a default Middleman project configuration are used. The [Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman) project template generates a file pre-populated with these defaults. -To customize the behavior of the SSE, edit `.gitlab/static-site-editor.yml`'s entries -(described in the table below) according to what works best for your project (respecting YAML syntax). +To customize the behavior of the SSE, edit `.gitlab/static-site-editor.yml`'s entries, +according to your project's needs. Make sure to respect YAML syntax. After the table, see an [example of the SSE configuration file](#gitlabstatic-site-editoryml-example). @@ -224,8 +230,9 @@ image_upload_path: 'source/images' # Relative path to the project's root. Don't ### Static Site Generator configuration The Static Site Editor uses Middleman's configuration file, `data/config.yml` -to customize the behavior of the project itself and to control the **Edit this -page** button, rendered through the file [`layout.erb`](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/-/blob/master/source/layouts/layout.erb). +to customize the behavior of the project itself. This file also controls the +**Edit this page** button, rendered through the file +[`layout.erb`](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/-/blob/master/source/layouts/layout.erb). To [configure the project template to your own project](#set-up-your-project), you must replace the `<username>` and `<project-name>` in the `data/config.yml` @@ -236,7 +243,7 @@ the Static Site Editor may use different configuration files or approaches. ## Using Other Static Site Generators -Although Middleman is the only Static Site Generator currently officially supported +Although Middleman is the only Static Site Generator officially supported by the Static Site Editor, you can configure your project's build and deployment to use a different Static Site Generator. In this case, use the Middleman layout as an example, and follow a similar approach to properly render an **Edit this page** diff --git a/doc/user/project/status_page/index.md b/doc/user/project/status_page/index.md deleted file mode 100644 index 513c410a6f9..00000000000 --- a/doc/user/project/status_page/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/incident_management/status_page.md' ---- - -This document was moved to [status_page.md](../../../operations/incident_management/status_page.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index c94795578ef..2b0ca38c57c 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -81,7 +81,7 @@ The following time units are available: Default conversion rates are 1mo = 4w, 1w = 5d and 1d = 8h. -### Limit displayed units to hours **(CORE ONLY)** +### Limit displayed units to hours **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29469/) in GitLab 12.1. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index af8e78afb28..69f58dad1dc 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -5,10 +5,10 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, how-to --- -# Web IDE **(CORE)** +# Web IDE **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Core in 10.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Free in 10.7. The Web IDE editor makes it faster and easier to contribute changes to your projects by providing an advanced editor with commit staging. @@ -22,11 +22,11 @@ and from merge requests. ## File finder -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18323) in [GitLab Core](https://about.gitlab.com/pricing/) 10.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18323) in [GitLab Free](https://about.gitlab.com/pricing/) 10.8. The file finder allows you to quickly open files in the current branch by searching for fragments of the file path. The file finder is launched using the keyboard shortcut -<kbd>Cmd</kbd>+<kbd>p</kbd>, <kbd>Ctrl</kbd>+<kbd>p</kbd>, or <kbd>t</kbd> +<kbd>Command</kbd>+<kbd>p</kbd>, <kbd>Control</kbd>+<kbd>p</kbd>, or <kbd>t</kbd> (when editor is not in focus). Type the filename or file path fragments to start seeing results. @@ -102,7 +102,7 @@ based on the [JSON Schema Store](https://www.schemastore.org/json/). 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)** +#### Enable or disable validation based on predefined schemas **(FREE SELF)** 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, @@ -154,7 +154,7 @@ Each schema entry supports two properties: ## Configure the Web IDE -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in [GitLab Core](https://about.gitlab.com/pricing/) 13.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in [GitLab Free](https://about.gitlab.com/pricing/) 13.1. The Web IDE supports configuration of certain editor settings by using [`.editorconfig` files](https://editorconfig.org/). When opening a file, the @@ -174,7 +174,7 @@ The Web IDE currently supports the following `.editorconfig` settings: ## Commit changes > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Core in 10.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Free in 10.7. > - From [GitLab 12.7 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/33441), files were automatically staged. > - From [GitLab 12.9 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/196609), support for staging files was removed to prevent loss of unstaged data. All your current changes necessarily have to be committed or discarded. @@ -202,7 +202,7 @@ shows you a preview of the merge request diff if you commit your changes. ## View CI job logs -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19279) in [GitLab Core](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19279) in [GitLab Free](https://about.gitlab.com/pricing/) 11.0. You can use the Web IDE to quickly fix failing tests by opening the branch or merge request in the Web IDE and opening the logs of the failed @@ -215,7 +215,7 @@ left. ## Switching merge requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19318) in [GitLab Core](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19318) in [GitLab Free](https://about.gitlab.com/pricing/) 11.0. To switch between your authored and assigned merge requests, click the dropdown in the top of the sidebar to open a list of merge requests. You need to commit or discard all your changes before switching to a different merge @@ -223,7 +223,7 @@ request. ## Switching branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20850) in [GitLab Core](https://about.gitlab.com/pricing/) 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20850) in [GitLab Free](https://about.gitlab.com/pricing/) 11.2. To switch between branches of the current project repository, click the dropdown in the top of the sidebar to open a list of branches. @@ -232,8 +232,8 @@ different branch. ## Markdown editing -> - Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18059) in [GitLab Core](https://about.gitlab.com/pricing/) 10.7. -> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in [GitLab Core](https://about.gitlab.com/pricing/) 13.1. +> - Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18059) in [GitLab Free](https://about.gitlab.com/pricing/) 10.7. +> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in [GitLab Free](https://about.gitlab.com/pricing/) 13.1. When you edit Markdown files in the Web IDE, you can preview your changes by clicking the **Preview Markdown** tab above the file editor. The Markdown preview @@ -246,7 +246,7 @@ added to the filename. ## Live Preview -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Core](https://about.gitlab.com/pricing/) 11.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Free](https://about.gitlab.com/pricing/) 11.2. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/213853) from _Client Side Evaluation_ to _Live Preview_ in GitLab 13.0. You can use the Web IDE to preview JavaScript projects right in the browser. @@ -285,7 +285,7 @@ below. ## Interactive Web Terminals for the Web IDE > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Core in 13.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Free in 13.1. WARNING: Interactive Web Terminals for the Web IDE is currently in **Beta**. @@ -307,7 +307,7 @@ to work: 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. - 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). **(ULTIMATE ONLY)** + [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **(ULTIMATE SELF)** If you have the terminal open and the job has finished with its tasks, the terminal blocks the job from finishing for the duration configured in @@ -389,7 +389,7 @@ click **Restart Terminal** to start a new terminal session. ### File syncing to web terminal > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) to GitLab Core in 13.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) to GitLab Free in 13.1. File changes in the Web IDE can be synced to a running web terminal. This enables users to test their code changes in a preconfigured terminal diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 779179a6665..087a9069c7c 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,11 +1,11 @@ --- stage: Create -group: Knowledge +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/#assignments" type: reference, how-to --- -# Wiki **(CORE)** +# Wiki **(FREE)** A separate system for documentation called Wiki, is built right into each GitLab project. It is enabled by default on all new projects and you can find diff --git a/doc/user/search/advanced_global_search.md b/doc/user/search/advanced_global_search.md index 1898bdf06a9..2d1a05cd966 100644 --- a/doc/user/search/advanced_global_search.md +++ b/doc/user/search/advanced_global_search.md @@ -5,9 +5,10 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Advanced Search **(STARTER)** +# Advanced Search **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109) in GitLab [Starter](https://about.gitlab.com/pricing/) 8.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109) in GitLab 8.4. +> - [Moved](../../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. NOTE: Advanced Search (powered by Elasticsearch) is enabled for Bronze and above on GitLab.com since 2020-07-10. diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index e3501be8e8e..19f7305124e 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -5,12 +5,10 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Advanced Search Syntax **(STARTER)** +# Advanced Search Syntax **(PREMIUM)** -> - Introduced in [GitLab Enterprise Starter](https://about.gitlab.com/pricing/) 9.2 - -NOTE: -Advanced Search (powered by Elasticsearch) is enabled for Bronze and above on GitLab.com since 2020-07-10. +> - Introduced in [GitLab](https://about.gitlab.com/pricing/) 9.2. +> - [Moved](../../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. Use advanced queries for more targeted search results. diff --git a/doc/user/search/img/search_history.gif b/doc/user/search/img/search_history.gif Binary files differdeleted file mode 100644 index 4cfa48ee0ab..00000000000 --- a/doc/user/search/img/search_history.gif +++ /dev/null diff --git a/doc/user/search/index.md b/doc/user/search/index.md index d229c27b608..7ea1c4cb307 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -9,16 +9,14 @@ type: index, reference, howto ## Issues and merge requests -To search through issues and merge requests in multiple projects, you can use the **Issues** or **Merge Requests** links -in the top-right part of your screen. +To search through issues and merge requests in multiple projects, use the **Issues** or **Merge Requests** links +in the top-right part of your screen. These instructions are valid for both. -Both of them work in the same way, therefore, the following notes are valid for both. - -The number displayed on their right represents the number of issues and merge requests assigned to you. +The number displayed on their right represents the number of issues and merge requests assigned to you:  -When you click **Issues**, the opened issues assigned to you are shown straight away: +When you click **Issues**, GitLab shows the opened issues assigned to you:  @@ -30,7 +28,7 @@ You can also filter the results using the search and filter field, as described ### Issues and MRs assigned to you or created by you GitLab shows shortcuts to issues and merge requests created by you or assigned to you -on the search field on the top-right of your screen: +in the search field in the upper right corner:  @@ -38,7 +36,7 @@ on the search field on the top-right of your screen: > - Filtering by Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. > - Filtering by child Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. -> - Filtering by Iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. +> - Filtering by Iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. [Moved](../../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. Follow these steps to filter the **Issues** and **Merge Requests** list pages in projects and groups: @@ -101,32 +99,34 @@ You can filter the **Issues** list to individual instances by their ID. For exam  -### Filtering merge requests by approvers **(STARTER)** +### Filtering merge requests by approvers **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9468) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9468) in GitLab 11.9. +> - [Moved](../../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. To filter merge requests by an individual approver, you can type (or select from the dropdown) **Approver** and select the user.  -### Filtering merge requests by "approved by" **(STARTER)** +### Filtering merge requests by "approved by" **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30335) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30335) in GitLab 13.0. +> - [Moved](../../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. To filter merge requests already approved by a specific individual, you can type (or select from the dropdown) **Approved-By** and select the user.  -### Filtering merge requests by reviewer **(CORE)** +### Filtering merge requests by reviewer **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47605) in GitLab 13.7. To filter review requested merge requests for a specific individual, you can type (or select from the dropdown) **Reviewer** and select the user. -### Filtering merge requests by environment or deployment date **(CORE)** +### Filtering merge requests by environment or deployment date **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44041) in GitLab 13.6. @@ -156,15 +156,16 @@ using the filter functionality, you can start typing characters to bring up relevant users or other attributes. For performance optimization, there is a requirement of a minimum of three -characters to begin your search. For example, if you want to search for -issues that have the assignee "Simone Presley", you must type at -least "Sim" before autocomplete gives any relevant results. +characters to begin your search. To search for issues with the assignee `Simone Presley`, +you must type at least `Sim` before autocomplete displays results. ## 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. +Search history is available for issues and merge requests, and is stored locally +in your browser. To run a search from history: - +1. In the top menu, click **Issues** or **Merge requests**. +1. To the left of the search bar, click **Recent searches**, and select a search from the list. ## Removing search filters @@ -174,7 +175,7 @@ To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Control</ ## Filtering with multiple filters of the same type -Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the AND logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results include only entries whereby the assignees are assigned to both Sam and Sarah are returned. +Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the `AND` logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results include only entries whereby the assignees are assigned to both Sam and Sarah are returned.  @@ -192,8 +193,8 @@ You can search through your projects from the left menu, by clicking the menu ba On the field **Filter by name**, type the project or group name you want to find, and GitLab filters them for you as you type. -You can also look for the projects you [starred](../project/index.md#star-a-project) (**Starred projects**), and **Explore** all -public and internal projects available in GitLab.com, from which you can filter by visibility, +You can also look for the projects you [starred](../project/index.md#star-a-project) (**Starred projects**). +You can **Explore** all public and internal projects available in GitLab.com, from which you can filter by visibility, through **Trending**, best rated with **Most stars**, or **All** of them. You can also sort them by **Name**, **Last created**, **Oldest created**, **Last updated**, @@ -217,7 +218,7 @@ and sort them by **Last created**, **Oldest created**, **Last updated**, or **Ol From an [Issue Board](../../user/project/issue_board.md), you can filter issues by **Author**, **Assignee**, **Milestone**, and **Labels**. You can also filter them by name (issue title), from the field **Filter by name**, which is loaded as you type. -When you want to search for issues to add to lists present in your Issue Board, click +To search for issues to add to lists present in your Issue Board, click the button **Add issues** on the top-right of your screen, opening a modal window from which you can, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**, and **Labels**, select multiple issues to add to a list of your choice: @@ -226,10 +227,14 @@ and **Labels**, select multiple issues to add to a list of your choice: ## Shortcut -GitLab shows a shortcut on the search field on the top-right of the project's dashboard to -quickly access issues and merge requests created or assigned to you in that project: +To view issues and merge requests created or assigned to you in a project: + +1. Go to your project. +1. In the top navigation bar, click the search box to display a list of issues and + merge requests. +1. Select your desired issue or merge request: - +  ### Autocomplete suggestions @@ -246,7 +251,7 @@ You can also type in this search bar to see autocomplete suggestions for: ## Basic search -The Basic search in GitLab is a global search service that allows you to search +The Basic search in GitLab enables you to search across the entire GitLab instance, in a group, or in a single project. Basic search is backed by the database and allows searching in: @@ -288,14 +293,14 @@ redirected to the commit result and given the option to return to the search res  -## Advanced Search **(STARTER)** +## Advanced Search **(PREMIUM)** Leverage Elasticsearch for faster, more advanced code search across your entire GitLab instance. [Learn how to use the Advanced Search.](advanced_global_search.md) -## Advanced Search Syntax **(STARTER)** +## Advanced Search Syntax **(PREMIUM)** Use advanced queries for more targeted search results. @@ -307,7 +312,7 @@ Use advanced queries for more targeted search results. > - It's [deployed behind a feature flag](../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-search-project-settings). **(CORE ONLY)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-search-project-settings). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -318,7 +323,7 @@ appear highlighted in the sections that match the search term.  -### Enable or disable Search project settings **(CORE ONLY)** +### Enable or disable Search project settings **(FREE SELF)** Search project settings is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default**. diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 282e3296735..014555cffed 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -35,6 +35,7 @@ These shortcuts are available in most areas of GitLab | <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. | | <kbd>p</kbd> + <kbd>b</kbd> | Show/hide the Performance Bar. | +| <kbd>g</kbd> + <kbd>x</kbd> | Toggle between [GitLab](https://gitlab.com/) and [GitLab Next](https://next.gitlab.com/) (GitLab SaaS only). | Additionally, the following shortcuts are available when editing text in text fields, for example comments, replies, issue descriptions, and merge request descriptions: @@ -42,10 +43,10 @@ for example comments, replies, issue descriptions, and merge request description | Keyboard Shortcut | 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 `[]()`). | +| <kbd>⌘</kbd> (Mac) / <kbd>Control</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>Control</kbd> + <kbd>b</kbd> | Bold the selected text (surround it with `**`). | +| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>i</kbd> | Italicize the selected text (surround it with `_`). | +| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>k</kbd> | Add a link (surround the selected text with `[]()`). | NOTE: The shortcuts for editing in text fields are always enabled, even when @@ -104,7 +105,7 @@ These shortcuts are available when browsing the files in a project (navigate to | <kbd>↑</kbd> | Move selection up. | | <kbd>↓</kbd> | Move selection down. | | <kbd>enter</kbd> | Open selection. | -| <kbd>esc</kbd> | Go back to file list screen (only while searching for files, **Repository > Files** then click on **Find File**). | +| <kbd>Escape</kbd> | Go back to file list screen (only while searching for files, **Repository > Files** then click on **Find File**). | | <kbd>y</kbd> | Go to file permalink (only while viewing a file). | ### Web IDE @@ -113,8 +114,8 @@ These shortcuts are available when editing a file with the [Web IDE](project/web | Keyboard Shortcut | Description | | ------------------------------------------------------- | ----------- | -| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>p</kbd> | Search for, and then open another file for editing. | -| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>Enter</kbd> | Commit (when editing the commit message). | +| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>p</kbd> | Search for, and then open another file for editing. | +| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Enter</kbd> | Commit (when editing the commit message). | ### Repository Graph @@ -145,7 +146,7 @@ These shortcuts are available when using a [filtered search input](search/index. | Keyboard Shortcut | Description | | ----------------------------------------------------- | ----------- | | <kbd>⌘</kbd> (Mac) + <kbd>⌫</kbd> | Clear entire search filter. | -| <kbd>⌥</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>⌫</kbd> | Clear one token at a time. | +| <kbd>⌥</kbd> (Mac) / <kbd>Control</kbd> + <kbd>⌫</kbd> | Clear one token at a time. | ## Epics **(ULTIMATE)** diff --git a/doc/user/snippets.md b/doc/user/snippets.md index af499221da6..e919e73f404 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -65,8 +65,8 @@ have version control enabled by default. This means that all snippets get their own underlying repository initialized with a `master` branch at the moment the snippet is created. Whenever a change to the snippet is saved, a -new commit to the master branch is recorded. Commit messages are automatically -generated. The snippet's repository has only one branch (master) by default, deleting +new commit to the `master` branch is recorded. Commit messages are automatically +generated. The snippet's repository has only one branch (`master`) by default, deleting it or creating other branches is not supported. Existing snippets are automatically migrated in 13.0. Their current @@ -75,14 +75,14 @@ content is saved as the initial commit to the snippets' repository. ### Filenames Snippets support syntax highlighting based on the filename and -extension provided for them. While it is possible to submit a snippet +extension provided for them. While you can submit a snippet without specifying a filename and extension, it needs a valid name so the content can be created as a file in the snippet's repository. -In case the user does not attribute a filename and extension to a snippet, -GitLab automatically adds a filename in the format `snippetfile<x>.txt` +If you don't attribute a filename and extension to a snippet, +GitLab adds a filename in the format `snippetfile<x>.txt` where `<x>` represents a number added to the file, starting with 1. This -number increases incrementally when more snippets without an attributed +number increments when more snippets without an attributed filename are added. When upgrading from an earlier version of GitLab to 13.0, existing snippets @@ -96,14 +96,15 @@ direct or embedded links to the snippet. > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2829) in GitLab 13.5. -GitLab Snippets support multiple files in one single snippet. It can be very handy +GitLab Snippets support multiple files in one single snippet. This is helpful when your code snippet is composed of multiple parts or when they relate to a certain context. For example: - A snippet that includes a script and its output. - A snippet that includes HTML, CSS, and JS code. - A snippet with a `docker-compose.yml` file and its associated `.env` file. -- A `gulpfile.js` file coupled with a `package.json` file, which together can be used to bootstrap a project and manage its dependencies. +- A `gulpfile.js` file coupled with a `package.json` file, which together can be + used to bootstrap a project and manage its dependencies. Snippets support between 1 and 10 files. They can be managed via Git (because they're [versioned](#versioned-snippets) by a Git repository), through the [Snippets API](../api/snippets.md), or in the GitLab UI. @@ -135,7 +136,7 @@ button above the snippet content to copy the URL of your choice. This allows you to have a local copy of the snippet's repository and make changes as needed. You can commit those changes and push them to the remote -master branch. +`master` branch. ### Reduce snippets repository size @@ -148,15 +149,15 @@ see the documentation on [reducing repository size](../user/project/repository/r ### Limitations - Binary files are not supported. -- Creating or deleting branches is not supported. Only a default *master* branch is used. +- Creating or deleting branches is not supported. Only a default `master` branch is used. - Git tags are not supported in snippet repositories. - Snippets' repositories are limited to 10 files. Attempting to push more -than 10 files results in an error. -- Revisions are not *yet* visible to the user on the GitLab UI, but -it's planned to be added in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) -for updates. + than 10 files results in an error. +- Revisions are not visible to the user on the GitLab UI, but this feature is planned + in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) + for updates. - The [maximum size for a snippet](../administration/snippets/index.md#snippets-content-size-limit) -is 50 MB, by default. + is 50 MB, by default. - Git LFS is not supported. ## Discover snippets @@ -168,10 +169,10 @@ dashboard of your GitLab instance via the top navigation. For GitLab.com you can navigate to an [overview]((https://gitlab.com/dashboard/snippets)) that shows snippets you created and allows you to explore all snippets. -If you want to discover snippets that belong to a specific project, you can navigate +To discover snippets that belong to a specific project, navigate to the Snippets page via the left side navigation on the project page. -Project snippets are enabled and available by default, but they can -be disabled by navigating to your project's **Settings**, expanding +Project snippets are enabled and available by default. You can +disable them by navigating to your project's **Settings**, expanding **Visibility, project features, permissions** and scrolling down to **Snippets**. From there, you can toggle to disable them or select a different visibility level from the dropdown menu. @@ -181,7 +182,7 @@ different visibility level from the dropdown menu. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/12910) in GitLab 9.2. With GitLab Snippets you engage in a conversation about that piece of code, -facilitating the collaboration among users. +encouraging user collaboration. ## Downloading snippets @@ -207,20 +208,23 @@ To embed a snippet, first make sure that: - In **Project > Settings > Permissions**, the snippets permissions are set to **Everyone with access** -After the above conditions are met, the "Embed" section appears in your -snippet where you can simply click on the "Copy" button. This copies a one-line -script that you can add to any website or blog post. - -Here's how an example code looks like: +After the above conditions are met, the **Embed** section appears in your +snippet. Click the **Copy** button to copy a one-line +script that you can add to any website or blog post. For example: ```html <script src="https://gitlab.com/namespace/project/snippets/SNIPPET_ID.js"></script> ``` -Here's how an embedded snippet looks like: +Here's what an embedded snippet looks like: <script src="https://gitlab.com/gitlab-org/gitlab-foss/snippets/1717978.js"></script> -Embedded snippets are displayed with a header that shows the filename if it's defined, -the snippet size, a link to GitLab, and the actual snippet content. Actions in -the header allow users to see the snippet in raw format and download it. +Embedded snippets are displayed with a header that shows: + +- The filename, if defined. +- The snippet size. +- A link to GitLab. +- The actual snippet content. + +Actions in the header enable users to see the snippet in raw format, and download it. diff --git a/doc/user/todos.md b/doc/user/todos.md index 27a849719c5..57ab7d4d888 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -5,7 +5,7 @@ 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/#assignments --- -# GitLab To-Do List **(CORE)** +# GitLab To-Do List **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2817) in GitLab 8.5. diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 8662efc03a7..c82fc6ab432 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Storage usage quota -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/13294) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/13294) in GitLab 12.0. > - Moved to GitLab Free. A project's repository has a free storage quota of 10 GB. When a project's repository reaches @@ -32,11 +32,11 @@ namespace to trigger a recalculation. A stacked bar graph shows the proportional storage used for the namespace, including a total per storage item. Click on each project's title to see a breakdown per storage item. -## Storage usage statistics **(BRONZE ONLY)** +## Storage usage statistics > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247831) in GitLab 13.7. > - It's [deployed behind a feature flag](../user/feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. +> - It's enabled on GitLab SaaS. > - It's recommended for production use. WARNING: |
