diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-05-11 09:09:11 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-05-11 09:09:11 +0000 |
commit | e348fb4c1b9eaf21655001dc4346ceb0c0c3d5b4 (patch) | |
tree | c11afe15edfe85d809ab0be78a6f52a539d28bec /doc | |
parent | ce567e98da6118031576d9084d3e05473746e4c6 (diff) | |
download | gitlab-ce-e348fb4c1b9eaf21655001dc4346ceb0c0c3d5b4.tar.gz |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/packages.md | 65 | ||||
-rw-r--r-- | doc/ci/mobile_devops.md | 410 | ||||
-rw-r--r-- | doc/gitlab-basics/start-using-git.md | 2 | ||||
-rw-r--r-- | doc/integration/jira/configure.md | 23 | ||||
-rw-r--r-- | doc/integration/saml.md | 3 | ||||
-rw-r--r-- | doc/operations/error_tracking.md | 6 | ||||
-rw-r--r-- | doc/user/analytics/value_streams_dashboard.md | 57 | ||||
-rw-r--r-- | doc/user/application_security/dast/proxy-based.md | 41 | ||||
-rw-r--r-- | doc/user/packages/maven_repository/index.md | 57 | ||||
-rw-r--r-- | doc/user/packages/package_registry/supported_functionality.md | 210 | ||||
-rw-r--r-- | doc/user/profile/account/two_factor_authentication.md | 47 | ||||
-rw-r--r-- | doc/user/profile/personal_access_tokens.md | 3 |
12 files changed, 709 insertions, 215 deletions
diff --git a/doc/api/packages.md b/doc/api/packages.md index 86eaf3028cf..58026f5e25f 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -37,6 +37,12 @@ GET /projects/:id/packages curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages" ``` +> **Deprecation:** +> +> The `pipelines` attribute in the response is deprecated in favor of the package pipelines endpoint, which was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341950) in GitLab 16.0. The `pipelines` attribute always returns an empty array if the feature flag is enabled. +> The `pipeline` attribute in the response is deprecated in favor of `pipelines`, which was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44348) in GitLab 13.6. Both are available until 13.7. +> The `build_info` attribute in the response is deprecated in favor of `pipeline`, which was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28040) in GitLab 12.10. + Example response: ```json @@ -46,14 +52,16 @@ Example response: "name": "com/mycompany/my-app", "version": "1.0-SNAPSHOT", "package_type": "maven", - "created_at": "2019-11-27T03:37:38.711Z" + "created_at": "2019-11-27T03:37:38.711Z", + "pipelines": [] }, { "id": 2, "name": "@foo/bar", "version": "1.0.3", "package_type": "npm", - "created_at": "2019-11-27T03:37:38.711Z" + "created_at": "2019-11-27T03:37:38.711Z", + "pipelines": [] }, { "id": 3, @@ -66,7 +74,8 @@ Example response: "delete_api_path": "https://gitlab.example.com/api/v4/projects/1/packages/3" }, "created_at": "2029-12-16T20:33:34.316Z", - "tags": [] + "tags": [], + "pipelines": [] } ] ``` @@ -106,6 +115,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a > **Deprecation:** > +> The `pipelines` attribute in the response is deprecated in favor of the package pipelines endpoint, which was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341950) in GitLab 16.0. The `pipelines` attribute always returns an empty array if the feature flag is enabled. > The `pipeline` attribute in the response is deprecated in favor of `pipelines`, which was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44348) in GitLab 13.6. Both are available until 13.7. > The `build_info` attribute in the response is deprecated in favor of `pipeline`, which was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28040) in GitLab 12.10. @@ -123,21 +133,7 @@ Example response: "delete_api_path": "/namespace1/project1/-/packages/1" }, "created_at": "2019-11-27T03:37:38.711Z", - "pipelines": [ - { - "id": 123, - "status": "pending", - "ref": "new-pipeline", - "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", - "web_url": "https://example.com/foo/bar/pipelines/47", - "created_at": "2016-08-11T11:28:34.085Z", - "updated_at": "2016-08-11T11:32:35.169Z", - "user": { - "name": "Administrator", - "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon" - } - } - ] + "pipelines": [] }, { "id": 2, @@ -149,21 +145,7 @@ Example response: "delete_api_path": "/namespace1/project1/-/packages/1" }, "created_at": "2019-11-27T03:37:38.711Z", - "pipelines": [ - { - "id": 123, - "status": "pending", - "ref": "new-pipeline", - "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", - "web_url": "https://example.com/foo/bar/pipelines/47", - "created_at": "2016-08-11T11:28:34.085Z", - "updated_at": "2016-08-11T11:32:35.169Z", - "user": { - "name": "Administrator", - "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon" - } - } - ] + "pipelines": [] } ] ``` @@ -197,6 +179,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a > **Deprecation:** > +> The `pipelines` attribute in the response is deprecated in favor of the package pipelines endpoint, which was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341950) in GitLab 16.0. The `pipelines` attribute always returns an empty array if the feature flag is enabled. > The `pipeline` attribute in the response is deprecated in favor of `pipelines`, which was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44348) in GitLab 13.6. Both are available until 13.7. > The `build_info` attribute in the response is deprecated in favor of `pipeline`, which was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28040) in GitLab 12.10. @@ -214,21 +197,7 @@ Example response: }, "created_at": "2019-11-27T03:37:38.711Z", "last_downloaded_at": "2022-09-07T07:51:50.504Z" - "pipelines": [ - { - "id": 123, - "status": "pending", - "ref": "new-pipeline", - "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", - "web_url": "https://example.com/foo/bar/pipelines/47", - "created_at": "2016-08-11T11:28:34.085Z", - "updated_at": "2016-08-11T11:32:35.169Z", - "user": { - "name": "Administrator", - "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon" - } - } - ], + "pipelines": [], "versions": [ { "id":2, diff --git a/doc/ci/mobile_devops.md b/doc/ci/mobile_devops.md index c4316a33980..175a63dc3b9 100644 --- a/doc/ci/mobile_devops.md +++ b/doc/ci/mobile_devops.md @@ -5,11 +5,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Mobile DevOps +# Mobile DevOps (Experimental) -GitLab Mobile DevOps is a collection of features and tools designed for mobile developers -and teams to automate their build and release process using GitLab CI/CD. Mobile DevOps -is an experimental feature developed by [GitLab Incubation Engineering](https://about.gitlab.com/handbook/engineering/incubation/). +Use GitLab Mobile DevOps to quickly build, sign, and release native and cross-platform mobile apps +for Android and iOS using GitLab CI/CD. Mobile DevOps is an experimental feature developed by +[GitLab Incubation Engineering](https://about.gitlab.com/handbook/engineering/incubation/). Mobile DevOps is still in development, but you can: @@ -17,14 +17,399 @@ Mobile DevOps is still in development, but you can: - [Report a bug](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=report_bug). - [Share feedback](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=general_feedback). +## Build environments + +Get started quickly by using [GitLab.com SaaS runners](../ci/runners/index.md), +or set up [self-managed runners](https://docs.gitlab.com/runner/#use-self-managed-runners) +for complete control over the build environment. + +### Android build environments + +Set up an Android build environment by selecting an appropriate Docker image +and adding it to your `.gitlab-ci.yml` file. [Fabernovel](https://hub.docker.com/r/fabernovel/android/tags) +provides a variety of supported Android versions. + +For example: + +```yaml +test: + image: fabernovel/android:api-33-v1.7.0 + stage: test + script: + - fastlane test +``` + +### iOS build environments + +GitLab SaaS runners on macOS are currently available in beta. Follow the [instructions to request access](../ci/runners/saas/macos_saas_runner.md#access-request-process) +for your project. + +After you are granted access to the beta macOS runners, [choose an image](../ci/runners/saas/macos/environment.md#available-images) +and add it to your `.gitlab-ci.yml` file. + +For example: + +```yaml +test: + image: macos-12-xcode-14 + stage: test + script: + - fastlane test + tags: + - saas-macos-medium-m1 +``` + ## Code signing -With [project-level secure files](secure_files/index.md), you can manage key stores and provision profiles -and signing certificates directly in a GitLab project. +All Android and iOS apps must be securely signed before being distributed through +the various app stores. Signing ensures that applications haven't been tampered with +before reaching a user's device. + +With [project-level secure files](secure_files/index.md), you can store the following +in GitLab, so that they can be used to securely sign apps in CI/CD builds: + +- Keystores +- Provision profiles +- Signing certificates <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Project-level secure files demo](https://youtu.be/O7FbJu3H2YM). +### Code signing Android projects with fastlane & Gradle + +To set up code signing for Android: + +1. Upload your keystore and keystore properties files to project-level secure files. +1. Update the Gradle configuration to use those files in the build. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [How to build and release an Android app to Google Play with GitLab](https://youtu.be/u8yC8W2k85U). + +#### Create a keystore + +Run the following command to generate a keystore file if you don't already have one: + +```shell +keytool -genkey -v -keystore release-keystore.jks -storepass password -alias release -keypass password -keyalg RSA -keysize 2048 -validity 10000 +``` + +Next, put the keystore configuration in a file called `release-keystore.properties`, +which should look similar to this example: + +```plaintext +storeFile=.secure_files/release-keystore.jks +keyAlias=release +keyPassword=password +storePassword=password +``` + +After these files are created: + +- [Upload them as Secure Files](secure_files/index.md) in the GitLab project + so they can be used in CI/CD jobs. +- Add both files to your `.gitignore` file so they aren't committed to version control. + +#### Configure Gradle + +The next step is to configure Gradle to use the newly created keystore. In the app's `build.gradle` file: + +1. Immediately after the plugins section, add: + + ```gradle + def keystoreProperties = new Properties() + def keystorePropertiesFile = rootProject.file('.secure_files/release-keystore.properties') + if (keystorePropertiesFile.exists()) { + keystoreProperties.load(new FileInputStream(keystorePropertiesFile)) + } + ``` + +1. Anywhere within the `android` block, add: + + ```gradle + signingConfigs { + release { + keyAlias keystoreProperties['keyAlias'] + keyPassword keystoreProperties['keyPassword'] + storeFile keystoreProperties['storeFile'] ? file(keystoreProperties['storeFile']) : null + storePassword keystoreProperties['storePassword'] + } + } + ``` + +1. Add the `signingConfig` to the release build type: + + ```gradle + signingConfig signingConfigs.release + ``` + +With this configuration in place, you can use fastlane to build & sign the app +with the files stored in secure files. + +For example: + +- Sample `fastlane/Fastfile` file: + + ```ruby + default_platform(:android) + + platform :android do + desc "Create and sign a new build" + lane :build do + gradle(tasks: ["clean", "assembleRelease", "bundleRelease"]) + end + end + ``` + +- Sample `.gitlab-ci.yml` file: + + ```yaml + build: + image: fabernovel/android:api-33-v1.7.0 + stage: build + script: + - apt update -y && apt install -y curl + - curl --silent "https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/download-secure-files/-/raw/main/installer" | bash + - fastlane build + ``` + +### Code sign iOS projects with fastlane + +To set up code signing for iOS, you must: + +1. Install fastlane locally so you can upload your signing certificates to GitLab. +1. Configure the build to use those files. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [How to build and release an iOS app to Test Flight with GitLab](https://youtu.be/Ar8IsBgP1as). + +#### Initialize fastlane + +With fastlane installed, start by running: + +```shell +fastlane init +``` + +This command creates a `fastlane` folder in the project with an `Appfile` and a stubbed-out `fastfile`. +This process asks you for login credentials to App Store Connect +to generate an app identifier and App Store app if they don't already exist. + +The next step sets up fastlane match to manage code signing files for the project. +Run the following command to generate a `Matchfile` with the configuration: + +```shell +fastlane match init +``` + +This command prompts you to: + +- Choose which storage backend you want to use, you must select `gitlab_secure_files`. +- Input your project path, for example `gitlab-org/gitlab`. + +#### Generate and upload certificates + +Run the following command to generate certificates and profiles in the Apple Developer portal +and upload those files to GitLab: + +```shell +PRIVATE_TOKEN=YOUR-TOKEN bundle exec fastlane match development +``` + +In this example: + +- `YOUR-TOKEN` must be either a personal or project access token with Maintainer role for the GitLab project. +- Replace `development` with the type of build you want to sign, for example `appstore` or `ad-hoc`. + +You can view the files in your project's CI/CD settings as soon as the command completes. + +#### Upload-only + +If you have already created signing certificates and provisioning profiles for your project, +you can optionally use `fastlane match import` to load your existing files into GitLab: + +```shell +PRIVATE_TOKEN=YOUR-TOKEN bundle exec fastlane match import +``` + +You are prompted to input the path to your files. After you provide those details, +your files are uploaded and visible in your project's CI/CD settings. +If prompted for the `git_url` during the import, it is safe to leave it blank and press <kbd>enter</kbd>. + +With this configuration in place, you can use fastlane to build and sign the app with +the files stored in secure files. + +For example: + +- Sample `fastlane/Fastfile` file: + + ```ruby + default_platform(:ios) + + platform :ios do + desc "Build and sign the application for development" + lane :build do + setup_ci + + match(type: 'development', readonly: is_ci) + + build_app( + project: "ios demo.xcodeproj", + scheme: "ios demo", + configuration: "Debug", + export_method: "development" + ) + end + end + ``` + +- Sample `.gitlab-ci.yml` file: + + ```yaml + build_ios: + image: macos-12-xcode-14 + stage: build + script: + - fastlane build + tags: + - shared-macos-amd64 + ``` + +## Distribution + +Signed builds can be uploaded to the Google Play Store or Apple App Store by using +the Mobile DevOps Distribution integrations. + +### Android distribution with Google Play integration and fastlane + +To create an Android distribution with Google Play integration and fastlane, you must: + +1. [Create a Google service account](https://docs.fastlane.tools/actions/supply/#setup) + in Google Cloud Platform and grant that account access to the project in Google Play. +1. [Enable the Google Play integration](#enable-google-play-integration). +1. Add the release step to your pipeline. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Google Play integration demo](https://youtu.be/Fxaj3hna4uk). + +#### Enable Google Play Integration + +Use the [Google Play integration](../user/project/integrations/google_play.md), +to configure your CI/CD pipelines to connect to the [Google Play Console](https://play.google.com/console) +to build and release Android apps. To enable the integration: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Google Play**. +1. In **Enable integration**, select the **Active** checkbox. +1. In **Package name**, enter the package name of the app. For example, `com.gitlab.app_name`. +1. In **Service account key (.JSON)** drag or upload your key file. +1. Select **Save changes**. + +With the integration enabled, you can use fastlane to distribute a build to Google Play. + +For example: + +- Sample `fastlane/Fastfile`: + + ```ruby + default_platform(:android) + + platform :android do + desc "Submit a new Beta build to the Google Play store" + lane :beta do + upload_to_play_store( + track: 'internal', + aab: 'app/build/outputs/bundle/release/app-release.aab', + release_status: 'draft' + ) + end + end + ``` + +- Sample `.gitlab-ci.yml`: + + ```yaml + beta: + image: fabernovel/android:api-33-v1.7.0 + stage: beta + script: + - fastlane beta + ``` + +### iOS distribution Apple Store integration and fastlane + +To create an iOS distribution with the Apple Store integration and fastlane, you must: + +1. Generate an API Key for App Store Connect API. In the Apple App Store Connect portal, + [generate a new private key for your project](https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api). +1. [Enable the Apple App Store integration](#enable-apple-app-store-integration). +1. Add the release step to your pipeline and fastlane configuration. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Apple App Store integration demo](https://youtu.be/CwzAWVgJeK8). + +#### Enable Apple App Store Integration + +Use the [Apple App Store integration](../user/project/integrations/apple_app_store.md) +to configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com/) +to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. To enable the integration: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Apple App Store**. +1. Turn on the **Active** toggle under **Enable Integration**. +1. Provide the Apple App Store Connect configuration information: + - **Issuer ID**: You can find the Apple App Store Connect Issuer ID in the **Keys** section under **Users and Access** in the Apple App Store Connect portal. + - **Key ID**: The key ID of the new private key that was just generated. + - **Private Key**: The private key that was just generated. You can only download this key one time. +1. Select **Save changes**. + +With the integration enabled, you can use fastlane to distribute a build to TestFlight +and the Apple App Store. + +For example: + +- Sample `fastlane/Fastfile`: + + ```ruby + default_platform(:ios) + + platform :ios do + desc "Build and sign the application for distribution, upload to TestFlight" + lane :beta do + setup_ci + + match(type: 'appstore', readonly: is_ci) + + app_store_connect_api_key + + increment_build_number( + build_number: latest_testflight_build_number(initial_build_number: 1) + 1, + xcodeproj: "ios demo.xcodeproj" + ) + + build_app( + project: "ios demo.xcodeproj", + scheme: "ios demo", + configuration: "Release", + export_method: "app-store" + ) + + upload_to_testflight + end + end + ``` + +- Sample `.gitlab-ci.yml`: + + ```yaml + beta_ios: + image: macos-12-xcode-14 + stage: beta + script: + - fastlane beta + ``` + ## Review apps for mobile You can use [review apps](review_apps/index.md) to preview changes directly from a merge request. @@ -42,11 +427,14 @@ to run static analyzers on code to check for known security vulnerabilities. Mob expands this functionality for mobile teams with an [experimental SAST feature](../user/application_security/sast/index.md#experimental-features) based on [Mobile Security Framework (MobSF)](https://github.com/MobSF/Mobile-Security-Framework-MobSF). -## Automated releases +## Sample Reference Projects -With the [Apple App Store integration](../user/project/integrations/apple_app_store.md), you can configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com/) to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. +See the sample reference projects below for complete build, sign, and release pipeline examples for various platforms. A list of all available projects can be found in [the Mobile DevOps Demo Projects group](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/demo-projects/). -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Apple App Store integration demo](https://youtu.be/CwzAWVgJeK8). +- [Android Demo](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/demo-projects/android_demo) +- [iOS Demo](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/demo-projects/ios-demo) +- [Flutter Demo](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/demo-projects/flutter-demo) + +## Mobile DevOps Blog -With the [Google Play integration](../user/project/integrations/google_play.md), you can configure your CI/CD pipelines to connect to the [Google Play Console](https://play.google.com/console) to build and release apps for Android devices. +Additional reference material can be found in the [#mobile section](https://about.gitlab.com/blog/tags.html#mobile) of the GitLab blog. diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md index b86765a318e..fd322b67abe 100644 --- a/doc/gitlab-basics/start-using-git.md +++ b/doc/gitlab-basics/start-using-git.md @@ -152,7 +152,7 @@ between your computer and GitLab. If you have enabled two-factor authentication (2FA) on your account, you cannot use your account password. Instead, you can do one of the following: - [Clone using a token](#clone-using-a-token) with `read_repository` or `write_repository` permissions. - - Install [Git Credential Manager](../user/profile/account/two_factor_authentication.md#git-credential-manager). + - Install an [OAuth credential helper](../user/profile/account/two_factor_authentication.md#oauth-credential-helpers). If you have not enabled 2FA, use your account password. diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index e6d5f392798..25aafb6089f 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -37,14 +37,21 @@ To configure your project settings in GitLab: [closing reference](../../user/project/issues/managing_issues.md#closing-issues-automatically) is made in GitLab, select **Enable Jira transitions**. 1. Provide Jira configuration information: - - **Web URL**: The base URL to the Jira instance web interface you're linking to - this GitLab project, such as `https://jira.example.com`. - - **Jira API URL**: The base URL to the Jira instance API, such as `https://jira-api.example.com`. - Defaults to the **Web URL** value if not set. Leave blank if using **Jira on Atlassian cloud**. - - **Username or Email**: - For **Jira Server**, use `username`. For **Jira on Atlassian cloud**, use `email`. - - **Password/API token**: - Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. + - **Web URL**: The base URL for the Jira instance web interface you're linking to + this GitLab project (for example, `https://jira.example.com`). + - **Jira API URL**: The base URL for the Jira instance API (for example, `https://jira-api.example.com`). + If this URL is not set, the **Web URL** value is used by default. Leave blank if you use **Jira Cloud**. + - **Authentication type**: From the dropdown list, select: + - **Basic** + - **Jira personal access token (Jira Data Center and Jira Server only)** + - **Email or username** (relevant to **Basic** authentication only): + - For Jira Cloud, enter an email. + - For Jira Data Center and Jira Server, enter a username. + - **New API token, password, or Jira personal access token**: + - For **Basic** authentication: + - For Jira Cloud, enter an API token. + - For Jira Data Center and Jira Server, enter a password. + - For **Jira personal access token** authentication, enter the token. 1. To enable users to [view Jira issues](issues.md#view-jira-issues) inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. diff --git a/doc/integration/saml.md b/doc/integration/saml.md index aa3e02abc29..f59824c8db6 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -2975,8 +2975,7 @@ Users authenticated with SSO or SAML must not use a password for Git operations over HTTPS. These users can instead: - Set up a [personal access token](../user/profile/personal_access_tokens.md). -- Use the [Git Credential Manager](../user/profile/account/two_factor_authentication.md#git-credential-manager) - which securely authenticates using OAuth. +- Use an [OAuth credential helper](../user/profile/account/two_factor_authentication.md#oauth-credential-helpers). ## Link SAML identity for an existing user diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index 8931f3ef833..db68abf0778 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -6,12 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Error Tracking **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389991) in GitLab 15.9. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389991) -for use in GitLab 15.9, and is planned for removal in GitLab 16.0. We are replacing this feature with functionality in the [GitLab Observability UI](https://gitlab.com/gitlab-org/opstrace/opstrace-ui). Please also reference our direction for [Observability](https://about.gitlab.com/direction/monitor/observability/) and [data visualization](https://about.gitlab.com/direction/monitor/observability/data-visualization/). - Error Tracking allows developers to discover and view errors generated by their application. Because error information is surfaced where the code is being developed, efficiency and awareness are increased. ## How error tracking works diff --git a/doc/user/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md index 9e4b828f4c2..771a7334c4e 100644 --- a/doc/user/analytics/value_streams_dashboard.md +++ b/doc/user/analytics/value_streams_dashboard.md @@ -68,14 +68,69 @@ You can customize the Value Streams Dashboard and configure what subgroups and p A view can display maximum four subgroups or projects. +### Using query parameters + To display multiple subgroups and projects, specify their path as a URL parameter. -For example, the parameter `query=gitlab-org/gitlab-foss,gitlab-org/gitlab,gitlab-org/gitlab-design,gitlab-org/gitlab-docs` displays three separate panels, one each for the: +For example, the parameter `query=gitlab-org/gitlab-ui,gitlab-org/plan-stage` displays three separate panels, one each for the: - `gitlab-org` group - `gitlab-ui` project - `gitlab-org/plan-stage` subgroup +### Using YAML configuration + +To change the default content of the page, you need to create a YAML configuration file in a project of your choice. Query parameters can still be used to override the YAML configuration. + +First, you need to set up the project. + +Prerequisite: + +- You must have at least the Maintainer role for the group. + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Scroll to **Analytics Dashboards** and select **Expand**. +1. Select the project where you would like to store your YAML configuration file. +1. Select **Save changes**. + +After you have set up the project, set up the configuration file: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. In the default branch, create the configuration file: `.gitlab/analytics/dashboards/value_streams/value_streams.yaml`. +1. In the `value_streams.yaml` configuration file, fill in the configuration options: + +```yaml +# title - Change the title of the Value Streams Dashboard. [optional] +title: 'Custom Dashboard title' + +# description - Change the description of the Value Streams Dashboard. [optional] +description: 'Custom description' + +# widgets - List of widgets that contain panel settings. +# title - Change the title of the panel. [optional] +# data.namespace - The Group or Project path to use for the chart panel. +widgets: + - title: 'My Custom Project' + data: + namespace: group/my-custom-project + - data: + namespace: group/another-project + - title: 'My Custom Group' + data: + namespace: group/my-custom-group + - data: + namespace: group/another-group +``` + + The following example has an option configuration for a widget for the `my-group` namespace: + + ```yaml + widgets: + - data: + namespace: my-group + ``` + ## Dashboard metrics and drill-down reports | Metric | Description | Drill-down report | Documentation page | diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md index 8b71e340a43..f65501712cc 100644 --- a/doc/user/application_security/dast/proxy-based.md +++ b/doc/user/application_security/dast/proxy-based.md @@ -358,37 +358,36 @@ including a large number of false positives. | CI/CD variable | Type | Description | |:------------------------------------------------|:--------------|:------------------------------| -| `DAST_ADVERTISE_SCAN` | boolean | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334947) in GitLab 14.1. | -| `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. | +| `DAST_ADVERTISE_SCAN` | boolean | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. | +| `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. | | `DAST_ALLOWED_HOSTS` | Comma-separated list of strings | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. Headers set using `DAST_REQUEST_HEADERS` are added to every request made to these hostnames. Example, `site.com,another.com`. | -| `DAST_API_HOST_OVERRIDE` <sup>1</sup> | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383467)** in GitLab 15.7. Replaced by [DAST API scan](../dast_api/index.md#available-cicd-variables). Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080`. | -| `DAST_API_SPECIFICATION` <sup>1</sup> | URL or string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383467)** in GitLab 15.7. Replaced by [DAST API scan](../dast_api/index.md#available-cicd-variables). The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. The variable `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_API_HOST_OVERRIDE` <sup>1</sup> | string | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/383467)** in GitLab 16.0. Replaced by [DAST API scan](../dast_api/index.md#available-cicd-variables). | +| `DAST_API_SPECIFICATION` <sup>1</sup> | URL or string | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/383467)** in GitLab 16.0. Replaced by [DAST API scan](../dast_api/index.md#available-cicd-variables). | | `DAST_AUTH_EXCLUDE_URLS` | URLs | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289959)** in GitLab 14.0. Replaced by `DAST_EXCLUDE_URLS`. The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. | | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false`. | -| `DAST_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | +| `DAST_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. | +| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. | | `DAST_EXCLUDE_URLS` <sup>1</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Example, `http://example.com/sign-out`. | -| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Default: `false` | | `DAST_FULL_SCAN_ENABLED` <sup>1</sup> | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | -| `DAST_HTML_REPORT` | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/384340)** in GitLab 15.7. The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_MARKDOWN_REPORT` | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/384340)** in GitLab 15.7. The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | -| `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. | -| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | -| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | -| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_HTML_REPORT` | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/384340)** in GitLab 15.7. The filename of the HTML report written at the end of a scan. | +| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. | +| `DAST_MARKDOWN_REPORT` | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/384340)** in GitLab 15.7. The filename of the Markdown report written at the end of a scan. | +| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked. Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | +| `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. | +| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. | +| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. | +| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line. | | `DAST_PKCS12_CERTIFICATE_BASE64` | string | The PKCS12 certificate used for sites that require Mutual TLS. Must be encoded as base64 text. | | `DAST_PKCS12_PASSWORD` | string | The password of the certificate used in `DAST_PKCS12_CERTIFICATE_BASE64`. | | `DAST_REQUEST_HEADERS` <sup>1</sup> | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | -| `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | -| `DAST_SPIDER_MINS` <sup>1</sup> | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | +| `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. | +| `DAST_SPIDER_MINS` <sup>1</sup> | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. | +| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. | | `DAST_TARGET_AVAILABILITY_TIMEOUT` <sup>1</sup> | number | Time limit in seconds to wait for target availability. | -| `DAST_USE_AJAX_SPIDER` <sup>1</sup> | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_XML_REPORT` | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/384340)** in GitLab 15.7. The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_USE_AJAX_SPIDER` <sup>1</sup> | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. | +| `DAST_XML_REPORT` | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/384340)** in GitLab 15.7. The filename of the XML report written at the end of a scan. | | `DAST_WEBSITE` <sup>1</sup> | URL | The URL of the website to scan. | -| `DAST_ZAP_CLI_OPTIONS` | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383467)** in GitLab 15.7. ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_ZAP_CLI_OPTIONS` | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383467)** in GitLab 15.7. ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. | | `DAST_ZAP_LOG_CONFIGURATION` | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383467)** in GitLab 15.7. Set to a semicolon-separated list of additional log4j properties for the ZAP Server. Example: `logger.httpsender.name=org.parosproxy.paros.network.HttpSender;logger.httpsender.level=debug;logger.sitemap.name=org.parosproxy.paros.model.SiteMap;logger.sitemap.level=debug;` | | `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 72bd7fd5b09..fd8049d9b75 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -16,6 +16,9 @@ Supported clients: - `mvn`. Learn how to build a [Maven](../workflows/build_packages.md#maven) package. - `gradle`. Learn how to build a [Gradle](../workflows/build_packages.md#gradle) package. +- `sbt`. + - `sbt` can only be used to [pull dependencies](#install-a-package). + See this [issue 408479](https://gitlab.com/gitlab-org/gitlab/-/issues/408479) for more details. ## Publish to the GitLab Package Registry @@ -124,6 +127,44 @@ file: } ``` +:::TabTitle `sbt` + +| Token type | Name must be | Token | +|-----------------------|------------------------------|------------------------------------------------------------------------| +| Personal access token | The username of the user | Paste token as-is, or define an environment variable to hold the token | +| Deploy token | The username of deploy token | Paste token as-is, or define an environment variable to hold the token | +| CI Job token | `gitlab-ci-token` | `sys.env.get("CI_JOB_TOKEN").get` | + +Authentication for [SBT](https://www.scala-sbt.org/index.html) is based on +[basic HTTP Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). +You must to provide a name and a password. + +NOTE: +The name field must be named to match the token you chose. + +To install a package from the Maven GitLab Package Registry by using `sbt`, you must configure +a [Maven resolver](https://www.scala-sbt.org/1.x/docs/Resolvers.html#Maven+resolvers). +If you're accessing a private or an internal project or group, you need to set up +[credentials](https://www.scala-sbt.org/1.x/docs/Publishing.html#Credentials). +After configuring the resolver and authentication, you can install a package +from a project, group, or namespace. + +In your [`build.sbt`](https://www.scala-sbt.org/1.x/docs/Directories.html#sbt+build+definition+files), add the following lines: + +```scala +resolvers += ("gitlab" at "<endpoint url>") + +credentials += Credentials("GitLab Packages Registry", "<host>", "<name>", "<token>") +``` + +In this example: + +- `<endpoint url>` is the [endpoint URL](#endpoint-urls). +Example: `https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven`. +- `<host>` is the host present in the `<endpoint url>` without the protocol +scheme or the port. Example: `gitlab.example.com`. +- `<name>` and `<token>` are explained in the table above. + ::EndTabs ### Naming convention @@ -403,6 +444,22 @@ To install a package by using `gradle`: gradle install ``` +:::TabTitle `sbt` + +To install a package by using `sbt`: + +1. Add an [inline dependency](https://www.scala-sbt.org/1.x/docs/Library-Management.html#Dependencies) to `build.sbt`: + + ```scala + libraryDependencies += "com.mycompany.mydepartment" % "my-project" % "8.4" + ``` + +1. In your project, run the following: + + ```shell + sbt update + ``` + ::EndTabs ## Helpful hints diff --git a/doc/user/packages/package_registry/supported_functionality.md b/doc/user/packages/package_registry/supported_functionality.md index aab35f4e8ac..ca174c43565 100644 --- a/doc/user/packages/package_registry/supported_functionality.md +++ b/doc/user/packages/package_registry/supported_functionality.md @@ -13,58 +13,64 @@ and pulling packages, request forwarding, managing duplicates, and authenticatio Packages can be published to your project, group, or instance. -| Package type | Project | Group | Instance | -|-----------------------------------------------------|---------|-------|----------| -| [Maven](../maven_repository/index.md) | Y | N | N | -| [npm](../npm_registry/index.md) | Y | N | N | -| [NuGet](../nuget_repository/index.md) | Y | N | N | -| [PyPI](../pypi_repository/index.md) | Y | N | N | -| [Generic packages](../generic_packages/index.md) | Y | N | N | -| [Terraform](../terraform_module_registry/index.md) | Y | N | N | -| [Composer](../composer_repository/index.md) | N | Y | N | -| [Conan](../conan_repository/index.md) | Y | N | Y | -| [Helm](../helm_repository/index.md) | Y | N | N | -| [Debian](../debian_repository/index.md) | Y | N | N | -| [Go](../go_proxy/index.md) | Y | N | N | -| [Ruby gems](../rubygems_registry/index.md) | Y | N | N | +| Package type | Project | Group | Instance | +|-------------------------------------------------------|---------|-------|----------| +| [Maven (with `mvn`)](../maven_repository/index.md) | Y | N | N | +| [Maven (with `gradle`)](../maven_repository/index.md) | Y | N | N | +| [Maven (with `sbt`)](../maven_repository/index.md) | N | N | N | +| [npm](../npm_registry/index.md) | Y | N | N | +| [NuGet](../nuget_repository/index.md) | Y | N | N | +| [PyPI](../pypi_repository/index.md) | Y | N | N | +| [Generic packages](../generic_packages/index.md) | Y | N | N | +| [Terraform](../terraform_module_registry/index.md) | Y | N | N | +| [Composer](../composer_repository/index.md) | N | Y | N | +| [Conan](../conan_repository/index.md) | Y | N | Y | +| [Helm](../helm_repository/index.md) | Y | N | N | +| [Debian](../debian_repository/index.md) | Y | N | N | +| [Go](../go_proxy/index.md) | Y | N | N | +| [Ruby gems](../rubygems_registry/index.md) | Y | N | N | ## Pulling packages **(FREE)** Packages can be pulled from your project, group, or instance. -| Package type | Project | Group | Instance | -|-----------------------------------------------------|---------|-------|----------| -| [Maven](../maven_repository/index.md) | Y | Y | Y | -| [npm](../npm_registry/index.md) | Y | N | Y | -| [NuGet](../nuget_repository/index.md) | Y | Y | N | -| [PyPI](../pypi_repository/index.md) | Y | Y | N | -| [Generic packages](../generic_packages/index.md) | Y | N | N | -| [Terraform](../terraform_module_registry/index.md) | N | Y | N | -| [Composer](../composer_repository/index.md) | Y | Y | N | -| [Conan](../conan_repository/index.md) | Y | N | Y | -| [Helm](../helm_repository/index.md) | Y | N | N | -| [Debian](../debian_repository/index.md) | Y | N | N | -| [Go](../go_proxy/index.md) | Y | N | Y | -| [Ruby gems](../rubygems_registry/index.md) | Y | N | N | +| Package type | Project | Group | Instance | +|-------------------------------------------------------|---------|-------|----------| +| [Maven (with `mvn`)](../maven_repository/index.md) | Y | Y | Y | +| [Maven (with `gradle`)](../maven_repository/index.md) | Y | Y | Y | +| [Maven (with `sbt`)](../maven_repository/index.md) | Y | Y | Y | +| [npm](../npm_registry/index.md) | Y | N | Y | +| [NuGet](../nuget_repository/index.md) | Y | Y | N | +| [PyPI](../pypi_repository/index.md) | Y | Y | N | +| [Generic packages](../generic_packages/index.md) | Y | N | N | +| [Terraform](../terraform_module_registry/index.md) | N | Y | N | +| [Composer](../composer_repository/index.md) | Y | Y | N | +| [Conan](../conan_repository/index.md) | Y | N | Y | +| [Helm](../helm_repository/index.md) | Y | N | N | +| [Debian](../debian_repository/index.md) | Y | N | N | +| [Go](../go_proxy/index.md) | Y | N | Y | +| [Ruby gems](../rubygems_registry/index.md) | Y | N | N | ## Forwarding requests **(PREMIUM)** Requests for packages not found in your GitLab project are forwarded to the public registry. For example, Maven Central, npmjs, or PyPI. -| Package type | Supports request forwarding | -|-----------------------------------------------------|-----------------------------| -| [Maven](../maven_repository/index.md) | [Yes (disabled by default)](../../admin_area/settings/continuous_integration.md#maven-forwarding) | -| [npm](../npm_registry/index.md) | [Yes](../../admin_area/settings/continuous_integration.md#npm-forwarding) | -| [NuGet](../nuget_repository/index.md) | N | -| [PyPI](../pypi_repository/index.md) | [Yes](../../admin_area/settings/continuous_integration.md#pypi-forwarding) | -| [Generic packages](../generic_packages/index.md) | N | -| [Terraform](../terraform_module_registry/index.md) | N | -| [Composer](../composer_repository/index.md) | N | -| [Conan](../conan_repository/index.md) | N | -| [Helm](../helm_repository/index.md) | N | -| [Debian](../debian_repository/index.md) | N | -| [Go](../go_proxy/index.md) | N | -| [Ruby gems](../rubygems_registry/index.md) | N | +| Package type | Supports request forwarding | +|-------------------------------------------------------|-----------------------------| +| [Maven (with `mvn`)](../maven_repository/index.md) | [Yes (disabled by default)](../../admin_area/settings/continuous_integration.md#maven-forwarding) | +| [Maven (with `gradle`)](../maven_repository/index.md) | [Yes (disabled by default)](../../admin_area/settings/continuous_integration.md#maven-forwarding) | +| [Maven (with `sbt`)](../maven_repository/index.md) | [Yes (disabled by default)](../../admin_area/settings/continuous_integration.md#maven-forwarding) | +| [npm](../npm_registry/index.md) | [Yes](../../admin_area/settings/continuous_integration.md#npm-forwarding) | +| [NuGet](../nuget_repository/index.md) | N | +| [PyPI](../pypi_repository/index.md) | [Yes](../../admin_area/settings/continuous_integration.md#pypi-forwarding) | +| [Generic packages](../generic_packages/index.md) | N | +| [Terraform](../terraform_module_registry/index.md) | N | +| [Composer](../composer_repository/index.md) | N | +| [Conan](../conan_repository/index.md) | N | +| [Helm](../helm_repository/index.md) | N | +| [Debian](../debian_repository/index.md) | N | +| [Go](../go_proxy/index.md) | N | +| [Ruby gems](../rubygems_registry/index.md) | N | ### Deleting packages @@ -87,20 +93,22 @@ To reduce the associated security risks, before deleting a package you can: By default, the GitLab package registry either allows or prevents duplicates based on the default of that specific package manager format. -| Package type | Duplicates allowed? | -|-----------------------------------------------------|---------------------| -| [Maven](../maven_repository/index.md) | Y (configurable) | -| [npm](../npm_registry/index.md) | N | -| [NuGet](../nuget_repository/index.md) | Y | -| [PyPI](../pypi_repository/index.md) | N | -| [Generic packages](../generic_packages/index.md) | Y (configurable) | -| [Terraform](../terraform_module_registry/index.md) | N | -| [Composer](../composer_repository/index.md) | N | -| [Conan](../conan_repository/index.md) | N | -| [Helm](../helm_repository/index.md) | Y | -| [Debian](../debian_repository/index.md) | Y | -| [Go](../go_proxy/index.md) | N | -| [Ruby gems](../rubygems_registry/index.md) | Y | +| Package type | Duplicates allowed? | +|-------------------------------------------------------|---------------------| +| [Maven (with `mvn`)](../maven_repository/index.md) | Y (configurable) | +| [Maven (with `gradle`)](../maven_repository/index.md) | Y (configurable) | +| [Maven (with `sbt`)](../maven_repository/index.md) | Y (configurable) | +| [npm](../npm_registry/index.md) | N | +| [NuGet](../nuget_repository/index.md) | Y | +| [PyPI](../pypi_repository/index.md) | N | +| [Generic packages](../generic_packages/index.md) | Y (configurable) | +| [Terraform](../terraform_module_registry/index.md) | N | +| [Composer](../composer_repository/index.md) | N | +| [Conan](../conan_repository/index.md) | N | +| [Helm](../helm_repository/index.md) | Y | +| [Debian](../debian_repository/index.md) | Y | +| [Go](../go_proxy/index.md) | N | +| [Ruby gems](../rubygems_registry/index.md) | Y | ## Authentication tokens **(FREE)** @@ -108,39 +116,45 @@ GitLab tokens are used to authenticate with the GitLab Package Registry. The following tokens are supported: -| Package type | Supported tokens | -|-----------------------------------------------------|------------------------------------------------------------------------| -| [Maven](../maven_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | -| [npm](../npm_registry/index.md) | Personal access, job tokens, deploy (project or group), project access | -| [NuGet](../nuget_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | -| [PyPI](../pypi_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | -| [Generic packages](../generic_packages/index.md) | Personal access, job tokens, deploy (project or group), project access | -| [Terraform](../terraform_module_registry/index.md) | Personal access, job tokens, deploy (project or group), project access | -| [Composer](../composer_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | -| [Conan](../conan_repository/index.md) | Personal access, job tokens, project access | -| [Helm](../helm_repository/index.md) | Personal access, job tokens, deploy (project or group) | -| [Debian](../debian_repository/index.md) | Personal access, job tokens, deploy (project or group) | -| [Go](../go_proxy/index.md) | Personal access, job tokens, project access | -| [Ruby gems](../rubygems_registry/index.md) | Personal access, job tokens, deploy (project or group) | +| Package type | Supported tokens | +|-------------------------------------------------------|------------------------------------------------------------------------| +| [Maven (with `mvn`)](../maven_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Maven (with `gradle`)](../maven_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Maven (with `sbt`)](../maven_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [npm](../npm_registry/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [NuGet](../nuget_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [PyPI](../pypi_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Generic packages](../generic_packages/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Terraform](../terraform_module_registry/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Composer](../composer_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Conan](../conan_repository/index.md) | Personal access, job tokens, project access | +| [Helm](../helm_repository/index.md) | Personal access, job tokens, deploy (project or group) | +| [Debian](../debian_repository/index.md) | Personal access, job tokens, deploy (project or group) | +| [Go](../go_proxy/index.md) | Personal access, job tokens, project access | +| [Ruby gems](../rubygems_registry/index.md) | Personal access, job tokens, deploy (project or group) | ## Authentication protocols **(FREE)** The following authentication protocols are supported: -| Package type | Supported auth protocols | -|-----------------------------------------------------|--------------------------| -| [Maven](../maven_repository/index.md) | Headers | -| [npm](../npm_registry/index.md) | OAuth | -| [NuGet](../nuget_repository/index.md) | Basic auth | -| [PyPI](../pypi_repository/index.md) | Basic auth | -| [Generic packages](../generic_packages/index.md) | Basic auth | -| [Terraform](../terraform_module_registry/index.md) | Token | -| [Composer](../composer_repository/index.md) | OAuth | -| [Conan](../conan_repository/index.md) | OAuth, Basic auth | -| [Helm](../helm_repository/index.md) | Basic auth | -| [Debian](../debian_repository/index.md) | Basic auth | -| [Go](../go_proxy/index.md) | Basic auth | -| [Ruby gems](../rubygems_registry/index.md) | Token | +| Package type | Supported auth protocols | +|-------------------------------------------------------|-------------------------------------------------------------| +| [Maven (with `mvn`)](../maven_repository/index.md) | Headers, Basic auth ([pulling](#pulling-packages) only) (1) | +| [Maven (with `gradle`)](../maven_repository/index.md) | Headers, Basic auth ([pulling](#pulling-packages) only) (1) | +| [Maven (with `sbt`)](../maven_repository/index.md) | Basic auth (1) | +| [npm](../npm_registry/index.md) | OAuth | +| [NuGet](../nuget_repository/index.md) | Basic auth | +| [PyPI](../pypi_repository/index.md) | Basic auth | +| [Generic packages](../generic_packages/index.md) | Basic auth | +| [Terraform](../terraform_module_registry/index.md) | Token | +| [Composer](../composer_repository/index.md) | OAuth | +| [Conan](../conan_repository/index.md) | OAuth, Basic auth | +| [Helm](../helm_repository/index.md) | Basic auth | +| [Debian](../debian_repository/index.md) | Basic auth | +| [Go](../go_proxy/index.md) | Basic auth | +| [Ruby gems](../rubygems_registry/index.md) | Token | + +1. Basic authentication for Maven packages [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212854) in GitLab 16.0. ## Supported hash types **(FREE)** @@ -148,16 +162,18 @@ Hash values are used to ensure you are using the correct package. You can view t The Package Registry supports the following hash types: -| Package type | Supported hashes | -|--------------------------------------------------|----------------------------------| -| [Maven](../maven_repository/index.md) | MD5, SHA1 | -| [npm](../npm_registry/index.md) | SHA1 | -| [NuGet](../nuget_repository/index.md) | not applicable | -| [PyPI](../pypi_repository/index.md) | MD5, SHA256 | -| [Generic packages](../generic_packages/index.md) | SHA256 | -| [Composer](../composer_repository/index.md) | not applicable | -| [Conan](../conan_repository/index.md) | MD5, SHA1 | -| [Helm](../helm_repository/index.md) | not applicable | -| [Debian](../debian_repository/index.md) | MD5, SHA1, SHA256 | -| [Go](../go_proxy/index.md) | MD5, SHA1, SHA256 | -| [Ruby gems](../rubygems_registry/index.md) | MD5, SHA1, SHA256 (gemspec only) | +| Package type | Supported hashes | +|-------------------------------------------------------|----------------------------------| +| [Maven (with `mvn`)](../maven_repository/index.md) | MD5, SHA1 | +| [Maven (with `gradle`)](../maven_repository/index.md) | MD5, SHA1 | +| [Maven (with `sbt`)](../maven_repository/index.md) | MD5, SHA1 | +| [npm](../npm_registry/index.md) | SHA1 | +| [NuGet](../nuget_repository/index.md) | not applicable | +| [PyPI](../pypi_repository/index.md) | MD5, SHA256 | +| [Generic packages](../generic_packages/index.md) | SHA256 | +| [Composer](../composer_repository/index.md) | not applicable | +| [Conan](../conan_repository/index.md) | MD5, SHA1 | +| [Helm](../helm_repository/index.md) | not applicable | +| [Debian](../debian_repository/index.md) | MD5, SHA1, SHA256 | +| [Go](../go_proxy/index.md) | MD5, SHA1, SHA256 | +| [Ruby gems](../rubygems_registry/index.md) | MD5, SHA1, SHA256 (gemspec only) | diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index a26f027f329..8827e1e27c5 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -24,19 +24,28 @@ If you set up a device, also set up a TOTP so you can still access your account When 2FA is enabled, you can't use your password to authenticate with Git over HTTPS or the [GitLab API](../../../api/rest/index.md). You can use a [personal access token](../personal_access_tokens.md) instead. -## Git Credential Manager +## OAuth credential helpers -For Git over HTTPS, [Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) (GCM) offers an alternative to personal access tokens. By default, GCM -authenticates using OAuth, opening GitLab in your web browser. The first time you authenticate, GitLab asks you to authorize the app. If you remain signed in to GitLab, subsequent -authentication requires no interaction. +The following Git credential helpers authenticate to GitLab using OAuth. This is compatible with two-factor authentication. The first time you authenticate, the helper opens the web browser and GitLab asks you to authorize the app. Subsequent authentication requires no interaction. -So you don't need to reauthenticate on every push, GCM supports caching as well as a variety of platform-specific credential stores that persist between sessions. This feature is useful whether you use personal access tokens or OAuth. +### Git Credential Manager -GCM supports GitLab.com out the box. To use with self-managed GitLab, see [GitLab support](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/gitlab.md) -documentation. +[Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) (GCM) authenticates by default using OAuth. GCM supports GitLab.com without any manual configuration. To use GCM with self-managed GitLab, see [GitLab support](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/gitlab.md). + +So you do not need to re-authenticate on every push, GCM supports caching as well as a variety of platform-specific credential stores that persist between sessions. This feature is useful whether you use personal access tokens or OAuth. + +Git for Windows includes Git Credential Manager. Git Credential Manager is developed primarily by GitHub, Inc. It is an open-source project and is supported by the community. +### git-credential-oauth + +[git-credential-oauth](https://github.com/hickford/git-credential-oauth) supports GitLab.com and several popular public hosts without any manual configuration needed. To use with self-managed GitLab, see the [git-credential-oauth custom hosts documentation](https://github.com/hickford/git-credential-oauth#custom-hosts). + +Many Linux distributions include git-credential-oauth as a package. + +git-credential-oauth is an open-source project supported by the community. + ## Enable two-factor authentication > - Account email confirmation requirement [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35102) in GitLab 14.3. [Deployed behind the `ensure_verified_primary_email_for_2fa` flag](../../../administration/feature_flags.md), enabled by default. @@ -485,23 +494,25 @@ access token instead of a password. This error occurs in the following scenarios: - You have 2FA enabled and have attempted to authenticate with a username and - password. For 2FA-enabled users, a [personal access token](../personal_access_tokens.md) (PAT) - must be used instead of a password. To authenticate: - - Git requests over HTTP(S), a PAT with `read_repository` or `write_repository` scope is required. - - [GitLab Container Registry](../../packages/container_registry/authenticate_with_container_registry.md) requests, a PAT - with `read_registry` or `write_registry` scope is required. - - [Dependency Proxy](../../packages/dependency_proxy/index.md#authenticate-with-the-dependency-proxy) requests, a PAT with - `read_registry` and `write_registry` scopes is required. + password. - You do not have 2FA enabled and have sent an incorrect username or password with your request. - You do not have 2FA enabled but an administrator has enabled the [enforce 2FA for all users](../../../security/two_factor_authentication.md#enforce-2fa-for-all-users) setting. - You do not have 2FA enabled, but an administrator has disabled the [password authentication enabled for Git over HTTP(S)](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled) - setting. You can authenticate Git requests: - - Over HTTP(S) using a [personal access token](../personal_access_tokens.md). - - In your browser using [Git Credential Manager](#git-credential-manager). - - If you have configured LDAP, over HTTP(S) using an [LDAP password](../../../administration/auth/ldap/index.md). + setting. + +Instead you can authenticate: + +- Using a [personal access token](../personal_access_tokens.md) (PAT): + - For Git requests over HTTP(S), a PAT with `read_repository` or `write_repository` scope is required. + - For [GitLab Container Registry](../../packages/container_registry/authenticate_with_container_registry.md) requests, a PAT + with `read_registry` or `write_registry` scope is required. + - For [Dependency Proxy](../../packages/dependency_proxy/index.md#authenticate-with-the-dependency-proxy) requests, a PAT with + `read_registry` and `write_registry` scopes is required. +- If you have configured LDAP, using an [LDAP password](../../../administration/auth/ldap/index.md) +- Using an [OAuth credential helper](#oauth-credential-helpers). ### Error: "invalid pin code" diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 68c9a5a4356..0d886519766 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -249,5 +249,4 @@ Running the following commands changes data directly. This could be damaging if ## Alternatives to personal access tokens -For Git over HTTPS, an alternative to personal access tokens is [Git Credential Manager](account/two_factor_authentication.md#git-credential-manager), -which securely authenticates using OAuth. +For Git over HTTPS, an alternative to personal access tokens is to use an [OAuth credential helper](account/two_factor_authentication.md#oauth-credential-helpers). |