diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-12-17 11:59:07 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-12-17 11:59:07 +0000 |
| commit | 8b573c94895dc0ac0e1d9d59cf3e8745e8b539ca (patch) | |
| tree | 544930fb309b30317ae9797a9683768705d664c4 /doc/topics | |
| parent | 4b1de649d0168371549608993deac953eb692019 (diff) | |
| download | gitlab-ce-8b573c94895dc0ac0e1d9d59cf3e8745e8b539ca.tar.gz | |
Add latest changes from gitlab-org/gitlab@13-7-stable-eev13.7.0-rc42
Diffstat (limited to 'doc/topics')
29 files changed, 298 insertions, 239 deletions
diff --git a/doc/topics/application_development_platform/index.md b/doc/topics/application_development_platform/index.md index c38b067f1f3..f9baa8916df 100644 --- a/doc/topics/application_development_platform/index.md +++ b/doc/topics/application_development_platform/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Application Development Platform @@ -35,14 +35,14 @@ of newer, more efficient, more profitable, and less error-prone techniques for s Because at GitLab we are [cloud-native first](https://about.gitlab.com/handbook/product/#cloud-native-first) our Application Development Platform initially focuses on providing robust support for Kubernetes, with other platforms -to follow. Teams can bring their own clusters and we will additionally make it easy to create new infrastructure +to follow. Teams can bring their own clusters and we additionally make it easy to create new infrastructure with various cloud providers. ### Build, test, deploy -In order to provide modern DevOps workflows, our Application Development Platform will rely on +In order to provide modern DevOps workflows, our Application Development Platform relies on [Auto DevOps](../autodevops/index.md) to provide those workflows. Auto DevOps works with -any Kubernetes cluster; you're not limited to running on GitLab's infrastructure. Additionally, Auto DevOps offers +any Kubernetes cluster; you're not limited to running on GitLab infrastructure. Additionally, Auto DevOps offers an incremental consumption path. Because it is [composable](../autodevops/customize.md#using-components-of-auto-devops), you can use as much or as little of the default pipeline as you'd like, and deeply customize without having to integrate a completely different platform. diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 8a876e07791..0e51042193c 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Authentication diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 95b6241583f..0d4f86f1284 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -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/#designated-technical-writers +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 --- # Customizing Auto DevOps @@ -38,7 +38,7 @@ For example: ### Multiple buildpacks Using multiple buildpacks is not fully supported by Auto DevOps, because Auto Test -won't work when using the `.buildpacks` file. The buildpack +can't use the `.buildpacks` file. The buildpack [heroku-buildpack-multi](https://github.com/heroku/heroku-buildpack-multi/), used in the backend to parse the `.buildpacks` file, does not provide the necessary commands `bin/test-compile` and `bin/test`. @@ -78,7 +78,7 @@ Use Base64 encoding if you need to pass complex values, such as newlines and spaces. Left unencoded, complex values like these can cause escaping issues due to how Auto DevOps uses the arguments. -CAUTION: **Warning:** +WARNING: Avoid passing secrets as Docker build arguments if possible, as they may be persisted in your image. See [this discussion of best practices with secrets](https://github.com/moby/moby/issues/13490) for details. @@ -133,7 +133,7 @@ You can override the Helm chart used by bundling up a chart into your project repository or by specifying a project variable: - **Bundled chart** - If your project has a `./chart` directory with a `Chart.yaml` - file in it, Auto DevOps will detect the chart and use it instead of the + file in it, Auto DevOps detects the chart and uses it instead of the [default chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app), enabling you to control exactly how your application is deployed. - **Project variable** - Create a [project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables) @@ -143,7 +143,7 @@ repository or by specifying a project variable: ## Customize values for Helm Chart -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30628) in GitLab 12.6, `.gitlab/auto-deploy-values.yaml` will be used by default for Helm upgrades. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30628) in GitLab 12.6, `.gitlab/auto-deploy-values.yaml` is used by default for Helm upgrades. You can override the default values in the `values.yaml` file in the [default Helm chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app) by either: @@ -154,7 +154,7 @@ You can override the default values in the `values.yaml` file in the `HELM_UPGRADE_VALUES_FILE` [environment variable](#environment-variables) with the path and name. -NOTE: **Note:** +NOTE: For GitLab 12.5 and earlier, use the `HELM_UPGRADE_EXTRA_ARGS` environment variable to override the default chart values by setting `HELM_UPGRADE_EXTRA_ARGS` to `--values <my-values.yaml>`. @@ -190,7 +190,7 @@ include: - template: Auto-DevOps.gitlab-ci.yml ``` -Add your changes, and your additions will be merged with the +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) using the behavior described for [`include`](../../ci/yaml/README.md#include). @@ -243,9 +243,9 @@ include: 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. -CAUTION: **Deprecation:** +WARNING: Auto DevOps templates using the [`only`](../../ci/yaml/README.md#onlyexcept-basic) or -[`except`](../../ci/yaml/README.md#onlyexcept-basic) syntax will switch +[`except`](../../ci/yaml/README.md#onlyexcept-basic) syntax have switched to the [`rules`](../../ci/yaml/README.md#rules) syntax, starting in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213336). If your `.gitlab-ci.yml` extends these Auto DevOps templates and override the `only` or @@ -268,7 +268,7 @@ postgres://user:password@postgres-host:postgres-port/postgres-database ### Upgrading PostgresSQL -CAUTION: **Deprecation:** +WARNING: The variable `AUTO_DEVOPS_POSTGRES_CHANNEL` that controls default provisioned PostgreSQL was changed to `2` in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/210499). To keep using the old PostgreSQL, set the `AUTO_DEVOPS_POSTGRES_CHANNEL` variable to @@ -295,12 +295,12 @@ You must define environment-scoped variables for `POSTGRES_ENABLED` and 1. Disable the built-in PostgreSQL installation for the required environments using scoped [environment variables](../../ci/environments/index.md#scoping-environments-with-specs). - For this use case, it's likely that only `production` will need to be added to this + For this use case, it's likely that only `production` must be added to this list. The built-in PostgreSQL setup for Review Apps and staging is sufficient.  -1. Define the `DATABASE_URL` CI variable as a scoped environment variable that will be +1. Define the `DATABASE_URL` CI variable as a scoped environment variable that is available to your application. This should be a URL in the following format: ```yaml @@ -328,14 +328,14 @@ applications. | `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_EXTRA_ARGS` | Extra arguments to be passed to the `docker build` command. Note that using quotes won't prevent word splitting. [More details](#passing-arguments-to-docker-build). | +| `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 variable names](#forward-ci-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). | | `AUTO_DEVOPS_CHART_REPOSITORY` | Helm Chart repository used to search for charts. Defaults to `https://charts.gitlab.io`. | | `AUTO_DEVOPS_CHART_REPOSITORY_NAME` | From GitLab 11.11, used to set the name of the Helm repository. Defaults to `gitlab`. | | `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME` | From GitLab 11.11, used to set a username to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD`. | | `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 will output debug logs. | +| `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). | @@ -345,9 +345,9 @@ applications. | `DOCKERFILE_PATH` | From GitLab 13.2, allows overriding the [default Dockerfile path for the build stage](#custom-dockerfile) | | `HELM_RELEASE_NAME` | From GitLab 12.1, allows the `helm` release name to be overridden. Can be used to assign unique release names when deploying multiple projects to a single namespace. | | `HELM_UPGRADE_VALUES_FILE` | From GitLab 12.6, allows the `helm upgrade` values file to be overridden. Defaults to `.gitlab/auto-deploy-values.yaml`. | -| `HELM_UPGRADE_EXTRA_ARGS` | From GitLab 11.11, allows extra options in `helm upgrade` commands when deploying the application. Note that using quotes won't prevent word splitting. | +| `HELM_UPGRADE_EXTRA_ARGS` | From GitLab 11.11, allows extra options in `helm upgrade` commands when deploying the application. Note that using quotes doesn't prevent word splitting. | | `INCREMENTAL_ROLLOUT_MODE` | From GitLab 11.4, if present, can be used to enable an [incremental rollout](#incremental-rollout-to-production) of your application for the production environment. Set to `manual` for manual deployment jobs or `timed` for automatic rollout deployments with a 5 minute delay each one. | -| `K8S_SECRET_*` | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) will be made available by Auto DevOps as environment variables to the deployed application. | +| `K8S_SECRET_*` | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) is made available by Auto DevOps as environment variables to the deployed application. | | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/index.md#base-domain) for more information. | | `PRODUCTION_REPLICAS` | Number of replicas to deploy in the production environment. Takes precedence over `REPLICAS` and defaults to 1. For zero downtime upgrades, set to 2 or greater. | | `REPLICAS` | Number of replicas to deploy. Defaults to 1. | @@ -355,12 +355,12 @@ applications. | `ROLLOUT_STATUS_DISABLED` | From GitLab 12.0, used to disable rollout status check because it does not support all resource types, for example, `cronjob`. | | `STAGING_ENABLED` | From GitLab 10.8, used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). | -TIP: **Tip:** +NOTE: After you set up your replica variables using a [project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables), you can scale your application by redeploying it. -CAUTION: **Caution:** +WARNING: You should *not* scale your application using Kubernetes directly. This can cause confusion with Helm not detecting the change, and subsequent deploys with Auto DevOps can undo your changes. @@ -377,26 +377,56 @@ The following table lists variables related to the database. | `POSTGRES_USER` | The PostgreSQL user. Defaults to `user`. Set it to use a custom username. | | `POSTGRES_PASSWORD` | The PostgreSQL password. Defaults to `testing-password`. Set it to use a custom password. | | `POSTGRES_DB` | The PostgreSQL database name. Defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-environment-variables). Set it to use a custom database name. | -| `POSTGRES_VERSION` | Tag for the [`postgres` Docker image](https://hub.docker.com/_/postgres) to use. Defaults to `9.6.16` for tests and deployments as of GitLab 13.0 (previously `9.6.2`). If `AUTO_DEVOPS_POSTGRES_CHANNEL` is set to `1`, deployments will use the default version `9.6.2`. | +| `POSTGRES_VERSION` | Tag for the [`postgres` Docker image](https://hub.docker.com/_/postgres) to use. Defaults to `9.6.16` for tests and deployments as of GitLab 13.0 (previously `9.6.2`). If `AUTO_DEVOPS_POSTGRES_CHANNEL` is set to `1`, deployments uses the default version `9.6.2`. | ### Disable jobs The following table lists variables used to disable jobs. -| **Variable** | **Description** | -|-----------------------------------------|------------------------------------| -| `CODE_QUALITY_DISABLED` | From GitLab 11.0, used to disable the `codequality` job. If the variable is present, the job won't be created. | -| `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0, used to disable the `sast:container` job. If the variable is present, the job won't be created. | -| `DAST_DISABLED` | From GitLab 11.0, used to disable the `dast` job. If the variable is present, the job won't be created. | -| `DEPENDENCY_SCANNING_DISABLED` | From GitLab 11.0, used to disable the `dependency_scanning` job. If the variable is present, the job won't be created. | -| `LICENSE_MANAGEMENT_DISABLED` | From GitLab 11.0, used to disable the `license_management` job. If the variable is present, the job won't be created. | -| `PERFORMANCE_DISABLED` | From GitLab 11.0, used to disable the browser `performance` job. If the variable is present, the job won't be created. | -| `LOAD_PERFORMANCE_DISABLED` | From GitLab 13.2, used to disable the `load_performance` job. If the variable is present, the job won't be created. | -| `REVIEW_DISABLED` | From GitLab 11.0, used to disable the `review` and the manual `review:stop` job. If the variable is present, these jobs won't be created. | -| `SAST_DISABLED` | From GitLab 11.0, used to disable the `sast` job. If the variable is present, the job won't be created. | -| `TEST_DISABLED` | From GitLab 11.0, used to disable the `test` job. If the variable is present, the job won't be created. | -| `SECRET_DETECTION_DISABLED` | From GitLab 13.1, used to disable the `secret_detection` job. If the variable is present, the job won't be created. | -| `CODE_INTELLIGENCE_DISABLED` | From GitLab 13.6, used to disable the `code_intelligence` job. If the variable is present, the job won't be created. | +| **Job Name** | **Variable** | **GitLab version** | **Description** | +|----------------------------------------|---------------------------------|-----------------------|-----------------| +| `.fuzz_base` | `COVFUZZ_DISABLED` | [From GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34984) | [Read more](../../user/application_security/coverage_fuzzing/) about how `.fuzz_base` provide capability for your own jobs. If the variable is present, your jobs aren't created. | +| `apifuzzer_fuzz` | `API_FUZZING_DISABLED` | [From GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39135) | If the variable is present, the job isn't created. | +| `bandit-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `brakeman-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `bundler-audit-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `canary` | `CANARY_ENABLED` | | This manual job is created if the variable is present. | +| `code_intelligence` | `CODE_INTELLIGENCE_DISABLED` | From GitLab 13.6 | If the variable is present, the job isn't created. | +| `codequality` | `CODE_QUALITY_DISABLED` | Until GitLab 11.0 | If the variable is present, the job isn't created. | +| `code_quality` | `CODE_QUALITY_DISABLED` | [From GitLab 11.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5773) | If the variable is present, the job isn't created. | +| `container_scanning` | `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `dast` | `DAST_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `dast_environment_deploy` | `DAST_DISABLED_FOR_DEFAULT_BRANCH` or `DAST_DISABLED` | [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17789) | If either variable is present, the job isn't created. | +| `dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `eslint-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `flawfinder-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `gemnasium-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `gemnasium-maven-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `gemnasium-python-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `gosec-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `kubesec-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `license_management` | `LICENSE_MANAGEMENT_DISABLED` | GitLab 11.0 to 12.7 | If the variable is present, the job isn't created. Job deprecated [from GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | +| `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. | +| `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. | +| `review` | `REVIEW_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `review:stop` | `REVIEW_DISABLED` | From GitLab 11.0 | Manual job. If the variable is present, the job isn't created. | +| `sast` | `SAST_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `sast:container` | `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `secret_detection` | `SECRET_DETECTION_DISABLED` | From GitLab 13.1 | If the variable is present, the job isn't created. | +| `secret_detection_default_branch` | `SECRET_DETECTION_DISABLED` | [From GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | If the variable is present, the job isn't created. | +| `security-code-scan-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `secrets-sast` | `SAST_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `sobelaw-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `stop_dast_environment` | `DAST_DISABLED_FOR_DEFAULT_BRANCH` or `DAST_DISABLED` | [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17789) | If either variable is present, the job isn't created. | +| `spotbugs-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `test` | `TEST_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `staging` | `STAGING_ENABLED` | | The job is created if the variable is present. | +| `stop_review` | `REVIEW_DISABLED` | | If the variable is present, the job isn't created. | ### Application secret variables @@ -418,7 +448,7 @@ To configure your application variables: 1. Run an Auto DevOps pipeline, either by manually creating a new pipeline or by pushing a code change to GitLab. -Auto DevOps pipelines will take your application secret variables to +Auto DevOps pipelines take your application secret variables to populate a Kubernetes secret. This secret is unique per environment. When deploying your application, the secret is loaded as environment variables in the container running the application. Following the @@ -444,7 +474,7 @@ type: Opaque Environment variables are generally considered immutable in a Kubernetes pod. If you update an application secret without changing any code, then manually -create a new pipeline, you will find any running application pods won't have +create a new pipeline, any running application pods don't receive the updated secrets. To update the secrets, either: - Push a code update to GitLab to force the Kubernetes deployment to recreate pods. @@ -465,7 +495,7 @@ enabling you to define your own variables for scaling the pod's replicas: - `TRACK`: The capitalized value of the `track` [Kubernetes label](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) - in the Helm Chart app definition. If not set, it won't be taken into account + in the Helm Chart app definition. If not set, it isn't taken into account to the variable name. - `ENV`: The capitalized environment name of the deploy job, set in `.gitlab-ci.yml`. @@ -508,7 +538,7 @@ service: > [Introduced](https://gitlab.com/gitlab-org/gitlab-ci-yml/-/merge_requests/160) in GitLab 10.8. -TIP: **Tip:** +NOTE: You can also set this inside your [project's settings](index.md#deployment-strategy). The normal behavior of Auto DevOps is to use continuous deployment, pushing @@ -537,7 +567,7 @@ If you define `CANARY_ENABLED` with a non-empty value, then two manual jobs are > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5415) in GitLab 10.8. -TIP: **Tip:** +NOTE: You can also set this inside your [project's settings](index.md#deployment-strategy). When you're ready to deploy a new version of your app to production, you may want @@ -547,7 +577,7 @@ check how the application is behaving before manually increasing the rollout up If `INCREMENTAL_ROLLOUT_MODE` is set to `manual` in your project, then instead of the standard `production` job, 4 different [manual jobs](../../ci/pipelines/index.md#add-manual-interaction-to-your-pipeline) -will be created: +are created: 1. `rollout 10%` 1. `rollout 25%` @@ -556,7 +586,7 @@ will be created: The percentage is based on the `REPLICAS` variable, and defines the number of pods you want to have for your deployment. If the value is `10`, and you run the -`10%` rollout job, there will be `1` new pod + `9` old ones. +`10%` rollout job, there is `1` new pod and `9` old ones. To start a job, click the play icon (**{play}**) next to the job's name. You're not required to go from `10%` to `100%`, you can jump to whatever job you want. @@ -566,7 +596,7 @@ back by redeploying the old version using the [rollback button](../../ci/environments/index.md#retrying-and-rolling-back) in the environment page. -Below, you can see how the pipeline will look if the rollout or staging +Below, you can see how the pipeline appears if the rollout or staging variables are defined. Without `INCREMENTAL_ROLLOUT_MODE` and without `STAGING_ENABLED`: @@ -585,16 +615,16 @@ With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and with `STAGING_ENABLED`  -CAUTION: **Caution:** +WARNING: Before GitLab 11.4, the presence of the `INCREMENTAL_ROLLOUT_ENABLED` environment -variable enabled this feature. This configuration is deprecated, and will be +variable enabled this feature. This configuration is deprecated, and is scheduled to be removed in the future. ### Timed incremental rollout to production **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7545) in GitLab 11.4. -TIP: **Tip:** +NOTE: You can also set this inside your [project's settings](index.md#deployment-strategy). This configuration is based on @@ -632,5 +662,5 @@ The banner can be disabled for: - Through the REST API with an admin access token: ```shell - curl --data "value=true" --header "PRIVATE-TOKEN: <personal_access_token>" https://gitlab.example.com/api/v4/features/auto_devops_banner_disabled + curl --data "value=true" --header "PRIVATE-TOKEN: <personal_access_token>" "https://gitlab.example.com/api/v4/features/auto_devops_banner_disabled" ``` diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 014690c4cdf..7234bca8e12 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -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/#designated-technical-writers +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 --- # Auto DevOps @@ -38,18 +38,21 @@ For requirements, see [Requirements for Auto DevOps](requirements.md) for more i > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41729) in GitLab 11.3. -Auto DevOps is enabled by default for all projects and attempts to run on all pipelines -in each project. An instance administrator can enable or disable this default in the +On self-managed instances, Auto DevOps is enabled by default for all projects. +It attempts to run on all pipelines in each project. An instance administrator can +enable or disable this default in the [Auto DevOps settings](../../user/admin_area/settings/continuous_integration.md#auto-devops). Auto DevOps automatically disables in individual projects on their first pipeline failure, -if it has not been explicitly enabled for the project. + +NOTE: +Auto DevOps is not enabled by default on GitLab.com. Since [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/26655), Auto DevOps runs on pipelines automatically only if a [`Dockerfile` or matching buildpack](stages.md#auto-build) exists. If a [CI/CD configuration file](../../ci/yaml/README.md) is present in the project, -it will continue to be used, whether or not Auto DevOps is enabled. +it continues to be used, whether or not Auto DevOps is enabled. ## Quick start @@ -73,7 +76,7 @@ innovative work done by [Heroku](https://www.heroku.com/) and goes beyond it in multiple ways: - Auto DevOps works with any Kubernetes cluster; you're not limited to running - on GitLab's infrastructure. (Note that many features also work without Kubernetes). + on infrastructure managed by GitLab. (Note that many features also work without Kubernetes). - There is no additional cost (no markup on the infrastructure costs), and you can use a Kubernetes cluster you host or Containers as a Service on any public cloud (for example, [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/)). @@ -85,6 +88,9 @@ in multiple ways: ## Features +NOTE: +Depending on your target platform, some features might not be available to you. + Comprised of a set of [stages](stages.md), Auto DevOps brings these best practices to your project in a simple and automatic way: @@ -120,7 +126,7 @@ Auto DevOps provides great defaults for all the stages and makes use of For an overview on the creation of Auto DevOps, read more [in this blog post](https://about.gitlab.com/blog/2017/06/29/whats-next-for-gitlab-ci/). -NOTE: **Note:** +NOTE: Kubernetes clusters can [be used without](../../user/project/clusters/index.md) Auto DevOps. @@ -146,14 +152,14 @@ any of the following places: The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence as other environment [variables](../../ci/variables/README.md#priority-of-environment-variables). If the CI/CD variable is not set and the cluster setting is left blank, the instance-wide **Auto DevOps domain** -setting will be used if set. +setting is used if set. -TIP: **Tip:** +NOTE: If you use the [GitLab managed app for Ingress](../../user/clusters/applications.md#ingress), the URL endpoint should be automatically configured for you. All you must do is use its value for the `KUBE_INGRESS_BASE_DOMAIN` variable. -NOTE: **Note:** +NOTE: `AUTO_DEVOPS_DOMAIN` was [deprecated in GitLab 11.8](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52363) and replaced with `KUBE_INGRESS_BASE_DOMAIN`, and removed in [GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56959). @@ -236,7 +242,7 @@ Auto DevOps at the group and project level, respectively. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0. -You can change the deployment strategy used by Auto DevOps by going to your +You can change the deployment strategy used by Auto DevOps by visiting your project's **Settings > CI/CD > Auto DevOps**. The following options are available: @@ -254,7 +260,7 @@ are available: - `master` branch is directly deployed to staging. - Manual actions are provided for incremental rollout to production. -TIP: **Tip:** +NOTE: Use the [blue-green deployment](../../ci/environments/incremental_rollouts.md#blue-green-deployment) technique to minimize downtime and risk. @@ -313,7 +319,7 @@ simplify configuration and prevent any unforeseen issues. ### Install applications behind a proxy -GitLab's Helm integration does not support installing applications when +The GitLab integration with Helm does not support installing applications when behind a proxy. Users who want to do so must inject their proxy settings into the installation pods at runtime, such as by using a [`PodPreset`](https://kubernetes.io/docs/concepts/workloads/pods/podpreset/): @@ -372,7 +378,7 @@ To fix this issue, you must either: ### Failure to create a Kubernetes namespace -Auto Deploy will fail if GitLab can't create a Kubernetes namespace and +Auto Deploy fails if GitLab can't create a Kubernetes namespace and service account for your project. For help debugging this issue, see [Troubleshooting failed deployment jobs](../../user/project/clusters/index.md#troubleshooting). @@ -407,7 +413,7 @@ If you receive this error, you can do one of the following actions: database by setting `AUTO_DEVOPS_POSTGRES_DELETE_V1` to a non-empty value and redeploying. - DANGER: **Warning:** + WARNING: Deleting the channel 1 PostgreSQL database permanently deletes the existing channel 1 database and all its data. See [Upgrading PostgreSQL](upgrading_postgresql.md) @@ -421,7 +427,7 @@ If you receive this error, you can do one of the following actions: and persisted by Helm, regardless of whether or not your chart uses the variable. -DANGER: **Warning:** +WARNING: Setting `POSTGRES_ENABLED` to `false` permanently deletes any existing channel 1 database for your environment. @@ -476,7 +482,7 @@ that works for this problem. Follow these steps to use the tool in Auto DevOps: ### Error: error initializing: Looks like "https://kubernetes-charts.storage.googleapis.com" is not a valid chart repository or cannot be reached As [announced in the official CNCF blogpost](https://www.cncf.io/blog/2020/10/07/important-reminder-for-all-helm-users-stable-incubator-repos-are-deprecated-and-all-images-are-changing-location/), -the stable Helm chart repository will be deprecated and removed on November 13th, 2020. +the stable Helm chart repository was deprecated and removed on November 13th, 2020. You may encounter this error after that date. Some GitLab features had dependencies on the stable chart. To mitigate the impact, we changed them @@ -495,7 +501,7 @@ include: image: "registry.gitlab.com/gitlab-org/cluster-integration/auto-deploy-image:v1.0.5" ``` -Keep in mind that this approach will eventually stop working when the stable repository is removed, +Keep in mind that this approach stops working when the stable repository is removed, so you must eventually fix your custom chart. To fix your custom chart: diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 3531035eb67..5c3b296fdea 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -1,20 +1,20 @@ --- stage: Configure group: Configure -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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Getting started with Auto DevOps -This step-by-step guide will help you use [Auto DevOps](index.md) to +This step-by-step guide helps you use [Auto DevOps](index.md) to deploy a project hosted on GitLab.com to Google Kubernetes Engine. -You will use GitLab's native Kubernetes integration, so you won't need +You are using the GitLab native Kubernetes integration, so you don't need to create a Kubernetes cluster manually using the Google Cloud Platform console. -You will create and deploy a simple application that you create from a GitLab template. +You are creating and deploying a simple application that you create from a GitLab template. -These instructions will also work for a self-managed GitLab instance; you'll just -need to ensure your own [runners are configured](../../ci/runners/README.md) and +These instructions also work for a self-managed GitLab instance; +ensure your own [runners are configured](../../ci/runners/README.md) and [Google OAuth is enabled](../../integration/google.md). ## Configure your Google account @@ -29,16 +29,16 @@ or Google Drive, or create a new one. 1. Ensure you've created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) with Google Cloud Platform. -TIP: **Tip:** +NOTE: Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial), and in partnership with Google, GitLab is able to offer an additional $200 for new -GCP accounts to get started with GitLab's Google Kubernetes Engine Integration. +GCP accounts to get started with the GitLab integration with Google Kubernetes Engine. [Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) and apply for credit. ## Create a new project from a template -We will use one of GitLab's project templates to get started. As the name suggests, +We are using a GitLab project template to get started. As the name suggests, those projects provide a bare-bones application built on some well-known frameworks. 1. In GitLab, click the plus icon (**{plus-square}**) at the top of the navigation bar, and select @@ -57,7 +57,7 @@ those projects provide a bare-bones application built on some well-known framewo 1. Click **Create project**. -Now that you've created a project, you'll next create the Kubernetes cluster +Now that you've created a project, create the Kubernetes cluster to deploy this project to. ## Create a Kubernetes cluster from within GitLab @@ -98,30 +98,30 @@ to deploy this project to. 1. Click **Create Kubernetes cluster**. -After a couple of minutes, the cluster will be created. You can also see its +After a couple of minutes, the cluster is created. You can also see its status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). -Next, you will install some applications on your cluster that are needed +Next, install some applications on your cluster that are needed to take full advantage of Auto DevOps. ## Install Ingress and Prometheus -After your cluster is running, you can install your first applications. -In this guide, we will install Ingress and Prometheus: +After your cluster is running, you can install your first applications, +Ingress and Prometheus: - Ingress - Provides load balancing, SSL termination, and name-based virtual hosting, using NGINX behind the scenes. - Prometheus - An open-source monitoring and alerting system used to supervise the deployed application. -We won't install GitLab Runner in this quick start guide, as this guide uses the +We aren't installing GitLab Runner in this quick start guide, as this guide uses the shared runners provided by GitLab.com. To install the applications: - Click the **Install** button for **Ingress**. - When the **Ingress Endpoint** is displayed, copy the IP address. -- Add your **Base domain**. For this guide, we will use the domain suggested by GitLab. +- Add your **Base domain**. For this guide, use the domain suggested by GitLab. - Click **Save changes**.  @@ -221,7 +221,7 @@ Kubernetes cluster, color-coded to show their status. Hovering over a square on the deploy board displays the state of the deployment, and clicking the square takes you to the pod's logs page. -TIP: **Tip:** +NOTE: The example shows only one pod hosting the application at the moment, but you can add more pods by defining the [`REPLICAS` variable](customize.md#environment-variables) in **Settings > CI/CD > Environment variables**. @@ -251,7 +251,7 @@ a few more that run only on branches other than `master`.  -After a few minutes you'll notice a test failed, which means a test was +After a few minutes a test fails, which means a test was 'broken' by your change. Click on the failed `test` job to see more information about it: diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index acec7b79d6b..824874ed4d4 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -1,13 +1,14 @@ --- stage: Configure group: Configure -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/#designated-technical-writers +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 --- # Requirements for Auto DevOps -You can set up Auto DevOps for [Kubernetes](#auto-devops-requirements-for-kubernetes) -or [Amazon Elastic Container Service (ECS)](#auto-devops-requirements-for-amazon-ecs). +You can set up Auto DevOps for [Kubernetes](#auto-devops-requirements-for-kubernetes), +[Amazon Elastic Container Service (ECS)](#auto-devops-requirements-for-amazon-ecs), +or [Amazon Cloud Compute](#auto-devops-requirements-for-amazon-ecs). For more information about Auto DevOps, see [the main Auto DevOps page](index.md) or the [quick start guide](quick_start_guide.md). @@ -27,15 +28,15 @@ To make full use of Auto DevOps with Kubernetes, you need: [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 GitLab's Kubernetes integration in the previous step. + 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. - NOTE: **Note:** - If you use your own Ingress instead of the one provided by GitLab's managed - apps, ensure you're running at least version 0.9.0 of NGINX Ingress and + 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 [annotate](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) @@ -46,7 +47,7 @@ To make full use of Auto DevOps with Kubernetes, you need: [Auto Deploy](stages.md#auto-deploy), and [Auto Monitoring](stages.md#auto-monitoring)) You need a domain configured with wildcard DNS, which all of your Auto DevOps - applications will use. If you're using the + applications use. If you're using the [GitLab-managed app for Ingress](../../user/clusters/applications.md#ingress), the URL endpoint is automatically configured for you. @@ -63,7 +64,7 @@ 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 GitLab's Kubernetes integration in the first step, you + 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). @@ -76,7 +77,7 @@ To make full use of Auto DevOps with Kubernetes, you need: 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 GitLab's Kubernetes integration, you can deploy it to + 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). @@ -94,8 +95,8 @@ To make full use of Auto DevOps with Kubernetes, you need: 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 GitLab's Kubernetes - integration, you can deploy it to your cluster by installing 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). If you don't have Kubernetes or Prometheus installed, then @@ -111,7 +112,7 @@ After all requirements are met, you can [enable Auto DevOps](index.md#enablingdi You can choose to target [AWS ECS](../../ci/cloud_deployment/index.md) as a deployment platform instead of using Kubernetes. -To get started on Auto DevOps to AWS ECS, you'll have to add a specific Environment +To get started on Auto DevOps to AWS ECS, you must add a specific Environment Variable. To do so, follow these steps: 1. In your project, go to **Settings > CI / CD** and expand the **Variables** @@ -124,19 +125,30 @@ Variable. To do so, follow these steps: When you trigger a pipeline, if you have Auto DevOps enabled and if you have correctly [entered AWS credentials as environment variables](../../ci/cloud_deployment/index.md#deploy-your-application-to-the-aws-elastic-container-service-ecs), -your application will be deployed to AWS 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 will run. +only the deployment to Kubernetes runs. -CAUTION: **Warning:** -Setting the `AUTO_DEVOPS_PLATFORM_TARGET` variable to `ECS` will trigger jobs +WARNING: +Setting the `AUTO_DEVOPS_PLATFORM_TARGET` variable to `ECS` triggers jobs defined in the [`Jobs/Deploy/ECS.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy/ECS.gitlab-ci.yml). However, it's not recommended to [include](../../ci/yaml/README.md#includetemplate) it on its own. This template is designed to be used with Auto DevOps only. It may change unexpectedly causing your pipeline to fail if included on its own. Also, the job names within this template may also change. Do not override these jobs' names in your -own pipeline, as the override will stop working when the name changes. +own pipeline, as the override stops working when the name changes. + +## Auto DevOps requirements for Amazon EC2 + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216008) in GitLab 13.6. + +You can target [AWS EC2](../../ci/cloud_deployment/index.md) +as a deployment platform instead of Kubernetes. To use Auto DevOps with AWS EC2, you must add a +specific environment 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. diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index f2d3b78e2b0..23ba6ad3356 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -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/#designated-technical-writers +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 --- # Stages of Auto DevOps @@ -11,6 +11,9 @@ Read them carefully to understand how each one works. ## Auto Build +NOTE: +Auto Build is not supported if Docker in Docker is not available for your GitLab Runners, like in OpenShift clusters. The OpenShift support in GitLab is tracked [in a dedicated epic](https://gitlab.com/groups/gitlab-org/-/epics/2068). + Auto Build creates a build of the application using an existing `Dockerfile` or Heroku buildpacks. The resulting Docker image is pushed to the [Container Registry](../../user/packages/container_registry/index.md), and tagged @@ -48,7 +51,7 @@ language: For the requirements of other languages and frameworks, read the [Heroku buildpacks documentation](https://devcenter.heroku.com/articles/buildpacks#officially-supported-buildpacks). -TIP: **Tip:** +NOTE: If Auto Build fails despite the project meeting the buildpack requirements, set a project variable `TRACE=true` to enable verbose logging, which may help you troubleshoot. @@ -64,7 +67,7 @@ value. The default builder is `heroku/buildpacks:18` but a different builder can be selected using the CI variable `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER`. Cloud Native Buildpacks (CNBs) are an evolution of Heroku buildpacks, and -will eventually supersede Herokuish-based builds within Auto DevOps. For more +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). Builds using Cloud Native Buildpacks support the same options as builds using @@ -78,7 +81,7 @@ Heroku buildpacks, with the following caveats: - The `/bin/herokuish` command is not present in the resulting image, and prefixing commands with `/bin/herokuish procfile exec` is no longer required (nor possible). -NOTE: **Note:** +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). @@ -96,7 +99,7 @@ Check the [currently supported languages](#currently-supported-languages). Auto Test uses tests you already have in your application. If there are no tests, it's up to you to add them. -NOTE: **Note:** +NOTE: Not all buildpacks supported by [Auto Build](#auto-build) are supported by Auto Test. Auto Test uses [Herokuish](https://gitlab.com/gitlab-org/gitlab/-/issues/212689), *not* Cloud Native Buildpacks, and only buildpacks that implement the @@ -147,16 +150,13 @@ out. The merge request widget also displays any > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. > - Select functionality made available in all tiers beginning in 13.1 -Static Application Security Testing (SAST) uses the -[SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast) to run static +Static Application Security Testing (SAST) runs static analysis on the current code, and checks for potential security issues. The -Auto SAST stage will be skipped on licenses other than -[Ultimate](https://about.gitlab.com/pricing/), and requires -[GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or above. +Auto SAST stage requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or above. After creating the report, it's uploaded as an artifact which you can later download and check out. The merge request widget also displays any security -warnings. +warnings on [Ultimate](https://about.gitlab.com/pricing/) licenses. To learn more about [how SAST works](../../user/application_security/sast/index.md), see the documentation. @@ -171,7 +171,7 @@ Secret Detection uses the After creating the report, it's uploaded as an artifact which you can later download and evaluate. The merge request widget also displays any security -warnings. +warnings on [Ultimate](https://about.gitlab.com/pricing/) licenses. To learn more, see [Secret Detection](../../user/application_security/secret_detection/index.md). @@ -179,9 +179,7 @@ To learn more, see [Secret Detection](../../user/application_security/secret_det > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. -Dependency Scanning uses the -[Dependency Scanning Docker image](https://gitlab.com/gitlab-org/security-products/dependency-scanning) -to run analysis on the project dependencies and check for potential security issues. +Dependency Scanning runs analysis on the project's dependencies and checks for potential security issues. The Auto Dependency Scanning stage is skipped on licenses other than [Ultimate](https://about.gitlab.com/pricing/) and requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or above. @@ -254,7 +252,7 @@ In GitLab 11.4 and later, [local Tiller](https://gitlab.com/gitlab-org/gitlab-fo used. Previous versions of GitLab had a Tiller installed in the project namespace. -CAUTION: **Caution:** +WARNING: Your apps should *not* be manipulated outside of Helm (using Kubernetes directly). This can cause confusion with Helm not detecting the change and subsequent deploys with Auto DevOps can undo your changes. Also, if you change something @@ -288,7 +286,7 @@ see the documentation. To use a custom target instead of the auto-deployed review apps, set a `DAST_WEBSITE` environment variable to the URL for DAST to scan. -DANGER: **Warning:** +WARNING: If [DAST Full Scan](../../user/application_security/dast/index.md#full-scan) is enabled, GitLab strongly advises **not** to set `DAST_WEBSITE` to any staging or production environment. DAST Full Scan @@ -373,7 +371,7 @@ In GitLab 11.4 and later, a used. Previous versions of GitLab had a Tiller installed in the project namespace. -CAUTION: **Caution:** +WARNING: Your apps should *not* be manipulated outside of Helm (using Kubernetes directly). This can cause confusion with Helm not detecting the change and subsequent deploys with Auto DevOps can undo your changes. Also, if you change something @@ -387,16 +385,16 @@ in the first place, and thus not realize that it needs to re-apply the old confi [GitLab Deploy Tokens](../../user/project/deploy_tokens/index.md#gitlab-deploy-token) are created for internal and private projects when Auto DevOps is enabled, and the Auto DevOps settings are saved. You can use a Deploy Token for permanent access to -the registry. After you manually revoke the GitLab Deploy Token, it won't be +the registry. After you manually revoke the GitLab Deploy Token, it isn't automatically created. If the GitLab Deploy Token can't be found, `CI_REGISTRY_PASSWORD` is used. -NOTE: **Note:** -`CI_REGISTRY_PASSWORD` is only valid during deployment. Kubernetes will be able -to successfully pull the container image during deployment, but if the image must -be pulled again, such as after pod eviction, Kubernetes will fail to do so +NOTE: +`CI_REGISTRY_PASSWORD` is only valid during deployment. Kubernetes can +successfully pull the container image during deployment, but if the image must +be pulled again, such as after pod eviction, Kubernetes cannot do so as it attempts to fetch the image using `CI_REGISTRY_PASSWORD`. ### Kubernetes 1.16+ @@ -405,7 +403,7 @@ as it attempts to fetch the image using `CI_REGISTRY_PASSWORD`. > - Support for deploying a PostgreSQL version that supports Kubernetes 1.16+ was [introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/merge_requests/49) in GitLab 12.9. > - Supported out of the box for new deployments as of GitLab 13.0. -CAUTION: **Deprecation:** +WARNING: The default value for the `deploymentApiVersion` setting was changed from `extensions/v1beta` to `apps/v1` in [GitLab 13.0](https://gitlab.com/gitlab-org/charts/auto-deploy-app/-/issues/47). @@ -431,7 +429,7 @@ To use Auto Deploy on a Kubernetes 1.16+ cluster: 1. If you are deploying your application for the first time and are using GitLab 12.9 or 12.10, set `AUTO_DEVOPS_POSTGRES_CHANNEL` to `2`. -DANGER: **Warning:** +WARNING: On GitLab 12.9 and 12.10, opting into `AUTO_DEVOPS_POSTGRES_CHANNEL` version `2` deletes the version `1` PostgreSQL database. Follow the [guide to upgrading PostgreSQL](upgrading_postgresql.md) @@ -455,7 +453,7 @@ initialization completes, GitLab deploys a second release with the application deployment as normal. Note that a post-install hook means that if any deploy succeeds, -`DB_INITIALIZE` won't be processed thereafter. +`DB_INITIALIZE` isn't processed thereafter. If present, `DB_MIGRATE` is run as a shell command within an application pod as a Helm pre-upgrade hook. @@ -492,7 +490,7 @@ the standard health checks, which expect a successful HTTP response on port the [`sidekiq_alive` gem](https://rubygems.org/gems/sidekiq_alive). To work with Sidekiq, you must also ensure your deployments have -access to a Redis instance. Auto DevOps won't deploy this instance for you, so +access to a Redis instance. Auto DevOps doesn't deploy this instance for you, so you must: - Maintain your own Redis instance. @@ -531,7 +529,7 @@ and accept traffic to and from any source. You can use [NetworkPolicy](https://kubernetes.io/docs/concepts/services-networking/network-policies/) to restrict connections to and from selected pods, namespaces, and the Internet. -NOTE: **Note:** +NOTE: You must use a Kubernetes network plugin that implements support for `NetworkPolicy`. The default network plugin for Kubernetes (`kubenet`) [does not implement](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/#kubenet) @@ -623,7 +621,7 @@ may require commands to be wrapped as follows: Some of the reasons you may need to wrap commands: - Attaching using `kubectl exec`. -- Using GitLab's [Web Terminal](../../ci/environments/index.md#web-terminals). +- Using the GitLab [Web Terminal](../../ci/environments/index.md#web-terminals). For example, to start a Rails console from the application root directory, run: diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 16536e5b586..c45390e935d 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -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/#designated-technical-writers +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -73,7 +73,9 @@ please proceed with the following upgrade guide. Otherwise, you can skip this pr #### Kubernetes 1.16+ -The v2 auto-deploy-image also drops support for Kubernetes 1.15 and lower. +The v2 auto-deploy-image drops support for Kubernetes 1.15 and lower. If you need to upgrade your +Kubernetes cluster, follow your cloud provider's instructions. Here's +[an example on GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/upgrading-a-cluster). #### Helm 3 @@ -114,6 +116,12 @@ If your Auto DevOps project has an active environment that was deployed with the `kubectl apply -f $backup`. 1. Remove the `MIGRATE_HELM_2TO3` variable. +#### In-Cluster PostgreSQL Channel 2 + +The v2 auto-deploy-image drops support for [legacy in-cluster PostgreSQL](upgrading_postgresql.md). +If your Kubernetes cluster still depends on it, [upgrade and migrate your data](upgrading_postgresql.md) +with the [v1 auto-deploy-image](#use-a-specific-version-of-auto-deploy-dependencies). + #### Traffic routing change for canary deployments and incremental rollouts > [Introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/merge_requests/109) in GitLab 13.4. @@ -176,7 +184,7 @@ include: - remote: https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.latest.gitlab-ci.yml ``` -CAUTION: **Warning:** +WARNING: Using a beta or unstable `auto-deploy-image` could cause unrecoverable damage to your environments. Do not test it with important projects or environments. diff --git a/doc/topics/autodevops/upgrading_chart.md b/doc/topics/autodevops/upgrading_chart.md index e4fb84d4509..2162969b53e 100644 --- a/doc/topics/autodevops/upgrading_chart.md +++ b/doc/topics/autodevops/upgrading_chart.md @@ -3,3 +3,6 @@ redirect_to: 'upgrading_auto_deploy_dependencies.md' --- This document was moved to [another location](upgrading_auto_deploy_dependencies.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md index a3c9f562f5e..55432ad61fa 100644 --- a/doc/topics/autodevops/upgrading_postgresql.md +++ b/doc/topics/autodevops/upgrading_postgresql.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -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/#designated-technical-writers +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 --- # Upgrading PostgreSQL for Auto DevOps @@ -36,7 +36,7 @@ involves: any existing channel 1 database. For more information, see [Detected an existing PostgreSQL database](index.md#detected-an-existing-postgresql-database). -TIP: **Tip:** +NOTE: If you have configured Auto DevOps to have staging, consider trying out the backup and restore steps on staging first, or trying this out on a review app. @@ -79,7 +79,7 @@ being modified after the database dump is created. deployment.extensions/production scaled ``` -1. You also will need to set replicas to zero for workers if you have any. +1. You must also set replicas to zero for workers if you have any. ## Backup @@ -112,7 +112,7 @@ being modified after the database dump is created. - `USERNAME` is the username you have configured for PostgreSQL. The default is `user`. - `DATABASE_NAME` is usually the environment name. - - You will be asked for the database password, the default is `testing-password`. + - When prompted for the database password, the default is `testing-password`. ```shell ## Format is: @@ -168,12 +168,12 @@ pvc-9085e3d3-5239-11ea-9c8d-42010a8e0096 8Gi RWO Retain ## Install new PostgreSQL -CAUTION: **Caution:** -Using the newer version of PostgreSQL will delete +WARNING: +Using the newer version of PostgreSQL deletes the older 0.7.1 PostgreSQL. To prevent the underlying data from being deleted, you can choose to retain the [persistent volume](#retain-persistent-volumes). -TIP: **Tip:** +NOTE: You can also [scope](../../ci/environments/index.md#scoping-environments-with-specs) the `AUTO_DEVOPS_POSTGRES_CHANNEL`, `AUTO_DEVOPS_POSTGRES_DELETE_V1` and @@ -196,9 +196,9 @@ higher*. This is the `XDB_INITIALIZE` or the `XDB_MIGRATE` to effectively disable them. 1. Run a new CI pipeline for the branch. In this case, we run a new CI pipeline for `master`. -1. Once the pipeline is successful, your application will now be upgraded - with the new PostgreSQL installed. There will also be zero replicas - which means no traffic will be served for your application (to prevent +1. After the pipeline is successful, your application is upgraded + with the new PostgreSQL installed. Zero replicas exist at this time, so + no traffic is served for your application (to prevent new data from coming in). ## Restore @@ -226,7 +226,7 @@ higher*. This is the 1. Once connected to the pod, run the following command to restore the database. - - You will be asked for the database password, the default is `testing-password`. + - When asked for the database password, the default is `testing-password`. - `USERNAME` is the username you have configured for PostgreSQL. The default is `user`. - `DATABASE_NAME` is usually the environment name. diff --git a/doc/topics/cron/index.md b/doc/topics/cron/index.md index 2be579b4e98..5abcc5e1eb1 100644 --- a/doc/topics/cron/index.md +++ b/doc/topics/cron/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Cron diff --git a/doc/topics/git/feature_branch_development.md b/doc/topics/git/feature_branch_development.md index 762eddbc130..c9fb81600d4 100644 --- a/doc/topics/git/feature_branch_development.md +++ b/doc/topics/git/feature_branch_development.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: how-tos --- @@ -15,7 +15,7 @@ Once work on the development branch is complete, then the feature branch can be GitLab frequently implements this process whenever there is an MVC that requires multiple MRs. -## Use case: GitLab's release posts +## Use case: GitLab release posts 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. diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index c01080400ac..6a4608223b4 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: concepts, howto description: "Introduction to Git rebase, force-push, and resolving merge conflicts through the command line." --- @@ -24,7 +24,7 @@ Git. There are the following rebase options: ### Before rebasing -CAUTION: **Warning:** +WARNING: `git rebase` rewrites the commit history. It **can be harmful** to do it in shared branches. It can cause complex and hard to resolve merge conflicts. In these cases, instead of rebasing your branch against the default branch, @@ -129,7 +129,7 @@ message, squash (join multiple commits into one), edit, or delete commits. It is handy for changing past commit messages, as well as for organizing the commit history of your branch to keep it clean. -TIP: **Tip:** +NOTE: If you want to keep the default branch commit history clean, you don't need to manually squash all your commits before merging every merge request; with [Squash and Merge](../../user/project/merge_requests/squash_and_merge.md) @@ -263,7 +263,7 @@ To fix conflicts locally, you can use the following method: git rebase --continue ``` - CAUTION: **Caution:** + WARNING: Up to this point, you can run `git rebase --abort` to stop the process. Git aborts the rebase and rolls back the branch to the state you had before running `git rebase`. diff --git a/doc/topics/git/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md index 1eea49d8ffe..5979cad1c0e 100644 --- a/doc/topics/git/how_to_install_git/index.md +++ b/doc/topics/git/how_to_install_git/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 description: 'This article describes how to install Git on macOS, Ubuntu Linux and Windows.' type: howto --- diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md index cb2d7b74522..cc4e546a244 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: index --- diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 80014358230..f6e0cdee2cf 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs/index.html' --- @@ -43,7 +43,7 @@ Documentation for GitLab instance administrators is under [LFS administration do - Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have to add the URL to Git configuration manually (see [troubleshooting](#troubleshooting)) -NOTE: **Note:** +NOTE: With 8.12 GitLab added LFS support to SSH. The Git LFS communication still goes over HTTP, but now the SSH client passes the correct credentials to the Git LFS client, so no action is required by the user. @@ -120,7 +120,7 @@ See the documentation on [File Locking](../../../user/project/file_lock.md). > - It's recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-lfs-objects-in-project-archives). -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. Prior to GitLab 13.5, [project source @@ -219,7 +219,7 @@ git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs" ### Credentials are always required when pushing an object -NOTE: **Note:** +NOTE: With 8.12 GitLab added LFS support to SSH. The Git LFS communication still goes over HTTP, but now the SSH client passes the correct credentials to the Git LFS client, so no action is required by the user. 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 d65d52841aa..30be9c42f01 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,13 +1,13 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- # Migration guide from Git Annex to Git LFS -DANGER: **Deprecated:** +WARNING: Git Annex support [has been removed](https://gitlab.com/gitlab-org/gitlab/-/issues/1648) in GitLab Enterprise Edition 9.0 (2017/03/22). @@ -32,7 +32,7 @@ ones that GitLab developed. - Git Annex requires a more complex setup, but has much more options than Git LFS. You can compare the commands each one offers by running `man git-annex` and `man git-lfs`. -- Annex files cannot be browsed directly in GitLab's interface, whereas LFS +- Annex files cannot be browsed directly in the GitLab interface, whereas LFS files can. ## Migration steps @@ -82,7 +82,7 @@ Here you'll find a guide on Since Annex files are stored as objects with symlinks and cannot be directly modified, we need to first remove those symlinks. -NOTE: **Note:** +NOTE: Make sure the you read about the [`direct` mode](https://git-annex.branchable.com/direct_mode/) as it contains useful information that may fit in your use case. Note that `annex direct` is deprecated in Git Annex version 6, so you may need to upgrade your repository @@ -216,7 +216,7 @@ GitLab.com), therefore, you don't need to do anything server-side. After the migration finishes successfully, you can remove all `git-annex` related branches from your repository. -On GitLab, navigate to your project's **Repository ➔ Branches** and delete all +On GitLab, navigate to your project's **Repository > Branches** and delete all branches created by Git Annex: `git-annex`, and all under `synced/`.  diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md index 596b2cb400f..941fc281e4c 100644 --- a/doc/topics/git/lfs/migrate_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_to_git_lfs.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 description: "How to migrate an existing Git repository to Git LFS with BFG." --- @@ -10,9 +10,8 @@ description: "How to migrate an existing Git repository to Git LFS with BFG." Using Git LFS can help you to reduce the size of your Git repository and improve its performance. -However, simply adding the -large files that are already in your repository to Git LFS, -will not actually reduce the size of your repository because +However, simply adding the large files that are already in your repository to Git LFS +doesn't actually reduce the size of your repository because the files are still referenced by previous commits. Through the method described on this document, first migrate @@ -26,7 +25,7 @@ This tutorial was inspired by the guide For more information on Git LFS, see the [references](#references) below. -CAUTION: **Warning:** +WARNING: The method described on this guide rewrites Git history. Make sure to back up your repository before beginning and use it at your own risk. @@ -41,7 +40,7 @@ Before beginning, make sure: Branches based on the repository before applying this method cannot be merged. Branches based on the repo before applying this method cannot be merged. -To follow this tutorial, you'll need: +To follow this tutorial, you need: - Maintainer permissions to the existing Git repository you'd like to migrate to LFS with access through the command line. @@ -60,7 +59,7 @@ To follow this tutorial, you'll need: brew install git-lfs ``` -NOTE: **Note:** +NOTE: This guide was tested on macOS Mojave. ## Steps @@ -74,7 +73,7 @@ Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs- 1. Clone `--mirror` the repository: - Cloning with the mirror flag will create a bare repository. + Cloning with the mirror flag creates a bare repository. This ensures you get all the branches within the repo. It creates a directory called `<repo-name>.git` @@ -150,7 +149,7 @@ Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs- ``` Now all existing the files you converted, as well as the new - ones you add, will be properly tracked with LFS. + ones you add, are properly tracked with LFS. 1. [Re-protect the default branch](../../../user/project/protected_branches.md): @@ -177,8 +176,8 @@ but commented out to help encourage others to add to it in the future. --> - [Getting Started with Git LFS](https://about.gitlab.com/blog/2017/01/30/getting-started-with-git-lfs-tutorial/) - [Migrate from Git Annex to Git LFS](migrate_from_git_annex_to_git_lfs.md) -- [GitLab's Git LFS user documentation](index.md) -- [GitLab's Git LFS administrator documentation](../../../administration/lfs/index.md) +- [GitLab Git LFS user documentation](index.md) +- [GitLab Git LFS administrator documentation](../../../administration/lfs/index.md) - Alternative method to [migrate an existing repository to Git LFS](https://github.com/git-lfs/git-lfs/wiki/Tutorial#migrating-existing-repository-data-to-lfs) <!-- diff --git a/doc/topics/git/migrate_to_git_lfs/index.md b/doc/topics/git/migrate_to_git_lfs/index.md index ff60603ae58..c530fa1dcb1 100644 --- a/doc/topics/git/migrate_to_git_lfs/index.md +++ b/doc/topics/git/migrate_to_git_lfs/index.md @@ -3,3 +3,6 @@ redirect_to: '../lfs/migrate_to_git_lfs.md' --- This document was moved to [another location](../lfs/migrate_to_git_lfs.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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 77732e0da3e..8fc2259c83e 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -1,14 +1,14 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- # Numerous undo possibilities in Git In this tutorial, we will show you different ways of undoing your work in Git, for which -we will assume you have a basic working knowledge of. Check GitLab's +we will assume you have a basic working knowledge of. Check the GitLab [Git documentation](../index.md) for reference. Also, we will only provide some general information of the commands, which is enough @@ -421,7 +421,7 @@ 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). -NOTE: **Note:** +NOTE: Never modify the commit history of `master` or shared branch. ### How modifying history is done @@ -457,7 +457,7 @@ pick <commit3-id> <commit3-commit-message> # Note that empty commits are commented out ``` -NOTE: **Note:** +NOTE: It is important to notice that comment from the output clearly states that, if you decide to abort, then do not just close your editor (as that will in-fact modify history), but remove all uncommented lines and save. diff --git a/doc/topics/git/partial_clone.md b/doc/topics/git/partial_clone.md index 58fa6d2f112..590a37d0128 100644 --- a/doc/topics/git/partial_clone.md +++ b/doc/topics/git/partial_clone.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -108,7 +108,7 @@ For more details, see the Git documentation for ## Filter by file path -CAUTION: **Experimental:** +WARNING: Partial Clone using `sparse` filters is experimental, slow, and will significantly increase Gitaly resource utilization when cloning and fetching. @@ -169,7 +169,7 @@ For more details, see the Git documentation for git rev-list --all --quiet --objects --missing=print | wc -l ``` - CAUTION: **IDE and Shell integrations:** + WARNING: Git integrations with `bash`, `zsh`, etc and editors that automatically show Git status information often run `git fetch` which will fetch the entire repository. You many need to disable or reconfigure these diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index 523718e4133..aace979004f 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_git.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: howto --- @@ -51,7 +51,7 @@ There's another option where you can prevent session timeouts by configuring SSH 'keep alive' either on the client or on the server (if you are a GitLab admin and have access to the server). -NOTE: **Note:** +NOTE: Configuring *both* the client and the server is unnecessary. **To configure SSH on the client side**: @@ -165,7 +165,7 @@ fatal: index-pack failed This can be fixed by increasing the existing `http.postBuffer` value to one greater than the repository size. For example, if `git clone` fails when cloning a 500M repository, the solution will be to set `http.postBuffer` to `524288000` so that the request only starts buffering after the first 524288000 bytes. -NOTE: **Note:** +NOTE: The default value of `http.postBuffer`, 1 MiB, is applied if the setting is not configured. ```shell diff --git a/doc/topics/git/useful_git_commands.md b/doc/topics/git/useful_git_commands.md index 0bf6075a1ea..6b4d1e06c2c 100644 --- a/doc/topics/git/useful_git_commands.md +++ b/doc/topics/git/useful_git_commands.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index 32676658bff..292e35922d6 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +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" disqus_identifier: 'https://docs.gitlab.com/ee/workflow/gitlab_flow.html' --- @@ -151,7 +151,7 @@ In GitLab, you can do this when merging. Removing finished branches ensures that the list of branches shows only work in progress. It also ensures that if someone reopens the issue, they can use the same branch name without causing problems. -NOTE: **Note:** +NOTE: When you reopen an issue you need to create a new merge request.  @@ -173,7 +173,7 @@ For example, the issue title "As an administrator, I want to remove users withou When you are ready to code, create a branch for the issue from the `master` branch. This branch is the place for any work related to this change. -NOTE: **Note:** +NOTE: The name of a branch might be dictated by organizational standards. When you are done or want to discuss the code, open a merge request. @@ -224,12 +224,12 @@ Not only does this rewrite history, but it also loses authorship information. Rebasing prevents the other authors from being attributed and sharing part of the [`git blame`](https://git-scm.com/docs/git-blame). If a merge involves many commits, it may seem more difficult to undo. -You might consider solving this by squashing all the changes into one commit just before merging by using GitLab's [Squash-and-Merge](../user/project/merge_requests/squash_and_merge.md) feature. +You might consider solving this by squashing all the changes into one commit just before merging by using the GitLab [Squash-and-Merge](../user/project/merge_requests/squash_and_merge.md) feature. Fortunately, there is an easy way to undo a merge with all its commits. The way to do this is by reverting the merge commit. Preserving this ability to revert a merge is a good reason to always use the "no fast-forward" (`--no-ff`) strategy when you merge manually. -NOTE: **Note:** +NOTE: If you revert a merge commit and then change your mind, revert the revert commit to redo the merge. Git does not allow you to merge the code again otherwise. @@ -254,7 +254,7 @@ If you need to use some code that was introduced in `master` after you created t If your feature branch has a merge conflict, creating a merge commit is a standard way of solving this. -NOTE: **Note:** +NOTE: Sometimes you can use `.gitattributes` to reduce merge conflicts. For example, you can set your changelog file to use the [union merge driver](https://git-scm.com/docs/gitattributes#gitattributes-union) so that multiple new entries don't conflict with each other. @@ -268,7 +268,7 @@ One option is to use continuous integration (CI) to merge in `master` at the sta 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. -NOTE: **Note:** +NOTE: Don't confuse automatic branch testing with continuous integration. Martin Fowler makes this distinction in [his article about feature branches](https://martinfowler.com/bliki/FeatureBranch.html): "I've heard people say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit. diff --git a/doc/topics/index.md b/doc/topics/index.md index 91b1905f1b6..276cb07c250 100644 --- a/doc/topics/index.md +++ b/doc/topics/index.md @@ -1,15 +1,15 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Topics Welcome to Topics! We have organized our content resources into topics to get you started on areas of your interest. Each topic page -consists of an index listing all related content. It will guide -you through better understanding GitLab's concepts +consists of an index listing all related content. It guides +you through better understanding GitLab concepts through our regular docs, and, when available, through articles (guides, tutorials, technical overviews, blog posts) and videos. diff --git a/doc/topics/offline/index.md b/doc/topics/offline/index.md index b40f5e92738..df6e1f9491e 100644 --- a/doc/topics/offline/index.md +++ b/doc/topics/offline/index.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Offline GitLab @@ -16,6 +16,6 @@ If you plan to deploy a GitLab instance on a physically-isolated and offline net ## Features -Follow these best practices to use GitLab's features in an offline environment: +Follow these best practices to use GitLab features in an offline environment: - [Operating the GitLab Secure scanners in an offline environment](../../user/application_security/offline_deployments/index.md). diff --git a/doc/topics/offline/quick_start_guide.md b/doc/topics/offline/quick_start_guide.md index 92f8f9167b7..dd1ddeb31ff 100644 --- a/doc/topics/offline/quick_start_guide.md +++ b/doc/topics/offline/quick_start_guide.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Getting started with an offline GitLab Installation @@ -11,22 +11,22 @@ instance entirely offline. ## Installation -NOTE: **Note:** +NOTE: This guide assumes the server is Ubuntu 18.04. Instructions for other servers may vary. This guide also assumes the server host resolves as `my-host`, which you should replace with your server's name. Follow the installation instructions [as outlined in the omnibus install guide](https://about.gitlab.com/install/#ubuntu), but make sure to specify an `http` -URL for the `EXTERNAL_URL` installation step. Once installed, we will manually +URL for the `EXTERNAL_URL` installation step. Once installed, we can manually configure the SSL ourselves. It is strongly recommended to setup a domain for IP resolution rather than bind to the server's IP address. This better ensures a stable target for our certs' CN -and will make long-term resolution simpler. +and makes long-term resolution simpler. ```shell -sudo EXTERNAL_URL="http://my-host.internal" install gitlab-ee +sudo EXTERNAL_URL="http://my-host.internal" apt-get install gitlab-ee ``` ## Enabling SSL diff --git a/doc/topics/web_application_firewall/index.md b/doc/topics/web_application_firewall/index.md index 83b3bfb1cef..1c1728d9277 100644 --- a/doc/topics/web_application_firewall/index.md +++ b/doc/topics/web_application_firewall/index.md @@ -1,7 +1,7 @@ --- stage: Protect group: Container Security -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/#designated-technical-writers +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 --- @@ -16,9 +16,9 @@ much more. ## Overview GitLab provides a WAF out of the box after Ingress is deployed. All you need to do is deploy your -application along with a service and Ingress resource. In GitLab's [Ingress](../../user/clusters/applications.md#ingress) +application along with a service and Ingress resource. In the GitLab [Ingress](../../user/clusters/applications.md#ingress) deployment, the [ModSecurity](https://modsecurity.org/) -module is loaded into Ingress-NGINX by default and monitors the traffic going to the applications +module is loaded into Ingress-NGINX by default and monitors the traffic to the applications which have an Ingress. The ModSecurity module runs with the [OWASP Core Rule Set (CRS)](https://coreruleset.org/) by default. The OWASP CRS detects and logs a wide range of common attacks. @@ -55,7 +55,7 @@ If you are using a self-managed instance of GitLab, you need to configure the [Google OAuth2 OmniAuth Provider](../../integration/google.md) before you can configure a cluster on GKE. Once this is set up, you can follow the steps on the [quick start guide](quick_start_guide.md) to get started. -NOTE: **Note:** +NOTE: This guide shows how the WAF can be deployed using Auto DevOps. The WAF is available by default to all applications no matter how they are deployed, as long as they are using Ingress. diff --git a/doc/topics/web_application_firewall/quick_start_guide.md b/doc/topics/web_application_firewall/quick_start_guide.md index 3df22854437..df355ff2413 100644 --- a/doc/topics/web_application_firewall/quick_start_guide.md +++ b/doc/topics/web_application_firewall/quick_start_guide.md @@ -1,50 +1,50 @@ --- stage: Protect group: Container Security -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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Getting started with the Web Application Firewall -This is a step-by-step guide that will help you use GitLab's [Web Application Firewall](index.md) after +This is a step-by-step guide to help you use the GitLab [Web Application Firewall](index.md) after deploying a project hosted on GitLab.com to Google Kubernetes Engine using [Auto DevOps](../autodevops/index.md). -We will use GitLab's native Kubernetes integration, so you will not need +The GitLab native Kubernetes integration is used, so you do not need to create a Kubernetes cluster manually using the Google Cloud Platform console. -We will create and deploy a simple application that we create from a GitLab template. +A simple application is created and deployed based on a GitLab template. -These instructions will also work for a self-managed GitLab instance. However, you will +These instructions also work for a self-managed GitLab instance. However, you need to ensure your own [runners are configured](../../ci/runners/README.md) and [Google OAuth is enabled](../../integration/google.md). -GitLab's Web Application Firewall is deployed with [Ingress](../../user/clusters/applications.md#ingress), -so it will be available to your applications no matter how you deploy them to Kubernetes. +The GitLab Web Application Firewall is deployed with [Ingress](../../user/clusters/applications.md#ingress), +so it is available to your applications no matter how you deploy them to Kubernetes. ## Configuring your Google account Before creating and connecting your Kubernetes cluster to your GitLab project, you need a Google Cloud Platform account. If you do not already have one, -sign up at <https://console.cloud.google.com>. You will need to either sign in with an existing +sign up at <https://console.cloud.google.com>. You need to either sign in with an existing Google account (for example, one that you use to access Gmail, Drive, etc.) or create a new one. 1. To enable the required APIs and related services, follow the steps in the ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). 1. Make sure you have created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account). -TIP: **Tip:** +NOTE: Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial), -and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with GitLab's +and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with the GitLab Google Kubernetes Engine integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?PCN=a0n60000006Vpz4AAC) and apply for credit. ## Creating a new project from a template -We will use one of GitLab's project templates to get started. As the name suggests, +We use a GitLab project templates to get started. As the name suggests, those projects provide a barebones application built on some well-known frameworks. 1. In GitLab, click the plus icon (**+**) at the top of the navigation bar and select **New project**. 1. Go to the **Create from template** tab where you can choose for example a Ruby on Rails, Spring, or NodeJS Express project. - We will use the Ruby on Rails template. + Use the Ruby on Rails template.  @@ -57,7 +57,7 @@ those projects provide a barebones application built on some well-known framewor 1. Click **Create project**. Now that the project is created, the next step is to create the Kubernetes cluster -under which this application will be deployed. +to deploy this application under. ## Creating a Kubernetes cluster from within GitLab @@ -76,9 +76,9 @@ under which this application will be deployed.  1. The last step is to provide the cluster details. - 1. Give it a name, leave the environment scope as is, and choose the GCP project under which the cluster - will be created (per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you). - 1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) under which the cluster will be created. + 1. Give it a name, leave the environment scope as is, and choose the GCP project under which to create the cluster. + (Per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you.) + 1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) to create the cluster in. 1. Enter the number of nodes you want it to have. 1. Choose the [machine type](https://cloud.google.com/compute/docs/machine-types). @@ -94,7 +94,7 @@ to take full advantage of Auto DevOps. ## Install Ingress -GitLab's Kubernetes integration comes with some +The GitLab Kubernetes integration comes with some [pre-defined applications](../../user/project/clusters/index.md#installing-applications) for you to install. @@ -111,14 +111,14 @@ auditing anomalous traffic, blocking mode ensures the traffic doesn't reach past After Ingress is installed, wait a few seconds and copy the IP address that is displayed in order to add in your base **Domain** at the top of the page. For -the purpose of this guide, we will use the one suggested by GitLab. Once you have +the purpose of this guide, we use the one suggested by GitLab. Once you have filled in the domain, click **Save changes**.  Prometheus should also be installed. It is an open-source monitoring and -alerting system that we will use to supervise the deployed application. -We will not install GitLab Runner as we will use the shared runners that +alerting system that is used to supervise the deployed application. +Installing GitLab Runner is not required as we use the shared runners that GitLab.com provides. ## Enabling Auto DevOps (optional) @@ -162,13 +162,13 @@ deploys the application in Kubernetes ([Auto Deploy](../autodevops/stages.md#aut The **production** stage creates Kubernetes objects like a Deployment, Service, and Ingress resource. The -application will be monitored by the WAF automatically. +application is monitored by the WAF automatically. ## Validating Ingress is running ModSecurity Now we can make sure that Ingress is running properly with ModSecurity and send a request to ensure our application is responding correctly. You must connect to -your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the [Google Cloud SDK](https://cloud.google.com/sdk/install). +your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install). 1. After connecting to your cluster, check if the Ingress-NGINX controller is running and ModSecurity is enabled. @@ -201,7 +201,7 @@ your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the NAME HOSTS PORTS production-auto-deploy fjdiaz-auto-devv-2.34.68.60.207.nip.io,le-16730183.34.68.60.207.nip.io 80, 443 - $ curl --location --insecure fjdiaz-auto-devv-2.34.68.60.207.nip.io | grep 'Rails!' --after 2 --before 2 + $ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" | grep 'Rails!' --after 2 --before 2 <body> <p>You're on Rails!</p> </body> @@ -216,7 +216,7 @@ Now let's send a potentially malicious request, as if we were a scanner, checking for vulnerabilities within our application and examine the ModSecurity logs: ```shell -$ curl --location --insecure fjdiaz-auto-devv-2.34.68.60.207.nip.io --header "User-Agent: absinthe" | grep 'Rails!' --after 2 --before 2 +$ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" --header "User-Agent: absinthe" | grep 'Rails!' --after 2 --before 2 <body> <p>You're on Rails!</p> </body> |