Commit 821d1e6e authored by Amy Qualls's avatar Amy Qualls

Partial tone and style revision

To make merging easier, this MR updates only the first few sections
of the AutoDevops stages page for tone and style fixes.
parent 832a2e08
# Stages of Auto DevOps # Stages of Auto DevOps
The following sections describe the stages of Auto DevOps. Read them carefully The following sections describe the stages of [Auto DevOps](index.md).
to understand how each one works. Read them carefully to understand how each one works.
## Auto Build ## Auto Build
Auto Build creates a build of the application using an existing `Dockerfile` or Auto Build creates a build of the application using an existing `Dockerfile` or
Heroku buildpacks. Heroku buildpacks. The resulting Docker image is pushed to the
[Container Registry](../../user/packages/container_registry/index.md), and tagged
Either way, the resulting Docker image is automatically pushed to the with the commit SHA or tag.
[Container Registry](../../user/packages/container_registry/index.md) and tagged with the commit SHA or tag.
### Auto Build using a Dockerfile ### Auto Build using a Dockerfile
If a project's repository contains a `Dockerfile` at its root, Auto Build will use If a project's repository contains a `Dockerfile` at its root, Auto Build uses
`docker build` to create a Docker image. `docker build` to create a Docker image.
If you are also using Auto Review Apps and Auto Deploy and choose to provide If you're also using Auto Review Apps and Auto Deploy, and you choose to provide
your own `Dockerfile`, make sure you expose your application to port your own `Dockerfile`, you must expose your application to port `5000`, as the
`5000` as this is the port assumed by the [default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app) assumes
[default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app). Alternatively you can override the default values by [customizing the Auto Deploy Helm chart](customize.md#custom-helm-chart) this port is available. You can override the default values by
[customizing the Auto Deploy Helm chart](customize.md#custom-helm-chart).
### Auto Build using Heroku buildpacks ### Auto Build using Heroku buildpacks
Auto Build builds an application using a project's `Dockerfile` if present, or Auto Build builds an application using a project's `Dockerfile` if present. If no
otherwise it will use [Herokuish](https://github.com/gliderlabs/herokuish) `Dockerfile` is present, it uses [Herokuish](https://github.com/gliderlabs/herokuish)
and [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) and [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks)
to automatically detect and build the application into a Docker image. to detect and build the application into a Docker image.
Each buildpack requires certain files to be in your project's repository for Each buildpack requires your project's repository to contain certain files for
Auto Build to successfully build your application. For example, the following Auto Build to build your application successfully. For example, your application's
files are required at the root of your application's repository, depending on root directory must contain the appropriate file for your application's
the language: language:
- A `Pipfile` or `requirements.txt` file for Python projects. - For Python projects, a `Pipfile` or `requirements.txt` file.
- A `Gemfile` or `Gemfile.lock` file for Ruby projects. - For Ruby projects, a `Gemfile` or `Gemfile.lock` file.
For the requirements of other languages and frameworks, read the For the requirements of other languages and frameworks, read the
[buildpacks docs](https://devcenter.heroku.com/articles/buildpacks#officially-supported-buildpacks). [Heroku buildpacks documentation](https://devcenter.heroku.com/articles/buildpacks#officially-supported-buildpacks).
TIP: **Tip:** TIP: **Tip:**
If Auto Build fails despite the project meeting the buildpack requirements, set If Auto Build fails despite the project meeting the buildpack requirements, set
a project variable `TRACE=true` to enable verbose logging, which may help to a project variable `TRACE=true` to enable verbose logging, which may help you
troubleshoot. troubleshoot.
### Auto Build using Cloud Native Buildpacks (beta) ### Auto Build using Cloud Native Buildpacks (beta)
...@@ -73,12 +73,12 @@ yet part of the Cloud Native Buildpack specification. For more information, see ...@@ -73,12 +73,12 @@ yet part of the Cloud Native Buildpack specification. For more information, see
## Auto Test ## Auto Test
Auto Test automatically runs the appropriate tests for your application using Auto Test runs the appropriate tests for your application using
[Herokuish](https://github.com/gliderlabs/herokuish) and [Heroku [Herokuish](https://github.com/gliderlabs/herokuish) and
buildpacks](https://devcenter.heroku.com/articles/buildpacks) by analyzing [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) by analyzing
your project to detect the language and framework. Several languages and your project to detect the language and framework. Several languages and
frameworks are detected automatically, but if your language is not detected, frameworks are detected automatically, but if your language is not detected,
you may succeed with a [custom buildpack](customize.md#custom-buildpacks). Check the create a [custom buildpack](customize.md#custom-buildpacks). Check the
[currently supported languages](index.md#currently-supported-languages). [currently supported languages](index.md#currently-supported-languages).
Auto Test uses tests you already have in your application. If there are no Auto Test uses tests you already have in your application. If there are no
...@@ -88,8 +88,8 @@ tests, it's up to you to add them. ...@@ -88,8 +88,8 @@ tests, it's up to you to add them.
Auto Code Quality uses the Auto Code Quality uses the
[Code Quality image](https://gitlab.com/gitlab-org/ci-cd/codequality) to run [Code Quality image](https://gitlab.com/gitlab-org/ci-cd/codequality) to run
static analysis and other code checks on the current code. The report is static analysis and other code checks on the current code. After creating the
created, and is uploaded as an artifact which you can later download and check report, it's uploaded as an artifact which you can later download and check
out. out.
Any differences between the source and target branches are also Any differences between the source and target branches are also
...@@ -101,14 +101,16 @@ Any differences between the source and target branches are also ...@@ -101,14 +101,16 @@ Any differences between the source and target branches are also
Static Application Security Testing (SAST) uses the Static Application Security Testing (SAST) uses the
[SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast) to run static [SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast) to run static
analysis on the current code and checks for potential security issues. The analysis on the current code, and checks for potential security issues. The
Auto SAST stage will be skipped on licenses other than Ultimate and requires GitLab Runner 11.5 or above. Auto SAST stage will be skipped on licenses other than
[Ultimate](https://about.gitlab.com/pricing/), and requires GitLab Runner 11.5 or above.
Once the report is created, it's uploaded as an artifact which you can later download and After creating the report, it's uploaded as an artifact which you can later
check out. download and check out.
Any security warnings are also shown in the merge request widget. Read more how Any security warnings are also shown in the merge request widget. To learn more
[SAST works](../../user/application_security/sast/index.md). about [how SAST works](../../user/application_security/sast/index.md), see the
documentation.
## Auto Dependency Scanning **(ULTIMATE)** ## Auto Dependency Scanning **(ULTIMATE)**
...@@ -161,7 +163,7 @@ Any security warnings are also shown in the merge request widget. Read more how ...@@ -161,7 +163,7 @@ Any security warnings are also shown in the merge request widget. Read more how
## Auto Review Apps ## Auto Review Apps
This is an optional step, since many projects do not have a Kubernetes cluster This is an optional step, since many projects don't have a Kubernetes cluster
available. If the [requirements](index.md#requirements) are not met, the job will available. If the [requirements](index.md#requirements) are not met, the job will
silently be skipped. silently be skipped.
...@@ -196,7 +198,7 @@ Your apps should *not* be manipulated outside of Helm (using Kubernetes directly ...@@ -196,7 +198,7 @@ Your apps should *not* be manipulated outside of Helm (using Kubernetes directly
This can cause confusion with Helm not detecting the change and subsequent 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 deploys with Auto DevOps can undo your changes. Also, if you change something
and want to undo it by deploying again, Helm may not detect that anything changed and want to undo it by deploying again, Helm may not detect that anything changed
in the first place, and thus not realize that it needs to re-apply the old config. in the first place, and thus not realize that it needs to re-apply the old configuration.
## Auto DAST **(ULTIMATE)** ## Auto DAST **(ULTIMATE)**
...@@ -223,7 +225,8 @@ To use a custom target instead of the auto-deployed review apps, ...@@ -223,7 +225,8 @@ 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. set a `DAST_WEBSITE` environment variable to the URL for DAST to scan.
NOTE: **Note:** NOTE: **Note:**
If [DAST Full Scan](../../user/application_security/dast/index.md#full-scan) is enabled, it is strongly advised **not** 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 to set `DAST_WEBSITE` to any staging or production environment. DAST Full Scan
actively attacks the target, which can take down the application and lead to actively attacks the target, which can take down the application and lead to
data loss or corruption. data loss or corruption.
...@@ -252,7 +255,7 @@ Any performance differences between the source and target branches are also ...@@ -252,7 +255,7 @@ Any performance differences between the source and target branches are also
## Auto Deploy ## Auto Deploy
This is an optional step, since many projects do not have a Kubernetes cluster This is an optional step, since many projects don't have a Kubernetes cluster
available. If the [requirements](index.md#requirements) are not met, the job will available. If the [requirements](index.md#requirements) are not met, the job will
silently be skipped. silently be skipped.
...@@ -261,7 +264,7 @@ After a branch or merge request is merged into the project's default branch (usu ...@@ -261,7 +264,7 @@ After a branch or merge request is merged into the project's default branch (usu
the Kubernetes cluster, with a namespace based on the project name and unique the Kubernetes cluster, with a namespace based on the project name and unique
project ID, for example `project-4321`. project ID, for example `project-4321`.
Auto Deploy doesn't include deployments to staging or canary by default, but the Auto Deploy does not include deployments to staging or canary by default, but the
[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) contains job definitions for these tasks if you want to [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) contains job definitions for these tasks if you want to
enable them. enable them.
...@@ -284,7 +287,7 @@ Your apps should *not* be manipulated outside of Helm (using Kubernetes directly ...@@ -284,7 +287,7 @@ Your apps should *not* be manipulated outside of Helm (using Kubernetes directly
This can cause confusion with Helm not detecting the change and subsequent 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 deploys with Auto DevOps can undo your changes. Also, if you change something
and want to undo it by deploying again, Helm may not detect that anything changed and want to undo it by deploying again, Helm may not detect that anything changed
in the first place, and thus not realize that it needs to re-apply the old config. in the first place, and thus not realize that it needs to re-apply the old configuration.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19507) in GitLab 11.0. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19507) in GitLab 11.0.
...@@ -292,11 +295,11 @@ For internal and private projects a [GitLab Deploy Token](../../user/project/dep ...@@ -292,11 +295,11 @@ For internal and private projects a [GitLab Deploy Token](../../user/project/dep
will be automatically created, when Auto DevOps is enabled and the Auto DevOps settings are saved. This Deploy Token will be automatically created, when Auto DevOps is enabled and the Auto DevOps settings are saved. This Deploy Token
can be used for permanent access to the registry. When the GitLab Deploy Token has been manually revoked, it won't be automatically created. can be used for permanent access to the registry. When the GitLab Deploy Token has been manually revoked, it won't be automatically created.
If the GitLab Deploy Token cannot be found, `CI_REGISTRY_PASSWORD` is If the GitLab Deploy Token can't be found, `CI_REGISTRY_PASSWORD` is
used. Note that `CI_REGISTRY_PASSWORD` is only valid during deployment. used. Note that `CI_REGISTRY_PASSWORD` is only valid during deployment.
This means that Kubernetes will be able to successfully pull the This means that Kubernetes will be able to successfully pull the
container image during deployment but in cases where the image needs to container image during deployment but in cases where the image needs to
be pulled again, e.g. after pod eviction, Kubernetes will fail to do so be pulled again, such as after pod eviction, Kubernetes will fail to do so
as it will be attempting to fetch the image using as it will be attempting to fetch the image using
`CI_REGISTRY_PASSWORD`. `CI_REGISTRY_PASSWORD`.
...@@ -310,7 +313,7 @@ The default value of `extensions/v1beta1` for the `deploymentApiVersion` setting ...@@ -310,7 +313,7 @@ The default value of `extensions/v1beta1` for the `deploymentApiVersion` setting
deprecated, and is scheduled to be changed to a new default of `apps/v1` in deprecated, and is scheduled to be changed to a new default of `apps/v1` in
[GitLab 13.0](https://gitlab.com/gitlab-org/charts/auto-deploy-app/issues/47). [GitLab 13.0](https://gitlab.com/gitlab-org/charts/auto-deploy-app/issues/47).
In Kubernetes 1.16 onwards, a number of [APIs were removed](https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/), In Kubernetes 1.16 and later, a number of [APIs were removed](https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/),
including support for `Deployment` in the `extensions/v1beta1` version. including support for `Deployment` in the `extensions/v1beta1` version.
To use Auto Deploy on a Kubernetes 1.16+ cluster, you must: To use Auto Deploy on a Kubernetes 1.16+ cluster, you must:
...@@ -351,7 +354,7 @@ GitLab will deploy a second release with the application deployment as ...@@ -351,7 +354,7 @@ GitLab will deploy a second release with the application deployment as
normal. normal.
Note that a post-install hook means that if any deploy succeeds, Note that a post-install hook means that if any deploy succeeds,
`DB_INITIALIZE` will not be processed thereafter. `DB_INITIALIZE` won't be processed thereafter.
If present, `DB_MIGRATE` will be run as a shell command within an application pod as If present, `DB_MIGRATE` will be run as a shell command within an application pod as
a Helm pre-upgrade hook. a Helm pre-upgrade hook.
...@@ -362,21 +365,21 @@ For example, in a Rails application in an image built with ...@@ -362,21 +365,21 @@ For example, in a Rails application in an image built with
- `DB_INITIALIZE` can be set to `RAILS_ENV=production /bin/herokuish procfile exec bin/rails db:setup` - `DB_INITIALIZE` can be set to `RAILS_ENV=production /bin/herokuish procfile exec bin/rails db:setup`
- `DB_MIGRATE` can be set to `RAILS_ENV=production /bin/herokuish procfile exec bin/rails db:migrate` - `DB_MIGRATE` can be set to `RAILS_ENV=production /bin/herokuish procfile exec bin/rails db:migrate`
Unless you have a `Dockerfile` in your repo, your image is built with Unless your repository contains a `Dockerfile`, your image is built with
Herokuish, and you must prefix commands run in these images with `/bin/herokuish Herokuish, and you must prefix commands run in these images with `/bin/herokuish
procfile exec` to replicate the environment where your application will run. procfile exec` to replicate the environment where your application will run.
### Workers ### Workers
Some web applications need to run extra deployments for "worker processes". For Some web applications need to run extra deployments for "worker processes". For
example, it is common in a Rails application to have a separate worker process example, Rails applications commonly have a separate worker process
to run background tasks like sending emails. to run background tasks like sending emails.
The [default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app) The [default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app)
used in Auto Deploy [has support for running worker used in Auto Deploy [has support for running worker
processes](https://gitlab.com/gitlab-org/charts/auto-deploy-app/-/merge_requests/9). processes](https://gitlab.com/gitlab-org/charts/auto-deploy-app/-/merge_requests/9).
In order to run a worker, you'll need to ensure that it is able to respond to In order to run a worker, you'll need to ensure the worker can respond to
the standard health checks, which expect a successful HTTP response on port the standard health checks, which expect a successful HTTP response on port
`5000`. For [Sidekiq](https://github.com/mperham/sidekiq), you could make use of `5000`. For [Sidekiq](https://github.com/mperham/sidekiq), you could make use of
the [`sidekiq_alive` gem](https://rubygems.org/gems/sidekiq_alive) to do this. the [`sidekiq_alive` gem](https://rubygems.org/gems/sidekiq_alive) to do this.
...@@ -389,7 +392,7 @@ need to: ...@@ -389,7 +392,7 @@ need to:
- Set a CI variable `K8S_SECRET_REDIS_URL`, which the URL of this instance to - Set a CI variable `K8S_SECRET_REDIS_URL`, which the URL of this instance to
ensure it's passed into your deployments. ensure it's passed into your deployments.
Once you have configured your worker to respond to health checks, run a Sidekiq After configuring your worker to respond to health checks, run a Sidekiq
worker for your Rails application. You can enable workers by setting the worker for your Rails application. You can enable workers by setting the
following in the [`.gitlab/auto-deploy-values.yaml` file](customize.md#customize-values-for-helm-chart): following in the [`.gitlab/auto-deploy-values.yaml` file](customize.md#customize-values-for-helm-chart):
...@@ -500,8 +503,8 @@ ingress: ...@@ -500,8 +503,8 @@ ingress:
### Running commands in the container ### Running commands in the container
Applications built with [Auto Build](#auto-build) using Herokuish, the default Applications built with [Auto Build](#auto-build) using Herokuish, the default
unless you have [a custom Dockerfile](#auto-build-using-a-dockerfile), may require unless your repository contains [a custom Dockerfile](#auto-build-using-a-dockerfile),
commands to be wrapped as follows: may require commands to be wrapped as follows:
```shell ```shell
/bin/herokuish procfile exec $COMMAND /bin/herokuish procfile exec $COMMAND
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment