WIP refactor environments
This commit is contained in:
parent
b7aae9a6cd
commit
6715091bbc
|
@ -3,16 +3,148 @@
|
||||||
>**Note:**
|
>**Note:**
|
||||||
Introduced in GitLab 8.9.
|
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.
|
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
|
Defining environments in a project's `.gitlab-ci.yml` lets developers track
|
||||||
[deployments] to these environments.
|
[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
|
### Checkout deployments locally
|
||||||
|
|
||||||
|
@ -27,45 +159,10 @@ fetch line:
|
||||||
fetch = +refs/environments/*:refs/remotes/origin/environments/*
|
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
|
[Pipelines]: pipelines.md
|
||||||
[jobs]: yaml/README.md#jobs
|
[jobs]: yaml/README.md#jobs
|
||||||
|
[yaml]: yaml/README.md
|
||||||
[environments]: #environments
|
[environments]: #environments
|
||||||
[deployments]: #deployments
|
[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:
|
deploy to production:
|
||||||
stage: deploy
|
stage: deploy
|
||||||
script: git push production HEAD:master
|
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
|
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:name`
|
||||||
- `environment:action`
|
- `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
|
#### dynamic environments
|
||||||
|
|
||||||
> [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6.
|
> [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)
|
These parameters can use any of the defined [CI variables](#variables)
|
||||||
(including predefined, secure variables and `.gitlab-ci.yml` variables).
|
(including predefined, secure variables and `.gitlab-ci.yml` variables).
|
||||||
|
|
||||||
For example:
|
---
|
||||||
|
|
||||||
|
**Example configurations**
|
||||||
|
|
||||||
```
|
```
|
||||||
deploy as review app:
|
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 commit status | | ✓ | ✓ | ✓ | ✓ |
|
||||||
| See a container registry | | ✓ | ✓ | ✓ | ✓ |
|
| See a container registry | | ✓ | ✓ | ✓ | ✓ |
|
||||||
| See environments | | ✓ | ✓ | ✓ | ✓ |
|
| See environments | | ✓ | ✓ | ✓ | ✓ |
|
||||||
|
| Create new environments | | | ✓ | ✓ | ✓ |
|
||||||
|
| Delete environments | | | | ✓ | ✓ |
|
||||||
| See a list of merge requests | | ✓ | ✓ | ✓ | ✓ |
|
| See a list of merge requests | | ✓ | ✓ | ✓ | ✓ |
|
||||||
| Manage/Accept merge requests | | | ✓ | ✓ | ✓ |
|
| Manage/Accept merge requests | | | ✓ | ✓ | ✓ |
|
||||||
| Create new merge request | | | ✓ | ✓ | ✓ |
|
| 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 | | | ✓ | ✓ | ✓ |
|
| Create or update commit status | | | ✓ | ✓ | ✓ |
|
||||||
| Update a container registry | | | ✓ | ✓ | ✓ |
|
| Update a container registry | | | ✓ | ✓ | ✓ |
|
||||||
| Remove a container registry image | | | ✓ | ✓ | ✓ |
|
| Remove a container registry image | | | ✓ | ✓ | ✓ |
|
||||||
| Create new environments | | | ✓ | ✓ | ✓ |
|
|
||||||
| Create new milestones | | | | ✓ | ✓ |
|
| Create new milestones | | | | ✓ | ✓ |
|
||||||
| Add new team members | | | | ✓ | ✓ |
|
| Add new team members | | | | ✓ | ✓ |
|
||||||
| Push to protected branches | | | | ✓ | ✓ |
|
| Push to protected branches | | | | ✓ | ✓ |
|
||||||
|
@ -58,7 +59,6 @@ The following table depicts the various user permission levels in a project.
|
||||||
| Manage runners | | | | ✓ | ✓ |
|
| Manage runners | | | | ✓ | ✓ |
|
||||||
| Manage build triggers | | | | ✓ | ✓ |
|
| Manage build triggers | | | | ✓ | ✓ |
|
||||||
| Manage variables | | | | ✓ | ✓ |
|
| Manage variables | | | | ✓ | ✓ |
|
||||||
| Delete environments | | | | ✓ | ✓ |
|
|
||||||
| Switch visibility level | | | | | ✓ |
|
| Switch visibility level | | | | | ✓ |
|
||||||
| Transfer project to another namespace | | | | | ✓ |
|
| Transfer project to another namespace | | | | | ✓ |
|
||||||
| Remove project | | | | | ✓ |
|
| Remove project | | | | | ✓ |
|
||||||
|
|
Loading…
Reference in New Issue