diff --git a/app/helpers/search_helper.rb b/app/helpers/search_helper.rb
index e07ee22339a5428b782bcbc5e4ee46c6d270b24e..0722e420134111bf64e71b7c323778eef310334c 100644
--- a/app/helpers/search_helper.rb
+++ b/app/helpers/search_helper.rb
@@ -177,7 +177,7 @@ def help_autocomplete
{ category: "Help", label: _("Permissions Help"), url: help_page_path("user/permissions") },
{ category: "Help", label: _("Public Access Help"), url: help_page_path("public_access/public_access") },
{ category: "Help", label: _("Rake Tasks Help"), url: help_page_path("raketasks/README") },
- { category: "Help", label: _("SSH Keys Help"), url: help_page_path("ssh/README") },
+ { category: "Help", label: _("SSH Keys Help"), url: help_page_path("ssh/index") },
{ category: "Help", label: _("System Hooks Help"), url: help_page_path("system_hooks/system_hooks") },
{ category: "Help", label: _("Webhooks Help"), url: help_page_path("user/project/integrations/webhooks") }
]
diff --git a/app/views/profiles/keys/index.html.haml b/app/views/profiles/keys/index.html.haml
index 69b8d2ddafe0870c547d9b8fa96d5417294133bb..584bd44e3860f7e0b7def6c0e3cc74e0c2e64f09 100644
--- a/app/views/profiles/keys/index.html.haml
+++ b/app/views/profiles/keys/index.html.haml
@@ -11,8 +11,8 @@
%h5.gl-mt-0
= _('Add an SSH key')
%p.profile-settings-content
- - generate_link_url = help_page_path("ssh/README", anchor: 'generate-an-ssh-key-pair')
- - existing_link_url = help_page_path("ssh/README", anchor: 'see-if-you-have-an-existing-ssh-key-pair')
+ - generate_link_url = help_page_path("ssh/index", anchor: 'generate-an-ssh-key-pair')
+ - existing_link_url = help_page_path("ssh/index", anchor: 'see-if-you-have-an-existing-ssh-key-pair')
- generate_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: generate_link_url }
- existing_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: existing_link_url }
= _('To add an SSH key you need to %{generate_link_start}generate one%{link_end} or use an %{existing_link_start}existing key%{link_end}.').html_safe % { generate_link_start: generate_link_start, existing_link_start: existing_link_start, link_end: '</a>'.html_safe }
diff --git a/app/views/shared/deploy_keys/_form.html.haml b/app/views/shared/deploy_keys/_form.html.haml
index 452e54f9cd49144f9a2ea40d4aa6cf6ca5998b57..bf2514f8b0d45e385cf71be172b8d66dd5855772 100644
--- a/app/views/shared/deploy_keys/_form.html.haml
+++ b/app/views/shared/deploy_keys/_form.html.haml
@@ -13,7 +13,7 @@
= form.label :key, class: 'col-form-label col-sm-2'
.col-sm-10
%p.light
- - link_start = "<a href='#{help_page_path('ssh/README')}' target='_blank' rel='noreferrer noopener'>".html_safe
+ - link_start = "<a href='#{help_page_path('ssh/index')}' target='_blank' rel='noreferrer noopener'>".html_safe
- link_end = '</a>'
= _('Paste a public key here. %{link_start}How do I generate it?%{link_end}').html_safe % { link_start: link_start, link_end: link_end.html_safe }
= form.text_area :key, class: 'form-control gl-form-input thin_area', rows: 5, data: { qa_selector: 'deploy_key_field' }
diff --git a/app/views/shared/deploy_keys/_project_group_form.html.haml b/app/views/shared/deploy_keys/_project_group_form.html.haml
index 0c671b4a1c06d093392655d5dc3164270c80ce72..8da48a7936aec62d5bd48faa0c05d043b2ead904 100644
--- a/app/views/shared/deploy_keys/_project_group_form.html.haml
+++ b/app/views/shared/deploy_keys/_project_group_form.html.haml
@@ -9,7 +9,7 @@
.form-group.row
%p.light.gl-mb-0
= _('Paste a public key here.')
- = link_to _('How do I generate it?'), help_page_path("ssh/README")
+ = link_to _('How do I generate it?'), help_page_path("ssh/index")
= f.fields_for :deploy_keys_projects do |deploy_keys_project_form|
.form-group.row
diff --git a/doc/README.md b/doc/README.md
index a56f17e3bf0157f4e6f856c4a95d34718229cd40..5ab8653dc35a543efd7c42b0da608637aae27c62 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -1,126 +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
-description: 'Learn how to use and administer GitLab, the most scalable Git-based fully integrated platform for software development.'
+redirect_to: 'index.md'
---
-<div class="d-none">
- <h3>Visit <a href="https://docs.gitlab.com/ee/">docs.gitlab.com</a> for the latest version
- of this help information with enhanced navigation, discoverability, and readability.</h3>
-</div>
-<!-- the div above will not display on the docs site but will display on /help -->
+This document was moved to [another location](index.md).
-# GitLab Docs
-
-Welcome to [GitLab](https://about.gitlab.com/) documentation.
-
-Here you can access the complete documentation for GitLab, the single application for the
-[entire DevOps lifecycle](#the-entire-devops-lifecycle).
-
-## Overview
-
-No matter how you use GitLab, we have documentation for you.
-
-| 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/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) | 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
-
-GitLab is the first single application for software development, security,
-and operations that enables [Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/).
-GitLab makes the software lifecycle faster and radically improves the speed of business.
-
-GitLab provides solutions for [each of the stages of the DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/).
-
-## New to Git and GitLab?
-
-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/index.md) | Start working on the command line and with GitLab. |
-| [GitLab workflow overview](https://about.gitlab.com/topics/version-control/what-is-gitlab-workflow/) | 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. |
-| [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. |
-| [User settings](user/profile/index.md#access-your-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 |
-|:-----------------------------------------------------------------------------|:------------|
-| [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. |
-
-## Coming to GitLab from another platform
-
-If you are coming to GitLab from another platform, the following information is useful:
-
-| 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. |
-
-## 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. |
-| [GitLab GraphQL API](api/graphql/index.md) | Integrate with GitLab using our GraphQL API. |
-| [Integrations](integration/index.md) | Integrations with third-party products. |
-
-## Contributing to GitLab
-
-GitLab Community Edition is [open source](https://gitlab.com/gitlab-org/gitlab-foss/)
-and GitLab Enterprise Edition is [open-core](https://gitlab.com/gitlab-org/gitlab/).
-
-Learn how to contribute to GitLab with the following resources:
-
-| Topic | Description |
-|:------------------------------------------------------------|:------------|
-| [Development](development/README.md) | How to contribute to GitLab development. |
-| [Legal](legal/index.md) | Contributor license agreements. |
-| [Writing documentation](development/documentation/index.md) | How to contribute to GitLab Docs. |
+<!-- This redirect file can be deleted after 2021-09-28. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
diff --git a/doc/administration/auth/index.md b/doc/administration/auth/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..a072cc73c43d9aa4e1b36a563d0014e3931d5f61
--- /dev/null
+++ b/doc/administration/auth/index.md
@@ -0,0 +1,52 @@
+---
+comments: false
+type: index
+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 authentication and authorization **(FREE SELF)**
+
+GitLab integrates with the following external authentication and authorization
+providers:
+
+- [Atlassian](atlassian.md)
+- [Auth0](../../integration/auth0.md)
+- [Authentiq](authentiq.md)
+- [AWS Cognito](cognito.md)
+- [Azure](../../integration/azure.md)
+- [Bitbucket Cloud](../../integration/bitbucket.md)
+- [CAS](../../integration/cas.md)
+- [Crowd](crowd.md)
+- [Facebook](../../integration/facebook.md)
+- [GitHub](../../integration/github.md)
+- [GitLab.com](../../integration/gitlab.md)
+- [Google OAuth](../../integration/google.md)
+- [JWT](jwt.md)
+- [Kerberos](../../integration/kerberos.md)
+- [LDAP](ldap/index.md): Includes Active Directory, Apple Open Directory, Open LDAP,
+ and 389 Server.
+ - [Google Secure LDAP](ldap/google_secure_ldap.md)
+- [Salesforce](../../integration/salesforce.md)
+- [SAML](../../integration/saml.md)
+- [SAML for GitLab.com groups](../../user/group/saml_sso/index.md) **(PREMIUM SAAS)**
+- [Shibboleth](../../integration/shibboleth.md)
+- [Smartcard](smartcard.md) **(PREMIUM SELF)**
+- [Twitter](../../integration/twitter.md)
+
+NOTE:
+UltraAuth has removed their software which supports OmniAuth integration. We have therefore removed all references to UltraAuth integration.
+
+## SaaS vs Self-Managed Comparison
+
+The external authentication and authorization providers may support the following capabilities.
+For more information, see the links shown on this page for each external provider.
+
+| Capability | SaaS | Self-Managed |
+|-------------------------------------------------|-----------------------------------------|------------------------------------|
+| **User Provisioning** | SCIM<br>JIT Provisioning | LDAP Sync |
+| **User Detail Updating** (not group management) | Not Available | LDAP Sync |
+| **Authentication** | SAML at top-level group (1 provider) | LDAP (multiple providers)<br>Generic OAuth2<br>SAML (only 1 permitted per unique provider)<br>Kerberos<br>JWT<br>Smartcard<br>OmniAuth Providers (only 1 permitted per unique provider) |
+| **Provider-to-GitLab Role Sync** | SAML Group Sync | LDAP Group Sync |
+| **User Removal** | SCIM (remove user from top-level group) | LDAP (Blocking User from Instance) |
diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md
index b381cee5c2db4435332515fbb4bd382f4152ae75..4f90d049ed0e7b6403d5bbf08ea77fc7cd3c5d43 100644
--- a/doc/administration/compliance.md
+++ b/doc/administration/compliance.md
@@ -10,7 +10,7 @@ You can configure the following GitLab features to help ensure that your GitLab
instance meets common compliance standards. Click a feature name for additional
documentation.
-The [security features](../security/README.md) in GitLab may also help you meet
+The [security features](../security/index.md) in GitLab may also help you meet
relevant compliance standards.
| Feature | GitLab tier | GitLab SaaS | Product level |
diff --git a/doc/administration/configure.md b/doc/administration/configure.md
index 12a8f721ccfa9b7f827476574b8709cd18268c79..73fbf527fe166878314f5ffac400ffee44add273 100644
--- a/doc/administration/configure.md
+++ b/doc/administration/configure.md
@@ -9,7 +9,7 @@ type: reference
Customize and configure your self-managed GitLab installation.
-- [Authentication](auth/README.md)
+- [Authentication](auth/index.md)
- [Configuration](../user/admin_area/index.md)
- [Repository storage](repository_storage_paths.md)
- [Geo](geo/index.md)
diff --git a/doc/administration/geo/replication/usage.md b/doc/administration/geo/replication/usage.md
index 1491aa3427eea7d77f8df5cb376e747471298f88..7fe8eec467e20c7b6ee40058a626415aaaf4242e 100644
--- a/doc/administration/geo/replication/usage.md
+++ b/doc/administration/geo/replication/usage.md
@@ -27,7 +27,7 @@ Everything up-to-date
```
NOTE:
-If you're using HTTPS instead of [SSH](../../../ssh/README.md) to push to the secondary,
+If you're using HTTPS instead of [SSH](../../../ssh/index.md) to push to the secondary,
you can't store credentials in the URL like `user:password@URL`. Instead, you can use a
[`.netrc` file](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html)
for Unix-like operating systems or `_netrc` for Windows. In that case, the credentials
diff --git a/doc/administration/index.md b/doc/administration/index.md
index 69e8689c589257fa7ff5d99d42c172e9446adfc6..b53b9754ee2c333479f6aa0d2b0809379f27e73a 100644
--- a/doc/administration/index.md
+++ b/doc/administration/index.md
@@ -43,7 +43,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
- [Adjust your instance's timezone](timezone.md): Customize the default time zone of GitLab.
- [System hooks](../system_hooks/system_hooks.md): Notifications when users, projects and keys are changed.
-- [Security](../security/README.md): Learn what you can do to further secure your GitLab instance.
+- [Security](../security/index.md): Learn what you can do to further secure your GitLab instance.
- [Usage statistics, version check, and usage ping](../user/admin_area/settings/usage_statistics.md): Enable or disable information about your instance to be sent to GitLab, Inc.
- [Global user settings](user_settings.md): Configure instance-wide user permissions.
- [Polling](polling.md): Configure how often the GitLab UI polls for updates.
@@ -122,7 +122,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
- [Libravatar](libravatar.md): Use Libravatar instead of Gravatar for user avatars.
- [Sign-up restrictions](../user/admin_area/settings/sign_up_restrictions.md): block email addresses of specific domains, or whitelist only specific domains.
- [Access restrictions](../user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols): Define which Git access protocols can be used to talk to GitLab (SSH, HTTP, HTTPS).
-- [Authentication and Authorization](auth/README.md): Configure external authentication with LDAP, SAML, CAS, and additional providers.
+- [Authentication and Authorization](auth/index.md): Configure external authentication with LDAP, SAML, CAS, and additional providers.
- [Sync LDAP](auth/ldap/index.md)
- [Kerberos authentication](../integration/kerberos.md)
- See also other [authentication](../topics/authentication/index.md#gitlab-administrators) topics (for example, enforcing 2FA).
@@ -241,7 +241,7 @@ who are aware of the risks.
- [GitLab Rails console commands](troubleshooting/gitlab_rails_cheat_sheet.md) (for Support Engineers)
- [Troubleshooting SSL](troubleshooting/ssl.md)
- Related links:
- - [GitLab Developer Documentation](../development/README.md)
+ - [GitLab Developer Documentation](../development/index.md)
- [Repairing and recovering broken Git repositories](https://git.seveas.net/repairing-and-recovering-broken-git-repositories.html)
- [Testing with OpenSSL](https://www.feistyduck.com/library/openssl-cookbook/online/ch-testing-with-openssl.html)
- [`strace` zine](https://wizardzines.com/zines/strace/)
diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md
index 341c6bfbc65e5bf41ed9247b04dc7231349834c3..994c194c6db7ca44923148341483b9f10ad31edf 100644
--- a/doc/administration/troubleshooting/postgresql.md
+++ b/doc/administration/troubleshooting/postgresql.md
@@ -55,7 +55,7 @@ This section is for links to information elsewhere in the GitLab documentation.
- Including [troubleshooting](../postgresql/replication_and_failover.md#troubleshooting)
`gitlab-ctl patroni check-leader` and PgBouncer errors.
-- [Developer database documentation](../../development/README.md#database-guides),
+- [Developer database documentation](../../development/index.md#database-guides),
some of which is absolutely not for production use. Including:
- Understanding EXPLAIN plans.
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 7080ce82b2cdf50b5ec6568dc05cf893e012e1b6..30de2dc957f891a434853ac6c206d4590e5a82d8 100644
--- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md
+++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md
@@ -106,7 +106,7 @@ sudo apt install acl
### Add SSH key
-Let's suppose we want to deploy our app to the production server from a private repository on GitLab. First, we need to [generate a new SSH key pair **with no passphrase**](../../../ssh/README.md) for the deployer user.
+Let's suppose we want to deploy our app to the production server from a private repository on GitLab. First, we need to [generate a new SSH key pair **with no passphrase**](../../../ssh/index.md) for the deployer user.
After that, we need to copy the private key, which will be used to connect to our server as the deployer user with SSH, to be able to automate our deployment process:
diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md
index a64efd50f6f71cdde0e1ee31359d137b7123665f..d23118f7c3864735fc1c4d02f2e9ef13818c5408 100644
--- a/doc/ci/review_apps/index.md
+++ b/doc/ci/review_apps/index.md
@@ -22,7 +22,7 @@ Review Apps:
- Provide an automatic live preview of changes made in a feature branch by spinning up a dynamic environment for your merge requests.
- Allow designers and product managers to see your changes without needing to check out your branch and run your changes in a sandbox environment.
-- Are fully integrated with the [GitLab DevOps LifeCycle](../../README.md#the-entire-devops-lifecycle).
+- Are fully integrated with the [GitLab DevOps LifeCycle](../../index.md#the-entire-devops-lifecycle).
- Allow you to deploy your changes wherever you want.
diff --git a/doc/ci/ssh_keys/index.md b/doc/ci/ssh_keys/index.md
index 85755f9a17921219c0ae83b695b99dd2da32f62d..6e1b5df6995e642cfca70605fe3fdde4e3f13ae7 100644
--- a/doc/ci/ssh_keys/index.md
+++ b/doc/ci/ssh_keys/index.md
@@ -48,7 +48,7 @@ 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).
+ the instructions to [generate an SSH key](../../ssh/index.md#generate-an-ssh-key-pair).
**Do not** add a passphrase to the SSH key, or the `before_script` will
prompt for it.
@@ -124,7 +124,7 @@ on, and use that key for all projects that are run on this machine.
```
1. Generate the SSH key pair as described in the instructions to
- [generate an SSH key](../../ssh/README.md#generate-an-ssh-key-pair).
+ [generate an SSH key](../../ssh/index.md#generate-an-ssh-key-pair).
**Do not** add a passphrase to the SSH key, or the `before_script` will
prompt for it.
diff --git a/doc/development/README.md b/doc/development/README.md
index bc996fdff21bbc10d34d4b863f198699bde5135f..5ab8653dc35a543efd7c42b0da608637aae27c62 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -1,308 +1,8 @@
---
-comments: false
-type: index, dev
-stage: none
-group: Development
-info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines"
-description: "Development Guidelines: learn how to contribute to GitLab."
+redirect_to: 'index.md'
---
-# Contributor and Development Docs
+This document was moved to [another location](index.md).
-Learn the processes and technical information needed for contributing to GitLab.
-
-This content is intended for members of the GitLab Team as well as community
-contributors. Content specific to the GitLab Team should instead be included in
-the [Handbook](https://about.gitlab.com/handbook/).
-
-For information on using GitLab to work on your own software projects, see the
-[GitLab user documentation](../user/index.md).
-
-For information on working with the GitLab APIs, see the [API documentation](../api/README.md).
-
-For information about how to install, configure, update, and upgrade your own
-GitLab instance, see the [administration documentation](../administration/index.md).
-
-## Get started
-
-- Set up the GitLab development environment with the
- [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/README.md)
-- [GitLab contributing guide](contributing/index.md)
- - [Issues workflow](contributing/issue_workflow.md) for more information about:
- - Issue tracker guidelines.
- - Triaging.
- - Labels.
- - Feature proposals.
- - Issue weight.
- - Regression issues.
- - Technical or UX debt.
- - [Merge requests workflow](contributing/merge_request_workflow.md) for more
- information about:
- - Merge request guidelines.
- - Contribution acceptance criteria.
- - Definition of done.
- - Dependencies.
- - [Style guides](contributing/style_guides.md)
- - [Implement design & UI elements](contributing/design.md)
-- [GitLab Architecture Overview](architecture.md)
-- [Rake tasks](rake_tasks.md) for development
-
-## Processes
-
-**Must-reads:**
-
-- [Guide on adapting existing and introducing new components](architecture.md#adapting-existing-and-introducing-new-components)
-- [Code review guidelines](code_review.md) for reviewing code and having code
- reviewed
-- [Database review guidelines](database_review.md) for reviewing
- database-related changes and complex SQL queries, and having them reviewed
-- [Secure coding guidelines](secure_coding_guidelines.md)
-- [Pipelines for the GitLab project](pipelines.md)
-
-Complementary reads:
-
-- [GitLab core team & GitLab Inc. contribution process](https://gitlab.com/gitlab-org/gitlab/-/blob/master/PROCESS.md)
-- [Security process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer)
-- [Guidelines for implementing Enterprise Edition features](ee_features.md)
-- [Danger bot](dangerbot.md)
-- [Guidelines for changelogs](changelog.md)
-- [Requesting access to ChatOps on GitLab.com](chatops_on_gitlabcom.md#requesting-access) (for GitLab team members)
-- [Patch release process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/patch/process.md#process-for-developers)
-- [Adding a new service component to GitLab](adding_service_component.md)
-
-### Development guidelines review
-
-When you submit a change to the GitLab development guidelines, who
-you ask for reviews depends on the level of change.
-
-#### Wording, style, or link changes
-
-Not all changes require extensive review. For example, MRs that don't change the
-content's meaning or function can be reviewed, approved, and merged by any
-maintainer or Technical Writer. These can include:
-
-- Typo fixes.
-- Clarifying links, such as to external programming language documentation.
-- Changes to comply with the [Documentation Style Guide](documentation/index.md)
- that don't change the intent of the documentation page.
-
-#### Specific changes
-
-If the MR proposes changes that are limited to a particular stage, group, or team,
-request a review and approval from an experienced GitLab Team Member in that
-group. For example, if you're documenting a new internal API used exclusively by
-a given group, request an engineering review from one of the group's members.
-
-After the engineering review is complete, assign the MR to the
-[Technical Writer associated with the stage and group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments)
-in the modified documentation page's metadata.
-
-If you have questions or need further input, request a review from the
-Technical Writer assigned to the [Development Guidelines](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines).
-
-#### Broader changes
-
-Some changes affect more than one group. For example:
-
-- Changes to [code review guidelines](code_review.md).
-- Changes to [commit message guidelines](contributing/merge_request_workflow.md#commit-messages-guidelines).
-- Changes to guidelines in [feature flags in development of GitLab](feature_flags/).
-- Changes to [feature flags documentation guidelines](documentation/feature_flags.md).
-
-In these cases, use the following workflow:
-
-1. Request a peer review from a member of your team.
-1. Request a review and approval of an Engineering Manager (EM)
- or Staff Engineer who's responsible for the area in question:
-
- - [Frontend](https://about.gitlab.com/handbook/engineering/frontend/)
- - [Backend](https://about.gitlab.com/handbook/engineering/)
- - [Database](https://about.gitlab.com/handbook/engineering/development/database/)
- - [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/)
-
- You can skip this step for MRs authored by EMs or Staff Engineers responsible
- for their area.
-
- If there are several affected groups, you may need approvals at the
- EM/Staff Engineer level from each affected area.
-
-1. After completing the reviews, consult with the EM/Staff Engineer
- author / approver of the MR.
-
- If this is a significant change across multiple areas, request final review
- and approval from the VP of Development, the DRI for Development Guidelines,
- @clefelhocz1.
-
-1. After all approvals are complete, assign the merge request to the
- Technical Writer for [Development Guidelines](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines)
- for final content review and merge. The Technical Writer may ask for
- additional approvals as previously suggested before merging the MR.
-
-## UX and Frontend guides
-
-- [GitLab Design System](https://design.gitlab.com/), for building GitLab with
- existing CSS styles and elements
-- [Frontend guidelines](fe_guide/index.md)
-- [Emoji guide](fe_guide/emojis.md)
-
-## Backend guides
-
-- [Directory structure](directory_structure.md)
-- [GitLab utilities](utilities.md)
-- [Issuable-like Rails models](issuable-like-models.md)
-- [Logging](logging.md)
-- [API style guide](api_styleguide.md) for contributing to the API
-- [GraphQL API style guide](api_graphql_styleguide.md) for contributing to the
- [GraphQL API](../api/graphql/index.md)
-- [Sidekiq guidelines](sidekiq_style_guide.md) for working with Sidekiq workers
-- [Working with Gitaly](gitaly.md)
-- [Manage feature flags](feature_flags/index.md)
-- [Licensed feature availability](licensed_feature_availability.md)
-- [Dealing with email/mailers](emails.md)
-- [Shell commands](shell_commands.md) in the GitLab codebase
-- [`Gemfile` guidelines](gemfile.md)
-- [Pry debugging](pry_debugging.md)
-- [Sidekiq debugging](../administration/troubleshooting/sidekiq.md)
-- [Accessing session data](session.md)
-- [Gotchas](gotchas.md) to avoid
-- [Avoid modules with instance variables](module_with_instance_variables.md), if
- possible
-- [How to dump production data to staging](db_dump.md)
-- [Working with the GitHub importer](github_importer.md)
-- [Import/Export development documentation](import_export.md)
-- [Test Import Project](import_project.md)
-- [Group migration](bulk_import.md)
-- [Elasticsearch integration docs](elasticsearch.md)
-- [Working with Merge Request diffs](diffs.md)
-- [Kubernetes integration guidelines](kubernetes.md)
-- [Permissions](permissions.md)
-- [Guidelines for reusing abstractions](reusing_abstractions.md)
-- [DeclarativePolicy framework](policies.md)
-- [How Git object deduplication works in GitLab](git_object_deduplication.md)
-- [Geo development](geo.md)
-- [Routing](routing.md)
-- [Repository mirroring](repository_mirroring.md)
-- [Git LFS](lfs.md)
-- [Developing against interacting components or features](interacting_components.md)
-- [File uploads](uploads.md)
-- [Auto DevOps development guide](auto_devops.md)
-- [Mass Inserting Models](mass_insert.md)
-- [Value Stream Analytics development guide](value_stream_analytics.md)
-- [Issue types vs first-class types](issue_types.md)
-- [Application limits](application_limits.md)
-- [Redis guidelines](redis.md)
-- [Rails initializers](rails_initializers.md)
-- [Code comments](code_comments.md)
-- [Renaming features](renaming_features.md)
-- [Windows Development on GCP](windows.md)
-- [Code Intelligence](code_intelligence/index.md)
-- [Approval Rules](approval_rules.md)
-- [Feature categorization](feature_categorization/index.md)
-- [Wikis development guide](wikis.md)
-- [Newlines style guide](newlines_styleguide.md)
-- [Image scaling guide](image_scaling.md)
-- [Export to CSV](export_csv.md)
-- [Cascading Settings](cascading_settings.md)
-- [FIPS compliance](fips_compliance.md)
-
-## Performance guides
-
-- [Instrumentation](instrumentation.md) for Ruby code running in production
- environments.
-- [Performance guidelines](performance.md) for writing code, benchmarks, and
- certain patterns to avoid.
-- [Merge request performance guidelines](merge_request_performance_guidelines.md)
- for ensuring merge requests do not negatively impact GitLab performance
-- [Profiling](profiling.md) a URL, measuring performance using Sherlock, or
- tracking down N+1 queries using Bullet.
-- [Cached queries guidelines](cached_queries.md), for tracking down N+1 queries
- masked by query caching, memory profiling and why should we avoid cached
- queries.
-
-## Database guides
-
-See [database guidelines](database/index.md).
-
-## Integration guides
-
-- [Jira Connect app](integrations/jira_connect.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)
-
-## Testing guides
-
-- [Testing standards and style guidelines](testing_guide/index.md)
-- [Frontend testing standards and style guidelines](testing_guide/frontend_testing.md)
-
-## Refactoring guides
-
-- [Refactoring guidelines](refactoring_guide/index.md)
-
-## Deprecation guides
-
-- [Deprecation guidelines](deprecation_guidelines/index.md)
-
-## Documentation guides
-
-- [Writing documentation](documentation/index.md)
-- [Documentation style guide](documentation/styleguide/index.md)
-- [Markdown](../user/markdown.md)
-
-## Internationalization (i18n) guides
-
-- [Introduction](i18n/index.md)
-- [Externalization](i18n/externalization.md)
-- [Translation](i18n/translation.md)
-
-## Product Intelligence guides
-
-- [Product Intelligence guide](https://about.gitlab.com/handbook/product/product-intelligence-guide/)
-- [Usage Ping guide](usage_ping/index.md)
-- [Snowplow guide](snowplow/index.md)
-
-## Experiment guide
-
-- [Introduction](experiment_guide/index.md)
-
-## Build guides
-
-- [Building a package for testing purposes](build_test_package.md)
-
-## Compliance
-
-- [Licensing](licensing.md) for ensuring license compliance
-
-## Go guides
-
-- [Go Guidelines](go_guide/index.md)
-
-## Shell Scripting guides
-
-- [Shell scripting standards and style guidelines](shell_scripting_guide/index.md)
-
-## Domain-specific guides
-
-- [CI/CD development documentation](cicd/index.md)
-- [AppSec development documentation](appsec/index.md)
-
-## Other Development guides
-
-- [Defining relations between files using projections](projections.md)
-- [Reference processing](reference_processing.md)
-- [Compatibility with multiple versions of the application running at the same time](multi_version_compatibility.md)
-- [Features inside `.gitlab/`](features_inside_dot_gitlab.md)
-- [Dashboards for stage groups](stage_group_dashboards.md)
-- [Preventing transient bugs](transient/prevention-patterns.md)
-
-## Other GitLab Development Kit (GDK) guides
-
-- [Run full Auto DevOps cycle in a GDK instance](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/auto_devops.md)
-- [Using GitLab Runner with the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/runner.md)
-- [Using the Web IDE terminal with the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/web_ide_terminal_gdk_setup.md)
+<!-- This redirect file can be deleted after 2021-09-28. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
diff --git a/doc/development/changelog.md b/doc/development/changelog.md
index f0c37af42aba05f7e81412871522883c68dd1e9a..e05428ea8266ef39c22c2b7d4b1541cfa8e3c4ec 100644
--- a/doc/development/changelog.md
+++ b/doc/development/changelog.md
@@ -188,4 +188,4 @@ documentation](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History).
---
-[Return to Development documentation](README.md)
+[Return to Development documentation](index.md)
diff --git a/doc/development/code_review.md b/doc/development/code_review.md
index df09b27c6b4a70141229e2b9e7fbf3bd0a33fafb..6f1d916fa787c702cacce8f37652abae5d7ddf63 100644
--- a/doc/development/code_review.md
+++ b/doc/development/code_review.md
@@ -644,4 +644,4 @@ Largely based on the [`thoughtbot` code review guide](https://github.com/thought
---
-[Return to Development documentation](README.md)
+[Return to Development documentation](index.md)
diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md
index 783cf7af6fcd7320da6f7f71299b0fb99d631931..9be89202d35e6af411130e1a838b1acf9ceca2d2 100644
--- a/doc/development/contributing/merge_request_workflow.md
+++ b/doc/development/contributing/merge_request_workflow.md
@@ -31,7 +31,7 @@ If you are new to GitLab development (or web development in general), see the
some potentially easy issues.
To start developing GitLab, download the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit)
-and see the [Development section](../../README.md) for the required guidelines.
+and see the [Development section](../../index.md) for the required guidelines.
## Merge request guidelines
diff --git a/doc/development/dangerbot.md b/doc/development/dangerbot.md
index 68268027b73db7c78ae1dbe7a81341b72cdf369d..3ecabd2d72db90a66fc0583379b44f9de3347f84 100644
--- a/doc/development/dangerbot.md
+++ b/doc/development/dangerbot.md
@@ -58,7 +58,7 @@ itself, increasing visibility.
## Development guidelines
-Danger code is Ruby code, so all our [usual backend guidelines](README.md#backend-guides)
+Danger code is Ruby code, so all our [usual backend guidelines](index.md#backend-guides)
continue to apply. However, there are a few things that deserve special emphasis.
### When to use Danger
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index 0f8c5f8e51f9510db462628df4d151768e608a3b..14798b747c8aab6716d50dd5d777027d853d3ee9 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -115,11 +115,11 @@ each page should have a metadata tag called `type`. It can be one or more of the
following:
- `index`: It consists mostly of a list of links to other pages.
- [Example page](../../README.md).
+ [Example page](../../index.md).
- `concepts`: The background or context of a subject.
[Example page](../../topics/autodevops/index.md).
- `howto`: Specific use case instructions.
- [Example page](../../ssh/README.md).
+ [Example page](../../ssh/index.md).
- `tutorial`: Learn a process/concept by doing.
[Example page](../../gitlab-basics/start-using-git.md).
- `reference`: A collection of information used as a reference to use a feature
@@ -395,7 +395,7 @@ This is preferred over static paths, as the helper also works on instances insta
### GitLab `/help` tests
Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/features/help_pages_spec.rb)
-are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../README.md) works correctly from `/help`.
+are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../index.md) works correctly from `/help`.
For example, [GitLab.com's `/help`](https://gitlab.com/help).
## Docs site architecture
diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md
index 871fb26ce084025afc87be0f52e063d29d149c61..b2152858e8e26bb8c146f86f19404f65dc452133 100644
--- a/doc/development/documentation/structure.md
+++ b/doc/development/documentation/structure.md
@@ -210,7 +210,7 @@ comments: false
---
```
-We're hiding comments only in main index pages, such as [the main documentation index](../../README.md),
+We're hiding comments only in main index pages, such as [the main documentation index](../../index.md),
since its content is too broad to comment on. Before omitting Disqus, you must
check with a technical writer.
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md
index fffb4d21a26e8d0b004f6b205591f5207a84e52f..4c4e3755451181168674501c7f0aaeac51714e64 100644
--- a/doc/development/documentation/styleguide/index.md
+++ b/doc/development/documentation/styleguide/index.md
@@ -1495,7 +1495,7 @@ elements:
## GitLab versions
-GitLab product documentation pages (not including [Contributor and Development](../../README.md)
+GitLab product documentation pages (not including [Contributor and Development](../../index.md)
pages in the `/development` directory) can include version information to help
users be aware of recent improvements or additions.
diff --git a/doc/development/emails.md b/doc/development/emails.md
index 3e651a6efb8cb0c84f3003583d659999652fcdf0..c1054077f9e9e68863451c3d9013063027140c41 100644
--- a/doc/development/emails.md
+++ b/doc/development/emails.md
@@ -141,4 +141,4 @@ Please note that `path/to/project` is used in GitLab as the handler for the Serv
---
-[Return to Development documentation](README.md)
+[Return to Development documentation](index.md)
diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md
index 2e814a9c41b4f0dc51b4b2b56da5a02c1146fa3d..59ab3d41f1617cb3420d0e2d4ae59a3b2bab5f45 100644
--- a/doc/development/gitaly.md
+++ b/doc/development/gitaly.md
@@ -235,7 +235,7 @@ changes to embed a new SHA in the `Gemfile.lock` file.
---
-[Return to Development documentation](README.md)
+[Return to Development documentation](index.md)
## Wrapping RPCs in Feature Flags
diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md
index ad24353fde8fe31774ffaaa8924786a6595e34ae..dab25711a5906cf0913de62e0fa2c7b64e8437c5 100644
--- a/doc/development/go_guide/index.md
+++ b/doc/development/go_guide/index.md
@@ -507,4 +507,4 @@ If the scanner report is small, less than 35 lines, then feel free to [inline th
---
-[Return to Development documentation](../README.md).
+[Return to Development documentation](../index.md).
diff --git a/doc/development/index.md b/doc/development/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..bc996fdff21bbc10d34d4b863f198699bde5135f
--- /dev/null
+++ b/doc/development/index.md
@@ -0,0 +1,308 @@
+---
+comments: false
+type: index, dev
+stage: none
+group: Development
+info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines"
+description: "Development Guidelines: learn how to contribute to GitLab."
+---
+
+# Contributor and Development Docs
+
+Learn the processes and technical information needed for contributing to GitLab.
+
+This content is intended for members of the GitLab Team as well as community
+contributors. Content specific to the GitLab Team should instead be included in
+the [Handbook](https://about.gitlab.com/handbook/).
+
+For information on using GitLab to work on your own software projects, see the
+[GitLab user documentation](../user/index.md).
+
+For information on working with the GitLab APIs, see the [API documentation](../api/README.md).
+
+For information about how to install, configure, update, and upgrade your own
+GitLab instance, see the [administration documentation](../administration/index.md).
+
+## Get started
+
+- Set up the GitLab development environment with the
+ [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/README.md)
+- [GitLab contributing guide](contributing/index.md)
+ - [Issues workflow](contributing/issue_workflow.md) for more information about:
+ - Issue tracker guidelines.
+ - Triaging.
+ - Labels.
+ - Feature proposals.
+ - Issue weight.
+ - Regression issues.
+ - Technical or UX debt.
+ - [Merge requests workflow](contributing/merge_request_workflow.md) for more
+ information about:
+ - Merge request guidelines.
+ - Contribution acceptance criteria.
+ - Definition of done.
+ - Dependencies.
+ - [Style guides](contributing/style_guides.md)
+ - [Implement design & UI elements](contributing/design.md)
+- [GitLab Architecture Overview](architecture.md)
+- [Rake tasks](rake_tasks.md) for development
+
+## Processes
+
+**Must-reads:**
+
+- [Guide on adapting existing and introducing new components](architecture.md#adapting-existing-and-introducing-new-components)
+- [Code review guidelines](code_review.md) for reviewing code and having code
+ reviewed
+- [Database review guidelines](database_review.md) for reviewing
+ database-related changes and complex SQL queries, and having them reviewed
+- [Secure coding guidelines](secure_coding_guidelines.md)
+- [Pipelines for the GitLab project](pipelines.md)
+
+Complementary reads:
+
+- [GitLab core team & GitLab Inc. contribution process](https://gitlab.com/gitlab-org/gitlab/-/blob/master/PROCESS.md)
+- [Security process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer)
+- [Guidelines for implementing Enterprise Edition features](ee_features.md)
+- [Danger bot](dangerbot.md)
+- [Guidelines for changelogs](changelog.md)
+- [Requesting access to ChatOps on GitLab.com](chatops_on_gitlabcom.md#requesting-access) (for GitLab team members)
+- [Patch release process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/patch/process.md#process-for-developers)
+- [Adding a new service component to GitLab](adding_service_component.md)
+
+### Development guidelines review
+
+When you submit a change to the GitLab development guidelines, who
+you ask for reviews depends on the level of change.
+
+#### Wording, style, or link changes
+
+Not all changes require extensive review. For example, MRs that don't change the
+content's meaning or function can be reviewed, approved, and merged by any
+maintainer or Technical Writer. These can include:
+
+- Typo fixes.
+- Clarifying links, such as to external programming language documentation.
+- Changes to comply with the [Documentation Style Guide](documentation/index.md)
+ that don't change the intent of the documentation page.
+
+#### Specific changes
+
+If the MR proposes changes that are limited to a particular stage, group, or team,
+request a review and approval from an experienced GitLab Team Member in that
+group. For example, if you're documenting a new internal API used exclusively by
+a given group, request an engineering review from one of the group's members.
+
+After the engineering review is complete, assign the MR to the
+[Technical Writer associated with the stage and group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments)
+in the modified documentation page's metadata.
+
+If you have questions or need further input, request a review from the
+Technical Writer assigned to the [Development Guidelines](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines).
+
+#### Broader changes
+
+Some changes affect more than one group. For example:
+
+- Changes to [code review guidelines](code_review.md).
+- Changes to [commit message guidelines](contributing/merge_request_workflow.md#commit-messages-guidelines).
+- Changes to guidelines in [feature flags in development of GitLab](feature_flags/).
+- Changes to [feature flags documentation guidelines](documentation/feature_flags.md).
+
+In these cases, use the following workflow:
+
+1. Request a peer review from a member of your team.
+1. Request a review and approval of an Engineering Manager (EM)
+ or Staff Engineer who's responsible for the area in question:
+
+ - [Frontend](https://about.gitlab.com/handbook/engineering/frontend/)
+ - [Backend](https://about.gitlab.com/handbook/engineering/)
+ - [Database](https://about.gitlab.com/handbook/engineering/development/database/)
+ - [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/)
+
+ You can skip this step for MRs authored by EMs or Staff Engineers responsible
+ for their area.
+
+ If there are several affected groups, you may need approvals at the
+ EM/Staff Engineer level from each affected area.
+
+1. After completing the reviews, consult with the EM/Staff Engineer
+ author / approver of the MR.
+
+ If this is a significant change across multiple areas, request final review
+ and approval from the VP of Development, the DRI for Development Guidelines,
+ @clefelhocz1.
+
+1. After all approvals are complete, assign the merge request to the
+ Technical Writer for [Development Guidelines](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines)
+ for final content review and merge. The Technical Writer may ask for
+ additional approvals as previously suggested before merging the MR.
+
+## UX and Frontend guides
+
+- [GitLab Design System](https://design.gitlab.com/), for building GitLab with
+ existing CSS styles and elements
+- [Frontend guidelines](fe_guide/index.md)
+- [Emoji guide](fe_guide/emojis.md)
+
+## Backend guides
+
+- [Directory structure](directory_structure.md)
+- [GitLab utilities](utilities.md)
+- [Issuable-like Rails models](issuable-like-models.md)
+- [Logging](logging.md)
+- [API style guide](api_styleguide.md) for contributing to the API
+- [GraphQL API style guide](api_graphql_styleguide.md) for contributing to the
+ [GraphQL API](../api/graphql/index.md)
+- [Sidekiq guidelines](sidekiq_style_guide.md) for working with Sidekiq workers
+- [Working with Gitaly](gitaly.md)
+- [Manage feature flags](feature_flags/index.md)
+- [Licensed feature availability](licensed_feature_availability.md)
+- [Dealing with email/mailers](emails.md)
+- [Shell commands](shell_commands.md) in the GitLab codebase
+- [`Gemfile` guidelines](gemfile.md)
+- [Pry debugging](pry_debugging.md)
+- [Sidekiq debugging](../administration/troubleshooting/sidekiq.md)
+- [Accessing session data](session.md)
+- [Gotchas](gotchas.md) to avoid
+- [Avoid modules with instance variables](module_with_instance_variables.md), if
+ possible
+- [How to dump production data to staging](db_dump.md)
+- [Working with the GitHub importer](github_importer.md)
+- [Import/Export development documentation](import_export.md)
+- [Test Import Project](import_project.md)
+- [Group migration](bulk_import.md)
+- [Elasticsearch integration docs](elasticsearch.md)
+- [Working with Merge Request diffs](diffs.md)
+- [Kubernetes integration guidelines](kubernetes.md)
+- [Permissions](permissions.md)
+- [Guidelines for reusing abstractions](reusing_abstractions.md)
+- [DeclarativePolicy framework](policies.md)
+- [How Git object deduplication works in GitLab](git_object_deduplication.md)
+- [Geo development](geo.md)
+- [Routing](routing.md)
+- [Repository mirroring](repository_mirroring.md)
+- [Git LFS](lfs.md)
+- [Developing against interacting components or features](interacting_components.md)
+- [File uploads](uploads.md)
+- [Auto DevOps development guide](auto_devops.md)
+- [Mass Inserting Models](mass_insert.md)
+- [Value Stream Analytics development guide](value_stream_analytics.md)
+- [Issue types vs first-class types](issue_types.md)
+- [Application limits](application_limits.md)
+- [Redis guidelines](redis.md)
+- [Rails initializers](rails_initializers.md)
+- [Code comments](code_comments.md)
+- [Renaming features](renaming_features.md)
+- [Windows Development on GCP](windows.md)
+- [Code Intelligence](code_intelligence/index.md)
+- [Approval Rules](approval_rules.md)
+- [Feature categorization](feature_categorization/index.md)
+- [Wikis development guide](wikis.md)
+- [Newlines style guide](newlines_styleguide.md)
+- [Image scaling guide](image_scaling.md)
+- [Export to CSV](export_csv.md)
+- [Cascading Settings](cascading_settings.md)
+- [FIPS compliance](fips_compliance.md)
+
+## Performance guides
+
+- [Instrumentation](instrumentation.md) for Ruby code running in production
+ environments.
+- [Performance guidelines](performance.md) for writing code, benchmarks, and
+ certain patterns to avoid.
+- [Merge request performance guidelines](merge_request_performance_guidelines.md)
+ for ensuring merge requests do not negatively impact GitLab performance
+- [Profiling](profiling.md) a URL, measuring performance using Sherlock, or
+ tracking down N+1 queries using Bullet.
+- [Cached queries guidelines](cached_queries.md), for tracking down N+1 queries
+ masked by query caching, memory profiling and why should we avoid cached
+ queries.
+
+## Database guides
+
+See [database guidelines](database/index.md).
+
+## Integration guides
+
+- [Jira Connect app](integrations/jira_connect.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)
+
+## Testing guides
+
+- [Testing standards and style guidelines](testing_guide/index.md)
+- [Frontend testing standards and style guidelines](testing_guide/frontend_testing.md)
+
+## Refactoring guides
+
+- [Refactoring guidelines](refactoring_guide/index.md)
+
+## Deprecation guides
+
+- [Deprecation guidelines](deprecation_guidelines/index.md)
+
+## Documentation guides
+
+- [Writing documentation](documentation/index.md)
+- [Documentation style guide](documentation/styleguide/index.md)
+- [Markdown](../user/markdown.md)
+
+## Internationalization (i18n) guides
+
+- [Introduction](i18n/index.md)
+- [Externalization](i18n/externalization.md)
+- [Translation](i18n/translation.md)
+
+## Product Intelligence guides
+
+- [Product Intelligence guide](https://about.gitlab.com/handbook/product/product-intelligence-guide/)
+- [Usage Ping guide](usage_ping/index.md)
+- [Snowplow guide](snowplow/index.md)
+
+## Experiment guide
+
+- [Introduction](experiment_guide/index.md)
+
+## Build guides
+
+- [Building a package for testing purposes](build_test_package.md)
+
+## Compliance
+
+- [Licensing](licensing.md) for ensuring license compliance
+
+## Go guides
+
+- [Go Guidelines](go_guide/index.md)
+
+## Shell Scripting guides
+
+- [Shell scripting standards and style guidelines](shell_scripting_guide/index.md)
+
+## Domain-specific guides
+
+- [CI/CD development documentation](cicd/index.md)
+- [AppSec development documentation](appsec/index.md)
+
+## Other Development guides
+
+- [Defining relations between files using projections](projections.md)
+- [Reference processing](reference_processing.md)
+- [Compatibility with multiple versions of the application running at the same time](multi_version_compatibility.md)
+- [Features inside `.gitlab/`](features_inside_dot_gitlab.md)
+- [Dashboards for stage groups](stage_group_dashboards.md)
+- [Preventing transient bugs](transient/prevention-patterns.md)
+
+## Other GitLab Development Kit (GDK) guides
+
+- [Run full Auto DevOps cycle in a GDK instance](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/auto_devops.md)
+- [Using GitLab Runner with the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/runner.md)
+- [Using the Web IDE terminal with the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/web_ide_terminal_gdk_setup.md)
diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md
index 872dea060cdab7b52f98ec009714fdba46781a75..4d6239352ac105efe67d902cc25456dd0fc4b909 100644
--- a/doc/development/pipelines.md
+++ b/doc/development/pipelines.md
@@ -813,4 +813,4 @@ and included in `rules` definitions via [YAML anchors](../ci/yaml/README.md#anch
---
-[Return to Development documentation](README.md)
+[Return to Development documentation](index.md)
diff --git a/doc/development/shell_scripting_guide/index.md b/doc/development/shell_scripting_guide/index.md
index 6071ae3a09dd34a7c08e54ccebd832cfa386ebf3..d3b446d45daa4acfb40b7b3ef20be4fbb157f993 100644
--- a/doc/development/shell_scripting_guide/index.md
+++ b/doc/development/shell_scripting_guide/index.md
@@ -127,4 +127,4 @@ for code review.
---
-[Return to Development documentation](../README.md).
+[Return to Development documentation](../index.md).
diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md
index c22a4e0b3add88a7651ff8a6fe446bdb4db8f066..889dc45d6e33d0bd0e318f4078fed3cbc3ef9aee 100644
--- a/doc/development/testing_guide/index.md
+++ b/doc/development/testing_guide/index.md
@@ -70,4 +70,4 @@ Everything you should know about how to run end-to-end tests using
Everything you should know about how to test migrations.
-[Return to Development documentation](../README.md)
+[Return to Development documentation](../index.md)
diff --git a/doc/gitlab-basics/create-your-ssh-keys.md b/doc/gitlab-basics/create-your-ssh-keys.md
index a99307e6dbfd253c5c98bf1bce85e76f1b0708c9..673fb2911fa417e1f649908c7abdd1ecc1a47eb0 100644
--- a/doc/gitlab-basics/create-your-ssh-keys.md
+++ b/doc/gitlab-basics/create-your-ssh-keys.md
@@ -1,9 +1,9 @@
---
-redirect_to: '../ssh/README.md'
+redirect_to: '../ssh/index.md'
remove_date: '2021-07-04'
---
-This document was moved to [another location](../ssh/README.md).
+This document was moved to [another location](../ssh/index.md).
<!-- 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/index.md b/doc/gitlab-basics/index.md
index 774931aad72d2b69b5c76103ef65369bcc015c7c..d2d0c4fad395d0a994650930f7a3d02297b5f30d 100644
--- a/doc/gitlab-basics/index.md
+++ b/doc/gitlab-basics/index.md
@@ -21,7 +21,7 @@ This documentation is split into the following groups:
The following are guides to basic GitLab functionality:
-- [Create and add your SSH public key](../ssh/README.md), for enabling Git over SSH.
+- [Create and add your SSH public key](../ssh/index.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-group), to combine and administer
projects together.
diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md
index f9623586e55457a32a61ec3379923a65f8985db9..9b26e1f102c1030e838979cbd74d3819b8783920 100644
--- a/doc/gitlab-basics/start-using-git.md
+++ b/doc/gitlab-basics/start-using-git.md
@@ -182,7 +182,7 @@ This connection requires you to add credentials. You can either use SSH or HTTPS
Clone with SSH when you want to authenticate only one time.
-1. Authenticate with GitLab by following the instructions in the [SSH documentation](../ssh/README.md).
+1. Authenticate with GitLab by following the instructions in the [SSH documentation](../ssh/index.md).
1. Go to your project's landing page and select **Clone**. Copy the URL for **Clone with SSH**.
1. Open a terminal and go to the directory where you want to clone the files. Git automatically creates a folder with the repository name and downloads the files there.
1. Run this command:
diff --git a/doc/index.md b/doc/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..cdb1114ca4094efb0056d10cdaf8b872df700912
--- /dev/null
+++ b/doc/index.md
@@ -0,0 +1,126 @@
+---
+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
+description: 'Learn how to use and administer GitLab, the most scalable Git-based fully integrated platform for software development.'
+---
+
+<div class="d-none">
+ <h3>Visit <a href="https://docs.gitlab.com/ee/">docs.gitlab.com</a> for the latest version
+ of this help information with enhanced navigation, discoverability, and readability.</h3>
+</div>
+<!-- the div above will not display on the docs site but will display on /help -->
+
+# GitLab Docs
+
+Welcome to [GitLab](https://about.gitlab.com/) documentation.
+
+Here you can access the complete documentation for GitLab, the single application for the
+[entire DevOps lifecycle](#the-entire-devops-lifecycle).
+
+## Overview
+
+No matter how you use GitLab, we have documentation for you.
+
+| 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/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) | 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
+
+GitLab is the first single application for software development, security,
+and operations that enables [Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/).
+GitLab makes the software lifecycle faster and radically improves the speed of business.
+
+GitLab provides solutions for [each of the stages of the DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/).
+
+## New to Git and GitLab?
+
+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/index.md) | Start working on the command line and with GitLab. |
+| [GitLab workflow overview](https://about.gitlab.com/topics/version-control/what-is-gitlab-workflow/) | 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. |
+| [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. |
+| [User settings](user/profile/index.md#access-your-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 |
+|:-----------------------------------------------------------------------------|:------------|
+| [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. |
+
+## Coming to GitLab from another platform
+
+If you are coming to GitLab from another platform, the following information is useful:
+
+| 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. |
+
+## 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. |
+| [GitLab GraphQL API](api/graphql/index.md) | Integrate with GitLab using our GraphQL API. |
+| [Integrations](integration/index.md) | Integrations with third-party products. |
+
+## Contributing to GitLab
+
+GitLab Community Edition is [open source](https://gitlab.com/gitlab-org/gitlab-foss/)
+and GitLab Enterprise Edition is [open-core](https://gitlab.com/gitlab-org/gitlab/).
+
+Learn how to contribute to GitLab with the following resources:
+
+| Topic | Description |
+|:------------------------------------------------------------|:------------|
+| [Development](development/index.md) | How to contribute to GitLab development. |
+| [Legal](legal/index.md) | Contributor license agreements. |
+| [Writing documentation](development/documentation/index.md) | How to contribute to GitLab Docs. |
diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md
index 1351489642eb830a6ca9486f2497dc899ed96735..1d31337fc39e26d42dd142fbd2801febac627e2f 100644
--- a/doc/install/azure/index.md
+++ b/doc/install/azure/index.md
@@ -71,7 +71,7 @@ The first items you need to configure are the basic settings of the underlying v
the user Azure uses to connect to the VM through SSH. By default, the user
has root access.
1. Determine if you want to provide your own SSH key or let Azure create one for you.
- Read the [SSH documentation](../../ssh/README.md) to learn more about how to set up SSH
+ Read the [SSH documentation](../../ssh/index.md) to learn more about how to set up SSH
public keys.
Review your entered settings, and then proceed to the Disks tab.
diff --git a/doc/install/next_steps.md b/doc/install/next_steps.md
index 4e4f1f01a08a39b50de0d98a1a1911561328a34e..f271caef493986cb489c43932cbdc41e4bd0d0c1 100644
--- a/doc/install/next_steps.md
+++ b/doc/install/next_steps.md
@@ -26,7 +26,7 @@ installation.
## Security
-- [Secure GitLab](../security/README.md#securing-your-gitlab-installation):
+- [Secure GitLab](../security/index.md#securing-your-gitlab-installation):
Recommended practices to secure your GitLab instance.
- Sign up for the GitLab [Security Newsletter](https://about.gitlab.com/company/preference-center/) to get notified for security updates upon release.
diff --git a/doc/migrate_ci_to_ce/index.md b/doc/migrate_ci_to_ce/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..dbe5a2730b53fce53992ecb8a751eba7e2128248
--- /dev/null
+++ b/doc/migrate_ci_to_ce/index.md
@@ -0,0 +1,9 @@
+---
+redirect_to: 'https://docs.gitlab.com/'
+remove_date: '2021-06-14'
+---
+
+This document was moved to [another location](https://docs.gitlab.com/).
+
+<!-- This redirect file can be deleted after <2021-09-14>. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
diff --git a/doc/security/README.md b/doc/security/README.md
index 6af3948fdcfda2e853e26dfe0ba23193ddb145ec..5ab8653dc35a543efd7c42b0da608637aae27c62 100644
--- a/doc/security/README.md
+++ b/doc/security/README.md
@@ -1,32 +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'
---
-# Security **(FREE)**
+This document was moved to [another location](index.md).
-- [Password storage](password_storage.md)
-- [Password length limits](password_length_limits.md)
-- [Generated passwords for users created through integrated authentication](passwords_for_integrated_authentication_methods.md)
-- [Restrict SSH key technologies and minimum length](ssh_keys_restrictions.md)
-- [Rate limits](rate_limits.md)
-- [Webhooks and insecure internal web services](webhooks.md)
-- [Information exclusivity](information_exclusivity.md)
-- [Reset user password](reset_user_password.md)
-- [Unlock a locked user](unlock_user.md)
-- [User File Uploads](user_file_uploads.md)
-- [How we manage the CRIME vulnerability](crime_vulnerability.md)
-- [Enforce Two-factor authentication](two_factor_authentication.md)
-- [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 variables](../ci/variables/README.md#cicd-variable-security)
-- [Token overview](token_overview.md)
-- [Project Import decompressed archive size limits](project_import_decompressed_archive_size_limits.md)
-
-## Securing your GitLab installation
-
-Consider access control features like [Sign up restrictions](../user/admin_area/settings/sign_up_restrictions.md) and [Authentication options](../topics/authentication/) to harden your GitLab instance and minimize the risk of unwanted user account creation.
+<!-- This redirect file can be deleted after 2021-09-28. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
diff --git a/doc/security/index.md b/doc/security/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..6af3948fdcfda2e853e26dfe0ba23193ddb145ec
--- /dev/null
+++ b/doc/security/index.md
@@ -0,0 +1,32 @@
+---
+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
+---
+
+# Security **(FREE)**
+
+- [Password storage](password_storage.md)
+- [Password length limits](password_length_limits.md)
+- [Generated passwords for users created through integrated authentication](passwords_for_integrated_authentication_methods.md)
+- [Restrict SSH key technologies and minimum length](ssh_keys_restrictions.md)
+- [Rate limits](rate_limits.md)
+- [Webhooks and insecure internal web services](webhooks.md)
+- [Information exclusivity](information_exclusivity.md)
+- [Reset user password](reset_user_password.md)
+- [Unlock a locked user](unlock_user.md)
+- [User File Uploads](user_file_uploads.md)
+- [How we manage the CRIME vulnerability](crime_vulnerability.md)
+- [Enforce Two-factor authentication](two_factor_authentication.md)
+- [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 variables](../ci/variables/README.md#cicd-variable-security)
+- [Token overview](token_overview.md)
+- [Project Import decompressed archive size limits](project_import_decompressed_archive_size_limits.md)
+
+## Securing your GitLab installation
+
+Consider access control features like [Sign up restrictions](../user/admin_area/settings/sign_up_restrictions.md) and [Authentication options](../topics/authentication/) to harden your GitLab instance and minimize the risk of unwanted user account creation.
diff --git a/doc/security/passwords_for_integrated_authentication_methods.md b/doc/security/passwords_for_integrated_authentication_methods.md
index 7c4ada4435cb6bf2741887f012da9385f5aa4b70..9931fd56e8360e92e19b75759764e4b7f236dc3e 100644
--- a/doc/security/passwords_for_integrated_authentication_methods.md
+++ b/doc/security/passwords_for_integrated_authentication_methods.md
@@ -7,7 +7,7 @@ type: reference
# Generated passwords for users created through integrated authentication **(FREE)**
-GitLab allows users to set up accounts through integration with external [authentication and authorization providers](../administration/auth/README.md).
+GitLab allows users to set up accounts through integration with external [authentication and authorization providers](../administration/auth/index.md).
These authentication methods do not require the user to explicitly create a password for their accounts.
However, to maintain data consistency, GitLab requires passwords for all user accounts.
diff --git a/doc/ssh/README.md b/doc/ssh/README.md
index 358323e4ef5ae8207141445c7e029df2cfc61d10..5ab8653dc35a543efd7c42b0da608637aae27c62 100644
--- a/doc/ssh/README.md
+++ b/doc/ssh/README.md
@@ -1,385 +1,8 @@
---
-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"
-type: howto, reference
+redirect_to: 'index.md'
---
-# GitLab and SSH keys
+This document was moved to [another location](index.md).
-Git is a distributed version control system, which means you can work locally,
-then share or "push" your changes to a server. In this case, the server is GitLab.
-
-GitLab uses the SSH protocol to securely communicate with Git.
-When you use SSH keys to authenticate to the GitLab remote server,
-you don't need to supply your username and password each time.
-
-## Prerequisites
-
-To use SSH to communicate with GitLab, you need:
-
-- 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.
-
-To view the version of SSH installed on your system, run `ssh -V`.
-
-## Supported SSH key types
-
-To communicate with GitLab, you can use the following SSH key types:
-
-- [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.)
-
-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.
-
-OpenSSH 6.5 introduced ED25519 SSH keys in 2014 and they should be available on most
-operating systems.
-
-### RSA SSH keys
-
-Available documentation suggests that ED25519 is more secure than RSA.
-
-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.
-
-## See if you have an existing SSH key pair
-
-Before you create a key pair, see if a key pair already exists.
-
-1. On Windows, Linux, or macOS, go to your home directory.
-1. Go to the `.ssh/` subdirectory. If the `.ssh/` subdirectory doesn't exist,
- you are either not in the home directory, or you haven't used `ssh` before.
- In the latter case, you need to [generate an SSH key pair](#generate-an-ssh-key-pair).
-1. See if a file with one of the following formats exists:
-
- | 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` |
-
-## Generate an SSH key pair
-
-If you do not have an existing SSH key pair, generate a new one.
-
-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:
-
- ```shell
- ssh-keygen -t ed25519 -C "<comment>"
- ```
-
- For 2048-bit RSA:
-
- ```shell
- ssh-keygen -t rsa -b 2048 -C "<comment>"
- ```
-
-1. Press Enter. Output similar to the following is displayed:
-
- ```plaintext
- Generating public/private ed25519 key pair.
- Enter file in which to save the key (/home/user/.ssh/id_ed25519):
- ```
-
-1. Accept the suggested filename and directory, unless you are generating a [deploy key](../user/project/deploy_keys/index.md)
- or want to save in a specific directory where you store other keys.
-
- You can also dedicate the SSH key pair to a [specific host](#configure-ssh-to-point-to-a-different-directory).
-
-1. Specify a [passphrase](https://www.ssh.com/ssh/passphrase/):
-
- ```plaintext
- Enter passphrase (empty for no passphrase):
- Enter same passphrase again:
- ```
-
-1. A confirmation is displayed, including information about where your files are stored.
-
-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.
-
-### Configure SSH to point to a different directory
-
-If you did not save your SSH key pair in the default directory,
-configure your SSH client to point to the directory where the private key is stored.
-
-1. Open a terminal and run this command:
-
- ```shell
- eval $(ssh-agent -s)
- ssh-add <directory to private SSH key>
- ```
-
-1. Save these settings in the `~/.ssh/config` file. For example:
-
- ```conf
- # GitLab.com
- Host gitlab.com
- PreferredAuthentications publickey
- IdentityFile ~/.ssh/gitlab_com_rsa
-
- # Private GitLab instance
- Host gitlab.company.com
- PreferredAuthentications publickey
- IdentityFile ~/.ssh/example_com_rsa
- ```
-
- For more information on these settings, see the [`man ssh_config`](https://man.openbsd.org/ssh_config) page in the SSH configuration manual.
-
-Public SSH keys must be unique to GitLab because they bind to your account.
-Your SSH key is the only identifier you have when you push code with SSH.
-It must uniquely map to a single user.
-
-### Update your SSH key passphrase
-
-You can update the passphrase for your SSH key.
-
-1. Open a terminal and run this command:
-
- ```shell
- ssh-keygen -p -f /path/to/ssh_key
- ```
-
-1. At the prompts, type the passphrase and press Enter.
-
-### Upgrade your RSA key pair to a more secure format
-
-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.
-
-1. Open a terminal and run this command:
-
- ```shell
- ssh-keygen -o -f ~/.ssh/id_rsa
- ```
-
- Alternatively, you can generate a new RSA key with the more secure encryption format with
- the following command:
-
- ```shell
- ssh-keygen -o -t rsa -b 4096 -C "<comment>"
- ```
-
-## Add an SSH key to your GitLab account
-
-To use SSH with GitLab, copy your public key to your GitLab account.
-
-1. Copy the contents of your public key file. You can do this manually or use a script.
- For example, to copy an ED25519 key to the clipboard:
-
- **macOS:**
-
- ```shell
- tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy
- ```
-
- **Linux** (requires the `xclip` package):
-
- ```shell
- xclip -sel clip < ~/.ssh/id_ed25519.pub
- ```
-
- **Git Bash on Windows:**
-
- ```shell
- cat ~/.ssh/id_ed25519.pub | clip
- ```
-
- Replace `id_ed25519.pub` with your filename. For example, use `id_rsa.pub` for RSA.
-
-1. Sign in to GitLab.
-1. In the top right corner, select your avatar.
-1. Select **Preferences**.
-1. From the left sidebar, select **SSH Keys**.
-1. In the **Key** box, paste the contents of your public key.
- If you manually copied the key, make sure you copy the entire key,
- which starts with `ssh-ed25519` or `ssh-rsa`, and may end with a comment.
-1. In the **Title** text box, type a description, like _Work Laptop_ or
- _Home Workstation_.
-1. Optional. In the **Expires at** box, select an expiration date. (Introduced in [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/36243).)
- The expiration date is informational only, and does not prevent you from using
- the key. However, administrators can view expiration dates and
- use them for guidance when [deleting keys](../user/admin_area/credentials_inventory.md#delete-a-users-ssh-key).
- - GitLab checks all SSH keys at 02:00 AM UTC every day. It emails an expiration notice for all SSH keys that expire on the current date. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.11.)
- - GitLab checks all SSH keys at 01:00 AM UTC every day. It emails an expiration notice for all SSH keys that are scheduled to expire seven days from now. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.11.)
-1. Select **Add key**.
-
-## Verify that you can connect
-
-Verify that your SSH key was added correctly.
-
-1. For GitLab.com, to ensure you're connecting to the correct server, confirm the
- [SSH host keys fingerprints](../user/gitlab_com/index.md#ssh-host-keys-fingerprints).
-1. Open a terminal and run this command, replacing `gitlab.example.com` with your GitLab instance URL:
-
- ```shell
- ssh -T git@gitlab.example.com
- ```
-
-1. If this is the first time you connect, you should verify the
- authenticity of the GitLab host. If you see a message like:
-
- ```plaintext
- The authenticity of host 'gitlab.example.com (35.231.145.151)' can't be established.
- ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
- Are you sure you want to continue connecting (yes/no)? yes
- Warning: Permanently added 'gitlab.example.com' (ECDSA) to the list of known hosts.
- ```
-
- Type `yes` and press Enter.
-
-1. Run the `ssh -T git@gitlab.example.com` command again. You should receive a _Welcome to GitLab, `@username`!_ message.
-
-If the welcome message doesn't appear, you can troubleshoot by running `ssh`
-in verbose mode:
-
-```shell
-ssh -Tvvv git@gitlab.example.com
-```
-
-## Use different keys for different repositories
-
-You can use a different key for each repository.
-
-Open a terminal and run this command:
-
-```shell
-git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null"
-```
-
-This command does not use the SSH Agent and requires Git 2.10 or later. For more information
-on `ssh` command options, see the `man` pages for both `ssh` and `ssh_config`.
-
-## Use different accounts on a single GitLab instance
-
-You can use multiple accounts to connect to a single instance of GitLab.
-You can do this by using the command in the [previous topic](#use-different-keys-for-different-repositories).
-However, even if you set `IdentitiesOnly` to `yes`, you cannot sign in if an `IdentityFile` exists
-outside of a `Host` block.
-
-Instead, you can assign aliases to hosts in the `~.ssh/config` file.
-
-- For the `Host`, use an alias like `user_1.gitlab.com` and
- `user_2.gitlab.com`. Advanced configurations
- are more difficult to maintain, and these strings are easier to
- understand when you use tools like `git remote`.
-- For the `IdentityFile`, use the path the private key.
-
-```conf
-# User1 Account Identity
-Host <user_1.gitlab.com>
- Hostname gitlab.com
- PreferredAuthentications publickey
- IdentityFile ~/.ssh/<example_ssh_key1>
-
-# User2 Account Identity
-Host <user_2.gitlab.com>
- Hostname gitlab.com
- PreferredAuthentications publickey
- IdentityFile ~/.ssh/<example_ssh_key2>
-```
-
-Now, to clone a repository for `user_1`, use `user_1.gitlab.com` in the `git clone` command:
-
-```shell
-git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git
-```
-
-To update a previously-cloned repository that is aliased as `origin`:
-
-```shell
-git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git
-```
-
-NOTE:
-Private and public keys contain sensitive data. Ensure the permissions
-on the files make them readable to you but not accessible to others.
-
-## Configure two-factor authentication (2FA)
-
-You can set up two-factor authentication (2FA) for
-[Git over SSH](../security/two_factor_authentication.md#two-factor-authentication-2fa-for-git-over-ssh-operations).
-
-## Use EGit on Eclipse
-
-If you are using [EGit](https://www.eclipse.org/egit/), you can [add your SSH key to Eclipse](https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration).
-
-## Use SSH on Microsoft Windows
-
-If you're running Windows 10, you can either use the [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
-with [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/install-win10#update-to-wsl-2) which
-has both `git` and `ssh` preinstalled, or install [Git for Windows](https://gitforwindows.org) to
-use SSH through Powershell.
-
-The SSH key generated in WSL is not directly available for Git for Windows, and vice versa,
-as both have a different home directory:
-
-- WSL: `/home/<user>`
-- Git for Windows: `C:\Users\<user>`
-
-You can either copy over the `.ssh/` directory to use the same key, or generate a key in each environment.
-
-Alternative tools include:
-
-- [Cygwin](https://www.cygwin.com)
-- [PuttyGen](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html)
-
-## Overriding SSH settings on the GitLab server
-
-GitLab integrates with the system-installed SSH daemon and designates a user
-(typically named `git`) through which all access requests are handled. Users
-who connect to the GitLab server over SSH are identified by their SSH key instead
-of their username.
-
-SSH *client* operations performed on the GitLab server are executed as this
-user. You can modify this SSH configuration. For example, you can specify
-a private SSH key for this user to use for authentication requests. However, this practice
-is **not supported** and is strongly discouraged as it presents significant
-security risks.
-
-GitLab checks for this condition, and directs you
-to this section if your server is configured this way. For example:
-
-```shell
-$ gitlab-rake gitlab:check
-
-Git user has default SSH configuration? ... no
- Try fixing it:
- mkdir ~/gitlab-check-backup-1504540051
- sudo mv /var/lib/git/.ssh/id_rsa ~/gitlab-check-backup-1504540051
- sudo mv /var/lib/git/.ssh/id_rsa.pub ~/gitlab-check-backup-1504540051
- For more information see:
- [Overriding SSH settings on the GitLab server](#overriding-ssh-settings-on-the-gitlab-server)
- Please fix the error above and rerun the checks.
-```
-
-Remove the custom configuration as soon as you can. These customizations
-are **explicitly not supported** and may stop working at any time.
-
-## Troubleshooting SSH connections
-
-When you run `git clone`, you may be prompted for a password, like `git@gitlab.example.com's password:`.
-This indicates that something is wrong with your SSH setup.
-
-- Ensure that you generated your SSH key pair correctly and added the public SSH
- key to your GitLab profile.
-- Try to manually register your private SSH key by using `ssh-agent`.
-- Try to debug the connection by running `ssh -Tv git@example.com`.
- Replace `example.com` with your GitLab URL.
+<!-- This redirect file can be deleted after 2021-09-28. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
diff --git a/doc/ssh/index.md b/doc/ssh/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..358323e4ef5ae8207141445c7e029df2cfc61d10
--- /dev/null
+++ b/doc/ssh/index.md
@@ -0,0 +1,385 @@
+---
+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"
+type: howto, reference
+---
+
+# GitLab and SSH keys
+
+Git is a distributed version control system, which means you can work locally,
+then share or "push" your changes to a server. In this case, the server is GitLab.
+
+GitLab uses the SSH protocol to securely communicate with Git.
+When you use SSH keys to authenticate to the GitLab remote server,
+you don't need to supply your username and password each time.
+
+## Prerequisites
+
+To use SSH to communicate with GitLab, you need:
+
+- 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.
+
+To view the version of SSH installed on your system, run `ssh -V`.
+
+## Supported SSH key types
+
+To communicate with GitLab, you can use the following SSH key types:
+
+- [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.)
+
+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.
+
+OpenSSH 6.5 introduced ED25519 SSH keys in 2014 and they should be available on most
+operating systems.
+
+### RSA SSH keys
+
+Available documentation suggests that ED25519 is more secure than RSA.
+
+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.
+
+## See if you have an existing SSH key pair
+
+Before you create a key pair, see if a key pair already exists.
+
+1. On Windows, Linux, or macOS, go to your home directory.
+1. Go to the `.ssh/` subdirectory. If the `.ssh/` subdirectory doesn't exist,
+ you are either not in the home directory, or you haven't used `ssh` before.
+ In the latter case, you need to [generate an SSH key pair](#generate-an-ssh-key-pair).
+1. See if a file with one of the following formats exists:
+
+ | 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` |
+
+## Generate an SSH key pair
+
+If you do not have an existing SSH key pair, generate a new one.
+
+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:
+
+ ```shell
+ ssh-keygen -t ed25519 -C "<comment>"
+ ```
+
+ For 2048-bit RSA:
+
+ ```shell
+ ssh-keygen -t rsa -b 2048 -C "<comment>"
+ ```
+
+1. Press Enter. Output similar to the following is displayed:
+
+ ```plaintext
+ Generating public/private ed25519 key pair.
+ Enter file in which to save the key (/home/user/.ssh/id_ed25519):
+ ```
+
+1. Accept the suggested filename and directory, unless you are generating a [deploy key](../user/project/deploy_keys/index.md)
+ or want to save in a specific directory where you store other keys.
+
+ You can also dedicate the SSH key pair to a [specific host](#configure-ssh-to-point-to-a-different-directory).
+
+1. Specify a [passphrase](https://www.ssh.com/ssh/passphrase/):
+
+ ```plaintext
+ Enter passphrase (empty for no passphrase):
+ Enter same passphrase again:
+ ```
+
+1. A confirmation is displayed, including information about where your files are stored.
+
+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.
+
+### Configure SSH to point to a different directory
+
+If you did not save your SSH key pair in the default directory,
+configure your SSH client to point to the directory where the private key is stored.
+
+1. Open a terminal and run this command:
+
+ ```shell
+ eval $(ssh-agent -s)
+ ssh-add <directory to private SSH key>
+ ```
+
+1. Save these settings in the `~/.ssh/config` file. For example:
+
+ ```conf
+ # GitLab.com
+ Host gitlab.com
+ PreferredAuthentications publickey
+ IdentityFile ~/.ssh/gitlab_com_rsa
+
+ # Private GitLab instance
+ Host gitlab.company.com
+ PreferredAuthentications publickey
+ IdentityFile ~/.ssh/example_com_rsa
+ ```
+
+ For more information on these settings, see the [`man ssh_config`](https://man.openbsd.org/ssh_config) page in the SSH configuration manual.
+
+Public SSH keys must be unique to GitLab because they bind to your account.
+Your SSH key is the only identifier you have when you push code with SSH.
+It must uniquely map to a single user.
+
+### Update your SSH key passphrase
+
+You can update the passphrase for your SSH key.
+
+1. Open a terminal and run this command:
+
+ ```shell
+ ssh-keygen -p -f /path/to/ssh_key
+ ```
+
+1. At the prompts, type the passphrase and press Enter.
+
+### Upgrade your RSA key pair to a more secure format
+
+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.
+
+1. Open a terminal and run this command:
+
+ ```shell
+ ssh-keygen -o -f ~/.ssh/id_rsa
+ ```
+
+ Alternatively, you can generate a new RSA key with the more secure encryption format with
+ the following command:
+
+ ```shell
+ ssh-keygen -o -t rsa -b 4096 -C "<comment>"
+ ```
+
+## Add an SSH key to your GitLab account
+
+To use SSH with GitLab, copy your public key to your GitLab account.
+
+1. Copy the contents of your public key file. You can do this manually or use a script.
+ For example, to copy an ED25519 key to the clipboard:
+
+ **macOS:**
+
+ ```shell
+ tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy
+ ```
+
+ **Linux** (requires the `xclip` package):
+
+ ```shell
+ xclip -sel clip < ~/.ssh/id_ed25519.pub
+ ```
+
+ **Git Bash on Windows:**
+
+ ```shell
+ cat ~/.ssh/id_ed25519.pub | clip
+ ```
+
+ Replace `id_ed25519.pub` with your filename. For example, use `id_rsa.pub` for RSA.
+
+1. Sign in to GitLab.
+1. In the top right corner, select your avatar.
+1. Select **Preferences**.
+1. From the left sidebar, select **SSH Keys**.
+1. In the **Key** box, paste the contents of your public key.
+ If you manually copied the key, make sure you copy the entire key,
+ which starts with `ssh-ed25519` or `ssh-rsa`, and may end with a comment.
+1. In the **Title** text box, type a description, like _Work Laptop_ or
+ _Home Workstation_.
+1. Optional. In the **Expires at** box, select an expiration date. (Introduced in [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/36243).)
+ The expiration date is informational only, and does not prevent you from using
+ the key. However, administrators can view expiration dates and
+ use them for guidance when [deleting keys](../user/admin_area/credentials_inventory.md#delete-a-users-ssh-key).
+ - GitLab checks all SSH keys at 02:00 AM UTC every day. It emails an expiration notice for all SSH keys that expire on the current date. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.11.)
+ - GitLab checks all SSH keys at 01:00 AM UTC every day. It emails an expiration notice for all SSH keys that are scheduled to expire seven days from now. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.11.)
+1. Select **Add key**.
+
+## Verify that you can connect
+
+Verify that your SSH key was added correctly.
+
+1. For GitLab.com, to ensure you're connecting to the correct server, confirm the
+ [SSH host keys fingerprints](../user/gitlab_com/index.md#ssh-host-keys-fingerprints).
+1. Open a terminal and run this command, replacing `gitlab.example.com` with your GitLab instance URL:
+
+ ```shell
+ ssh -T git@gitlab.example.com
+ ```
+
+1. If this is the first time you connect, you should verify the
+ authenticity of the GitLab host. If you see a message like:
+
+ ```plaintext
+ The authenticity of host 'gitlab.example.com (35.231.145.151)' can't be established.
+ ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
+ Are you sure you want to continue connecting (yes/no)? yes
+ Warning: Permanently added 'gitlab.example.com' (ECDSA) to the list of known hosts.
+ ```
+
+ Type `yes` and press Enter.
+
+1. Run the `ssh -T git@gitlab.example.com` command again. You should receive a _Welcome to GitLab, `@username`!_ message.
+
+If the welcome message doesn't appear, you can troubleshoot by running `ssh`
+in verbose mode:
+
+```shell
+ssh -Tvvv git@gitlab.example.com
+```
+
+## Use different keys for different repositories
+
+You can use a different key for each repository.
+
+Open a terminal and run this command:
+
+```shell
+git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null"
+```
+
+This command does not use the SSH Agent and requires Git 2.10 or later. For more information
+on `ssh` command options, see the `man` pages for both `ssh` and `ssh_config`.
+
+## Use different accounts on a single GitLab instance
+
+You can use multiple accounts to connect to a single instance of GitLab.
+You can do this by using the command in the [previous topic](#use-different-keys-for-different-repositories).
+However, even if you set `IdentitiesOnly` to `yes`, you cannot sign in if an `IdentityFile` exists
+outside of a `Host` block.
+
+Instead, you can assign aliases to hosts in the `~.ssh/config` file.
+
+- For the `Host`, use an alias like `user_1.gitlab.com` and
+ `user_2.gitlab.com`. Advanced configurations
+ are more difficult to maintain, and these strings are easier to
+ understand when you use tools like `git remote`.
+- For the `IdentityFile`, use the path the private key.
+
+```conf
+# User1 Account Identity
+Host <user_1.gitlab.com>
+ Hostname gitlab.com
+ PreferredAuthentications publickey
+ IdentityFile ~/.ssh/<example_ssh_key1>
+
+# User2 Account Identity
+Host <user_2.gitlab.com>
+ Hostname gitlab.com
+ PreferredAuthentications publickey
+ IdentityFile ~/.ssh/<example_ssh_key2>
+```
+
+Now, to clone a repository for `user_1`, use `user_1.gitlab.com` in the `git clone` command:
+
+```shell
+git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git
+```
+
+To update a previously-cloned repository that is aliased as `origin`:
+
+```shell
+git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git
+```
+
+NOTE:
+Private and public keys contain sensitive data. Ensure the permissions
+on the files make them readable to you but not accessible to others.
+
+## Configure two-factor authentication (2FA)
+
+You can set up two-factor authentication (2FA) for
+[Git over SSH](../security/two_factor_authentication.md#two-factor-authentication-2fa-for-git-over-ssh-operations).
+
+## Use EGit on Eclipse
+
+If you are using [EGit](https://www.eclipse.org/egit/), you can [add your SSH key to Eclipse](https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration).
+
+## Use SSH on Microsoft Windows
+
+If you're running Windows 10, you can either use the [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
+with [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/install-win10#update-to-wsl-2) which
+has both `git` and `ssh` preinstalled, or install [Git for Windows](https://gitforwindows.org) to
+use SSH through Powershell.
+
+The SSH key generated in WSL is not directly available for Git for Windows, and vice versa,
+as both have a different home directory:
+
+- WSL: `/home/<user>`
+- Git for Windows: `C:\Users\<user>`
+
+You can either copy over the `.ssh/` directory to use the same key, or generate a key in each environment.
+
+Alternative tools include:
+
+- [Cygwin](https://www.cygwin.com)
+- [PuttyGen](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html)
+
+## Overriding SSH settings on the GitLab server
+
+GitLab integrates with the system-installed SSH daemon and designates a user
+(typically named `git`) through which all access requests are handled. Users
+who connect to the GitLab server over SSH are identified by their SSH key instead
+of their username.
+
+SSH *client* operations performed on the GitLab server are executed as this
+user. You can modify this SSH configuration. For example, you can specify
+a private SSH key for this user to use for authentication requests. However, this practice
+is **not supported** and is strongly discouraged as it presents significant
+security risks.
+
+GitLab checks for this condition, and directs you
+to this section if your server is configured this way. For example:
+
+```shell
+$ gitlab-rake gitlab:check
+
+Git user has default SSH configuration? ... no
+ Try fixing it:
+ mkdir ~/gitlab-check-backup-1504540051
+ sudo mv /var/lib/git/.ssh/id_rsa ~/gitlab-check-backup-1504540051
+ sudo mv /var/lib/git/.ssh/id_rsa.pub ~/gitlab-check-backup-1504540051
+ For more information see:
+ [Overriding SSH settings on the GitLab server](#overriding-ssh-settings-on-the-gitlab-server)
+ Please fix the error above and rerun the checks.
+```
+
+Remove the custom configuration as soon as you can. These customizations
+are **explicitly not supported** and may stop working at any time.
+
+## Troubleshooting SSH connections
+
+When you run `git clone`, you may be prompted for a password, like `git@gitlab.example.com's password:`.
+This indicates that something is wrong with your SSH setup.
+
+- Ensure that you generated your SSH key pair correctly and added the public SSH
+ key to your GitLab profile.
+- Try to manually register your private SSH key by using `ssh-agent`.
+- Try to debug the connection by running `ssh -Tv git@example.com`.
+ Replace `example.com` with your GitLab URL.
diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md
index 4181e32fcf23b0e80f53b27e16b8798fb59e96b1..cb77811a5daac02acd0eec7a7840de4a5e656d68 100644
--- a/doc/topics/authentication/index.md
+++ b/doc/topics/authentication/index.md
@@ -10,7 +10,7 @@ This page gathers all the resources for the topic **Authentication** within GitL
## GitLab users
-- [SSH](../../ssh/README.md)
+- [SSH](../../ssh/index.md)
- [Two-Factor Authentication (2FA)](../../user/profile/account/two_factor_authentication.md#two-factor-authentication)
- [Why do I keep getting signed out?](../../user/profile/index.md#why-do-i-keep-getting-signed-out)
- **Articles:**
diff --git a/doc/topics/git/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md
index 8b097c4c1daff64d12ee5c4a8ff703e301ef5e60..fc9c0e0ec639d6a9190783ad846c9314ec47e923 100644
--- a/doc/topics/git/how_to_install_git/index.md
+++ b/doc/topics/git/how_to_install_git/index.md
@@ -62,7 +62,7 @@ To verify that Git works on your system, run:
git --version
```
-Next, read our article on [adding an SSH key to GitLab](../../../ssh/README.md).
+Next, read our article on [adding an SSH key to GitLab](../../../ssh/index.md).
## Install Git on Ubuntu Linux
@@ -86,13 +86,13 @@ To verify that Git works on your system, run:
git --version
```
-Next, read our article on [adding an SSH key to GitLab](../../../ssh/README.md).
+Next, read our article on [adding an SSH key to GitLab](../../../ssh/index.md).
## Installing Git on Windows from the Git website
Open the [Git website](https://git-scm.com/) and download and install Git for Windows.
-Next, read our article on [adding an SSH key to GitLab](../../../ssh/README.md).
+Next, read our article on [adding an SSH key to GitLab](../../../ssh/index.md).
<!-- ## Troubleshooting
diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md
index 8db683f62914c26046f605b33f2f2b4087aaf5e5..cc2631c94451062cfba880ed0641c2529e47d330 100644
--- a/doc/topics/git/troubleshooting_git.md
+++ b/doc/topics/git/troubleshooting_git.md
@@ -45,7 +45,7 @@ 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-ssh-connections) documentation.
+instructions in the [SSH troubleshooting](../../ssh/index.md#troubleshooting-ssh-connections) documentation.
If you're a GitLab administrator with server access, you can also prevent
session timeouts by configuring SSH `keep-alive` on the client or the server.
diff --git a/doc/topics/set_up_organization.md b/doc/topics/set_up_organization.md
index d8b1ab59b9e2ead68fbbff3b9d767ace2d49b8be..d6e82a6ce87bb1317156cba1d5a9d63c7a98f094 100644
--- a/doc/topics/set_up_organization.md
+++ b/doc/topics/set_up_organization.md
@@ -12,5 +12,5 @@ and give everyone access to the projects they need.
- [Members](../user/project/members/index.md)
- [Groups](../user/group/index.md)
- [User account options](../user/profile/index.md)
-- [SSH keys](../ssh/README.md)
+- [SSH keys](../ssh/index.md)
- [GitLab.com settings](../user/gitlab_com/index.md)
diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md
index ecd259a345ce6fc913c8aca4c136f4c0b1c0f385..333e9465c31f2eee836e4d8bb5eb38f384ffdd18 100644
--- a/doc/user/admin_area/settings/sign_in_restrictions.md
+++ b/doc/user/admin_area/settings/sign_in_restrictions.md
@@ -21,7 +21,7 @@ To access sign-in restriction settings:
You can restrict the password authentication for web interface and Git over HTTP(S):
-- **Web interface**: When this feature is disabled, the **Standard** sign-in tab is removed and an [external authentication provider](../../../administration/auth/README.md) must be used.
+- **Web interface**: When this feature is disabled, the **Standard** sign-in tab is removed and an [external authentication provider](../../../administration/auth/index.md) must be used.
- **Git over HTTP(S)**: When this feature is disabled, a [Personal Access Token](../../profile/personal_access_tokens.md) must be used to authenticate.
## Admin Mode
diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md
index 8a5cdb79186b1394980a1636f91af8522cc4c1c9..3a5ea85ef150a17dc14cbd25c71bf8e8c91bbe77 100644
--- a/doc/user/group/saml_sso/index.md
+++ b/doc/user/group/saml_sso/index.md
@@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
> Introduced in GitLab 11.0.
This page describes SAML for Groups. For instance-wide SAML on self-managed GitLab instances, see [SAML OmniAuth Provider](../../../integration/saml.md).
-[View the differences between SaaS and Self-Managed Authentication and Authorization Options](../../../administration/auth/README.md#saas-vs-self-managed-comparison).
+[View the differences between SaaS and Self-Managed Authentication and Authorization Options](../../../administration/auth/index.md#saas-vs-self-managed-comparison).
SAML on GitLab.com allows users to sign in through their SAML identity provider. If the user is not already a member, the sign-in process automatically adds the user to the appropriate group.
diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md
index c097790ef16a344a2ec76e5bb4364e8aaf021ecb..1d5db6757bc5c76223b6228c3a2b6fba67bff1b1 100644
--- a/doc/user/group/settings/import_export.md
+++ b/doc/user/group/settings/import_export.md
@@ -84,7 +84,7 @@ As an administrator, you can modify the maximum import file size. To do so, use
You can export groups from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) and vice versa.
-The Enterprise Edition retains some group data that isn't part of the Community Edition. If you're exporting a group from the Enterprise Edition to the Community Edition, you may lose this data. For more information, see [downgrading from EE to CE](../../../README.md).
+The Enterprise Edition retains some group data that isn't part of the Community Edition. If you're exporting a group from the Enterprise Edition to the Community Edition, you may lose this data. For more information, see [downgrading from EE to CE](../../../index.md).
## Importing the group
diff --git a/doc/user/markdown.md b/doc/user/markdown.md
index fdfd953e52a6b9aa060538cae2be6ca31c905216..db2d6846b7c55f717b7fad1936f37916b70d1461 100644
--- a/doc/user/markdown.md
+++ b/doc/user/markdown.md
@@ -1181,7 +1181,7 @@ Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLink
<pre class="highlight"><code>- This is an [inline-style link](https://www.google.com)
- This is a [link to a repository file in the same directory](index.md)
-- This is a [relative link to a readme one directory higher](../README.md)
+- This is a [relative link to a readme one directory higher](../index.md)
- This is a [link that also has title text](https://www.google.com "This link takes you to Google!")
Using header ID anchors:
@@ -1204,7 +1204,7 @@ Some text to show that the reference links can follow later.
- This is an [inline-style link](https://www.google.com)
- This is a [link to a repository file in the same directory](index.md)
-- This is a [relative link to a README one directory higher](../README.md)
+- This is a [relative link to a README one directory higher](../index.md)
- This is a [link that also has title text](https://www.google.com "This link takes you to Google!")
Using header ID anchors:
diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md
index 9c2fccfea82cad204a989698c18371bdf869f219..70abb4237127f7005f885b10b1621b4bd246e42b 100644
--- a/doc/user/profile/index.md
+++ b/doc/user/profile/index.md
@@ -280,6 +280,6 @@ Without the `config.extend_remember_period` flag, you would be forced to sign in
- [Receive emails for sign-ins from unknown IP addresses or devices](unknown_sign_in_notification.md)
- Manage applications that can [use GitLab as an OAuth provider](../../integration/oauth_provider.md#introduction-to-oauth)
- Manage [personal access tokens](personal_access_tokens.md) to access your account via API and authorized applications
-- Manage [SSH keys](../../ssh/README.md) to access your account via SSH
+- Manage [SSH keys](../../ssh/index.md) to access your account via SSH
- Change your [syntax highlighting theme](preferences.md#syntax-highlighting-theme)
- [View your active sessions](active_sessions.md) and revoke any of them if necessary
diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md
index 890784cecf548a76893fa29840001196ef8a7ec3..08d00149037299f968cbdaa30c52ed68126e2433 100644
--- a/doc/user/project/settings/import_export.md
+++ b/doc/user/project/settings/import_export.md
@@ -110,7 +110,7 @@ and the exports between them are compatible.
You can export projects from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) and vice versa.
This assumes [version history](#version-history) requirements are met.
-If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose data that is retained only in the Enterprise Edition. For more information, see [downgrading from EE to CE](../../../README.md).
+If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose data that is retained only in the Enterprise Edition. For more information, see [downgrading from EE to CE](../../../index.md).
## Exported contents
diff --git a/lib/system_check/app/git_user_default_ssh_config_check.rb b/lib/system_check/app/git_user_default_ssh_config_check.rb
index ea6bc9c4f0136c588739b8422d46b9f099b0eea6..2876f1eb688ce3afef98f1566f20aec2abfee937 100644
--- a/lib/system_check/app/git_user_default_ssh_config_check.rb
+++ b/lib/system_check/app/git_user_default_ssh_config_check.rb
@@ -31,7 +31,7 @@ def show_error
end
try_fixing_it("mkdir #{backup_dir}", *instructions)
- for_more_information('doc/ssh/README.md in section "Overriding SSH settings on the GitLab server"')
+ for_more_information('doc/ssh/index.md in section "Overriding SSH settings on the GitLab server"')
fix_and_rerun
end
diff --git a/spec/controllers/help_controller_spec.rb b/spec/controllers/help_controller_spec.rb
index 71d9cab72801c477bf846ca18418594a3f663d44..90515e7c8f7fc96d409c754b437961d285a07fe6 100644
--- a/spec/controllers/help_controller_spec.rb
+++ b/spec/controllers/help_controller_spec.rb
@@ -150,11 +150,11 @@
context 'for Markdown formats' do
subject { get :show, params: { path: path }, format: :md }
- let(:path) { 'ssh/README' }
+ let(:path) { 'ssh/index' }
context 'when requested file exists' do
before do
- expect_file_read(File.join(Rails.root, 'doc/ssh/README.md'), content: fixture_file('blockquote_fence_after.md'))
+ expect_file_read(File.join(Rails.root, 'doc/ssh/index.md'), content: fixture_file('blockquote_fence_after.md'))
subject
end
@@ -265,7 +265,7 @@
it 'always renders not found' do
get :show,
params: {
- path: 'ssh/README'
+ path: 'ssh/index'
},
format: :foo
expect(response).to be_not_found
diff --git a/spec/haml_lint/linter/documentation_links_spec.rb b/spec/haml_lint/linter/documentation_links_spec.rb
index 22c406de57a6612233dcfd2f5233e6d80298044e..75002097d698376838d4a0667c3b6d2bc7129c42 100644
--- a/spec/haml_lint/linter/documentation_links_spec.rb
+++ b/spec/haml_lint/linter/documentation_links_spec.rb
@@ -10,30 +10,30 @@
shared_examples 'link validation rules' do |link_pattern|
context 'when link_to points to the existing file path' do
- let(:haml) { "= link_to 'Description', #{link_pattern}('README.md')" }
+ let(:haml) { "= link_to 'Description', #{link_pattern}('index.md')" }
it { is_expected.not_to report_lint }
end
context 'when link_to points to the existing file with valid anchor' do
- let(:haml) { "= link_to 'Description', #{link_pattern}('README.md', anchor: 'overview'), target: '_blank'" }
+ let(:haml) { "= link_to 'Description', #{link_pattern}('index.md', anchor: 'overview'), target: '_blank'" }
it { is_expected.not_to report_lint }
end
context 'when link_to points to the existing file path without .md extension' do
- let(:haml) { "= link_to 'Description', #{link_pattern}('README')" }
+ let(:haml) { "= link_to 'Description', #{link_pattern}('index')" }
it { is_expected.not_to report_lint }
end
context 'when anchor is not correct' do
- let(:haml) { "= link_to 'Description', #{link_pattern}('README.md', anchor: 'wrong')" }
+ let(:haml) { "= link_to 'Description', #{link_pattern}('index.md', anchor: 'wrong')" }
it { is_expected.to report_lint }
context "when #{link_pattern} has multiple options" do
- let(:haml) { "= link_to 'Description', #{link_pattern}('README.md', key: :value, anchor: 'wrong')" }
+ let(:haml) { "= link_to 'Description', #{link_pattern}('index.md', key: :value, anchor: 'wrong')" }
it { is_expected.to report_lint }
end
@@ -58,7 +58,7 @@
end
context 'when anchor belongs to a different element' do
- let(:haml) { "= link_to 'Description', #{link_pattern}('README.md'), target: (anchor: 'blank')" }
+ let(:haml) { "= link_to 'Description', #{link_pattern}('index.md'), target: (anchor: 'blank')" }
it { is_expected.not_to report_lint }
end
@@ -82,7 +82,7 @@
end
context 'when the second link is invalid' do
- let(:haml) { ".data-form{ data: { url: #{link_pattern}('README.md'), wrong_url: #{link_pattern}('wrong.md') } }" }
+ let(:haml) { ".data-form{ data: { url: #{link_pattern}('index.md'), wrong_url: #{link_pattern}('wrong.md') } }" }
it { is_expected.to report_lint }
end
diff --git a/spec/views/help/show.html.haml_spec.rb b/spec/views/help/show.html.haml_spec.rb
index ab3039196739c49f483b1df47b7eb67f2bccca37..dc73b4a2cfe2077687c3b53e994dee82b35a49ed 100644
--- a/spec/views/help/show.html.haml_spec.rb
+++ b/spec/views/help/show.html.haml_spec.rb
@@ -5,7 +5,7 @@
RSpec.describe 'help/show' do
describe 'Markdown rendering' do
before do
- assign(:path, 'ssh/README')
+ assign(:path, 'ssh/index')
assign(:markdown, 'Welcome to [GitLab](https://about.gitlab.com/) Documentation.')
end