diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-06-16 18:25:58 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-06-16 18:25:58 +0000 |
| commit | a5f4bba440d7f9ea47046a0a561d49adf0a1e6d4 (patch) | |
| tree | fb69158581673816a8cd895f9d352dcb3c678b1e /doc/topics | |
| parent | d16b2e8639e99961de6ddc93909f3bb5c1445ba1 (diff) | |
| download | gitlab-ce-a5f4bba440d7f9ea47046a0a561d49adf0a1e6d4.tar.gz | |
Add latest changes from gitlab-org/gitlab@14-0-stable-eev14.0.0-rc42
Diffstat (limited to 'doc/topics')
35 files changed, 492 insertions, 397 deletions
diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 25640671e78..4181e32fcf2 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Authentication +# Authentication **(FREE)** This page gathers all the resources for the topic **Authentication** within GitLab. @@ -33,15 +33,15 @@ This page gathers all the resources for the topic **Authentication** within GitL - [Atlassian Crowd OmniAuth Provider](../../administration/auth/crowd.md) - [CAS OmniAuth Provider](../../integration/cas.md) - [SAML OmniAuth Provider](../../integration/saml.md) - - [SAML for GitLab.com Groups](../../user/group/saml_sso/index.md) **(PREMIUM SAAS)** - - [SCIM user provisioning for GitLab.com Groups](../../user/group/saml_sso/scim_setup.md) **(PREMIUM SAAS)** - - [Kerberos integration (GitLab EE)](../../integration/kerberos.md) **(STARTER)** + - [SAML for GitLab.com Groups](../../user/group/saml_sso/index.md) + - [SCIM user provisioning for GitLab.com Groups](../../user/group/saml_sso/scim_setup.md) + - [Kerberos integration (GitLab EE)](../../integration/kerberos.md) ## API - [OAuth 2 Tokens](../../api/README.md#oauth2-tokens) - [Personal access tokens](../../api/README.md#personalproject-access-tokens) -- [Project access tokens](../../api/README.md#personalproject-access-tokens) **(FREE SELF)** +- [Project access tokens](../../api/README.md#personalproject-access-tokens) - [Impersonation tokens](../../api/README.md#impersonation-tokens) - [GitLab as an OAuth2 provider](../../api/oauth2.md#gitlab-as-an-oauth2-provider) @@ -53,4 +53,4 @@ This page gathers all the resources for the topic **Authentication** within GitL - [Jenkins GitLab OAuth Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+OAuth+Plugin) - [OKD - Configuring Authentication and User Agent](https://docs.okd.io/3.11/install_config/configuring_authentication.html#GitLab) -<!-- vale gitlab.Spelling = YES -->
\ No newline at end of file +<!-- vale gitlab.Spelling = YES --> diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index a1a12ccd451..42c54961c1d 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -16,15 +16,25 @@ staging and canary deployments, ## Custom buildpacks -If the automatic buildpack detection fails for your project, or if you want to -use a custom buildpack, you can override the buildpack using a project CI/CD variable -or a `.buildpacks` file in your project: +If the automatic buildpack detection fails for your project, or if you +need more control over your build, you can customize the buildpacks +used for the build. -- **Project variable** - Create a project variable `BUILDPACK_URL` with the URL - of the buildpack to use. -- **`.buildpacks` file** - Add a file in your project's repository called `.buildpacks`, - and add the URL of the buildpack to use on a line in the file. If you want to - use multiple buildpacks, enter one buildpack per line. +### Custom buildpacks with Cloud Native Buildpacks + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28165) in GitLab 12.10. + +Specify either: + +- The CI/CD variable `BUILDPACK_URL` according to [`pack`'s specifications](https://buildpacks.io/docs/app-developer-guide/specific-buildpacks/). +- A [`project.toml` project descriptor](https://buildpacks.io/docs/app-developer-guide/using-project-descriptor/) with the buildpacks you would like to include. + +### Custom buildpacks with Herokuish + +Specify either: + +- The CI/CD variable `BUILDPACK_URL`. +- A `.buildpacks` file at the root of your project, containing one buildpack URL per line. The buildpack URL can point to either a Git repository URL or a tarball URL. For Git repositories, you can point to a specific Git reference (such as @@ -176,7 +186,7 @@ to the desired environment. See [Limit environment scope of CI/CD variables](../ ## Customizing `.gitlab-ci.yml` Auto DevOps is completely customizable because the -[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) +[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) is just an implementation of a [`.gitlab-ci.yml`](../../ci/yaml/README.md) file, and uses only features available to any implementation of `.gitlab-ci.yml`. @@ -191,11 +201,11 @@ include: ``` Add your changes, and your additions are merged with the -[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) +[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) using the behavior described for [`include`](../../ci/yaml/README.md#include). If you need to specifically remove a part of the file, you can also copy and paste the contents of the -[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) +[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) into your project and edit it as needed. ## Customizing the Kubernetes namespace @@ -241,7 +251,7 @@ include: - template: Jobs/Build.gitlab-ci.yml ``` -See the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) for information on available jobs. +See the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) for information on available jobs. WARNING: Auto DevOps templates using the [`only`](../../ci/yaml/README.md#only--except) or @@ -255,6 +265,27 @@ base template is migrated to use the `rules` syntax. For users who cannot migrate just yet, you can alternatively pin your templates to the [GitLab 12.10 based templates](https://gitlab.com/gitlab-org/auto-devops-v12-10). +## Use images hosted in a local Docker registry + +You can configure many Auto DevOps jobs to run in an [offline environment](../../user/application_security/offline_deployments/index.md): + +1. Copy the required Auto DevOps Docker images from Docker Hub and `registry.gitlab.com` to their local GitLab container registry. +1. After the images are hosted and available in a local registry, edit `.gitlab-ci.yml` to point to the locally-hosted images. For example: + + ```yaml + include: + - template: Auto-DevOps.gitlab-ci.yml + + variables: + REGISTRY_URL: "registry.gitlab.example" + + build: + image: "$REGISTRY_URL/docker/auto-build-image:v0.6.0" + services: + - name: "$REGISTRY_URL/greg/docker/docker:20.10.6-dind" + command: ['--tls=false', '--host=tcp://0.0.0.0:2375'] + ``` + ## PostgreSQL database support To support applications requiring a database, @@ -326,8 +357,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_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` | When set to a non-empty value and no `Dockerfile` is present, Auto Build builds your application using Cloud Native Buildpacks instead of Herokuish. [More details](stages.md#auto-build-using-cloud-native-buildpacks-beta). | -| `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-beta). | +| `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). | | `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` | Extra arguments to be passed to the `docker build` command. Note that using quotes doesn't prevent word splitting. [More details](#passing-arguments-to-docker-build). | | `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` | A [comma-separated list of CI/CD variable names](#forward-cicd-variables-to-the-build-environment) to be forwarded to the build environment (the buildpack builder or `docker build`). | | `AUTO_DEVOPS_CHART` | Helm Chart used to deploy your apps. Defaults to the one [provided by GitLab](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app). | @@ -337,8 +368,7 @@ applications. | `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD` | From GitLab 11.11, used to set a password to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME`. | | `AUTO_DEVOPS_DEPLOY_DEBUG` | From GitLab 13.1, if this variable is present, Helm outputs debug logs. | | `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V<N>` | From [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) v1.0.0, if this variable is present, a new major version of chart is forcibly deployed. For more information, see [Ignore warnings and continue deploying](upgrading_auto_deploy_dependencies.md#ignore-warnings-and-continue-deploying). | -| `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` | From GitLab 12.5, used in combination with [ModSecurity feature flag](../../user/clusters/applications.md#web-application-firewall-modsecurity) to toggle [ModSecurity's `SecRuleEngine`](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#SecRuleEngine) behavior. Defaults to `DetectionOnly`. | -| `BUILDPACK_URL` | Buildpack's full URL. Can point to either [a Git repository URL or a tarball URL](#custom-buildpacks). | +| `BUILDPACK_URL` | Buildpack's full URL. [Must point to a URL supported by Pack or Herokuish](#custom-buildpacks). | | `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. | @@ -411,7 +441,8 @@ 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` | From GitLab 11.0 | Browser performance. 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`. | +| `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. | | `retire-js-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 03454649c7e..f2ce61044ef 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -264,7 +264,7 @@ When using Auto DevOps, you can deploy different environments to different Kubernetes clusters, due to the 1:1 connection [existing between them](../../user/project/clusters/index.md#multiple-kubernetes-clusters). -The [Deploy Job template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) +The [Deploy Job template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) used by Auto DevOps currently defines 3 environment names: - `review/` (every environment starting with `review/`) @@ -286,14 +286,14 @@ The following table is an example of how to configure the three different cluste To add a different cluster for each environment: -1. Navigate to your project's **Operations > Kubernetes**. +1. Navigate to your project's **Infrastructure > Kubernetes clusters**. 1. Create the Kubernetes clusters with their respective environment scope, as described from the table above. -1. After creating the clusters, navigate to each cluster and install - Ingress. Wait for the Ingress IP address to be assigned. +1. After creating the clusters, navigate to each cluster and [install + Ingress](quick_start_guide.md#install-ingress). Wait for the Ingress IP address to be assigned. 1. Make sure you've [configured your DNS](#auto-devops-base-domain) with the specified Auto DevOps domains. -1. Navigate to each cluster's page, through **Operations > Kubernetes**, +1. Navigate to each cluster's page, through **Infrastructure > Kubernetes clusters**, and add the domain based on its Ingress IP address. After completing configuration, you can test your setup by creating a merge request diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 631180f696c..448e9526b88 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -63,7 +63,8 @@ to deploy this project to. ## Create a Kubernetes cluster from within GitLab 1. On your project's landing page, click **Add Kubernetes cluster** - (note that this option is also available when you navigate to **Operations > Kubernetes**). + (note that this option is also available when you navigate to + **Infrastructure > Kubernetes clusters**).  @@ -106,7 +107,8 @@ status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). After your cluster is running, you must install NGINX Ingress Controller as a load balancer, to route traffic from the internet to your application. Because you've created a Google GKE cluster in this guide, you can install NGINX Ingress Controller -with Google Cloud Shell: +through the GitLab [Cluster management project template](../../user/clusters/management_project_template.md), +or manually with Google Cloud Shell: 1. Go to your cluster's details page, and click the **Advanced Settings** tab. 1. Click the link to Google Kubernetes Engine to visit the cluster on Google Cloud Console. @@ -114,21 +116,28 @@ with Google Cloud Shell: 1. After the Cloud Shell starts, run these commands to install NGINX Ingress Controller: ```shell - helm repo add nginx-stable https://helm.nginx.com/stable + kubectl create ns gitlab-managed-apps + helm repo add stable https://charts.helm.sh/stable helm repo update - helm install nginx-ingress nginx-stable/nginx-ingress + helm install ingress stable/nginx-ingress -n gitlab-managed-apps # Check that the ingress controller is installed successfully - kubectl get service nginx-ingress-nginx-ingress + kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps ``` -1. A few minutes after you install NGINX, the load balancer obtains an IP address, and you can - get the external IP address with this command: +## Configure your base domain + +Follow these steps to configure the Base Domain where your apps will be accessible. +1. A few minutes after you install NGINX, the load balancer obtains an IP address, and you can + get the external IP address with the following command: + ```shell - kubectl get service nginx-ingress-nginx-ingress -ojson | jq -r '.status.loadBalancer.ingress[].ip' + kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -ojson | jq -r '.status.loadBalancer.ingress[].ip' ``` + Replace `gitlab-managed-apps` if you have overwritten your namespace. + Copy this IP address, as you need it in the next step. 1. Go back to the cluster page on GitLab, and go to the **Details** tab. @@ -186,7 +195,7 @@ The jobs are separated into stages: - Jobs suffixed with `-sast` run static analysis on the current code to check for potential security issues, and are allowed to fail ([Auto SAST](stages.md#auto-sast)) **(ULTIMATE)** - The `secret-detection` job checks for leaked secrets and is allowed to fail ([Auto Secret Detection](stages.md#auto-secret-detection)) **(ULTIMATE)** - - The `license_management` job searches the application's dependencies to determine each of their + - The `license_scanning` job searches the application's dependencies to determine each of their licenses and is allowed to fail ([Auto License Compliance](stages.md#auto-license-compliance)) **(ULTIMATE)** @@ -208,7 +217,7 @@ to monitor it. After successfully deploying your application, you can view its website and check on its health on the **Environments** page by navigating to -**Operations > Environments**. This page displays details about +**Deployments > Environments**. This page displays details about the deployed applications, and the right-hand column displays icons that link you to common environment tasks: @@ -308,6 +317,5 @@ and customized to fit your workflow. Here are some helpful resources for further 1. [Multiple Kubernetes clusters](index.md#using-multiple-kubernetes-clusters) 1. [Incremental rollout to production](customize.md#incremental-rollout-to-production) **(PREMIUM)** 1. [Disable jobs you don't need with CI/CD variables](customize.md#cicd-variables) -1. [Use a static IP for your cluster](../../user/clusters/applications.md#using-a-static-ip) 1. [Use your own buildpacks to build your application](customize.md#custom-buildpacks) 1. [Prometheus monitoring](../../user/project/integrations/prometheus.md) diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index 8fb16511e34..7e59ecb4916 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -26,23 +26,26 @@ To make full use of Auto DevOps with Kubernetes, you need: [new cluster using the GitLab UI](../../user/project/clusters/add_remove_clusters.md#create-new-cluster). For Kubernetes 1.16+ clusters, you must perform additional configuration for [Auto Deploy for Kubernetes 1.16+](stages.md#kubernetes-116). - 1. NGINX Ingress. You can deploy it to your Kubernetes cluster by installing - the [GitLab-managed app for Ingress](../../user/clusters/applications.md#ingress), - after configuring the GitLab integration with Kubernetes in the previous step. - - Alternatively, you can use the - [`nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress) - Helm chart to install Ingress manually. + 1. For external HTTP traffic, an Ingress controller is required. For regular + deployments, any Ingress controller should work, but as of GitLab 14.0, + [canary deployments](../../user/project/canary_deployments.md) require + NGINX Ingress. You can deploy the NGINX Ingress controller to your + Kubernetes cluster either through the GitLab [Cluster management project template](../../user/clusters/management_project_template.md) + or manually by using the [`ingress-nginx`](https://github.com/kubernetes/ingress-nginx/tree/master/charts/ingress-nginx) + Helm chart. NOTE: - If you use your own Ingress instead of the one provided by GitLab Managed - Apps, ensure you're running at least version 0.9.0 of NGINX Ingress and - [enable Prometheus metrics](https://github.com/helm/charts/tree/master/stable/nginx-ingress#prometheus-metrics) - for the response metrics to appear. You must also + For metrics to appear when using the [Prometheus cluster integration](../../user/clusters/integrations.md#prometheus-cluster-integration), you must [enable Prometheus metrics](https://github.com/kubernetes/ingress-nginx/tree/master/charts/ingress-nginx#prometheus-metrics). + + When deploying [using custom charts](customize.md#custom-helm-chart), you must also [annotate](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) - the NGINX Ingress deployment to be scraped by Prometheus using + the Ingress manifest to be scraped by Prometheus using `prometheus.io/scrape: "true"` and `prometheus.io/port: "10254"`. + NOTE: + If your cluster is installed on bare metal, see + [Auto DevOps Requirements for bare metal](#auto-devops-requirements-for-bare-metal). + - **Base domain** (for [Auto Review Apps](stages.md#auto-review-apps), [Auto Deploy](stages.md#auto-deploy), and [Auto Monitoring](stages.md#auto-monitoring)) @@ -61,42 +64,34 @@ To make full use of Auto DevOps with Kubernetes, you need: You can configure Docker-based runners to autoscale as well, using [Docker Machine](https://docs.gitlab.com/runner/install/autoscaling.html). - If you've configured the GitLab integration with Kubernetes in the first step, you - can deploy it to your cluster by installing the - [GitLab-managed app for GitLab Runner](../../user/clusters/applications.md#gitlab-runner). - - Runners should be registered as [shared runners](../../ci/runners/README.md#shared-runners) - for the entire GitLab instance, or [specific runners](../../ci/runners/README.md#specific-runners) - that are assigned to specific projects (the default if you've installed the - GitLab Runner managed application). + Runners should be registered as [shared runners](../../ci/runners/runners_scope.md#shared-runners) + for the entire GitLab instance, or [specific runners](../../ci/runners/runners_scope.md#specific-runners) + that are assigned to specific projects. - **Prometheus** (for [Auto Monitoring](stages.md#auto-monitoring)) To enable Auto Monitoring, you need Prometheus installed either inside or outside your cluster, and configured to scrape your Kubernetes cluster. - If you've configured the GitLab integration with Kubernetes, you can deploy it to - your cluster by installing the - [GitLab-managed app for Prometheus](../../user/clusters/applications.md#prometheus). + If you've configured the GitLab integration with Kubernetes, you can + instruct GitLab to query an in-cluster Prometheus by enabling + the [Prometheus cluster integration](../../user/clusters/integrations.md#prometheus-cluster-integration). - The [Prometheus service](../../user/project/integrations/prometheus.md) - integration must be enabled for the project, or enabled as a - [default service template](../../user/project/integrations/services_templates.md) - for the entire GitLab installation. + The [Prometheus integration](../../user/project/integrations/prometheus.md) + integration must be activated for the project, or activated at the group or instance level. + Learn more about [Project integration management](../../user/admin_area/settings/project_integration_management.md). To get response metrics (in addition to system metrics), you must [configure Prometheus to monitor NGINX](../../user/project/integrations/prometheus_library/nginx_ingress.md#configuring-nginx-ingress-monitoring). - **cert-manager** (optional, for TLS/HTTPS) - To enable HTTPS endpoints for your application, you must install cert-manager, + To enable HTTPS endpoints for your application, you can [install cert-manager](https://cert-manager.io/docs/installation/kubernetes/), a native Kubernetes certificate management controller that helps with issuing certificates. Installing cert-manager on your cluster issues a [Let's Encrypt](https://letsencrypt.org/) certificate and ensures the - certificates are valid and up-to-date. If you've configured the GitLab integration - with Kubernetes, you can deploy it to your cluster by installing the - [GitLab-managed app for cert-manager](../../user/clusters/applications.md#cert-manager). + certificates are valid and up-to-date. -If you don't have Kubernetes or Prometheus installed, then +If you don't have Kubernetes or Prometheus configured, then [Auto Review Apps](stages.md#auto-review-apps), [Auto Deploy](stages.md#auto-deploy), and [Auto Monitoring](stages.md#auto-monitoring) are skipped. @@ -124,9 +119,6 @@ When you trigger a pipeline, if you have Auto DevOps enabled and if you have cor [entered AWS credentials as variables](../../ci/cloud_deployment/index.md#deploy-your-application-to-the-aws-elastic-container-service-ecs), your application is deployed to AWS ECS. -[GitLab Managed Apps](../../user/clusters/applications.md) are not available when deploying to AWS ECS. -You must manually configure your application (such as Ingress or Help) on AWS ECS. - If you have both a valid `AUTO_DEVOPS_PLATFORM_TARGET` variable and a Kubernetes cluster tied to your project, only the deployment to Kubernetes runs. @@ -149,3 +141,18 @@ specific CI/CD variable. For more details, see [Custom build job for Auto DevOps](../../ci/cloud_deployment/index.md#custom-build-job-for-auto-devops) for deployments to AWS EC2. + +## Auto DevOps requirements for bare metal + +According to the [Kubernetes Ingress-NGINX docs](https://kubernetes.github.io/ingress-nginx/deploy/baremetal/): + +> In traditional cloud environments, where network load balancers are available on-demand, +a single Kubernetes manifest suffices to provide a single point of contact to the NGINX Ingress +controller to external clients and, indirectly, to any application running inside the cluster. +Bare-metal environments lack this commodity, requiring a slightly different setup to offer the +same kind of access to external consumers. + +The docs linked above explain the issue and present possible solutions, for example: + +- Through [MetalLB](https://github.com/metallb/metallb). +- Through [PorterLB](https://github.com/kubesphere/porterlb). diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index 66b37f30bbc..d3f217d3749 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -33,15 +33,24 @@ your own `Dockerfile`, you must either: - Override the default values by [customizing the Auto Deploy Helm chart](customize.md#custom-helm-chart). -### Auto Build using Heroku buildpacks +### Auto Build using Cloud Native Buildpacks + +> - Introduced in [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28165). +> - Auto Build using Cloud Native Buildpacks by default was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63351) in GitLab 14.0. Auto Build builds an application using a project's `Dockerfile` if present. If no -`Dockerfile` is present, it uses [Herokuish](https://github.com/gliderlabs/herokuish) -and [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) -to detect and build the application into a Docker image. +`Dockerfile` is present, Auto Build builds your application using +[Cloud Native Buildpacks](https://buildpacks.io) to detect and build the +application into a Docker image. The feature uses the +[`pack` command](https://github.com/buildpacks/pack). +The default [builder](https://buildpacks.io/docs/concepts/components/builder/) +is `heroku/buildpacks:18` but a different builder can be selected using +the CI/CD variable `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER`. Each buildpack requires your project's repository to contain certain files for -Auto Build to build your application successfully. For example, your application's +Auto Build to build your application successfully. The structure is +specific to the builder and buildpacks you have selected. +For example, when using the Heroku's builder (the default), your application's root directory must contain the appropriate file for your application's language: @@ -52,39 +61,38 @@ For the requirements of other languages and frameworks, read the [Heroku buildpacks documentation](https://devcenter.heroku.com/articles/buildpacks#officially-supported-buildpacks). NOTE: -If Auto Build fails despite the project meeting the buildpack requirements, set -a project CI/CD variable `TRACE=true` to enable verbose logging, which may help you -troubleshoot. +Auto Test still uses Herokuish, as test suite detection is not +yet part of the Cloud Native Buildpack specification. For more information, see +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212689). -### Auto Build using Cloud Native Buildpacks (beta) +### Auto Build using Herokuish -> Introduced in [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28165). +> [Replaced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63351) with Cloud Native Buildpacks in GitLab 14.0. -Auto Build supports building your application using [Cloud Native Buildpacks](https://buildpacks.io) -through the [`pack` command](https://github.com/buildpacks/pack). To use Cloud Native Buildpacks, -set the CI/CD variable `AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED` to a non-empty -value. The default builder is `heroku/buildpacks:18` but a different builder -can be selected using the CI/CD variable `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER`. +Prior to GitLab 14.0, [Herokuish](https://github.com/gliderlabs/herokuish) was +the default build method for projects without a `Dockerfile`. Herokuish can +still be used by setting the CI/CD variable `AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED` +to `false`. -Cloud Native Buildpacks (CNBs) are an evolution of Heroku buildpacks, and -GitLab expects them to eventually supersede Herokuish-based builds within Auto DevOps. For more -information, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212692). +NOTE: +If Auto Build fails despite the project meeting the buildpack requirements, set +a project CI/CD variable `TRACE=true` to enable verbose logging, which may help you +troubleshoot. + +### Moving from Herokuish to Cloud Native Buildpacks Builds using Cloud Native Buildpacks support the same options as builds using -Heroku buildpacks, with the following caveats: +Herokuish, with the following caveats: - The buildpack must be a Cloud Native Buildpack. A Heroku buildpack can be converted to a Cloud Native Buildpack using Heroku's [`cnb-shim`](https://github.com/heroku/cnb-shim). -- `BUILDPACK_URL` must be in a form +- `BUILDPACK_URL` must be in a format [supported by `pack`](https://buildpacks.io/docs/app-developer-guide/specific-buildpacks/). -- The `/bin/herokuish` command is not present in the resulting image, and prefixing +- The `/bin/herokuish` command is not present in the built image, and prefixing commands with `/bin/herokuish procfile exec` is no longer required (nor possible). - -NOTE: -Auto Test still uses Herokuish, as test suite detection is not -yet part of the Cloud Native Buildpack specification. For more information, see -[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212689). + Instead, custom commands should be prefixed with `/cnb/lifecycle/launcher` + to receive the correct execution environment. ## Auto Test @@ -208,9 +216,9 @@ documentation. ## Auto Container Scanning **(ULTIMATE)** -Vulnerability Static Analysis for containers uses either [Clair](https://github.com/quay/clair) -or [Trivy](https://aquasecurity.github.io/trivy/latest/) to check for potential security issues in -Docker images. The Auto Container Scanning stage is skipped on licenses other than [Ultimate](https://about.gitlab.com/pricing/). +Vulnerability static analysis for containers uses [Trivy](https://aquasecurity.github.io/trivy/latest/) +to check for potential security issues in Docker images. The Auto Container Scanning stage is +skipped on licenses other than [Ultimate](https://about.gitlab.com/pricing/). After creating the report, it's uploaded as an artifact which you can later download and check out. The merge request displays any detected security issues. @@ -349,7 +357,7 @@ project ID, such as `project-4321`. Auto Deploy does not include deployments to staging or canary environments by default, but the -[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) +[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) contains job definitions for these tasks if you want to enable them. You can use [CI/CD variables](customize.md#cicd-variables) to automatically @@ -461,15 +469,16 @@ If present, `DB_MIGRATE` is run as a shell command within an application pod as a Helm pre-upgrade hook. For example, in a Rails application in an image built with -[Herokuish](https://github.com/gliderlabs/herokuish): +[Cloud Native Buildpacks](#auto-build-using-cloud-native-buildpacks): -- `DB_INITIALIZE` can be set to `RAILS_ENV=production /bin/herokuish procfile exec bin/rails db:setup` -- `DB_MIGRATE` can be set to `RAILS_ENV=production /bin/herokuish procfile exec bin/rails db:migrate` +- `DB_INITIALIZE` can be set to `RAILS_ENV=production /cnb/lifecycle/launcher bin/rails db:setup` +- `DB_MIGRATE` can be set to `RAILS_ENV=production /cnb/lifecycle/launcher bin/rails db:migrate` Unless your repository contains a `Dockerfile`, your image is built with -Herokuish, and you must prefix commands run in these images with -`/bin/herokuish procfile exec` (for Herokuish) or `/cnb/lifecycle/launcher` -(for Cloud Native Buildpacks) to replicate the environment where your +Cloud Native Buildpacks, and you must prefix commands run in these images with +`/cnb/lifecycle/launcher`, (or `/bin/herokuish procfile exec` when +using [Herokuish](#auto-build-using-herokuish)) +to replicate the environment where your application runs. ### Upgrade auto-deploy-app Chart @@ -508,14 +517,10 @@ workers: sidekiq: replicaCount: 1 command: - - /bin/herokuish - - procfile - - exec + - /cnb/lifecycle/launcher - sidekiq preStopCommand: - - /bin/herokuish - - procfile - - exec + - /cnb/lifecycle/launcher - sidekiqctl - quiet terminationGracePeriodSeconds: 60 @@ -645,42 +650,6 @@ ciliumNetworkPolicy: For more information on installing Network Policies, see [Install Cilium using GitLab CI/CD](../../user/clusters/applications.md#install-cilium-using-gitlab-cicd). -### Web Application Firewall (ModSecurity) customization - -> [Introduced](https://gitlab.com/gitlab-org/charts/auto-deploy-app/-/merge_requests/44) in GitLab 12.8. - -Customization on an [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) -or on a deployment base is available for clusters with -[ModSecurity installed](../../user/clusters/applications.md#web-application-firewall-modsecurity). - -To enable ModSecurity with Auto Deploy, you must create a `.gitlab/auto-deploy-values.yaml` -file in your project with the following attributes. - -|Attribute | Description | Default | ------------|-------------|---------| -|`enabled` | Enables custom configuration for ModSecurity, defaulting to the [Core Rule Set](https://coreruleset.org/) | `false` | -|`secRuleEngine` | Configures the [rules engine](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#secruleengine) | `DetectionOnly` | -|`secRules` | Creates one or more additional [rule](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#SecRule) | `nil` | - -In the following `auto-deploy-values.yaml` example, some custom settings -are enabled for ModSecurity. Those include setting its engine to -process rules instead of only logging them, while adding two specific -header-based rules: - -```yaml -ingress: - modSecurity: - enabled: true - secRuleEngine: "On" - secRules: - - variable: "REQUEST_HEADERS:User-Agent" - operator: "printer" - action: "log,deny,id:'2010',status:403,msg:'printer is an invalid agent'" - - variable: "REQUEST_HEADERS:Content-Type" - operator: "text/plain" - action: "log,deny,id:'2011',status:403,msg:'Text is not supported as content type'" -``` - ### Running commands in the container Applications built with [Auto Build](#auto-build) using Herokuish, the default @@ -723,11 +692,6 @@ The metrics include: - **Response Metrics:** latency, throughput, error rate - **System Metrics:** CPU utilization, memory utilization -GitLab provides some initial alerts for you after you install Prometheus: - -- Ingress status code `500` > 0.1% -- NGINX status code `500` > 0.1% - To use Auto Monitoring: 1. [Install and configure the Auto DevOps requirements](requirements.md). diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 0dabb80204a..62dc061aba6 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -100,9 +100,15 @@ If your Auto DevOps project has an active environment that was deployed with the MIGRATE_HELM_2TO3: "true" .auto-deploy: - image: registry.gitlab.com/gitlab-org/cluster-integration/auto-deploy-image:v2.0.0-beta.1 + # Optional: If you are on GitLab 13.12 or older, pin the auto-deploy-image + # image: registry.gitlab.com/gitlab-org/cluster-integration/auto-deploy-image:v2.6.0 variables: AUTO_DEVOPS_FORCE_DEPLOY_V2: 1 + # If you have non-public pipelines, you can back up the entire namespace in a job artifact + # prior to the migration by setting the CI variable BACKUP_NAMESPACE to a non-empty value. + # WARNING: If you have public pipelines, this artifact will be public and can + # expose your secrets. + # BACKUP_HELM2_RELEASES: 1 ``` 1. Run the `<environment-name>:helm-2to3:migrate` job. @@ -110,10 +116,16 @@ If your Auto DevOps project has an active environment that was deployed with the 1. If the deployment succeeds, you can safely run `environment:helm-2to3:cleanup`. This deletes all Helm 2 release data from the namespace. - If you accidentally delete the Helm 2 releases before you are ready, the `<environment-name>:helm2to3:migrate` + If you set `BACKUP_HELM2_RELEASES` to a non-empty value, the `<environment-name>:helm2to3:migrate` job saves a backup for 1 week in a job artifact called `helm-2-release-backups`. - The backup is in a Kubernetes manifest file that can be restored using + If you accidentally delete the Helm 2 releases before you are ready, then + this backup is in a Kubernetes manifest file that can be restored using `kubectl apply -f $backup`. + + **WARNING:** + This artifact can contain secrets and is visible to any + user who can see your job. + 1. Remove the `MIGRATE_HELM_2TO3` CI/CD variable. #### In-Cluster PostgreSQL Channel 2 @@ -164,6 +176,8 @@ include: - remote: https://gitlab.com/gitlab-org/gitlab/-/raw/v13.3.0-ee/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml ``` +Alternatively, you can use the [v13.12 Auto DevOps templates archive](https://gitlab.com/hfyngvason/auto-devops-v13-12). + ### Ignore warnings and continue deploying If you are certain that the new chart version is safe to be deployed, you can add diff --git a/doc/topics/build_your_application.md b/doc/topics/build_your_application.md new file mode 100644 index 00000000000..d084ecec435 --- /dev/null +++ b/doc/topics/build_your_application.md @@ -0,0 +1,16 @@ +--- +stage: +group: +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 +--- + +# Build your application **(FREE)** + +Add your source code to a repository, create merge requests to check in +code, and use CI/CD to generate your application. Include packages in your app and output it to a variety of environments. + +- [Repositories](../user/project/repository/index.md) +- [Merge requests](../user/project/merge_requests/index.md) +- [CI/CD](../ci/README.md) +- [Packages & Registries](../user/packages/index.md) +- [Application infrastructure](../user/project/clusters/index.md) diff --git a/doc/topics/git/bisect.md b/doc/topics/git/bisect.md index 8af77031c93..e587a51ba17 100644 --- a/doc/topics/git/bisect.md +++ b/doc/topics/git/bisect.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +stage: Create +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false --- -# Bisect +# Bisect **(FREE)** - Find a commit that introduced a bug - Works through a process of elimination diff --git a/doc/topics/git/cherry_picking.md b/doc/topics/git/cherry_picking.md index 5a0867371bb..4a875e25e1b 100644 --- a/doc/topics/git/cherry_picking.md +++ b/doc/topics/git/cherry_picking.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w comments: false --- -# Cherry Pick +# Cherry pick **(FREE)** Given an existing commit on one branch, apply the change to another branch. diff --git a/doc/topics/git/feature_branch_development.md b/doc/topics/git/feature_branch_development.md index 8d18441aadd..ae1485741a5 100644 --- a/doc/topics/git/feature_branch_development.md +++ b/doc/topics/git/feature_branch_development.md @@ -9,7 +9,7 @@ type: how-tos GitLab values encourage the use of [Minimal Viable Change (MVC)](https://about.gitlab.com/handbook/values/#minimal-viable-change-mvc). However, viable changes are not always small. In such cases, it can help to set up a dedicated feature branch. -People can contribute MRs to that feature branch, without affecting the functionality of the default (usually `master`) branch. +People can contribute MRs to that feature branch, without affecting the functionality of the [default branch](../../user/project/repository/branches/default.md). Once work on the development branch is complete, then the feature branch can be finally merged into the default branch. @@ -19,14 +19,14 @@ GitLab frequently implements this process whenever there is an MVC that requires This section describes the use case with GitLab [release posts](https://about.gitlab.com/handbook/marketing/blog/release-posts/). Dozens of GitLab team members contribute to each monthly release post. -In such cases, it may be more efficient to submit an MR on the release post feature branch instead of master. +In such cases, it may be more efficient to submit an MR on the release post feature branch instead of the [default branch](../../user/project/repository/branches/default.md). In this case, the feature branch would be `release-X-Y`. Assuming the `release-X-Y` branch already exists, you can set up an MR against that branch, with the following steps: -1. Navigate to the main (master) branch: +1. Navigate to the [default branch](../../user/project/repository/branches/default.md) (here, `main`): ```shell - git checkout master + git checkout main ``` 1. Make sure you have the latest version of your repository: @@ -101,8 +101,8 @@ we have selected `test-branch` as the source, and `release-13-0` as the target. Request to merge test-branch into release-13-0 ``` - That confirms you've set up the MR to merge into the specified branch, not master. + That confirms you've set up the MR to merge into the specified branch, not the [default branch](../../user/project/repository/branches/default.md). 1. Proceed with the change as you would with any other MR. 1. When your MR is approved, and an appropriate user merges that MR, you can rest assured that your work is incorporated directly into the feature branch. -When the feature branch is ready, it can then be merged into master. +When the feature branch is ready, it can then be merged into the [default branch](../../user/project/repository/branches/default.md). diff --git a/doc/topics/git/feature_branching.md b/doc/topics/git/feature_branching.md index f6233bddb18..f0ded5511ee 100644 --- a/doc/topics/git/feature_branching.md +++ b/doc/topics/git/feature_branching.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +stage: Create +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false --- -# Feature branching +# Feature branching **(FREE)** - Efficient parallel workflow for teams - Develop each feature in a branch diff --git a/doc/topics/git/getting_started.md b/doc/topics/git/getting_started.md index 2c3d5fe15de..7e04eae622f 100644 --- a/doc/topics/git/getting_started.md +++ b/doc/topics/git/getting_started.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +stage: Create +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false --- -# Getting Started +# Getting started **(FREE)** ## Instantiating Repositories diff --git a/doc/topics/git/git_add.md b/doc/topics/git/git_add.md index d136b9151bc..e15a1e9a60d 100644 --- a/doc/topics/git/git_add.md +++ b/doc/topics/git/git_add.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +stage: Create +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false --- -# Git Add +# Git Add **(FREE)** Adds content to the index or staging area. diff --git a/doc/topics/git/git_log.md b/doc/topics/git/git_log.md index ae4ae69ce76..3988d7f7ac9 100644 --- a/doc/topics/git/git_log.md +++ b/doc/topics/git/git_log.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +stage: Create +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false --- -# Git Log +# Git Log **(FREE)** Git log lists commit history. It allows searching and filtering. diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index 78303d24a20..8844d362c10 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.md @@ -32,7 +32,7 @@ consider pulling it instead (`git pull origin master`). It has a similar effect without compromising the work of your contributors. It's safer to back up your branch before rebasing to make sure you don't lose -any changes. For example, consider a [feature branch](../../gitlab-basics/start-using-git.md#branching) +any changes. For example, consider a [feature branch](../../gitlab-basics/start-using-git.md#branches) called `my-feature-branch`: 1. Open your feature branch in the terminal: @@ -80,12 +80,13 @@ ensure that the changes you're adding to the codebase do not break any existing changes added to the target branch _after_ you created your feature branch. -For example, to update your branch `my-feature-branch` with `master`: +For example, to update your branch `my-feature-branch` with your +[default branch](../../user/project/repository/branches/default.md) (here, using `main`): -1. Fetch the latest changes from `master`: +1. Fetch the latest changes from `main`: ```shell - git fetch origin master + git fetch origin main ``` 1. Checkout your feature branch: @@ -94,24 +95,24 @@ For example, to update your branch `my-feature-branch` with `master`: git checkout my-feature-branch ``` -1. Rebase it against `master`: +1. Rebase it against `main`: ```shell - git rebase origin/master + git rebase origin/main ``` 1. [Force-push](#force-push) to your branch. When you rebase: -1. Git imports all the commits submitted to `master` _after_ the +1. Git imports all the commits submitted to `main` _after_ the moment you created your feature branch until the present moment. 1. Git puts the commits you have in your feature branch on top of all - the commits imported from `master`: + the commits imported from `main`:  -You can replace `master` with any other branch you want to rebase against, for +You can replace `main` with any other branch you want to rebase against, for example, `release-10-3`. You can also replace `origin` with other remote repositories, for example, `upstream`. To check what remotes you have linked to your local repository, you can run `git remote -v`. diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 0851d3f6b50..dfb175cbb82 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -114,11 +114,9 @@ See the documentation on [File Locking](../../../user/project/file_lock.md). ## LFS objects in project archives > - Support for including Git LFS blobs inside [project source downloads](../../../user/project/repository/index.md) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. -> - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/268409) in GitLab 13.6. > - Enabled on GitLab.com. > - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-lfs-objects-in-project-archives). WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -134,32 +132,40 @@ oid sha256:3ea5dd307f195f449f0e08234183b82e92c3d5f4cff11c2a6bb014f9e0de12aa size 177735 ``` -Starting with GitLab 13.5, these pointers are converted to the uploaded -LFS object if the `include_lfs_blobs_in_archive` feature flag is -enabled. +In GitLab version 13.5 and later, these pointers are converted to the uploaded +LFS object. Technical details about how this works can be found in the [development documentation for LFS](../../../development/lfs.md#including-lfs-blobs-in-project-archives). -### Enable or disable LFS objects in project archives +## Troubleshooting -_LFS objects in project archives_ is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. +### Encountered `n` file(s) that should have been pointers, but weren't -To enable it: +This error indicates the file (or files) are expected to be tracked by LFS, but for +some reason the repository is not tracking them as LFS. This issue can be one +potential reason for this error: +[Files not tracked with LFS when uploaded through the web interface](https://gitlab.com/gitlab-org/gitlab/-/issues/326342#note_586820485) -```ruby -Feature.enable(:include_lfs_blobs_in_archive) -``` +To resolve the problem, migrate the affected file (or files) and push back to the repository: -To disable it: +1. Migrate the file to LFS: -```ruby -Feature.disable(:include_lfs_blobs_in_archive) -``` + ```shell + git lfs migrate import --yes --no-rewrite "<your-file>" + ``` -## Troubleshooting +1. Push back to your repository: + + ```shell + git push + ``` + +1. (Optional) Clean up your `.git` folder: + + ```shell + git reflog expire --expire-unreachable=now --all + git gc --prune=now + ``` ### error: Repository or object not found diff --git a/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md b/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md index 741b2a78b85..d7fb8a37b9c 100644 --- a/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md @@ -1,5 +1,6 @@ --- redirect_to: 'index.md' +remove_date: '2021-07-22' --- This document was moved to [another location](index.md). diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md index 3f8e0575add..d1231257f38 100644 --- a/doc/topics/git/lfs/migrate_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_to_git_lfs.md @@ -41,7 +41,7 @@ Before beginning, make sure: To follow this tutorial, you need: -- Maintainer permissions to the existing Git repository +- The [Maintainer role](../../../user/permissions.md) for the existing Git repository you'd like to migrate to LFS with access through the command line. - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [Java Runtime Environment](https://www.java.com/en/download/manual.jsp) @@ -137,8 +137,8 @@ Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs- # Change into the upstream repo directory: cd test-git-lfs-repo-migration - # You may need to reset your local copy with upstream's `master` after force-pushing from the mirror: - git reset --hard origin/master + # You may need to reset your local copy with upstream's `main` after force-pushing from the mirror: + git reset --hard origin/main # Track the files with LFS: git lfs track "*.gif" "*.png" "*.jpg" "*.psd" "*.mp4" "img/" diff --git a/doc/topics/git/merge_conflicts.md b/doc/topics/git/merge_conflicts.md index 66771559298..bf69190030c 100644 --- a/doc/topics/git/merge_conflicts.md +++ b/doc/topics/git/merge_conflicts.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +stage: Create +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false --- -# Merge conflicts +# Merge conflicts **(FREE)** - Happen often - Learning to fix conflicts is hard diff --git a/doc/topics/git/merge_requests.md b/doc/topics/git/merge_requests.md index 751bf8195d0..d889bc8ffe5 100644 --- a/doc/topics/git/merge_requests.md +++ b/doc/topics/git/merge_requests.md @@ -1,5 +1,6 @@ --- redirect_to: '../../user/project/merge_requests/index.md' +remove_date: '2021-08-13' --- This document was moved to [another location](../../user/project/merge_requests/index.md). diff --git a/doc/topics/git/numerous_undo_possibilities_in_git/img/rebase_reset.png b/doc/topics/git/numerous_undo_possibilities_in_git/img/rebase_reset.png Binary files differindex 6506de209f4..c1a67e0b566 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/img/rebase_reset.png +++ b/doc/topics/git/numerous_undo_possibilities_in_git/img/rebase_reset.png diff --git a/doc/topics/git/numerous_undo_possibilities_in_git/img/revert.png b/doc/topics/git/numerous_undo_possibilities_in_git/img/revert.png Binary files differindex 040f8118d72..0732a73278b 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/img/revert.png +++ b/doc/topics/git/numerous_undo_possibilities_in_git/img/revert.png 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 b151ddfff71..6de62897041 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -36,7 +36,7 @@ You can undo changes at any point in this workflow: - [When you're working locally](#undo-local-changes) and haven't yet pushed to a remote repository. - When you have already pushed to a remote repository and you want to: - [Keep the history intact](#undo-remote-changes-without-changing-history) (preferred). - - [Change the history](#undo-remote-changes-with-modifying-history) (requires + - [Change the history](#undo-remote-changes-while-changing-history) (requires coordination with team and force pushes). ## Undo local changes @@ -139,6 +139,12 @@ If you want to change to another branch, you can use [`git stash`](https://www.g 1. Commit, push, and test. 1. Return to the branch where you want to resume your changes. 1. Use `git stash list` to list all previously stashed commits. + + ```shell + stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation + stash@{1}: On master: 9cc0589... Add git-stash + ``` + 1. Run a version of `git stash`: - Use `git stash pop` to redo previously stashed changes and remove them from stashed list. @@ -146,7 +152,7 @@ If you want to change to another branch, you can use [`git stash`](https://www.g ## Undo committed local changes -When you commit to your local repository (`git commit`), the version control system records +When you commit to your local repository (`git commit`), Git records your changes. Because you did not push to a remote repository yet, your changes are not public (or shared with other developers). At this point, you can undo your changes. @@ -212,64 +218,53 @@ which clashes with what other developers have locally. ### Undo staged local changes with history modification -You can rewrite history in Git, but you should avoid it, because it can cause problems -when multiple developers are contributing to the same codebase. - -There is one command for history modification and that is `git rebase`. Command -provides interactive mode (`-i` flag) which enables you to: +The following tasks rewrite Git history. -- **reword** commit messages (there is also `git commit --amend` for editing - last commit message). -- **edit** the commit content (changes introduced by commit) and message. -- **squash** multiple commits into a single one, and have a custom or aggregated - commit message. -- **drop** commits - delete them. -- and few more options. +#### Delete a specific commit -Let us check few examples. Again there are commits `A-B-C-D` where you want to -delete commit `B`. +You can delete a specific commit. For example, if you have +commits `A-B-C-D` and you want to delete commit `B`. -- Rebase the range from current commit D to A: +1. Rebase the range from current commit `D` to `B`: - ```shell - git rebase -i A - ``` + ```shell + git rebase -i A + ``` -- Command opens your favorite editor where you write `drop` in front of commit - `B`, but you leave default `pick` with all other commits. Save and exit the - editor to perform a rebase. Remember: if you want to cancel delete whole - file content before saving and exiting the editor + A list of commits is displayed in your editor. -In case you want to modify something introduced in commit `B`. +1. In front of commit `B`, replace `pick` with `drop`. +1. Leave the default, `pick`, for all other commits. +1. Save and exit the editor. -- Rebase the range from current commit D to A: +#### Modify a specific commit - ```shell - git rebase -i A - ``` +You can modify a specific commit. For example, if you have +commits `A-B-C-D` and you want to modify something introduced in commit `B`. -- Command opens your favorite text editor where you write `edit` in front of commit - `B`, but leave default `pick` with all other commits. Save and exit the editor to - perform a rebase. +1. Rebase the range from current commit `D` to `B`: -- Now do your edits and commit changes: + ```shell + git rebase -i A + ``` - ```shell - git commit -a - ``` + A list of commits is displayed in your editor. + +1. In front of commit `B`, replace `pick` with `edit`. +1. Leave the default, `pick`, for all other commits. +1. Save and exit the editor. +1. Open the file in your editor, make your edits, and commit the changes: -You can find some more examples in the section explaining -[how to modify history](#how-modifying-history-is-done). + ```shell + git commit -a + ``` ### Redoing the undo -Sometimes you realize that the changes you undid were useful and you want them -back. Well because of first paragraph you are in luck. Command `git reflog` -enables you to *recall* detached local commits by referencing or applying them -via commit ID. Although, do not expect to see really old commits in reflog, because -Git regularly [cleans the commits which are *unreachable* by branches or tags](https://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery). +You can recall previous local commits. However, not all previous commits are available, because +Git regularly [cleans the commits that are unreachable by branches or tags](https://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery). -To view repository history and to track older commits you can use below command: +To view repository history and track prior commits, run `git reflog show`. For example: ```shell $ git reflog show @@ -287,89 +282,64 @@ eb37e74 HEAD@{6}: rebase -i (pick): Commit C 6e43d59 HEAD@{16}: commit: Commit B ``` -Output of command shows repository history. In first column there is commit ID, -in following column, number next to `HEAD` indicates how many commits ago something -was made, after that indicator of action that was made (commit, rebase, merge, ...) -and then on end description of that action. +This output shows the repository history, including: -## Undo remote changes without changing history +- The commit SHA. +- How many `HEAD`-changing actions ago the commit was made (`HEAD@{12}` was 12 `HEAD`-changing actions ago). +- The action that was taken, for example: commit, rebase, merge. +- A description of the action that changed `HEAD`. -This topic is roughly same as modifying committed local changes without modifying -history. **It should be the preferred way of undoing changes on any remote repository -or public branch.** Keep in mind that branching is the best solution when you want -to retain the history of faulty development, yet start anew from certain point. +## Undo remote changes without changing history -Branching -enables you to include the existing changes in new development (by merging) and -it also provides a clear timeline and development structure. +To undo changes in the remote repository, you can create a new commit with the changes you +want to undo. You should follow this process, which preserves the history and +provides a clear timeline and development structure. However, you +only need this procedure if your work was merged into a branch that +other developers use as the base for their work.  -If you want to revert changes introduced in certain `commit-id`, you can -revert that `commit-id` (swap additions and deletions) in newly created commit: -You can do this with +To revert changes introduced in a specific commit `B`: ```shell -git revert commit-id +git revert B ``` -or creating a new branch: - -```shell -git checkout commit-id -git checkout -b new-path-of-feature -``` +## Undo remote changes while changing history -## Undo remote changes with modifying history +You can undo remote changes and change history. -This is useful when you want to *hide* certain things - like secret keys, -passwords, and SSH keys. It is and should not be used to hide mistakes, as -it makes it harder to debug in case there are some other bugs. The main -reason for this is that you loose the real development progress. Keep in -mind that, even with modified history, commits are just detached and can still be -accessed through commit ID - at least until all repositories perform -the automated cleanup of detached commits. +Even with an updated history, old commits can still be +accessed by commit SHA. This is the case at least until all the automated cleanup +of detached commits is performed, or a cleanup is run manually. Even the cleanup might not remove old commits if there are still refs pointing to them.  -### Where modifying history is generally acceptable +### When changing history is acceptable -Modified history breaks the development chain of other developers, as changed -history does not have matching commit IDs. For that reason it should not be -used on any public branch or on branch that might be used by other developers. -When contributing to big open source repositories (for example, [GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/CONTRIBUTING.md#contribution-acceptance-criteria) -itself), it is acceptable to squash commits into a single one, to present a -nicer history of your contribution. +You should not change the history when you're working in a public branch +or a branch that might be used by other developers. -Keep in mind that this also removes the comments attached to certain commits -in merge requests, so if you need to retain traceability in GitLab, then -modifying history is not acceptable. +When you contribute to large open source repositories, like [GitLab](https://gitlab.com/gitlab-org/gitlab), +you can squash your commits into a single one. -A feature branch of a merge request is a public branch and might be used by -other developers, but project process and rules might allow or require -you to use `git rebase` (command that changes history) to reduce number of -displayed commits on target branch after reviews are done (for example -GitLab). There is a `git merge --squash` command which does exactly that -(squashes commits on feature-branch to a single commit on target branch -at merge). +To squash commits on a feature branch to a single commit on a target branch +at merge, use `git merge --squash`. NOTE: -Never modify the commit history of `master` or shared branch. +Never modify the commit history of your [default branch](../../../user/project/repository/branches/default.md) or shared branch. -### How modifying history is done +### How to change history -After you know what you want to modify (how far in history or how which range of -old commits), use `git rebase -i commit-id`. This command displays all the commits from -current version to chosen commit ID and allow modification, squashing, deletion -of that commits. +A feature branch of a merge request is a public branch and might be used by +other developers. However, the project rules might require +you to use `git rebase` to reduce the number of +displayed commits on target branch after reviews are done. -```shell -$ git rebase -i commit1-id..commit3-id -pick <commit1-id> <commit1-commit-message> -pick <commit2-id> <commit2-commit-message> -pick <commit3-id> <commit3-commit-message> +You can modify history by using `git rebase -i`. Use this command to modify, squash, +and delete commits. -# Rebase commit1-id..commit3-id onto <commit4-id> (3 command(s)) +```shell # # Commands: # p, pick = use commit @@ -382,50 +352,48 @@ pick <commit3-id> <commit3-commit-message> # # These lines can be re-ordered; they are executed from top to bottom. # -# If you remove a line here THAT COMMIT WILL BE LOST. +# If you remove a line THAT COMMIT WILL BE LOST. # # However, if you remove everything, the rebase will be aborted. # -# Note that empty commits are commented out +# Empty commits are commented out ``` NOTE: -The comment from the output clearly states that, if -you decide to abort, don't just close your editor (as that -modifies history), but remove all uncommented lines and save. +If you decide to stop a rebase, do not close your editor. +Instead, remove all uncommented lines and save. -Use `git rebase` carefully on -shared and remote branches, but rest assured: nothing is broken until -you push back to the remote repository (so you can freely explore the -different outcomes locally). +Use `git rebase` carefully on shared and remote branches. +Experiment locally before you push to the remote repository. ```shell # Modify history from commit-id to HEAD (current commit) git rebase -i commit-id ``` -### Deleting sensitive information from commits +### Delete sensitive information from commits + +You can use Git to delete sensitive information from your past commits. However, +history is modified in the process. + +To rewrite history with +[certain filters](https://git-scm.com/docs/git-filter-branch#_options), +run `git filter-branch`. -Git also enables you to delete sensitive information from your past commits and -it does modify history in the progress. That is why we have included it in this -section and not as a standalone topic. To do so, you should run the -`git filter-branch`, which enables you to rewrite history with -[certain filters](https://git-scm.com/docs/git-filter-branch#_options). -This command uses rebase to modify history and if you want to remove certain -file from history altogether use: +To remove a file from the history altogether use: ```shell git filter-branch --tree-filter 'rm filename' HEAD ``` -Because `git filter-branch` command might be slow on big repositories, there are -tools that can use some of Git specifics to enable faster execution of common -tasks (which is exactly what removing sensitive information file is about). +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/). -Keep in mind that these tools are faster because they do not provide the same +These tools are faster because they do not provide the same feature set as `git filter-branch` does, but focus on specific use cases. -Refer [Reduce repository size](../../../user/project/repository/reducing_the_repo_size_using_git.md) page to know more about purging files from repository history & GitLab storage. +Refer to [Reduce repository size](../../../user/project/repository/reducing_the_repo_size_using_git.md) to +learn more about purging files from repository history and GitLab storage. <!-- ## Troubleshooting diff --git a/doc/topics/git/rollback_commits.md b/doc/topics/git/rollback_commits.md index 34c2d9687bb..478dce179d2 100644 --- a/doc/topics/git/rollback_commits.md +++ b/doc/topics/git/rollback_commits.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +stage: Create +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false --- -# Rollback Commits +# Rollback commits **(FREE)** ## Undo Commits diff --git a/doc/topics/git/stash.md b/doc/topics/git/stash.md index 051103e5f4b..d321795e034 100644 --- a/doc/topics/git/stash.md +++ b/doc/topics/git/stash.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +stage: Create +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false --- -# Git Stash +# Git Stash **(FREE)** We use `git stash` to store our changes when they are not ready to be committed and we need to change to a different branch. diff --git a/doc/topics/git/subtree.md b/doc/topics/git/subtree.md index 54461915a05..0bf89668405 100644 --- a/doc/topics/git/subtree.md +++ b/doc/topics/git/subtree.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +stage: Create +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false --- -# Subtree +# Subtree **(FREE)** - Used when there are nested repositories. - Not recommended when the amount of dependencies is too large. diff --git a/doc/topics/git/tags.md b/doc/topics/git/tags.md index 70580ecf778..6e0622273bb 100644 --- a/doc/topics/git/tags.md +++ b/doc/topics/git/tags.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Tags +# Tags **(FREE)** Tags are useful for marking certain deployments and releases for later reference. Git supports two types of tags: diff --git a/doc/topics/git/unstage.md b/doc/topics/git/unstage.md index 30d26854135..b5f7c01de24 100644 --- a/doc/topics/git/unstage.md +++ b/doc/topics/git/unstage.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +stage: Create +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false --- -# Unstage +# Unstage **(FREE)** - To remove files from stage use reset HEAD where HEAD is the last commit of the current branch. This unstages the file but maintain the modifications. diff --git a/doc/topics/git/useful_git_commands.md b/doc/topics/git/useful_git_commands.md index 38b44d97583..61f170d934a 100644 --- a/doc/topics/git/useful_git_commands.md +++ b/doc/topics/git/useful_git_commands.md @@ -180,12 +180,13 @@ Git includes a complete set of [traces for debugging Git commands](https://git-s ## Rebasing -### Rebase your branch onto master +### Rebase your branch onto the default -The `-i` flag stands for 'interactive': +The `-i` flag stands for 'interactive'. Replace `<default-branch>` with the name +of your [default branch](../../user/project/repository/branches/default.md): ```shell -git rebase -i master +git rebase -i <default-branch> ``` ### Continue the rebase if paused diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index c238951be51..df5029bb0d1 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -45,13 +45,13 @@ For a video introduction of how this works in GitLab, see [GitLab Flow](https:// <!-- vale gitlab.Spelling = YES --> Git flow was one of the first proposals to use Git branches, and it has received a lot of attention. -It suggests a `master` branch and a separate `develop` branch, as well as supporting branches for features, releases, and hotfixes. -The development happens on the `develop` branch, moves to a release branch, and is finally merged into the `master` branch. +It suggests a `main` branch and a separate `develop` branch, as well as supporting branches for features, releases, and hotfixes. +The development happens on the `develop` branch, moves to a release branch, and is finally merged into the `main` branch. Git flow is a well-defined standard, but its complexity introduces two problems. -The first problem is that developers must use the `develop` branch and not `master`. `master` is reserved for code that is released to production. -It is a convention to call your default branch `master` and to mostly branch from and merge to this. -Because most tools automatically use the `master` branch as the default, it is annoying to have to switch to another branch. +The first problem is that developers must use the `develop` branch and not `main`. `main` is reserved for code that is released to production. +It is a convention to call your default branch `main` and to mostly branch from and merge to this. +Because most tools automatically use the `main` branch as the default, it is annoying to have to switch to another branch. The second problem of Git flow is the complexity introduced by the hotfix and release branches. These branches can be a good idea for some organizations but are overkill for the vast majority of them. @@ -59,7 +59,7 @@ Nowadays, most organizations practice continuous delivery, which means that your Continuous delivery removes the need for hotfix and release branches, including all the ceremony they introduce. An example of this ceremony is the merging back of release branches. Though specialized tools do exist to solve this, they require documentation and add complexity. -Frequently, developers make mistakes such as merging changes only into `master` and not into the `develop` branch. +Frequently, developers make mistakes such as merging changes only into `main` and not into the `develop` branch. The reason for these errors is that Git flow is too complicated for most use cases. For example, many projects do releases but don't need to do hotfixes. @@ -68,10 +68,10 @@ For example, many projects do releases but don't need to do hotfixes.  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 `master` branch. +[GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `main` branch. 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 `master` branch and frequently deploying means you minimize the amount of unreleased code. This approach is in line with lean and continuous delivery best practices. +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. However, this flow still leaves a lot of questions unanswered regarding deployments, environments, releases, and integrations with issues. With GitLab flow, we offer additional guidance for these questions. @@ -88,7 +88,7 @@ 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 `master` into the production branch. +You can deploy a new version by merging `main` into the production branch. 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. @@ -99,16 +99,16 @@ This flow prevents the overhead of releasing, tagging, and merging that happens  -It might be a good idea to have an environment that is automatically updated to the `master` branch. +It might be a good idea to have an environment that is automatically updated to the `main` 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 `master` branch to staging. -To deploy to pre-production, create a merge request from the `master` branch to the pre-production branch. +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. 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 `master` 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 `main` with a merge request. In this case, do not delete the feature branch yet. -If `master` passes automatic testing, you then merge the feature branch into the other branches. +If `main` 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 @@ -117,15 +117,15 @@ If this is not possible because more manual testing is required, you can send me 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 `master` as a starting point, and branch as late as possible. +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. -If possible, first merge these bug fixes into `master`, and then cherry-pick them into the release branch. -If you start by merging into the release branch, you might forget to cherry-pick them into `master`, and then you'd encounter the same bug in subsequent releases. -Merging into `master` and then cherry-picking into release is called an "upstream first" policy, which is also practiced by [Google](https://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first) and [Red Hat](https://www.redhat.com/en/blog/a-community-for-using-openstack-with-red-hat-rdo). +If possible, first merge these bug fixes into `main`, and then cherry-pick them into the release branch. +If you start by merging into the release branch, you might forget to cherry-pick them into `main`, and then you'd encounter the same bug in subsequent releases. +Merging into `main` and then cherry-picking into release is called an "upstream first" policy, which is also practiced by [Google](https://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first) and [Red Hat](https://www.redhat.com/en/blog/a-community-for-using-openstack-with-red-hat-rdo). Every time you include a bug fix in a release branch, increase the patch version (to comply with [Semantic Versioning](https://semver.org/)) by setting a new tag. Some projects also have a stable branch that points to the same commit as the latest released branch. -In this flow, it is not common to have a production branch (or Git flow `master` branch). +In this flow, it is not common to have a production branch (or Git flow `main` branch). ## Merge/pull requests with GitLab flow @@ -151,8 +151,9 @@ Also, mention any other people from whom you would like feedback. After the assigned person feels comfortable with the result, they can merge the branch. If the assigned person does not feel comfortable, they can request more changes or close the merge request without merging. -In GitLab, it is common to protect the long-lived branches, such as the `master` branch, so [most developers can't modify them](../user/permissions.md). -So, if you want to merge into a protected branch, assign your merge request to someone with maintainer permissions. +In GitLab, it is common to protect the long-lived branches, such as the `main` branch, so [most developers can't modify them](../user/permissions.md). +So, if you want to merge into a protected branch, assign your merge request to someone with the +[Maintainer role](../user/permissions.md). After you merge a feature branch, you should remove it from the source control software. In GitLab, you can do this when merging. @@ -178,7 +179,7 @@ In many organizations, raising an issue is part of the development process becau The issue title should describe the desired state of the system. For example, the issue title "As an administrator, I want to remove users without receiving an error" is better than "Administrators can't remove users." -When you are ready to code, create a branch for the issue from the `master` branch. +When you are ready to code, create a branch for the issue from the `main` branch. This branch is the place for any work related to this change. NOTE: @@ -188,11 +189,11 @@ When you are done or want to discuss the code, open a merge request. A merge request is an online place to discuss the change and review the code. If you open the merge request but do not assign it to anyone, it is a [draft merge request](../user/project/merge_requests/drafts.md). -These are used to discuss the proposed implementation but are not ready for inclusion in the `master` branch yet. +These are used to discuss the proposed implementation but are not ready for inclusion in the `main` branch yet. Start the title of the merge request with `[Draft]`, `Draft:` or `(Draft)` to prevent it from being merged before it's ready. When you think the code is ready, assign the merge request to a reviewer. -The reviewer can merge the changes when they think the code is ready for inclusion in the `master` branch. +The reviewer can merge the changes when they think the code is ready for inclusion in the `main` branch. When they press the merge button, GitLab merges the code and creates a merge commit that makes this event visible later on. Merge requests always create a merge commit, even when the branch could be merged without one. This merge strategy is called "no fast-forward" in Git. @@ -247,18 +248,18 @@ Git does not allow you to merge the code again otherwise. 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 `master` branch. -Using rebase prevents a merge commit when merging `master` into your feature branch, and it creates a neat linear history. +Often, people avoid merge commits by just using rebase to reorder their commits after the commits on the `main` branch. +Using rebase prevents a merge commit when merging `main` into your feature branch, and it creates a neat linear history. However, as discussed in [the section about rebasing](#squashing-commits-with-rebase), you should avoid rebasing commits in a feature branch that you're sharing with others. Rebasing could create more work, as every time you rebase, you may need to resolve the same conflicts. Sometimes you can reuse recorded resolutions (`rerere`), but merging is better, because you only have to resolve conflicts once. Atlassian has a more thorough explanation of the tradeoffs between merging and rebasing [on their blog](https://www.atlassian.com/blog/git/git-team-workflows-merge-or-rebase). -A good way to prevent creating many merge commits is to not frequently merge `master` into the feature branch. -There are three reasons to merge in `master`: utilizing new code, resolving merge conflicts, and updating long-running branches. +A good way to prevent creating many merge commits is to not frequently merge `main` into the feature branch. +There are three reasons to merge in `main`: utilizing new code, resolving merge conflicts, and updating long-running branches. -If you need to use some code that was introduced in `master` after you created the feature branch, you can often solve this by just cherry-picking a commit. +If you need to use some code that was introduced in `main` after you created the feature branch, you can often solve this by just cherry-picking a commit. If your feature branch has a merge conflict, creating a merge commit is a standard way of solving this. @@ -272,9 +273,9 @@ Most feature branches should take less than one day of work. If your feature branches often take more than a day of work, try to split your features into smaller units of work. If you need to keep a feature branch open for more than a day, there are a few strategies to keep it up-to-date. -One option is to use continuous integration (CI) to merge in `master` at the start of the day. +One option is to use continuous integration (CI) to merge in `main` at the start of the day. Another option is to only merge in from well-defined points in time, for example, a tagged release. -You could also use [feature toggles](https://martinfowler.com/bliki/FeatureToggle.html) to hide incomplete features so you can still merge back into `master` every day. +You could also use [feature toggles](https://martinfowler.com/bliki/FeatureToggle.html) to hide incomplete features so you can still merge back into `main` every day. NOTE: Don't confuse automatic branch testing with continuous integration. @@ -327,26 +328,26 @@ Issue: gitlab.com/gitlab-org/gitlab/-/issues/1  -In old workflows, the continuous integration (CI) server commonly ran tests on the `master` branch only. -Developers had to ensure their code did not break the `master` branch. -When using GitLab flow, developers create their branches from this `master` branch, so it is essential that it never breaks. +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. Therefore, each merge request must be tested before it is accepted. CI software like Travis CI and GitLab CI/CD show the build results right in the merge request itself to simplify the process. There is one drawback to testing merge requests: the CI server only tests the feature branch itself, not the merged result. -Ideally, the server could also test the `master` branch after each change. -However, retesting on every commit to `master` is computationally expensive and means you are more frequently waiting for test results. +Ideally, the server could also test the `main` branch after each change. +However, retesting on every commit to `main` is computationally expensive and means you are more frequently waiting for test results. Because feature branches should be short-lived, testing just the branch is an acceptable risk. -If new commits in `master` cause merge conflicts with the feature branch, merge `master` back into the branch to make the CI server re-run the tests. +If new commits in `main` cause merge conflicts with the feature branch, merge `main` back into the branch to make the CI server re-run the tests. As said before, if you often have feature branches that last for more than a few days, you should make your issues smaller. ## Working with feature branches  -When creating a feature branch, always branch from an up-to-date `master`. +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. -If you have not pushed your commits to a shared location yet, you can also incorporate changes by rebasing on `master` or another feature branch. +If you have not pushed your commits to a shared location yet, you can also incorporate changes by rebasing on `main` or another feature branch. Do not merge from upstream again if your code can work and merge cleanly without doing so. -Merging only when needed prevents creating merge commits in your feature branch that later end up littering the `master` history. +Merging only when needed prevents creating merge commits in your feature branch that later end up littering the `main` history. diff --git a/doc/topics/plan_and_track.md b/doc/topics/plan_and_track.md new file mode 100644 index 00000000000..662898e88fc --- /dev/null +++ b/doc/topics/plan_and_track.md @@ -0,0 +1,28 @@ +--- +stage: +group: +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 +--- + +# Plan and track work **(FREE)** + +Plan your work by creating requirements, issues, and epics. Schedule work +with milestones and track your team's time. Learn how to save time with +quick actions, see how GitLab renders Markdown text, and learn how to +use Git to interact with GitLab. + +- [Epics](../user/group/epics/index.md) +- [Issues](../user/project/issues/index.md) +- [Labels](../user/project/labels.md) +- [Discussions](../user/discussions/index.md) +- [Iterations](../user/group/iterations/index.md) +- [Milestones](../user/project/milestones/index.md) +- [Requirements](../user/project/requirements/index.md) +- [Roadmaps](../user/group/roadmap/index.md) +- [Time tracking](../user/project/time_tracking.md) +- [Wikis](../user/project/wiki/index.md) +- [Keyboard shortcuts](../user/shortcuts.md) +- [Quick actions](../user/project/quick_actions.md) +- [Markdown](../user/markdown.md) +- [To-Do lists](../user/todos.md) +- [Using Git](../topics/git/index.md) diff --git a/doc/topics/release_your_application.md b/doc/topics/release_your_application.md new file mode 100644 index 00000000000..31eb7705760 --- /dev/null +++ b/doc/topics/release_your_application.md @@ -0,0 +1,13 @@ +--- +stage: +group: +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 +--- + +# Release your application **(FREE)** + +Release your application internally or to the public. Use +flags to release features incrementally. + +- [Releases](../user/project/releases/index.md) +- [Feature flags](../operations/feature_flags.md) diff --git a/doc/topics/set_up_organization.md b/doc/topics/set_up_organization.md new file mode 100644 index 00000000000..d8b1ab59b9e --- /dev/null +++ b/doc/topics/set_up_organization.md @@ -0,0 +1,16 @@ +--- +stage: +group: +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 +--- + +# Set up your organization **(FREE)** + +Configure your organization and its users. Determine user roles +and give everyone access to the projects they need. + +- [Members](../user/project/members/index.md) +- [Groups](../user/group/index.md) +- [User account options](../user/profile/index.md) +- [SSH keys](../ssh/README.md) +- [GitLab.com settings](../user/gitlab_com/index.md) diff --git a/doc/topics/use_gitlab.md b/doc/topics/use_gitlab.md new file mode 100644 index 00000000000..f45dc91131c --- /dev/null +++ b/doc/topics/use_gitlab.md @@ -0,0 +1,19 @@ +--- +stage: +group: +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 +--- + +# Use GitLab **(FREE)** + +Get to know the GitLab end-to-end workflow. Configure permissions, +organize your work, create and secure your application, and analyze its performance. Report on team productivity throughout the process. + +- [Set up your organization](set_up_organization.md) +- [Organize work with projects](../user/project/index.md) +- [Plan and track work](plan_and_track.md) +- [Build your application](build_your_application.md) +- [Secure your application](../user/application_security/index.md) +- [Release your application](release_your_application.md) +- [Monitor application performance](../operations/index.md) +- [Analyze GitLab usage](../user/analytics/index.md) |
