Skip to content

G
gitlab-ce
Commit 28aa29e8 authored by Suzanne Selhorn's avatar Suzanne Selhorn Committed by Nick Gaskill
Browse files
Options

Edited down for style and CTRT 

Related to: https://gitlab.com/gitlab-org/gitlab/-/issues/300312/
parent 590af934
Hide whitespace changes
Inline Side-by-side
Showing with 192 additions and 454 deletions
doc/api/deployments.md
View file @ 28aa29e8
......@@ -22,7 +22,7 @@ GET /projects/:id/deployments
| `sort` | string | no | Return deployments sorted in `asc` or `desc` order. Default is `asc` |
| `updated_after` | datetime | no | Return deployments updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `updated_before` | datetime | no | Return deployments updated before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `environment` | string | no | The [name of the environment](../ci/environments/index.md#defining-environments) to filter deployments by |
| `environment` | string | no | The [name of the environment](../ci/environments/index.md) to filter deployments by |
| `status` | string | no | The status to filter deployments by |
The status attribute can be one of the following values:
......@@ -281,7 +281,7 @@ POST /projects/:id/deployments
| Attribute | Type | Required | Description |
|---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `environment` | string | yes | The [name of the environment](../ci/environments/index.md#defining-environments) to create the deployment for |
| `environment` | string | yes | The [name of the environment](../ci/environments/index.md) to create the deployment for |
| `sha` | string | yes | The SHA of the commit that is deployed |
| `ref` | string | yes | The name of the branch or tag that is deployed |
| `tag` | boolean | yes | A boolean that indicates if the deployed ref is a tag (true) or not (false) |
......
doc/ci/environments/index.md
View file @ 28aa29e8
......@@ -25,229 +25,111 @@ If you have a deployment service like [Kubernetes](../../user/project/clusters/i
associated with your project, you can use it to assist with your deployments.
You can even access a [web terminal](#web-terminals) for your environment from within GitLab.
## Configuring environments
## View environments and deployments
Configuring environments involves:
1. Understanding how [pipelines](../pipelines/index.md) work.
1. Defining environments in your project's [`.gitlab-ci.yml`](../yaml/README.md) file.
1. Creating a job configured to deploy your application. For example, a deploy job configured with [`environment`](../yaml/README.md#environment) to deploy your application to a [Kubernetes cluster](../../user/project/clusters/index.md).
The rest of this section illustrates how to configure environments and deployments using
an example scenario. It assumes you have already:
- Created a [project](../../user/project/working_with_projects.md#create-a-project) in GitLab.
- Set up [a runner](../runners/README.md).
In the scenario:
- We are developing an application.
- We want to run tests and build our app on all branches.
- Our default branch is `master`.
- We deploy the app only when a pipeline on `master` branch is run.
### Defining environments
You can create environments manually in the web interface, but we recommend
that you define your environments in the `.gitlab-ci.yml` file. After the first
deploy, the environments are automatically created.
Let's consider the following `.gitlab-ci.yml` example:
```yaml
stages:
- test
- build
- deploy
test:
stage: test
script: echo "Running tests"
build:
stage: build
script: echo "Building the app"
deploy_staging:
stage: deploy
script:
- echo "Deploy to staging server"
environment:
name: staging
url: https://staging.example.com
only:
- master
```
We have defined three [stages](../yaml/README.md#stages):
- `test`
- `build`
- `deploy`
The jobs assigned to these stages run in this order. If any job fails, then
the pipeline fails and jobs that are assigned to the next stage don't run.
In our case:
Prerequisites:
- The `test` job runs first.
- Then the `build` job.
- Lastly the `deploy_staging` job.
- You must have a minimum of [Reporter permission](../../user/permissions.md#project-members-permissions).
With this configuration, we:
To view a list of environments and deployments:
- Check that the tests pass.
- Ensure that our app is able to be built successfully.
- Lastly we deploy to the staging server.
1. Go to the project's **Operations > Environments** page.
The environments are displayed.
Note that the `environment` keyword defines where the app is deployed. The environment `name` and
`url` is exposed in various places within GitLab. Each time a job that has an environment specified
succeeds, a deployment is recorded along with the Git SHA and environment name.
![Environments list](img/environments_list.png)
WARNING:
Some characters are not allowed in environment names. Use only letters,
numbers, spaces, and `-`, `_`, `/`, `{`, `}`, or `.`. Also, it must not start nor end with `/`.
1. To view a list of deployments for an environment, select the environment name,
for example, `staging`.
In summary, with the above `.gitlab-ci.yml` we have achieved the following:
![Deployments list](img/deployments_list.png)
- All branches run the `test` and `build` jobs.
- The `deploy_staging` job runs [only](../yaml/README.md#onlyexcept-basic) on the `master`
branch, which means all merge requests that are created from branches don't
get deployed to the staging server.
- When a merge request is merged, all jobs run and the `deploy_staging`
job deploys our code to a staging server while the deployment
is recorded in an environment named `staging`.
Deployments show up in this list only after a deployment job has created them.
#### CI/CD variables and runners
## Types of environments
Starting with GitLab 8.15, the environment name is exposed to the runner in
two forms:
There are two types of environments:
- `$CI_ENVIRONMENT_NAME`. The name given in `.gitlab-ci.yml` (with any CI/CD variables
expanded).
- `$CI_ENVIRONMENT_SLUG`. A "cleaned-up" version of the name, suitable for use in URLs,
DNS, etc.
- Static environments have static names, like `staging` or `production`.
- Dynamic environments have dynamic names. Dynamic environments
are a fundamental part of [Review apps](../review_apps/index.md).
If you change the name of an existing environment, the:
### Create a static environment
- `$CI_ENVIRONMENT_NAME` variable is updated with the new environment name.
- `$CI_ENVIRONMENT_SLUG` variable remains unchanged to prevent unintended side
effects.
You can create an environment and deployment in the UI or in your `.gitlab-ci.yml` file.
Starting with GitLab 9.3, the environment URL is exposed to the runner via
`$CI_ENVIRONMENT_URL`. The URL is expanded from either:
In the UI:
- `.gitlab-ci.yml`.
- The external URL from the environment if not defined in `.gitlab-ci.yml`.
1. Go to the project's **Operations > Environments** page.
1. Select **New environment**.
1. Enter a name and external URL.
1. Select **Save**.
#### Set dynamic environment URLs after a job finishes
In your `.gitlab-ci.yml` file:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17066) in GitLab 12.9.
1. Specify a name for the environment and optionally, a URL, which determines the deployment URL.
For example:
In a job script, you can specify a static [environment URL](#using-the-environment-url).
However, there may be times when you want a dynamic URL. For example,
if you deploy a Review App to an external hosting
service that generates a random URL per deployment, like `https://94dd65b.amazonaws.com/qa-lambda-1234567`,
you don't know the URL before the deployment script finishes.
If you want to use the environment URL in GitLab, you would have to update it manually.
```yaml
deploy_staging:
stage: deploy
script:
- echo "Deploy to staging server"
environment:
name: staging
url: https://staging.example.com
```
To address this problem, you can configure a deployment job to report back a set of
variables, including the URL that was dynamically-generated by the external service.
GitLab supports the [dotenv (`.env`)](https://github.com/bkeepers/dotenv) file format,
and expands the `environment:url` value with variables defined in the `.env` file.
1. Trigger a deployment. (For example, by creating and pushing a commit.)
To use this feature, specify the
[`artifacts:reports:dotenv`](../pipelines/job_artifacts.md#artifactsreportsdotenv) keyword in `.gitlab-ci.yml`.
When the job runs, the environment and deployment are created.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, see [Set dynamic URLs after a job finished](https://youtu.be/70jDXtOf4Ig).
NOTE:
Some characters cannot be used in environment names.
For more information about the `environment` keywords, see
[the `.gitlab-ci.yml` keyword reference](../yaml/README.md#environment).
##### Example of setting dynamic environment URLs
### Create a dynamic environment
The following example shows a Review App that creates a new environment
per merge request. The `review` job is triggered by every push, and
creates or updates an environment named `review/your-branch-name`.
The environment URL is set to `$DYNAMIC_ENVIRONMENT_URL`:
To create a dynamic name and URL for an environment, you can use
[predefined CI/CD variables](../variables/predefined_variables.md). For example:
```yaml
review:
script:
- DYNAMIC_ENVIRONMENT_URL=$(deploy-script) # In script, get the environment URL.
- echo "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" >> deploy.env # Add the value to a dotenv file.
artifacts:
reports:
dotenv: deploy.env # Report back dotenv file to rails.
environment:
name: review/$CI_COMMIT_REF_SLUG
url: $DYNAMIC_ENVIRONMENT_URL # and set the variable produced in script to `environment:url`
on_stop: stop_review
stop_review:
deploy_review:
stage: deploy
script:
- ./teardown-environment
when: manual
- echo "Deploy a review app"
environment:
name: review/$CI_COMMIT_REF_SLUG
action: stop
name: review/$CI_COMMIT_REF_NAME
url: https://$CI_ENVIRONMENT_SLUG.example.com
only:
- branches
except:
- master
```
As soon as the `review` job finishes, GitLab updates the `review/your-branch-name`
environment's URL.
It parses the `deploy.env` report artifact, registers a list of variables as runtime-created,
uses it for expanding `environment:url: $DYNAMIC_ENVIRONMENT_URL` and sets it to the environment URL.
You can also specify a static part of the URL at `environment:url:`, such as
`https://$DYNAMIC_ENVIRONMENT_URL`. If the value of `DYNAMIC_ENVIRONMENT_URL` is
`example.com`, the final result is `https://example.com`.
The assigned URL for the `review/your-branch-name` environment is [visible in the UI](#using-the-environment-url).
In this example:
Note the following:
- The `name` is `review/$CI_COMMIT_REF_NAME`. Because the [environment name](../yaml/README.md#environmentname)
can contain slashes (`/`), you can use this pattern to distinguish between dynamic and static environments.
- For the `url`, you could use `$CI_COMMIT_REF_NAME`, but because this value
may contain a `/` or other characters that would not be valid in a domain name or URL,
use `$CI_ENVIRONMENT_SLUG` instead. The `$CI_ENVIRONMENT_SLUG` variable is guaranteed to be unique.
- `stop_review` doesn't generate a dotenv report artifact, so it doesn't recognize the
`DYNAMIC_ENVIRONMENT_URL` environment variable. Therefore you shouldn't set `environment:url:` in the
`stop_review` job.
- If the environment URL isn't valid (for example, the URL is malformed), the system doesn't update
the environment URL.
- If the script that runs in `stop_review` exists only in your repository and therefore can't use
`GIT_STRATEGY: none`, configure [pipelines for merge requests](../../ci/merge_request_pipelines/index.md)
for these jobs. This ensures that runners can fetch the repository even after a feature branch is
deleted. For more information, see [Ref Specs for Runners](../pipelines/index.md#ref-specs-for-runners).
### Configuring manual deployments
You do not have to use the same prefix or only slashes (`/`) in the dynamic environment name.
However, when you use this format, you can use the [grouping similar environments](#grouping-similar-environments)
feature.
Adding `when: manual` to an automatically executed job's configuration converts it to
a job requiring manual action.
NOTE:
Some variables cannot be used as environment names or URLs.
For more information about the `environment` keywords, see
[the `.gitlab-ci.yml` keyword reference](../yaml/README.md#environment).
To expand on the [previous example](#defining-environments), the following includes
another job that deploys our app to a production server and is
tracked by a `production` environment.
## Configure manual deployments
The `.gitlab-ci.yml` file for this is as follows:
You can create a job that requires someone to manually start the deployment.
For example:
```yaml
stages:
- test
- build
- deploy
test:
stage: test
script: echo "Running tests"
build:
stage: build
script: echo "Building the app"
deploy_staging:
stage: deploy
script:
- echo "Deploy to staging server"
environment:
name: staging
url: https://staging.example.com
only:
- master
deploy_prod:
stage: deploy
script:
......@@ -262,106 +144,12 @@ deploy_prod:
The `when: manual` action:
- Exposes a "play" button in the GitLab UI for that job.
- Means the `deploy_prod` job is only triggered when the "play" button is clicked.
You can find the "play" button in the pipelines, environments, deployments, and jobs views.
| View | Screenshot |
|:----------------|:-------------------------------------------------------------------------------|
| Pipelines | ![Pipelines manual action](../img/environments_manual_action_pipelines.png) |
| Single pipeline | ![Pipelines manual action](../img/environments_manual_action_single_pipeline.png) |
| Environments | ![Environments manual action](../img/environments_manual_action_environments.png) |
| Deployments | ![Deployments manual action](../img/environments_manual_action_deployments.png) |
| Jobs | ![Builds manual action](../img/environments_manual_action_jobs.png) |
Clicking the play button in any view triggers the `deploy_prod` job. The deployment is recorded as a
new environment named `production`.
If your environment's name is `production` (all lowercase), it's recorded in
[Value Stream Analytics](../../user/analytics/value_stream_analytics.md).
- Exposes a play button for the job in the GitLab UI.
- Means the `deploy_prod` job is only triggered when the play button is clicked.
### Configuring dynamic environments
You can find the play button in the pipelines, environments, deployments, and jobs views.
Regular environments are good when deploying to "stable" environments like staging or production.
However, for environments for branches other than `master`, dynamic environments
can be used. Dynamic environments make it possible to create environments on the fly by
declaring their names dynamically in `.gitlab-ci.yml`.
Dynamic environments are a fundamental part of [Review apps](../review_apps/index.md).
#### Allowed variables
The `name` and `url` keywords for dynamic environments can use most available CI/CD variables,
including:
- [Predefined CI/CD variables](../variables/README.md#predefined-cicd-variables)
- [Project and group CI/CD variables](../variables/README.md)
- [`.gitlab-ci.yml` CI/CD variables](../yaml/README.md#variables)
However, you cannot use variables defined:
- Under `script`.
- On the runner's side.
There are also other variables that are unsupported in the context of `environment:name`.
For more information, see [Where variables can be used](../variables/where_variables_can_be_used.md).
#### Example configuration
Runners expose various [predefined CI/CD variables](../variables/predefined_variables.md) when a job runs, so
you can use them as environment names.
In the following example, the job deploys to all branches except `master`:
```yaml
deploy_review:
stage: deploy
script:
- echo "Deploy a review app"
environment:
name: review/$CI_COMMIT_REF_NAME
url: https://$CI_ENVIRONMENT_SLUG.example.com
only:
- branches
except:
- master
```
In this example:
- The job's name is `deploy_review` and it runs on the `deploy` stage.
- We set the `environment` with the `environment:name` as `review/$CI_COMMIT_REF_NAME`.
Since the [environment name](../yaml/README.md#environmentname) can contain slashes (`/`), we can
use this pattern to distinguish between dynamic and regular environments.
- We tell the job to run [`only`](../yaml/README.md#onlyexcept-basic) on branches,
[`except`](../yaml/README.md#onlyexcept-basic) `master`.
For the value of:
- `environment:name`, the first part is `review`, followed by a `/` and then `$CI_COMMIT_REF_NAME`,
which receives the value of the branch name.
- `environment:url`, we want a specific and distinct URL for each branch. `$CI_COMMIT_REF_NAME`
may contain a `/` or other characters that would be invalid in a domain name or URL,
so we use `$CI_ENVIRONMENT_SLUG` to guarantee that we get a valid URL.
For example, given a `$CI_COMMIT_REF_NAME` of `100-Do-The-Thing`, the URL is something
like `https://100-do-the-4f99a2.example.com`. Again, the way you set up
the web server to serve these requests is based on your setup.
We have used `$CI_ENVIRONMENT_SLUG` here because it is guaranteed to be unique. If
you're using a workflow like [GitLab Flow](../../topics/gitlab_flow.md), collisions
are unlikely and you may prefer environment names to be more closely based on the
branch name. In that case, you could use `$CI_COMMIT_REF_NAME` in `environment:url` in
the example above: `https://$CI_COMMIT_REF_NAME.example.com`, which would give a URL
of `https://100-do-the-thing.example.com`.
You aren't required to use the same prefix or only slashes (`/`) in the dynamic environments' names.
However, using this format enables the [grouping similar environments](#grouping-similar-environments)
feature.
### Configuring Kubernetes deployments
## Configure Kubernetes deployments
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6.
......@@ -402,132 +190,114 @@ trace on the deployment job page:
![Deployment cluster information](../img/environments_deployment_cluster_v12_8.png)
#### Configuring incremental rollouts
### Configure incremental rollouts
Learn how to release production changes to only a portion of your Kubernetes pods with
[incremental rollouts](../environments/incremental_rollouts.md).
### Deployment safety
## CI/CD variables for environments and deployments
Deployment jobs can be more sensitive than other jobs in a pipeline,
and might need to be treated with an extra care. There are multiple features
in GitLab that helps maintain deployment security and stability.
When you create an environment, you specify the name and URL.
- [Restrict write-access to a critical environment](deployment_safety.md#restrict-write-access-to-a-critical-environment)
- [Limit the job-concurrency for deployment jobs](deployment_safety.md#ensure-only-one-deployment-job-runs-at-a-time)
- [Skip outdated deployment jobs](deployment_safety.md#skip-outdated-deployment-jobs)
- [Prevent deployments during deploy freeze windows](deployment_safety.md#prevent-deployments-during-deploy-freeze-windows)
If you want to use the name or URL in another job, you can use:
### Complete example
- `$CI_ENVIRONMENT_NAME`. The name defined in the `.gitlab-ci.yml` file.
- `$CI_ENVIRONMENT_SLUG`. A "cleaned-up" version of the name, suitable for use in URLs,
DNS, etc. This variable is guaranteed to be unique.
- `$CI_ENVIRONMENT_URL`. The environment's URL, which was specified in the
`.gitlab-ci.yml` file or automatically assigned.
The configuration in this section provides a full development workflow where your app is:
If you change the name of an existing environment, the:
- Tested.
- Built.
- Deployed as a Review App.
- Deployed to a staging server after the merge request is merged.
- Finally, able to be manually deployed to the production server.
- `$CI_ENVIRONMENT_NAME` variable is updated with the new environment name.
- `$CI_ENVIRONMENT_SLUG` variable remains unchanged to prevent unintended side
effects.
The following combines the previous configuration examples, including:
## Set dynamic environment URLs after a job finishes
- Defining [simple environments](#defining-environments) for testing, building, and deployment to staging.
- Adding [manual actions](#configuring-manual-deployments) for deployment to production.
- Creating [dynamic environments](#configuring-dynamic-environments) for deployments for reviewing.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17066) in GitLab 12.9.
```yaml
stages:
- test
- build
- deploy
In a job script, you can specify a static environment URL.
However, there may be times when you want a dynamic URL. For example,
if you deploy a Review App to an external hosting
service that generates a random URL per deployment, like `https://94dd65b.amazonaws.com/qa-lambda-1234567`,
you don't know the URL before the deployment script finishes.
If you want to use the environment URL in GitLab, you would have to update it manually.
To address this problem, you can configure a deployment job to report back a set of
variables, including the URL that was dynamically-generated by the external service.
GitLab supports the [dotenv (`.env`)](https://github.com/bkeepers/dotenv) file format,
and expands the `environment:url` value with variables defined in the `.env` file.
test:
stage: test
script: echo "Running tests"
To use this feature, specify the
[`artifacts:reports:dotenv`](../pipelines/job_artifacts.md#artifactsreportsdotenv) keyword in `.gitlab-ci.yml`.
build:
stage: build
script: echo "Building the app"
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, see [Set dynamic URLs after a job finished](https://youtu.be/70jDXtOf4Ig).
deploy_review:
stage: deploy
script:
- echo "Deploy a review app"
environment:
name: review/$CI_COMMIT_REF_NAME
url: https://$CI_ENVIRONMENT_SLUG.example.com
only:
- branches
except:
- master
### Example of setting dynamic environment URLs
deploy_staging:
stage: deploy
script:
- echo "Deploy to staging server"
environment:
name: staging
url: https://staging.example.com
only:
- master
The following example shows a Review App that creates a new environment
per merge request. The `review` job is triggered by every push, and
creates or updates an environment named `review/your-branch-name`.
The environment URL is set to `$DYNAMIC_ENVIRONMENT_URL`:
deploy_prod:
stage: deploy
```yaml
review:
script:
- echo "Deploy to production server"
- DYNAMIC_ENVIRONMENT_URL=$(deploy-script) # In script, get the environment URL.
- echo "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" >> deploy.env # Add the value to a dotenv file.
artifacts:
reports:
dotenv: deploy.env # Report back dotenv file to rails.
environment:
name: production
url: https://example.com
when: manual
only:
- master
```
A more realistic example would also include copying files to a location where a
webserver (for example, NGINX) could then access and serve them.
The example below copies the `public` directory to `/srv/nginx/$CI_COMMIT_REF_SLUG/public`:
name: review/$CI_COMMIT_REF_SLUG
url: $DYNAMIC_ENVIRONMENT_URL # and set the variable produced in script to `environment:url`
on_stop: stop_review
```yaml
review_app:
stage: deploy
stop_review:
script:
- rsync -av --delete public /srv/nginx/$CI_COMMIT_REF_SLUG
- ./teardown-environment
when: manual
environment:
name: review/$CI_COMMIT_REF_NAME
url: https://$CI_COMMIT_REF_SLUG.example.com
name: review/$CI_COMMIT_REF_SLUG
action: stop
```
This example requires that NGINX and GitLab Runner are set up on the server this job runs on.
See the [limitations](#limitations) section for some edge cases regarding the naming of your
branches and Review Apps.
The complete example provides the following workflow to developers:
As soon as the `review` job finishes, GitLab updates the `review/your-branch-name`
environment's URL.
It parses the `deploy.env` report artifact, registers a list of variables as runtime-created,
uses it for expanding `environment:url: $DYNAMIC_ENVIRONMENT_URL` and sets it to the environment URL.
You can also specify a static part of the URL at `environment:url:`, such as
`https://$DYNAMIC_ENVIRONMENT_URL`. If the value of `DYNAMIC_ENVIRONMENT_URL` is
`example.com`, the final result is `https://example.com`.
- Create a branch locally.
- Make changes and commit them.
- Push the branch to GitLab.
- Create a merge request.
The assigned URL for the `review/your-branch-name` environment is visible in the UI.
Behind the scenes, the runner:
Note the following:
- Picks up the changes and starts running the jobs.
- Runs the jobs sequentially as defined in `stages`:
- First, run the tests.
- If the tests succeed, build the app.
- If the build succeeds, the app is deployed to an environment with a name specific to the
branch.
- `stop_review` doesn't generate a dotenv report artifact, so it doesn't recognize the
`DYNAMIC_ENVIRONMENT_URL` environment variable. Therefore you shouldn't set `environment:url:` in the
`stop_review` job.
- If the environment URL isn't valid (for example, the URL is malformed), the system doesn't update
the environment URL.
- If the script that runs in `stop_review` exists only in your repository and therefore can't use
`GIT_STRATEGY: none`, configure [pipelines for merge requests](../../ci/merge_request_pipelines/index.md)
for these jobs. This ensures that runners can fetch the repository even after a feature branch is
deleted. For more information, see [Ref Specs for Runners](../pipelines/index.md#ref-specs-for-runners).
So now, every branch:
## Deployment safety
- Gets its own environment.
- Is deployed to its own unique location, with the added benefit of:
- Having a [history of deployments](#view-the-deployment-history).
- Being able to [roll back changes](#retry-or-roll-back-a-deployment) if needed.
Deployment jobs can be more sensitive than other jobs in a pipeline,
and might need to be treated with an extra care. There are multiple features
in GitLab that help maintain deployment security and stability.
For more information, see [Using the environment URL](#using-the-environment-url).
- [Restrict write-access to a critical environment](deployment_safety.md#restrict-write-access-to-a-critical-environment)
- [Limit the job-concurrency for deployment jobs](deployment_safety.md#ensure-only-one-deployment-job-runs-at-a-time)
- [Skip outdated deployment jobs](deployment_safety.md#skip-outdated-deployment-jobs)
- [Prevent deployments during deploy freeze windows](deployment_safety.md#prevent-deployments-during-deploy-freeze-windows)
### Protected environments
## Protected environments
Environments can be "protected", restricting access to them.
......@@ -538,36 +308,16 @@ For more information, see [Protected environments](protected_environments.md).
Once environments are configured, GitLab provides many features for working with them,
as documented below.
### View environments and deployments
### Environment rollback
Prerequisites:
- You must have a minimum of [Reporter permission](../../user/permissions.md#project-members-permissions).
To view a list of environments and deployment statuses:
- Go to the project's **Operations > Environments** page.
The **Environments** page shows the latest deployments.
- An environment can have multiple deployments. Some deployments may not be listed on the page.
- Only deploys that happen after your `.gitlab-ci.yml` is properly configured
show up in the **Environment** and **Last deployment** lists.
### View the deployment history
When you roll back a deployment on a specific commit,
a _new_ deployment is created. This deployment has its own unique job ID.
It points to the commit you're rolling back to.
GitLab tracks your deployments, so you:
For the rollback to succeed, the deployment process must be defined in
the job's `script`.
- Always know what is currently deployed on your servers.
- Have the full history of your deployments for every environment.
- Go to the project's **Operations > Environments** page.
![Deployments](../img/deployments_view.png)
This view is similar to the **Environments** page, but all deployments are shown.
### Retry or roll back a deployment
#### Retry or roll back a deployment
If there is a problem with a deployment, you can retry it or roll it back.
......@@ -575,32 +325,23 @@ To retry or rollback a deployment:
1. Go to the project's **Operations > Environments**.
1. Select the environment.
1. In the deployment history list for the environment:
- To retry a deployment, select **Retry**.
- to roll back to a deployment, next to a previously successful deployment, select **Rollback**.
1. To the right of the deployment name:
- To retry a deployment, select **Re-deploy to environment**.
- To roll back to a deployment, next to a previously successful deployment, select **Rollback environment**.
#### What to expect with a rollback
Pressing the **Rollback** button on a specific commit triggers a _new_ deployment with its own
unique job ID. This new deployment points to the commit you're
rolling back to.
Note that the defined deployment process in the job's `script` determines whether the rollback
succeeds.
### Using the environment URL
### Environment URL
The [environment URL](../yaml/README.md#environmenturl) is exposed in a few
places within GitLab:
- In a merge request widget as a link:
- In a merge request as a link:
![Environment URL in merge request](../img/environments_mr_review_app.png)
- In the Environments view as a button:
![Environment URL in environments](../img/environments_available_13_7.png)
![Environment URL in environments](../img/environments_available_13_10.png)
- In the Deployments view as a button:
![Environment URL in deployments](../img/deployments_view.png)
You can see this information in a merge request itself if:
You can see this information in a merge request if:
- The merge request is eventually merged to the default branch (usually `master`).
- That branch also deploys to an environment (for example, `staging` or `production`).
......@@ -616,19 +357,16 @@ from source files to public pages in the environment set for Review Apps.
### Stopping an environment
Stopping an environment:
When you stop an environment:
- Moves it from the list of **Available** environments to the list of **Stopped**
- It moves from the list of **Available** environments to the list of **Stopped**
environments on the [**Environments** page](#view-environments-and-deployments).
- Executes an [`on_stop` action](../yaml/README.md#environmenton_stop), if defined.
This is often used when multiple developers are working on a project at the same time,
each of them pushing to their own branches, causing many dynamic environments to be created.
- An [`on_stop` action](../yaml/README.md#environmenton_stop), if defined, is executed.
Starting with GitLab 8.14, dynamic environments stop automatically when their associated branch is
Dynamic environments stop automatically when their associated branch is
deleted.
#### Automatically stopping an environment
#### Stop an environment when a branch is deleted
Environments can be stopped automatically using special configuration.
......@@ -678,7 +416,7 @@ possible to trigger `action: stop` to stop the environment automatically.
You can read more in the [`.gitlab-ci.yml` reference](../yaml/README.md#environmenton_stop).
#### Environments auto-stop
#### Stop an environment after a certain time period
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8.
......@@ -763,7 +501,7 @@ environment name to see its details and **Delete** it from there.
You can also delete environments by viewing the details for a
stopped environment:
1. Navigate to **Operations > Environments**.
1. Go to the project's **Operations > Environments** page.
1. Click on the name of an environment within the **Stopped** environments list.
1. Click on the **Delete** button that appears at the top for all stopped environments.
1. Finally, confirm your chosen environment in the modal that appears to delete it.
......@@ -776,7 +514,7 @@ Environments can also be deleted by using the [Environments API](../../api/envir
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208655) in GitLab 13.2.
By default, GitLab creates a [deployment](#view-the-deployment-history) every time a
By default, GitLab creates a deployment every time a
build with the specified environment runs. Newer deployments can also
[cancel older ones](deployment_safety.md#skip-outdated-deployment-jobs).
......@@ -801,15 +539,15 @@ build:
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7015) in GitLab 8.14.
As documented in [Configuring dynamic environments](#configuring-dynamic-environments), you can
As documented in [Create a dynamic environment](#create-a-dynamic-environment), you can
prepend environment name with a word, followed by a `/`, and finally the branch
name, which is automatically defined by the `CI_COMMIT_REF_NAME` predefined CI/CD variable.
In short, environments that are named like `type/foo` are all presented under the same
group, named `type`.
In our [minimal example](#example-configuration), we named the environments `review/$CI_COMMIT_REF_NAME`
where `$CI_COMMIT_REF_NAME` is the branch name. Here is a snippet of the example:
If you name the environments `review/$CI_COMMIT_REF_NAME`
where `$CI_COMMIT_REF_NAME` is the branch name:
```yaml
deploy_review:
......@@ -820,7 +558,7 @@ deploy_review:
name: review/$CI_COMMIT_REF_NAME
```
In this case, if you visit the **Environments** page and the branches
If you visit the **Environments** page and the branches
exist, you should see something like:
![Environment groups](../img/environments_dynamic_groups.png)
......
doc/ci/img/deployments_view.png
View replaced file @ 590af934 View file @ 28aa29e8
doc/ci/img/deployments_view.png

23 KB | W: | H:

doc/ci/img/deployments_view.png

39.4 KB | W: | H:

doc/ci/img/deployments_view.png
doc/ci/img/deployments_view.png
doc/ci/img/deployments_view.png
doc/ci/img/deployments_view.png
  • 2-up
  • Swipe
  • Onion skin
doc/ci/pipelines/index.md
View file @ 28aa29e8
......@@ -96,7 +96,7 @@ This table lists the refspecs injected for each pipeline type:
The refs `refs/heads/<name>` and `refs/tags/<name>` exist in your
project repository. GitLab generates the special ref `refs/pipelines/<id>` during a
running pipeline job. This ref can be created even after the associated branch or tag has been
deleted. It's therefore useful in some features such as [automatically stopping an environment](../environments/index.md#automatically-stopping-an-environment),
deleted. It's therefore useful in some features such as [automatically stopping an environment](../environments/index.md#stopping-an-environment),
and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md)
that might run pipelines after branch deletion.
......@@ -208,7 +208,7 @@ You can do this straight from the pipeline graph. Just click the play button
to execute that particular job.
For example, your pipeline might start automatically, but it requires manual action to
[deploy to production](../environments/index.md#configuring-manual-deployments). In the example below, the `production`
[deploy to production](../environments/index.md#configure-manual-deployments). In the example below, the `production`
stage has a job with a manual action.
![Pipelines example](img/pipelines.png)
......
doc/ci/review_apps/index.md
View file @ 28aa29e8
......@@ -56,7 +56,7 @@ After adding Review Apps to your workflow, you follow the branched Git flow. Tha
## Configuring Review Apps
Review Apps are built on [dynamic environments](../environments/index.md#configuring-dynamic-environments), which allow you to dynamically create a new environment for each branch.
Review Apps are built on [dynamic environments](../environments/index.md#create-a-dynamic-environment), which allow you to dynamically create a new environment for each branch.
The process of configuring Review Apps is as follows:
......@@ -89,7 +89,7 @@ you can copy and paste into `.gitlab-ci.yml` as a starting point. To do so:
## Review Apps auto-stop
See how to [configure Review Apps environments to expire and auto-stop](../environments/index.md#environments-auto-stop)
See how to [configure Review Apps environments to expire and auto-stop](../environments/index.md#stop-an-environment-after-a-certain-time-period)
after a given period of time.
## Review Apps examples
......
doc/ci/yaml/README.md
View file @ 28aa29e8
......@@ -2322,7 +2322,7 @@ started by a user. You might want to use manual jobs for things like deploying t
To make a job manual, add `when: manual` to its configuration.
Manual jobs can be started from the pipeline, job, [environment](../environments/index.md#configuring-manual-deployments),
Manual jobs can be started from the pipeline, job, [environment](../environments/index.md#configure-manual-deployments),
and deployment views.
Manual jobs can be either optional or blocking:
......@@ -2562,7 +2562,7 @@ it is set to `manual`, so it needs a [manual action](#whenmanual) from
the GitLab UI to run.
Also in the example, `GIT_STRATEGY` is set to `none`. If the
`stop_review_app` job is [automatically triggered](../environments/index.md#automatically-stopping-an-environment),
`stop_review_app` job is [automatically triggered](../environments/index.md#stopping-an-environment),
the runner won’t try to check out the code after the branch is deleted.
The example also overwrites global variables. If your `stop` `environment` job depends
......@@ -2608,7 +2608,7 @@ When the environment for `review_app` is created, the environment's lifetime is
Every time the review app is deployed, that lifetime is also reset to `1 day`.
For more information, see
[the environments auto-stop documentation](../environments/index.md#environments-auto-stop)
[the environments auto-stop documentation](../environments/index.md#stop-an-environment-after-a-certain-time-period)
#### `environment:kubernetes`
......@@ -2634,7 +2634,7 @@ environment, using the `production`
[Kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/).
For more information, see
[Available settings for `kubernetes`](../environments/index.md#configuring-kubernetes-deployments).
[Available settings for `kubernetes`](../environments/index.md#configure-kubernetes-deployments).
NOTE:
Kubernetes configuration is not supported for Kubernetes clusters
......
doc/development/testing_guide/review_apps.md
View file @ 28aa29e8
......@@ -109,7 +109,7 @@ subgraph "CNG-mirror pipeline"
### Auto-stopping of Review Apps
Review Apps are automatically stopped 2 days after the last deployment thanks to
the [Environment auto-stop](../../ci/environments/index.md#environments-auto-stop) feature.
the [Environment auto-stop](../../ci/environments/index.md#stop-an-environment-after-a-certain-time-period) feature.
If you need your Review App to stay up for a longer time, you can
[pin its environment](../../ci/environments/index.md#auto-stop-example) or retry the
......
doc/topics/autodevops/customize.md
View file @ 28aa29e8
......@@ -204,7 +204,7 @@ into your project and edit it as needed.
For clusters not managed by GitLab, you can customize the namespace in
`.gitlab-ci.yml` by specifying
[`environment:kubernetes:namespace`](../../ci/environments/index.md#configuring-kubernetes-deployments).
[`environment:kubernetes:namespace`](../../ci/environments/index.md#configure-kubernetes-deployments).
For example, the following configuration overrides the namespace used for
`production` deployments:
......
doc/user/project/clusters/index.md
View file @ 28aa29e8
......@@ -312,7 +312,7 @@ following command in your deployment job script, for Kubernetes to access the re
The Kubernetes cluster integration exposes these
[deployment variables](../../../ci/variables/README.md#deployment-variables) in the
GitLab CI/CD build environment to deployment jobs. Deployment jobs have
[defined a target environment](../../../ci/environments/index.md#defining-environments).
[defined a target environment](../../../ci/environments/index.md).
| Deployment Variable | Description |
|----------------------------|-------------|
......@@ -345,7 +345,7 @@ You can customize the deployment namespace in a few ways:
- For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`,
but the user is responsible for ensuring its existence. You can fully customize
this value using
[`environment:kubernetes:namespace`](../../../ci/environments/index.md#configuring-kubernetes-deployments)
[`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments)
in `.gitlab-ci.yml`.
When you customize the namespace, existing environments remain linked to their current
......@@ -432,7 +432,7 @@ Reasons for failure include:
- The token you gave GitLab does not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
privileges required by GitLab.
- Missing `KUBECONFIG` or `KUBE_TOKEN` deployment variables. To be passed to your job, they must have a matching
[`environment:name`](../../../ci/environments/index.md#defining-environments). If your job has no
[`environment:name`](../../../ci/environments/index.md). If your job has no
`environment:name` set, the Kubernetes credentials are not passed to it.
NOTE:
......
doc/user/project/deploy_boards.md
View file @ 28aa29e8
......@@ -75,7 +75,7 @@ specific environment, there are a lot of use cases. To name a few:
To display the Deploy Boards for a specific [environment](../../ci/environments/index.md) you should:
1. Have [defined an environment](../../ci/environments/index.md#defining-environments) with a deploy stage.
1. Have [defined an environment](../../ci/environments/index.md) with a deploy stage.
1. Have a Kubernetes cluster up and running.
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7