Commit 6715091b authored by Achilleas Pipinellis's avatar Achilleas Pipinellis 🚀

WIP refactor environments

parent b7aae9a6
......@@ -3,69 +3,166 @@
>**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
### Checkout deployments locally
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.
Since 8.13, a reference in the git repository is saved for each deployment. So
knowing what the state is of your current environments is only a `git fetch`
away.
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.
In your git config, append the `[remote "<your-remote>"]` block with an extra
fetch line:
Add something like this to your `.gitlab-ci.yml`:
```
fetch = +refs/environments/*:refs/remotes/origin/environments/*
production:
stage: deploy
script: make deploy-to-prod
environment:
name: production
```
## Defining environments
See the [yaml definition](yaml/README.md#environment) of 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.
### View the environment status
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.
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
Add something like this to your `.gitlab-ci.yml`:
```
production:
review:
stage: deploy
script: dpl...
environment: production
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
```
See full [documentation](yaml/README.md#environment).
### Closing an environment
## Seeing environment status
```
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
```
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.
## The relationship between deployments and environments
>**Note:**
Only deploys that happen after your `.gitlab-ci.yml` is properly configured will
show up in the environments and deployments lists.
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.
## Seeing deployment history
### 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
Since 8.13, a reference in the git repository is saved for each deployment. So
knowing what the state is of your current environments is only a `git fetch`
away.
In your git config, append the `[remote "<your-remote>"]` block with an extra
fetch line:
```
fetch = +refs/environments/*:refs/remotes/origin/environments/*
```
[Pipelines]: pipelines.md
[jobs]: yaml/README.md#jobs
[yaml]: yaml/README.md
[environments]: #environments
[deployments]: #deployments
[permissions]: ../user/permissions.md
[variables]: variables/README.md
......@@ -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 | | | | | ✓ |
......
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