Skip to content

G
gitlab-ce
Commit 99927cf1 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

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

Update 6 readmes to index

See merge request gitlab-org/gitlab!64893
parents 4a0281dd d008b305
Hide whitespace changes
Inline Side-by-side
Showing with 991 additions and 898 deletions
app/helpers/search_helper.rb
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
---
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 0 → 100644
View file @ 99927cf1
---
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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
---
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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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 0 → 100644
View file @ 99927cf1
---
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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
---
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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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 0 → 100644
View file @ 99927cf1
---
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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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 0 → 100644
View file @ 99927cf1
---
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
View file @ 99927cf1
---
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 0 → 100644
View file @ 99927cf1
---
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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
---
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 0 → 100644
View file @ 99927cf1
---
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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
View file @ 99927cf1
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7