diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-12-16 21:09:43 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-12-16 21:09:43 +0300 |
commit | 0122d00cac3c058508a2fcb258f12ecfb7bc9055 (patch) | |
tree | b2a0e138ed4113e80588df57b542dc76d5360e2b /doc | |
parent | f1357e5566b2c1f4f5e7b933b72a2d24431905e9 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/administration/clusters/kas.md | 2 | ||||
-rw-r--r-- | doc/development/database/migrations_for_multiple_databases.md | 18 | ||||
-rw-r--r-- | doc/development/database/multiple_databases.md | 4 | ||||
-rw-r--r-- | doc/development/documentation/styleguide/img/tier_badge.png | bin | 9320 -> 0 bytes | |||
-rw-r--r-- | doc/development/migration_style_guide.md | 22 | ||||
-rw-r--r-- | doc/integration/jira/connect-app.md | 3 | ||||
-rw-r--r-- | doc/integration/saml.md | 127 | ||||
-rw-r--r-- | doc/user/packages/nuget_repository/img/visual_studio_adding_nuget_source.png | bin | 36730 -> 0 bytes | |||
-rw-r--r-- | doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png | bin | 6234 -> 0 bytes | |||
-rw-r--r-- | doc/user/project/pages/img/remove_fork_relationship_v13_1.png | bin | 11640 -> 0 bytes |
10 files changed, 104 insertions, 72 deletions
diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md index d7e1c9af1de..79dd69183a6 100644 --- a/doc/administration/clusters/kas.md +++ b/doc/administration/clusters/kas.md @@ -69,7 +69,7 @@ To enable the agent server on multiple nodes: - `gitlab_kas['api_secret_key']` is the shared secret used for authentication between KAS and GitLab. This value must be Base64-encoded and exactly 32 bytes long. - `gitlab_kas['private_api_secret_key']` is the shared secret used for authentication between different KAS instances. This value must be Base64-encoded and exactly 32 bytes long. -1. For each application node, follow the steps in: [Use an external installation](../clusters/kas.md#use-an-external-installation). +1. For each application node, follow the steps in [Use an external installation](../clusters/kas.md#use-an-external-installation). If the agent server is enabled on the application node, do not include `gitlab_kas['enable'] = false` in the configuration for that node. 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). ### For GitLab Helm Chart diff --git a/doc/development/database/migrations_for_multiple_databases.md b/doc/development/database/migrations_for_multiple_databases.md index 0ae9cbaf1c2..bc0ef654336 100644 --- a/doc/development/database/migrations_for_multiple_databases.md +++ b/doc/development/database/migrations_for_multiple_databases.md @@ -75,10 +75,18 @@ end #### Example: Add a new table to store in a single database -1. Define the [GitLab Schema](multiple_databases.md#gitlab-schema) of the table in [`lib/gitlab/database/gitlab_schemas.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/gitlab_schemas.yml): +1. Add the table to the [database dictionary](database_dictionary.md) in [`db/docs/`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/db/docs): ```yaml - ssh_signatures: :gitlab_main + table_name: ssh_signatures + description: Description example + introduced_by_url: Merge request link + milestone: Milestone example + feature_categories: + - Feature category example + classes: + - Class example + gitlab_schema: gitlab_main ``` 1. Create the table in a schema migration: @@ -211,7 +219,7 @@ end #### Example: run DML `gitlab_shared` only on the database containing the given `gitlab_schema` Example migration updating `loose_foreign_keys_deleted_records` table -that is marked in `lib/gitlab/database/gitlab_schemas.yml` as `gitlab_shared`. +that is marked in `db/docs/loose_foreign_keys_deleted_records.yml` as `gitlab_shared`. This migration since it configures restriction on `gitlab_ci` is executed only in context of database containing `gitlab_ci` schema. @@ -261,7 +269,7 @@ the `database_tasks: false` set. `gitlab:db:validate_config` always runs before ## Validation Validation in a nutshell uses [`pg_query`](https://github.com/pganalyze/pg_query) to analyze -each query and classify tables with information from [`gitlab_schema.yml`](multiple_databases.md#gitlab-schema). +each query and classify tables with information from [`db/docs/`](database_dictionary.md). The migration is skipped if the specified `gitlab_schema` is outside of a list of schemas managed by a given database connection (`Gitlab::Database::gitlab_schemas_for_connection`). @@ -435,4 +443,4 @@ tables in any database, just like any ordinary Sidekiq worker can. ## How to determine `gitlab_schema` for a given table -See [GitLab Schema](multiple_databases.md#gitlab-schema). +See [database dictionary](database_dictionary.md). diff --git a/doc/development/database/multiple_databases.md b/doc/development/database/multiple_databases.md index e5b6cfb8866..d22e3209096 100644 --- a/doc/development/database/multiple_databases.md +++ b/doc/development/database/multiple_databases.md @@ -14,9 +14,9 @@ On GitLab.com we are using two separate databases. ## GitLab Schema For properly discovering allowed patterns between different databases -the GitLab application implements the `lib/gitlab/database/gitlab_schemas.yml` YAML file. +the GitLab application implements the [database dictionary](database_dictionary.md). -This file provides a virtual classification of tables into a `gitlab_schema` +The database dictionary provides a virtual classification of tables into a `gitlab_schema` which conceptually is similar to [PostgreSQL Schema](https://www.postgresql.org/docs/current/ddl-schemas.html). We decided as part of [using database schemas to better isolated CI decomposed features](https://gitlab.com/gitlab-org/gitlab/-/issues/333415) that we cannot use PostgreSQL schema due to complex migration procedures. Instead we implemented diff --git a/doc/development/documentation/styleguide/img/tier_badge.png b/doc/development/documentation/styleguide/img/tier_badge.png Binary files differdeleted file mode 100644 index 5fc38e08172..00000000000 --- a/doc/development/documentation/styleguide/img/tier_badge.png +++ /dev/null diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index e857ae5b112..8f035d4aa13 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -184,13 +184,21 @@ git checkout origin/master db/structure.sql VERSION=<migration ID> bundle exec rails db:migrate:main ``` -### Adding new tables to GitLab Schema - -GitLab connects to two different Postgres databases: `main` and `ci`. New tables should be defined in [`lib/gitlab/database/gitlab_schemas.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/gitlab_schemas.yml) with the databases they need to be added to. - - ```yaml - <TABLE_NAME>: :gitlab_main - ``` +### Adding new tables to the database dictionary + +GitLab connects to two different Postgres databases: `main` and `ci`. New tables should be defined in [`db/docs/`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/db/docs): + +```yaml +table_name: table name exmaple +description: Description example +introduced_by_url: Merge request link +milestone: Milestone example +feature_categories: +- Feature category example +classes: +- Class example +gitlab_schema: gitlab_main +``` ## Avoiding downtime diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index d5a6b13b25f..513877a7b71 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -87,13 +87,14 @@ Prerequisites: - GitLab.com must serve as a proxy for the instance. - The instance must be publicly available. +- The instance must be on version 15.7 or later. You can link self-managed instances after installing the GitLab.com for Jira Cloud app from the marketplace. Jira apps can only link to one URL per marketplace listing. The official listing links to GitLab.com. ### Set up your instance -To set up your self-managed instance for the GitLab.com for Jira Cloud app: +To set up your self-managed instance for the GitLab.com for Jira Cloud app in GitLab 15.7 or later: 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Applications** (`/admin/applications`). diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 5e15a6c02f5..84879b7c4c7 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -82,8 +82,8 @@ For more information on: 1. Configure the following attributes so your SAML users cannot change them: - - [`NameID`](../user/group/saml_sso/index.md#nameid) - - `Email` when used with `omniauth_auto_link_saml_user` + - [`NameID`](../user/group/saml_sso/index.md#nameid). + - `Email` when used with `omniauth_auto_link_saml_user`. If users can change these attributes, they can sign in as other authorized users. See your SAML IdP documentation for information on how to make these attributes @@ -186,18 +186,48 @@ Your IdP may need additional configuration. For more information, see > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14361) in GitLab 14.6. -You can configure GitLab to use multiple SAML 2.0 identity providers if: +You can configure GitLab to use multiple SAML IdPs if: -- Each provider has a unique name set that matches a name set in `args`. At least one provider **must** have the name `saml` to mitigate a - [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/366450) in GitLab 14.6 and newer. -- The providers' names are: - - Used in OmniAuth configuration for properties based on the provider name. For example, `allowBypassTwoFactor`, `allowSingleSignOn`, and - `syncProfileFromProvider`. - - Used for association to each existing user as an additional identity. +- Each provider has a unique name set that matches a name set in `args`. At least + one provider must have the name `saml` to mitigate a + [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/366450) in GitLab + 14.6 and newer. +- The providers' names are used: + - In OmniAuth configuration for properties based on the provider name. For example, + `allowBypassTwoFactor`, `allowSingleSignOn`, and `syncProfileFromProvider`. + - For association to each existing user as an additional identity. - The `assertion_consumer_service_url` matches the provider name. -- The `strategy_class` is explicitly set because it cannot be inferred from provider name. +- The `strategy_class` is explicitly set because it cannot be inferred from provider + name. + +Example provider's configuration for installations from source: + +```yaml +omniauth: + providers: + - { + name: 'saml', # This must match the following name configuration parameter + args: { + name: 'saml', # This is mandatory and must match the provider name + strategy_class: 'OmniAuth::Strategies::SAML', + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider + ... # Put here all the required arguments similar to a single provider + }, + label: 'Provider 1' # Differentiate the two buttons and providers in the UI + } + - { + name: 'saml1', # This must match the following name configuration parameter + args: { + name: 'saml1', # This is mandatory and must match the provider name + strategy_class: 'OmniAuth::Strategies::SAML', + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider + ... # Put here all the required arguments similar to a single provider + }, + label: 'Provider 2' # Differentiate the two buttons and providers in the UI + } +``` -Example multiple providers configuration for Omnibus GitLab: +Example provider's configuration for Omnibus GitLab installations: To allow your users to use SAML to sign up without having to manually create an account from either of the providers, add the following values to your configuration. @@ -230,31 +260,11 @@ gitlab_rails['omniauth_providers'] = [ ] ``` -Example providers configuration for installations from source: +To allow your users to use SAML to sign up without having to manually create an +account from either of the providers, add the following values to your configuration. -```yaml -omniauth: - providers: - - { - name: 'saml', - args: { - name: 'saml', # This is mandatory and must match the provider name - strategy_class: 'OmniAuth::Strategies::SAML', - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider - ... # Put here all the required arguments similar to a single provider - }, - label: 'Provider 1' # Differentiate the two buttons and providers in the UI - } - - { - name: 'saml1', - args: { - name: 'saml1', # This is mandatory and must match the provider name - strategy_class: 'OmniAuth::Strategies::SAML', - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider - ... # Put here all the required arguments similar to a single provider - }, - label: 'Provider 2' # Differentiate the two buttons and providers in the UI - } +```ruby +gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml1'] ``` ## Set up identity providers @@ -643,11 +653,11 @@ For more information on solving these errors, see the [troubleshooting SAML guid ### Redirect users to SAML server for authentication -You can add this setting to your GitLab configuration to automatically redirect you -to your SAML server for authentication. This removes the requirement to select a button -before actually signing in. +You can add the `auto_sign_in_with_provider` setting to your GitLab configuration +to automatically redirect you to your SAML server for authentication. This removes +the requirement to select an element before actually signing in. -For Omnibus package: +For Omnibus GitLab installations: ```ruby gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml' @@ -660,31 +670,28 @@ omniauth: auto_sign_in_with_provider: saml ``` -Keep in mind that every sign in attempt redirects to the SAML server; -you cannot sign in using local credentials. Ensure at least one of the -SAML users has administrator access. +Every sign in attempt redirects to the SAML server, so you cannot sign in using +local credentials. Make sure at least one of the SAML users has administrator access. -You may also bypass the auto sign-in feature by browsing to +You can also bypass the auto sign-in feature by `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. ### Map SAML response attribute names **(FREE SELF)** -NOTE: -This setting should be used only to map attributes that are part of the OmniAuth -`info` hash schema. - -`attribute_statements` is used to map Attribute Names in a `SAMLResponse` to entries +You can use `attribute_statements` to map attribute names in a SAML response to entries in the OmniAuth [`info` hash](https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema#schema-10-and-later). +NOTE: +Only use this setting to map attributes that are part of the OmniAuth `info` hash schema. + For example, if your `SAMLResponse` contains an Attribute called `EmailAddress`, specify `{ email: ['EmailAddress'] }` to map the Attribute to the corresponding key in the `info` hash. URI-named Attributes are also supported, for example, `{ email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }`. -This setting allows you tell GitLab where to look for certain attributes required -to create an account. Like mentioned above, if your IdP sends the user's email -address as `EmailAddress` instead of `email`, let GitLab know by setting it on -your configuration: +Use this setting to tell GitLab where to look for certain attributes required +to create an account. If your IdP sends the user's email address as `EmailAddress` +instead of `email`, let GitLab know by setting it on your configuration: ```yaml args: { @@ -738,7 +745,9 @@ args: { ### Designate a unique attribute for the `uid` -By default, the `uid` is set as the `name_id` in the SAML response. If you'd like to designate a unique attribute for the `uid`, you can set the `uid_attribute`. In the example below, the value of `uid` attribute in the SAML response is set as the `uid_attribute`. +By default, the `uid` is set as the `name_id` in the SAML response. To designate +a unique attribute for the `uid`, you can set the `uid_attribute`. In the following +example, the value of `uid` attribute in the SAML response is set as the `uid_attribute`. ```yaml args: { @@ -751,9 +760,15 @@ args: { } ``` -Ensure that attributes define the SAML user, such as -[`NameID`](../user/group/saml_sso/index.md#nameid) and email address, are fixed -for each user before changing this value. +Before setting the `uid` to a unique attribute, make sure that you have configured +the following attributes so your SAML users cannot change them: + +- [`NameID`](../user/group/saml_sso/index.md#nameid). +- `Email` when used with `omniauth_auto_link_saml_user`. + +If users can change these attributes, they can sign in as other authorized users. +See your SAML IdP documentation for information on how to make these attributes +unchangeable. ## Assertion encryption (optional) diff --git a/doc/user/packages/nuget_repository/img/visual_studio_adding_nuget_source.png b/doc/user/packages/nuget_repository/img/visual_studio_adding_nuget_source.png Binary files differdeleted file mode 100644 index 7397403f4bf..00000000000 --- a/doc/user/packages/nuget_repository/img/visual_studio_adding_nuget_source.png +++ /dev/null diff --git a/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png b/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png Binary files differdeleted file mode 100644 index 8c14a14e304..00000000000 --- a/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png +++ /dev/null diff --git a/doc/user/project/pages/img/remove_fork_relationship_v13_1.png b/doc/user/project/pages/img/remove_fork_relationship_v13_1.png Binary files differdeleted file mode 100644 index 84aa2e571c7..00000000000 --- a/doc/user/project/pages/img/remove_fork_relationship_v13_1.png +++ /dev/null |