WIP refactor environments
This commit is contained in:
parent
b7aae9a6cd
commit
6715091bbc
|
@ -3,16 +3,148 @@
|
|||
>**Note:**
|
||||
Introduced in GitLab 8.9.
|
||||
|
||||
## Environments
|
||||
During the development of a software there can be many stages until it's ready
|
||||
for public consumption. You sure want to first see your code in a testing or
|
||||
staging environment before you release it to the public. That way you can
|
||||
prevent bugs not only in your software, but in the deployment process as well.
|
||||
|
||||
With environments you can control the Continuous Deployment of your software all
|
||||
within GitLab. All you need to do is define them in your project's
|
||||
[`.gitlab-ci.yml`][yaml].
|
||||
|
||||
In the following sections, we'll see how that works.
|
||||
|
||||
## An environments example
|
||||
|
||||
Let's assume that you have
|
||||
|
||||
1. Define the environments in `.gitlab-ci.yml`
|
||||
1. Push the repository to GitLab
|
||||
1. Runner picks up the job
|
||||
1. The job finishes successfully
|
||||
1. The environments get created if they don't already exist
|
||||
1. A deployment is recorded remembering the environment name and the Git SHA of
|
||||
the last commit of the pipeline
|
||||
|
||||
Further runs of the CI will
|
||||
|
||||
Actions
|
||||
|
||||
View environments
|
||||
View deployments
|
||||
Rollback deployments
|
||||
Run deployments
|
||||
View link to environment URL
|
||||
View last commit message of deployment
|
||||
View person who performed the deployment
|
||||
View commit SHA that triggered the deployment
|
||||
View branch the deployment was based on
|
||||
View time ago the deployment was performed
|
||||
|
||||
Environments are like tags for your CI jobs, describing where code gets deployed.
|
||||
|
||||
You can think of names such as testing, staging or production.
|
||||
|
||||
Environments are places where code gets deployed, such as staging or production.
|
||||
CI/CD [Pipelines] usually have one or more [jobs] that deploy to an environment.
|
||||
|
||||
Defining environments in a project's `.gitlab-ci.yml` lets developers track
|
||||
[deployments] to these environments.
|
||||
|
||||
## Deployments
|
||||
The environments page can only be viewed by Reporters and above. For more
|
||||
information on the permissions, see the [permissions documentation][permissions].
|
||||
|
||||
Deployments are created when [jobs] deploy versions of code to [environments].
|
||||
### Defining environments
|
||||
|
||||
While you can create and delete environments manually in the web interface, we
|
||||
recommend that you define your environments in `.gitlab-ci.yml` first. They will
|
||||
be automatically created for you after the first deploy.
|
||||
|
||||
The `environment` keyword is just a hint for GitLab that this job actually
|
||||
deploys to this environment. Each time the job succeeds, a deployment is
|
||||
recorded, remembering the Git SHA and environment name.
|
||||
|
||||
Add something like this to your `.gitlab-ci.yml`:
|
||||
|
||||
```
|
||||
production:
|
||||
stage: deploy
|
||||
script: make deploy-to-prod
|
||||
environment:
|
||||
name: production
|
||||
```
|
||||
|
||||
See the [yaml definition](yaml/README.md#environment) of environments.
|
||||
|
||||
### View the environment status
|
||||
|
||||
GitLab keeps track of your deployments, so you always know what is currently
|
||||
being deployed on your servers. You can find the environment list under
|
||||
**Pipelines > Environments** for your project. You'll see the git SHA and date
|
||||
of the last deployment to each environment defined.
|
||||
|
||||
![Environments](img/environments_view.png)
|
||||
|
||||
>**Note:**
|
||||
Only deploys that happen after your `.gitlab-ci.yml` is properly configured will
|
||||
show up in the "Environment" and "Last deployment" lists.
|
||||
|
||||
## Manually deploying to environments
|
||||
|
||||
|
||||
## Dynamic environments
|
||||
|
||||
As the name suggests, it is possible to create environments on the fly by just
|
||||
declaring their names dynamically in `.gitlab-ci.yml`.
|
||||
|
||||
GitLab Runner exposes various [environment variables][variables] when a job runs,
|
||||
and as such you can use them
|
||||
|
||||
```
|
||||
review:
|
||||
stage: deploy
|
||||
script:
|
||||
- rsync -av --delete public /srv/nginx/pages/$CI_BUILD_REF_NAME
|
||||
environment:
|
||||
name: review/$CI_BUILD_REF_NAME
|
||||
url: https://$CI_BUILD_REF_NAME.example.com
|
||||
```
|
||||
|
||||
### Closing an environment
|
||||
|
||||
```
|
||||
review:
|
||||
stage: deploy
|
||||
script:
|
||||
- rsync -av --delete public /srv/nginx/pages/$CI_BUILD_REF_NAME
|
||||
environment:
|
||||
name: review/$CI_BUILD_REF_NAME
|
||||
url: http://$CI_BUILD_REF_NAME.$APPS_DOMAIN
|
||||
on_stop: stop_review
|
||||
|
||||
stop_review:
|
||||
script: rm -rf /srv/nginx/pages/$CI_BUILD_REF_NAME
|
||||
when: manual
|
||||
environment:
|
||||
name: review/$CI_BUILD_REF_NAME
|
||||
action: stop
|
||||
```
|
||||
|
||||
## The relationship between deployments and environments
|
||||
|
||||
Deployments are created when [jobs] deploy versions of code to [environments],
|
||||
so every environment can have one or more deployments. GitLab keeps track of
|
||||
your deployments, so you always know what is currently being deployed on your
|
||||
servers.
|
||||
|
||||
### View the deployment history
|
||||
|
||||
Clicking on an environment will show the history of deployments.
|
||||
|
||||
![Deployments](img/deployments_view.png)
|
||||
|
||||
>**Note:**
|
||||
Only deploys that happen after your `.gitlab-ci.yml` is properly configured will
|
||||
show up in the environments and deployments lists.
|
||||
|
||||
### Checkout deployments locally
|
||||
|
||||
|
@ -27,45 +159,10 @@ fetch line:
|
|||
fetch = +refs/environments/*:refs/remotes/origin/environments/*
|
||||
```
|
||||
|
||||
## Defining environments
|
||||
|
||||
You can create and delete environments manually in the web interface, but we
|
||||
recommend that you define your environments in `.gitlab-ci.yml` first, which
|
||||
will automatically create environments for you after the first deploy.
|
||||
|
||||
The `environment` is just a hint for GitLab that this job actually deploys to
|
||||
this environment. Each time the job succeeds, a deployment is recorded,
|
||||
remembering the git SHA and environment.
|
||||
|
||||
Add something like this to your `.gitlab-ci.yml`:
|
||||
```
|
||||
production:
|
||||
stage: deploy
|
||||
script: dpl...
|
||||
environment: production
|
||||
```
|
||||
|
||||
See full [documentation](yaml/README.md#environment).
|
||||
|
||||
## Seeing environment status
|
||||
|
||||
You can find the environment list under **Pipelines > Environments** for your
|
||||
project. You'll see the git SHA and date of the last deployment to each
|
||||
environment defined.
|
||||
|
||||
>**Note:**
|
||||
Only deploys that happen after your `.gitlab-ci.yml` is properly configured will
|
||||
show up in the environments and deployments lists.
|
||||
|
||||
## Seeing deployment history
|
||||
|
||||
Clicking on an environment will show the history of deployments.
|
||||
|
||||
>**Note:**
|
||||
Only deploys that happen after your `.gitlab-ci.yml` is properly configured will
|
||||
show up in the environments and deployments lists.
|
||||
|
||||
[Pipelines]: pipelines.md
|
||||
[jobs]: yaml/README.md#jobs
|
||||
[yaml]: yaml/README.md
|
||||
[environments]: #environments
|
||||
[deployments]: #deployments
|
||||
[permissions]: ../user/permissions.md
|
||||
[variables]: variables/README.md
|
||||
|
|
Binary file not shown.
After Width: | Height: | Size: 176 KiB |
Binary file not shown.
After Width: | Height: | Size: 56 KiB |
|
@ -573,7 +573,8 @@ In its simplest form, the `environment` keyword can be defined like:
|
|||
deploy to production:
|
||||
stage: deploy
|
||||
script: git push production HEAD:master
|
||||
environment: production
|
||||
environment:
|
||||
name: production
|
||||
```
|
||||
|
||||
In the above example, the `deploy to production` job will be marked as doing a
|
||||
|
@ -673,6 +674,61 @@ The `stop_review_app` job is **required** to have the following keywords defined
|
|||
- `environment:name`
|
||||
- `environment:action`
|
||||
|
||||
#### environment:name
|
||||
|
||||
#### environment:url
|
||||
|
||||
Optional.
|
||||
|
||||
#### environment:on_stop
|
||||
|
||||
> [Introduced][ce-6669] in GitLab 8.13.
|
||||
|
||||
Closing environments can be achieved with the `on_stop` keyword defined under
|
||||
`environment`. It declares a different job that has to be run in order to close
|
||||
the environment.
|
||||
|
||||
This job is required to have the following keywords defined:
|
||||
|
||||
- `when` - [reference](#when)
|
||||
- `environment:name`
|
||||
- `environment:action` - reference below
|
||||
|
||||
See below for an example.
|
||||
|
||||
#### environment:action
|
||||
|
||||
> [Introduced][ce-6669] in GitLab 8.13.
|
||||
|
||||
The `action` keyword is to be used in conjunction with `on_stop` and is defined
|
||||
in the job that depends on the one that was called from.
|
||||
|
||||
Take for instance:
|
||||
|
||||
```yaml
|
||||
review:
|
||||
stage: deploy
|
||||
script: make deploy-app
|
||||
environment:
|
||||
name: review
|
||||
on_stop: stop_review
|
||||
|
||||
stop_review:
|
||||
stage: deploy
|
||||
script: make delete-app
|
||||
when: manual
|
||||
environment:
|
||||
name: review
|
||||
action: stop
|
||||
```
|
||||
|
||||
In the above example we set up the `review` job to deploy to the `review`
|
||||
environment, and we also defined a new `stop_review` job under `on_stop`.
|
||||
Once the `review` job is successfully finished, it will trigger the `stop_review`
|
||||
job based on what is defined under `when`. In this case we set it up to `manual`
|
||||
so it will need a [manual action](#manual-actions) via GitLab's web interface
|
||||
in order to run.
|
||||
|
||||
#### dynamic environments
|
||||
|
||||
> [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6.
|
||||
|
@ -681,7 +737,9 @@ The `stop_review_app` job is **required** to have the following keywords defined
|
|||
These parameters can use any of the defined [CI variables](#variables)
|
||||
(including predefined, secure variables and `.gitlab-ci.yml` variables).
|
||||
|
||||
For example:
|
||||
---
|
||||
|
||||
**Example configurations**
|
||||
|
||||
```
|
||||
deploy as review app:
|
||||
|
|
|
@ -32,6 +32,8 @@ The following table depicts the various user permission levels in a project.
|
|||
| See a commit status | | ✓ | ✓ | ✓ | ✓ |
|
||||
| See a container registry | | ✓ | ✓ | ✓ | ✓ |
|
||||
| See environments | | ✓ | ✓ | ✓ | ✓ |
|
||||
| Create new environments | | | ✓ | ✓ | ✓ |
|
||||
| Delete environments | | | | ✓ | ✓ |
|
||||
| See a list of merge requests | | ✓ | ✓ | ✓ | ✓ |
|
||||
| Manage/Accept merge requests | | | ✓ | ✓ | ✓ |
|
||||
| Create new merge request | | | ✓ | ✓ | ✓ |
|
||||
|
@ -45,7 +47,6 @@ The following table depicts the various user permission levels in a project.
|
|||
| Create or update commit status | | | ✓ | ✓ | ✓ |
|
||||
| Update a container registry | | | ✓ | ✓ | ✓ |
|
||||
| Remove a container registry image | | | ✓ | ✓ | ✓ |
|
||||
| Create new environments | | | ✓ | ✓ | ✓ |
|
||||
| Create new milestones | | | | ✓ | ✓ |
|
||||
| Add new team members | | | | ✓ | ✓ |
|
||||
| Push to protected branches | | | | ✓ | ✓ |
|
||||
|
@ -58,7 +59,6 @@ The following table depicts the various user permission levels in a project.
|
|||
| Manage runners | | | | ✓ | ✓ |
|
||||
| Manage build triggers | | | | ✓ | ✓ |
|
||||
| Manage variables | | | | ✓ | ✓ |
|
||||
| Delete environments | | | | ✓ | ✓ |
|
||||
| Switch visibility level | | | | | ✓ |
|
||||
| Transfer project to another namespace | | | | | ✓ |
|
||||
| Remove project | | | | | ✓ |
|
||||
|
|
Loading…
Reference in New Issue