diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-20 16:18:24 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-20 16:18:24 +0300 |
commit | 0653e08efd039a5905f3fa4f6e9cef9f5d2f799c (patch) | |
tree | 4dcc884cf6d81db44adae4aa99f8ec1233a41f55 /doc/topics | |
parent | 744144d28e3e7fddc117924fef88de5d9674fe4c (diff) |
Add latest changes from gitlab-org/gitlab@14-3-stable-eev14.3.0-rc42
Diffstat (limited to 'doc/topics')
30 files changed, 240 insertions, 107 deletions
diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 83c9e180c1c..25e6e590f77 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -11,7 +11,7 @@ This page gathers all the resources for the topic **Authentication** within GitL ## GitLab users - [SSH](../../ssh/index.md) -- [Two-Factor Authentication (2FA)](../../user/profile/account/two_factor_authentication.md#two-factor-authentication) +- [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:** - [Support for Universal 2nd Factor Authentication - YubiKeys](https://about.gitlab.com/blog/2016/06/22/gitlab-adds-support-for-u2f/) @@ -23,7 +23,7 @@ This page gathers all the resources for the topic **Authentication** within GitL ## GitLab administrators - [LDAP](../../administration/auth/ldap/index.md) -- [Enforce Two-factor Authentication (2FA)](../../security/two_factor_authentication.md#enforce-two-factor-authentication-2fa) +- [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md) - **Articles:** - [Feature Highlight: LDAP Integration](https://about.gitlab.com/blog/2014/07/10/feature-highlight-ldap-sync/) - [Debugging LDAP](https://about.gitlab.com/handbook/support/workflows/debugging_ldap.html) @@ -43,7 +43,7 @@ This page gathers all the resources for the topic **Authentication** within GitL - [Personal access tokens](../../api/index.md#personalproject-access-tokens) - [Project access tokens](../../api/index.md#personalproject-access-tokens) - [Impersonation tokens](../../api/index.md#impersonation-tokens) -- [GitLab as an OAuth2 provider](../../api/oauth2.md#gitlab-as-an-oauth2-provider) +- [GitLab as an OAuth2 provider](../../api/oauth2.md#gitlab-as-an-oauth-20-provider) ## Third-party resources diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 72f688a0ed5..f8b63f5b41a 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -373,6 +373,8 @@ applications. |-----------------------------------------|------------------------------------| | `ADDITIONAL_HOSTS` | Fully qualified domain names specified as a comma-separated list that are added to the Ingress hosts. | | `<ENVIRONMENT>_ADDITIONAL_HOSTS` | For a specific environment, the fully qualified domain names specified as a comma-separated list that are added to the Ingress hosts. This takes precedence over `ADDITIONAL_HOSTS`. | +| `AUTO_BUILD_IMAGE_VERSION` | Customize the image version used for the `build` job. See [list of versions](https://gitlab.com/gitlab-org/cluster-integration/auto-build-image/-/releases). | +| `AUTO_DEPLOY_IMAGE_VERSION` | Customize the image version used for Kubernetes deployment jobs. See [list of versions](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/releases). | | `AUTO_DEVOPS_ATOMIC_RELEASE` | As of GitLab 13.0, Auto DevOps uses [`--atomic`](https://v2.helm.sh/docs/helm/#options-43) for Helm deployments by default. Set this variable to `false` to disable the use of `--atomic` | | `AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED` | Set to `false` to use Herokuish instead of Cloud Native Buildpacks with Auto Build. [More details](stages.md#auto-build-using-cloud-native-buildpacks). | | `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER` | The builder used when building with Cloud Native Buildpacks. The default builder is `heroku/buildpacks:18`. [More details](stages.md#auto-build-using-cloud-native-buildpacks). | @@ -390,6 +392,7 @@ applications. | `CANARY_ENABLED` | From GitLab 11.0, used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments). | | `CANARY_PRODUCTION_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md) in the production environment. Takes precedence over `CANARY_REPLICAS`. Defaults to 1. | | `CANARY_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md). Defaults to 1. | +| `DAST_AUTO_DEPLOY_IMAGE_VERSION` | Customize the image version used for DAST deployments on the default branch. Should usually be the same as `AUTO_DEPLOY_IMAGE_VERSION`. See [list of versions](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/releases). | | `DOCKERFILE_PATH` | From GitLab 13.2, allows overriding the [default Dockerfile path for the build stage](#custom-dockerfile) | | `HELM_RELEASE_NAME` | From GitLab 12.1, allows the `helm` release name to be overridden. Can be used to assign unique release names when deploying multiple projects to a single namespace. | | `HELM_UPGRADE_VALUES_FILE` | From GitLab 12.6, allows the `helm upgrade` values file to be overridden. Defaults to `.gitlab/auto-deploy-values.yaml`. | @@ -461,7 +464,7 @@ The following table lists variables used to disable jobs. | `license_scanning` | `LICENSE_MANAGEMENT_DISABLED` | [From GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | If the variable is present, the job isn't created. | | `load_performance` | `LOAD_PERFORMANCE_DISABLED` | From GitLab 13.2 | If the variable is present, the job isn't created. | | `nodejs-scan-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `performance` | `PERFORMANCE_DISABLED` | GitLab 11.0 to GitLab 13.12 | Browser performance. If the variable is present, the job isn't created. Replaced by `browser_peformance`. | +| `performance` | `PERFORMANCE_DISABLED` | GitLab 11.0 to GitLab 13.12 | Browser performance. If the variable is present, the job isn't created. Replaced by `browser_performance`. | | `browser_performance` | `BROWSER_PERFORMANCE_DISABLED` | From GitLab 14.0 | Browser performance. If the variable is present, the job isn't created. Replaces `performance`. | | `phpcs-security-audit-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | | `pmd-apex-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | @@ -491,9 +494,9 @@ these prefixed variables available to the deployed application as environment va To configure your application variables: -1. Go to your project's **Settings > CI/CD**, then expand the - **Variables** section. - +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Variables**. 1. Create a CI/CD variable, ensuring the key is prefixed with `K8S_SECRET_`. For example, you can create a variable with key `K8S_SECRET_RAILS_MASTER_KEY`. diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index f4936e9162d..e232af05d50 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -105,7 +105,7 @@ test your application. If you want to build, test, and deploy your app: -1. See the [requirements for deployment](requirements.md). +1. View the [requirements for deployment](requirements.md). 1. [Enable Auto DevOps](#enable-or-disable-auto-devops). 1. Follow the [quick start guide](#quick-start). @@ -153,16 +153,18 @@ precedence over the Auto DevOps pipeline. To enable Auto DevOps for a project: -1. Go to your project's **Settings > CI/CD > Auto DevOps**. -1. Select the **Default to Auto DevOps pipeline**. -1. (Recommended) Add the [base domain](requirements.md#auto-devops-base-domain). -1. (Recommended) Choose the [deployment strategy](requirements.md#auto-devops-deployment-strategy). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Auto DevOps**. +1. Select the **Default to Auto DevOps pipeline** checkbox. +1. Optional but recommended. Add the [base domain](requirements.md#auto-devops-base-domain). +1. Optional but recommended. Choose the [deployment strategy](requirements.md#auto-devops-deployment-strategy). 1. Select **Save changes**. GitLab triggers the Auto DevOps pipeline on the default branch. -To disable it, follow the same process and deselect **Default to Auto -DevOps pipeline**. +To disable it, follow the same process and clear the +**Default to Auto DevOps pipeline** checkbox. #### At the group level @@ -180,20 +182,22 @@ at the group level. To enable Auto DevOps for a group: -1. Go to your group's **Settings > CI/CD > Auto DevOps**. -1. Select **Default to Auto DevOps pipeline**. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Auto DevOps**. +1. Select the **Default to Auto DevOps pipeline** checkbox. 1. Select **Save changes**. +To disable Auto DevOps on the group level, follow the same process and +clear the **Default to Auto DevOps pipeline** checkbox. + After enabling Auto DevOps at the group level, you can trigger the Auto DevOps pipeline for any project that belongs to that group. To do so: -1. Go to the project's homepage. +1. On the top bar, select **Menu > Projects** and find your project. 1. Make sure the project doesn't contain a `.gitlab-ci.yml` file. -1. From the project's sidebar, go to **CI/CD > Pipelines**. -1. Select **Run pipeline** to trigger the Auto DevOps pipeline. - -To disable Auto DevOps on the group level, follow the same process and -deselect **Default to Auto DevOps pipeline**. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. To trigger the Auto DevOps pipeline, select **Run pipeline**. #### At the instance level **(FREE SELF)** @@ -210,10 +214,11 @@ can still enable Auto DevOps at the group and project levels. To enable Auto DevOps for your instance: -1. From the top bar, select **Menu >** **{admin}** **Admin**. -1. Go to **Settings > CI/CD > Continuous Integration and Deployment**. -1. Select **Default to Auto DevOps pipeline**. -1. (Optional) Add the Auto DevOps [base domain](requirements.md#auto-devops-base-domain). +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Auto DevOps**. +1. Select the **Default to Auto DevOps pipeline** checkbox. +1. Optional. Add the Auto DevOps [base domain](requirements.md#auto-devops-base-domain). 1. Select **Save changes**. When enabled, it attempts to run Auto DevOps pipelines in every project. If the @@ -224,7 +229,7 @@ If a [CI/CD configuration file](../../ci/yaml/index.md) is present, it remains unchanged and Auto DevOps doesn't affect it. To disable Auto DevOps in the instance level, follow the same process -and deselect the **Default to Auto DevOps pipeline** checkbox. +and clear the **Default to Auto DevOps pipeline** checkbox. ### Quick start diff --git a/doc/topics/autodevops/prepare_deployment.md b/doc/topics/autodevops/prepare_deployment.md index 830aff11824..c23774b1ffd 100644 --- a/doc/topics/autodevops/prepare_deployment.md +++ b/doc/topics/autodevops/prepare_deployment.md @@ -12,7 +12,7 @@ recommend that you prepare them before enabling Auto DevOps. ## Deployment strategy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0. When using Auto DevOps to deploy your applications, choose the [continuous deployment strategy](../../ci/introduction/index.md) @@ -44,7 +44,7 @@ To define the base domain, either: - In the project, group, or instance level: go to your cluster settings and add it there. - In the project or group level: add it as an environment variable: `KUBE_INGRESS_BASE_DOMAIN`. -- In the instance level: go to **Menu >** **{admin}** **Admin > Settings > CI/CD> Continuous Integration and Delivery** and add it there. +- In the instance level: go to **Menu > Admin > Settings > CI/CD > Continuous Integration and Delivery** and add it there. The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence as other environment [variables](../../ci/variables/index.md#cicd-variable-precedence). diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 2cf5a5befd7..59c61da0c45 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -6,7 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Tutorial: Use Auto DevOps to deploy an application to Google Kubernetes Engine **(FREE)** -This step-by-step guide helps you use [Auto DevOps](index.md) to In this tutorial, we'll help you to get started with [Auto DevOps](index.md) through an example of how to deploy an application to Google Kubernetes Engine (GKE). @@ -244,7 +243,7 @@ you to common environment tasks: - **Stop environment** (**{stop}**) - For more information, see [Stopping an environment](../../ci/environments/index.md#stop-an-environment) -GitLab displays the [Deploy Board](../../user/project/deploy_boards.md) below the +GitLab displays the [deploy board](../../user/project/deploy_boards.md) below the environment's information, with squares representing pods in your Kubernetes cluster, color-coded to show their status. Hovering over a square on the deploy board displays the state of the deployment, and selecting the square diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index 535ec18e5b6..8dd7c0317d9 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -42,7 +42,9 @@ that works best for your needs: You can choose the deployment method when enabling Auto DevOps or later: -1. In GitLab, go to your project's **Settings > CI/CD > Auto DevOps**. +1. In GitLab, on the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Auto DevOps**. 1. Choose the deployment strategy. 1. Select **Save changes**. @@ -60,7 +62,7 @@ To define the base domain, either: - In the project, group, or instance level: go to your cluster settings and add it there. - In the project or group level: add it as an environment variable: `KUBE_INGRESS_BASE_DOMAIN`. -- In the instance level: go to **Menu >** **{admin}** **Admin > Settings > CI/CD> Continuous Integration and Delivery** and add it there. +- In the instance level: go to **Menu > Admin > Settings > CI/CD > Continuous Integration and Delivery** and add it there. The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence as other environment [variables](../../ci/variables/index.md#cicd-variable-precedence). @@ -181,9 +183,9 @@ You can choose to target [AWS ECS](../../ci/cloud_deployment/index.md) as a depl To get started on Auto DevOps to AWS ECS, you must add a specific CI/CD variable. To do so, follow these steps: -1. In your project, go to **Settings > CI/CD** and expand the **Variables** - section. - +1. In GitLab, on the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Auto DevOps**. 1. Specify which AWS platform to target during the Auto DevOps deployment by adding the `AUTO_DEVOPS_PLATFORM_TARGET` variable with one of the following values: - `FARGATE` if the service you're targeting must be of launch type FARGATE. diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index 3b595cc7ea8..9e6f3103664 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -425,9 +425,9 @@ including support for `Deployment` in the `extensions/v1beta1` version. To use Auto Deploy on a Kubernetes 1.16+ cluster: 1. If you are deploying your application for the first time in GitLab 13.0 or - newer, no configuration should be required. + later, no configuration should be required. -1. In GitLab 12.10 or older, set the following in the [`.gitlab/auto-deploy-values.yaml` file](customize.md#customize-values-for-helm-chart): +1. In GitLab 12.10 and earlier, set the following in the [`.gitlab/auto-deploy-values.yaml` file](customize.md#customize-values-for-helm-chart): ```yaml deploymentApiVersion: apps/v1 @@ -696,11 +696,12 @@ To use Auto Monitoring: 1. [Install and configure the Auto DevOps requirements](requirements.md). 1. [Enable Auto DevOps](index.md#enable-or-disable-auto-devops), if you haven't done already. -1. Navigate to your project's **{rocket}** **CI/CD > Pipelines** and click **Run pipeline**. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. Select **Run pipeline**. 1. After the pipeline finishes successfully, open the [monitoring dashboard for a deployed environment](../../ci/environments/index.md#monitor-environments) to view the metrics of your deployed application. To view the metrics of the - whole Kubernetes cluster, navigate to **Operations > Metrics**. + whole Kubernetes cluster, on the left sidebar, select **Monitor > Metrics**. ![Auto Metrics](img/auto_monitoring.png) diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index e4378ce2d78..7ddcdcbacb5 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -159,7 +159,7 @@ steps to upgrade to v2: To use a specific version of Auto Deploy dependencies, specify the previous Auto Deploy stable template that contains the [desired version of `auto-deploy-image` and `auto-deploy-app`](#verify-dependency-versions). -For example, if the template is bundled in GitLab v13.3, change your `.gitlab-ci.yml` to: +For example, if the template is bundled in GitLab 13.3, change your `.gitlab-ci.yml` to: ```yaml include: @@ -258,7 +258,7 @@ change. If that happens, the deployment job fails with a message similar to: ```plaintext ************************************************************************************* [WARNING] -Detected a major version difference between the the chart that is currently deploying (auto-deploy-app-v0.7.0), and the previously deployed chart (auto-deploy-app-v1.0.0). +Detected a major version difference between the chart that is currently deploying (auto-deploy-app-v0.7.0), and the previously deployed chart (auto-deploy-app-v1.0.0). A new major version might not be backward compatible with the current release (production). The deployment could fail or be stuck in an unrecoverable status. ... ``` diff --git a/doc/topics/git/cherry_picking.md b/doc/topics/git/cherry_picking.md index 4a875e25e1b..64d1914019d 100644 --- a/doc/topics/git/cherry_picking.md +++ b/doc/topics/git/cherry_picking.md @@ -5,49 +5,76 @@ info: To determine the technical writer assigned to the Stage/Group associated w comments: false --- -# Cherry pick **(FREE)** +# Cherry-pick a Git commit **(FREE)** -Given an existing commit on one branch, apply the change to another branch. +In Git, you can *cherry-pick* a commit (a set of changes) from an existing branch, +and apply those changes to another branch. Cherry-picks can help you: -This can be useful for backporting bug fixes to previous release branches. Make -the commit on the default branch, and then cherry pick it into the release branch. +- Backport bug fixes from the default branch to previous release branches. +- Copy changes from a fork + [to the upstream repository](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-into-a-project). -## Sample workflow +You can cherry-pick commits from the command line. In the GitLab user interface, +you can also: -1. Check out a new `stable` branch from the default branch: +- Cherry-pick [all changes from a merge request](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-a-merge-request). +- Cherry-pick [a single commit](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-a-commit). +- Cherry-pick [from a fork to the upstream repository](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-into-a-project). + +## Cherry-pick from the command line + +These instructions explain how to cherry-pick a commit from the default branch (`main`) +into a different branch (`stable`): + +1. Check out the default branch, then check out a new `stable` branch based on it: ```shell - git checkout master + git checkout main git checkout -b stable ``` 1. Change back to the default branch: ```shell - git checkout master + git checkout main ``` -1. Make any required changes, then commit the changes: +1. Make your changes, then commit them: ```shell git add changed_file.rb git commit -m 'Fix bugs in changed_file.rb' ``` -1. Review the commit log and copy the SHA of the latest commit: +1. Display the commit log: ```shell - git log + $ git log + + commit 0000011111222223333344444555556666677777 + Merge: 88888999999 aaaaabbbbbb + Author: user@example.com + Date: Tue Aug 31 21:19:41 2021 +0000 ``` -1. Check out the `stable` branch: +1. Identify the `commit` line, and copy the string of letters and numbers on that line. + This information is the SHA (Secure Hash Algorithm) of the commit. The SHA is + a unique identifier for this commit, and you need it in a future step. + +1. Now that you know the SHA, check out the `stable` branch again: ```shell git checkout stable ``` -1. Cherry pick the commit by using the SHA copied previously: +1. Cherry-pick the commit into the `stable` branch, and change `SHA` to your commit + SHA: ```shell - git cherry-pick <commit SHA> + git cherry-pick <SHA> ``` + +## Related links + +- Cherry-pick commits with [the Commits API](../../api/commits.md#cherry-pick-a-commit) +- Git documentation [for cherry-picks](https://git-scm.com/docs/git-cherry-pick) diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index 0e288f1445e..b09f9fa0f6c 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.md @@ -228,8 +228,13 @@ git push --force-with-lease origin my-feature-branch ``` If the branch you want to force-push is [protected](../../user/project/protected_branches.md), -you can't force-push to it unless you unprotect it first. Then you can -force-push and re-protect it. +you can't force push to it unless you either: + +- Unprotect it. +- [Allow force push](../../user/project/protected_branches.md#allow-force-push-on-a-protected-branch) + to it. + +Then you can force push and protect it again. ## Merge conflicts diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md index c1e766a7c48..e95d8121b66 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/index.md @@ -34,8 +34,8 @@ The following resources can help you get started with Git: - [Edit files through the command line](../../gitlab-basics/command-line-commands.md) - [GitLab Git Cheat Sheet (download)](https://about.gitlab.com/images/press/git-cheat-sheet.pdf) - Commits: - - [Revert a commit](../../user/project/merge_requests/revert_changes.md#reverting-a-commit) - - [Cherry-picking a commit](../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) + - [Revert a commit](../../user/project/merge_requests/revert_changes.md#revert-a-commit) + - [Cherry-picking a commit](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-a-commit) - [Squashing commits](../gitlab_flow.md#squashing-commits-with-rebase) - [Squash-and-merge](../../user/project/merge_requests/squash_and_merge.md) - [Signing commits](../../user/project/repository/gpg_signed_commits/index.md) @@ -58,7 +58,7 @@ The following are resources on version control concepts: You can do many Git tasks from the command line: - [Bisect](bisect.md). -- [Cherry pick](cherry_picking.md). +- [Cherry-pick](cherry_picking.md). - [Feature branching](feature_branching.md). - [Getting started with Git](getting_started.md). - [Git add](git_add.md). diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md index d1231257f38..2786368a9d7 100644 --- a/doc/topics/git/lfs/migrate_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_to_git_lfs.md @@ -7,6 +7,11 @@ description: "How to migrate an existing Git repository to Git LFS with BFG." # Migrate a Git repository into Git LFS with BFG +WARNING: +The following documentation is deprecated. We recommend using +[`git lfs migrate`](https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-migrate.1.ronn) +instead of the method documented below. + Using Git LFS can help you to reduce the size of your Git repository and improve its performance. diff --git a/doc/topics/git/numerous_undo_possibilities_in_git/index.md b/doc/topics/git/numerous_undo_possibilities_in_git/index.md index 4d58c7ab455..9786d1399f7 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -209,7 +209,7 @@ To recover from multiple incorrect commits: The commits are now `A-B-C-D-E`. Alternatively, with GitLab, -you can [cherry-pick](../../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) +you can [cherry-pick](../../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-a-commit) that commit into a new merge request. NOTE: @@ -388,7 +388,6 @@ git filter-branch --tree-filter 'rm filename' HEAD The `git filter-branch` command might be slow on large repositories. Tools are available to execute Git commands more quickly. -An alternative is the open source community-maintained tool [BFG](https://rtyley.github.io/bfg-repo-cleaner/). These tools are faster because they do not provide the same feature set as `git filter-branch` does, but focus on specific use cases. diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index d9aff6c35e5..e831c35a8ea 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -7,8 +7,6 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/gitlab_flow.html' # Introduction to GitLab Flow **(FREE)** -![GitLab Flow](img/gitlab_flow.png) - Git allows a wide variety of branching strategies and workflows. Because of this, many organizations end up with workflows that are too complicated, not clearly defined, or not integrated with issue tracking systems. Therefore, we propose GitLab flow as a clearly defined set of best practices. @@ -16,9 +14,16 @@ It combines [feature-driven development](https://en.wikipedia.org/wiki/Feature-d Organizations coming to Git from other version control systems frequently find it hard to develop a productive workflow. This article describes GitLab flow, which integrates the Git workflow with an issue tracking system. -It offers a transparent and effective way to work with Git. - -![Four stages (working copy, index, local repository, remote repository) and three steps between them](img/gitlab_flow_four_stages.png) +It offers a transparent and effective way to work with Git: + +```mermaid +graph LR + subgraph Git workflow + A[Working copy] --> |git add| B[Index] + B --> |git commit| C[Local repository] + C --> |git push| D[Remote repository] + end +``` When converting to Git, you have to get used to the fact that it takes three steps to share a commit with colleagues. Most version control systems have only one step: committing from the working copy to a shared server. @@ -26,8 +31,6 @@ In Git, you add files from the working copy to the staging area. After that, you The third step is pushing to a shared remote repository. After getting used to these three steps, the next challenge is the branching model. -![Multiple long-running branches and merging in all directions](img/gitlab_flow_messy_flow.png) - Because many organizations new to Git have no conventions for how to work with it, their repositories can quickly become messy. The biggest problem is that many long-running branches emerge that all contain part of the changes. People have a hard time figuring out which branch has the latest code, or which branch to deploy to production. @@ -65,10 +68,20 @@ For example, many projects do releases but don't need to do hotfixes. ## GitHub flow as a simpler alternative -![Branch with feature branches merged in](img/gitlab_flow_github_flow.png) - In reaction to Git flow, GitHub created a simpler alternative. -[GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `main` branch. +[GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `main` branch: + +```mermaid +graph TD + subgraph Feature branches in GitHub Flow + A[main branch] ===>B[main branch] + D[nav branch] --> |add navigation| B + B ===> C[main branch] + E[feature-branch] --> |add feature| C + C ==> F[main branch] + end +``` + This flow is clean and straightforward, and many organizations have adopted it with great success. Atlassian recommends [a similar strategy](https://www.atlassian.com/blog/git/simple-git-workflow-is-simple), although they rebase feature branches. Merging everything into the `main` branch and frequently deploying means you minimize the amount of unreleased code. This approach is in line with lean and continuous delivery best practices. @@ -77,8 +90,6 @@ With GitLab flow, we offer additional guidance for these questions. ## Production branch with GitLab flow -![Branches with an arrow that indicates a deployment](img/gitlab_flow_production_branch.png) - GitHub flow assumes you can deploy to production every time you merge a feature branch. While this is possible in some cases, such as SaaS applications, there are some cases where this is not possible, such as: @@ -88,7 +99,22 @@ While this is possible in some cases, such as SaaS applications, there are some operations team is at full capacity - but you also merge code at other times. In these cases, you can make a production branch that reflects the deployed code. -You can deploy a new version by merging `main` into the production branch. +You can deploy a new version by merging `development` into the production branch: + +```mermaid +graph TD + subgraph Production branch in GitLab Flow + A[development] ==>B[development] + B ==> C[development] + C ==> D[development] + + E[production] ====> F[production] + C --> |deployment| F + D ==> G[development] + F ==> H[production] + end +``` + If you need to know what code is in production, you can check out the production branch to see. The approximate time of deployment is visible as the merge commit in the version control system. This time is pretty accurate if you automatically deploy your production branch. @@ -97,26 +123,66 @@ This flow prevents the overhead of releasing, tagging, and merging that happens ## Environment branches with GitLab flow -![Multiple branches with the code cascading from one to another](img/gitlab_flow_environment_branches.png) - -It might be a good idea to have an environment that is automatically updated to the `main` branch. +It might be a good idea to have an environment that is automatically updated to the `staging` branch. Only, in this case, the name of this environment might differ from the branch name. -Suppose you have a staging environment, a pre-production environment, and a production environment. -In this case, deploy the `main` branch to staging. -To deploy to pre-production, create a merge request from the `main` branch to the pre-production branch. -Go live by merging the pre-production branch into the production branch. +Suppose you have a staging environment, a pre-production environment, and a production environment: + +```mermaid +graph LR + subgraph Environment branches in GitLab Flow + + A[staging] ==> B[staging] + B ==> C[staging] + C ==> D[staging] + + A --> |deploy to<br>pre-prod| G + + F[pre-prod] ==> G[pre-prod] + G ==> H[pre-prod] + H ==> I[pre-prod] + + C --> |deploy to<br>pre-prod| I + + J[production] ==> K[production] + K ==> L[production] + + G --> |production <br>deployment| K + + end +``` + +In this case, deploy the `staging` branch to your staging environment. +To deploy to pre-production, create a merge request from the `staging` branch to the `pre-prod` branch. +Go live by merging the `pre-prod` branch into the `production` branch. This workflow, where commits only flow downstream, ensures that everything is tested in all environments. -If you need to cherry-pick a commit with a hotfix, it is common to develop it on a feature branch and merge it into `main` with a merge request. +If you need to cherry-pick a commit with a hotfix, it is common to develop it on a feature branch and merge it into `production` with a merge request. In this case, do not delete the feature branch yet. -If `main` passes automatic testing, you then merge the feature branch into the other branches. +If `production` passes automatic testing, you then merge the feature branch into the other branches. If this is not possible because more manual testing is required, you can send merge requests from the feature branch to the downstream branches. ## Release branches with GitLab flow -![Multiple release branches that vary in length with cherry-picks](img/gitlab_flow_release_branches.png) +You should work with release branches only if you need to release software to +the outside world. In this case, each branch contains a minor version, such as +`2.3-stable` or `2.4-stable`: + +```mermaid +graph LR + A:::main ===> B((main)) + B:::main ==> C((main)) + C:::main ==> D((main)) + D:::main ==> E((main)) + + A((main)) ----> F((2.3-stable)):::first + F --> G((2.3-stable)):::first + C -.-> |cherry-pick| G + D --> H((2.4-stable)):::second + + classDef main fill:#f4f0ff,stroke:#7b58cf + classDef first fill:#e9f3fc,stroke:#1f75cb + classDef second fill:#ecf4ee,stroke:#108548 +``` -You only need to work with release branches if you need to release software to the outside world. -In this case, each branch contains a minor version, such as `2-3-stable` or `2-4-stable`. Create stable branches using `main` as a starting point, and branch as late as possible. By doing this, you minimize the length of time during which you have to apply bug fixes to multiple branches. After announcing a release branch, only add serious bug fixes to the branch. @@ -167,8 +233,6 @@ When you reopen an issue you need to create a new merge request. ## Issue tracking with GitLab flow -![Merge request with the branch name "15-require-a-password-to-change-it" and assignee field shown](img/gitlab_flow_merge_request.png) - GitLab flow is a way to make the relation between the code and the issue tracker more transparent. Any significant change to the code should start with an issue that describes the goal. @@ -207,8 +271,6 @@ It is possible that one feature branch solves more than one issue. ## Linking and closing issues from merge requests -![Merge request showing the linked issues to close](img/gitlab_flow_close_issue_mr.png) - Link to issues by mentioning them in commit messages or the description of a merge request, for example, "Fixes #16" or "Duck typing is preferred. See #12." GitLab then creates links to the mentioned issues and creates comments in the issues linking back to the merge request. @@ -218,10 +280,35 @@ If you have an issue that spans across multiple repositories, create an issue fo ## Squashing commits with rebase -![Vim screen showing the rebase view](img/gitlab_flow_rebase.png) - With Git, you can use an interactive rebase (`rebase -i`) to squash multiple commits into one or reorder them. -This feature helps you replace a couple of small commits with a single commit, or if you want to make the order more logical. +This feature helps you replace a couple of small commits with a single commit, or if you want to make the order more logical: + +```shell +pick c6ee4d3 add a new file to the repo +pick c3c130b change readme + +# Rebase 168afa0..c3c130b onto 168afa0 +# +# Commands: +# p, pick = use commit +# r, reword = use commit, but edit the commit message +# e, edit = use commit, but stop for amending +# s, squash = use commit, but meld into previous commit +# f, fixup = like "squash", but discard this commit's log message +# x, exec = run command (the rest of the line) using shell +# +# These lines can be re-ordered; they are executed from top to bottom. +# +# If you remove a line here THAT COMMIT WILL BE LOST. +# +# However, if you remove everything, the rebase will be aborted. +# +# Note that empty commits are commented out +~ +~ +~ +"~/demo/gitlab-ce/.git/rebase-merge/git-rebase-todo" 20L, 673C +``` However, you should avoid rebasing commits you have pushed to a remote server if you have other active contributors in the same branch. Because rebasing creates new commits for all your changes, it can cause confusion because the same change would have multiple identifiers. @@ -244,8 +331,6 @@ Git does not allow you to merge the code again otherwise. ## Reducing merge commits in feature branches -![List of sequential merge commits](img/gitlab_flow_merge_commits.png) - Having lots of merge commits can make your repository history messy. Therefore, you should try to avoid merge commits in feature branches. Often, people avoid merge commits by just using rebase to reorder their commits after the commits on the `main` branch. @@ -303,13 +388,19 @@ Sharing your work before it's complete also allows for discussion and feedback a ## How to write a good commit message -![Good and bad commit message](img/gitlab_flow_good_commit.png) - A commit message should reflect your intention, not just the contents of the commit. -You can see the changes in a commit, so the commit message should explain why you made those changes. +You can see the changes in a commit, so the commit message should explain why you made those changes: + +```shell +# This commit message doesn't give enough information +git commit -m 'Improve XML generation' + +# These commit messages clearly state the intent of the commit +git commit -m 'Properly escape special characters in XML generation' +``` + An example of a good commit message is: "Combine templates to reduce duplicate code in the user views." The words "change," "improve," "fix," and "refactor" don't add much information to a commit message. -For example, "Improve XML generation" could be better written as "Properly escape special characters in XML generation." For more information about formatting commit messages, please see this excellent [blog post by Tim Pope](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). To add more context to a commit message, consider adding information regarding the @@ -326,8 +417,6 @@ Issue: gitlab.com/gitlab-org/gitlab/-/issues/1 ## Testing before merging -![Merge requests showing the test states: red, yellow, and green](img/gitlab_flow_ci_mr.png) - In old workflows, the continuous integration (CI) server commonly ran tests on the `main` branch only. Developers had to ensure their code did not break the `main` branch. When using GitLab flow, developers create their branches from this `main` branch, so it is essential that it never breaks. @@ -343,8 +432,6 @@ As said before, if you often have feature branches that last for more than a few ## Working with feature branches -![Shell output showing git pull output](img/gitlab_flow_git_pull.png) - When creating a feature branch, always branch from an up-to-date `main`. If you know before you start that your work depends on another branch, you can also branch from there. If you need to merge in another branch after starting, explain the reason in the merge commit. diff --git a/doc/topics/img/gitlab_flow.png b/doc/topics/img/gitlab_flow.png Binary files differdeleted file mode 100644 index c12405455f9..00000000000 --- a/doc/topics/img/gitlab_flow.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_ci_mr.png b/doc/topics/img/gitlab_flow_ci_mr.png Binary files differdeleted file mode 100644 index 85a609cb814..00000000000 --- a/doc/topics/img/gitlab_flow_ci_mr.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_close_issue_mr.png b/doc/topics/img/gitlab_flow_close_issue_mr.png Binary files differdeleted file mode 100644 index 70de2fb6cee..00000000000 --- a/doc/topics/img/gitlab_flow_close_issue_mr.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_environment_branches.png b/doc/topics/img/gitlab_flow_environment_branches.png Binary files differdeleted file mode 100644 index 0aff33c6bb8..00000000000 --- a/doc/topics/img/gitlab_flow_environment_branches.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_four_stages.png b/doc/topics/img/gitlab_flow_four_stages.png Binary files differdeleted file mode 100644 index 3ef6a33d2d4..00000000000 --- a/doc/topics/img/gitlab_flow_four_stages.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_git_pull.png b/doc/topics/img/gitlab_flow_git_pull.png Binary files differdeleted file mode 100644 index 0e56e59471c..00000000000 --- a/doc/topics/img/gitlab_flow_git_pull.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_github_flow.png b/doc/topics/img/gitlab_flow_github_flow.png Binary files differdeleted file mode 100644 index 21a22becdb6..00000000000 --- a/doc/topics/img/gitlab_flow_github_flow.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_good_commit.png b/doc/topics/img/gitlab_flow_good_commit.png Binary files differdeleted file mode 100644 index ceb0d4b1691..00000000000 --- a/doc/topics/img/gitlab_flow_good_commit.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_merge_commits.png b/doc/topics/img/gitlab_flow_merge_commits.png Binary files differdeleted file mode 100644 index 4a80811c6e3..00000000000 --- a/doc/topics/img/gitlab_flow_merge_commits.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_merge_request.png b/doc/topics/img/gitlab_flow_merge_request.png Binary files differdeleted file mode 100644 index 010e95983fc..00000000000 --- a/doc/topics/img/gitlab_flow_merge_request.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_messy_flow.png b/doc/topics/img/gitlab_flow_messy_flow.png Binary files differdeleted file mode 100644 index 4fa22d2bb5d..00000000000 --- a/doc/topics/img/gitlab_flow_messy_flow.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_production_branch.png b/doc/topics/img/gitlab_flow_production_branch.png Binary files differdeleted file mode 100644 index c132d51bfb6..00000000000 --- a/doc/topics/img/gitlab_flow_production_branch.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_rebase.png b/doc/topics/img/gitlab_flow_rebase.png Binary files differdeleted file mode 100644 index fe865177ba8..00000000000 --- a/doc/topics/img/gitlab_flow_rebase.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_release_branches.png b/doc/topics/img/gitlab_flow_release_branches.png Binary files differdeleted file mode 100644 index 0a7f61d0248..00000000000 --- a/doc/topics/img/gitlab_flow_release_branches.png +++ /dev/null diff --git a/doc/topics/offline/index.md b/doc/topics/offline/index.md index df6e1f9491e..a48ac9feb1a 100644 --- a/doc/topics/offline/index.md +++ b/doc/topics/offline/index.md @@ -4,7 +4,7 @@ group: Distribution 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 --- -# Offline GitLab +# Offline GitLab **(FREE SELF)** Computers in an offline environment are isolated from the public internet as a security measure. This page lists all the information available for running GitLab in an offline environment. diff --git a/doc/topics/offline/quick_start_guide.md b/doc/topics/offline/quick_start_guide.md index dd1ddeb31ff..09fae2b1fd5 100644 --- a/doc/topics/offline/quick_start_guide.md +++ b/doc/topics/offline/quick_start_guide.md @@ -4,7 +4,7 @@ group: Distribution 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 --- -# Getting started with an offline GitLab Installation +# Getting started with an offline GitLab Installation **(FREE SELF)** This is a step-by-step guide that helps you install, configure, and use a self-managed GitLab instance entirely offline. |