Merge branch 'docs-rename-readmes-ci-4' into 'master'

Update 6 readmes to index

See merge request gitlab-org/gitlab!64893

app/helpers/search_helper.rb

@@ -177,7 +177,7 @@ module SearchHelper
       { 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") }
     ]

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 }

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' }

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

doc/README.md

 ---
-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 -->

doc/administration/auth/index.md

+---
+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) |

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 |

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)

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

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/)

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.
 

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:
 

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.
 
 ![Review Apps Workflow](img/continuous-delivery-review-apps.svg)

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.
 

doc/development/README.md

 ---
-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 -->

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)

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)

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
 

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

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

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.
 

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.
 

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)

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
 

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).

doc/development/index.md

+---
+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)

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)

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).

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)

doc/gitlab-basics/create-your-ssh-keys.md

 ---
-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

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.

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:

doc/index.md

+---
+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. |

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.

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.
 

doc/migrate_ci_to_ce/index.md

+---
+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 -->

doc/security/README.md

 ---
-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 -->

doc/security/index.md

+---
+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.

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.

doc/ssh/README.md

 ---
-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 -->

doc/ssh/index.md

+---
+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.

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:**

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
 

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.

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)

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

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.
 

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
 

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:

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

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
 

lib/system_check/app/git_user_default_ssh_config_check.rb

@@ -31,7 +31,7 @@ module SystemCheck
         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
 

spec/controllers/help_controller_spec.rb

@@ -150,11 +150,11 @@ RSpec.describe HelpController do
     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 @@ RSpec.describe HelpController do
       it 'always renders not found' do
         get :show,
             params: {
-              path: 'ssh/README'
+              path: 'ssh/index'
             },
             format: :foo
         expect(response).to be_not_found

spec/haml_lint/linter/documentation_links_spec.rb

@@ -10,30 +10,30 @@ RSpec.describe HamlLint::Linter::DocumentationLinks do
 
   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 @@ RSpec.describe HamlLint::Linter::DocumentationLinks do
     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 @@ RSpec.describe HamlLint::Linter::DocumentationLinks do
     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

spec/views/help/show.html.haml_spec.rb

@@ -5,7 +5,7 @@ require 'spec_helper'
 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