| title | description | ms.topic | ms.assetid | ms.date | monikerRange |
|---|---|---|---|---|---|
Create target environment |
Collection of deployment targets useful for traceability and recording deployment history. |
how-to |
4abec444-5d74-4959-832d-20fd0acee81d |
04/26/2022 |
>= azure-devops-2020 |
[!INCLUDE version-gt-eq-2020]
An environment is a collection of resources that you can target with deployments from a pipeline. Typical examples of environment names are Dev, Test, QA, Staging, and Production.
Environments provide the following benefits.
| Benefit | Description |
|---|---|
| Deployment history | Pipeline name and run details get recorded for deployments to an environment and its resources. In the context of multiple pipelines targeting the same environment or resource, deployment history of an environment is useful to identify the source of changes. |
| Traceability of commits and work items | View jobs within the pipeline run that target an environment. You can also view the commits and work items that were newly deployed to the environment. Traceability also allows one to track whether a code change (commit) or feature/bug-fix (work items) reached an environment. |
| Diagnostic resource health | Validate whether the application is functioning at its wanted state. |
| Security | Secure environments by specifying which users and pipelines are allowed to target an environment. |
While an environment is a grouping of resources, the resources themselves represent actual deployment targets. The Kubernetes resource and virtual machine resource types are currently supported.
When you author a YAML pipeline and refer to an environment that does not exist, Azure Pipelines automatically creates the environment when the user performing the operation is known and permissions can be assigned. When Azure Pipelines does not have information about the user creating the environment (example: a YAML update from an external code editor), your pipeline will fail if the environment does not already exist.
-
Sign in to your organization:
https://dev.azure.com/{yourorganization}and select your project. -
Select Pipelines > Environments > Create environment.
[!div class="mx-imgBorder"]
-
Enter information for the environment, and then select Create. Resources can be added to an existing environment later.
:::image type="content" source="media/create-new-environment.png" alt-text="Screenshot of creating a new environment.":::
Use a Pipeline to create and deploy to environments, too. For more information, see the how-to guide.
Tip
You can create an empty environment and reference it from deployment jobs. This lets you record the deployment history against the environment.
A deployment job is a collection of steps to be run sequentially. A deployment job can be used to target an entire environment (group of resources) as shown in the following YAML snippet.
- stage: deploy
jobs:
- deployment: DeployWeb
displayName: deploy Web App
pool:
vmImage: 'Ubuntu-latest'
# creates an environment if it doesn't exist
environment: 'smarthotel-dev'
strategy:
runOnce:
deploy:
steps:
- script: echo Hello worldYou can scope the target of deployment to a particular resource within the environment. Then, you can record deployment history on a specific resource within the environment. The steps of the deployment job automatically inherit the service connection details from the resource targeted by the deployment job.
environment: 'smarthotel-dev.bookings'
strategy:
runOnce:
deploy:
steps:
- task: KubernetesManifest@0
displayName: Deploy to Kubernetes cluster
inputs:
action: deploy
namespace: $(k8sNamespace)
manifests: $(System.ArtifactsDirectory)/manifests/*
imagePullSecrets: $(imagePullSecret)
containers: $(containerRegistry)/$(imageRepository):$(tag)
# value for kubernetesServiceConnection input automatically passed down to task by environment.resource inputAll environments that get targeted by deployment jobs of a specific run of a pipeline can be found under the Environments tab of pipeline run details.
[!div class="mx-imgBorder"]
If you're using an AKS private cluster, the Environments tab isn't available.
Manually control when a stage should run using approval checks. Use approval checks to control deployments to production environments. Checks are available to the resource Owner to control when a stage in a pipeline consumes a resource. As the owner of a resource, such as an environment, you can define approvals and checks that must be satisfied before a stage consuming that resource starts.
We support manual approval checks on environments. For more information, see Approvals.
The Creator, Administrator, and user roles can manage approvals and checks. The Reader role can't manage approvals and checks.
The deployment history view within environments provides the following advantages.
-
View jobs from all pipelines that target a specific environment. For example, two micro-services, each having its own pipeline, are deploying to the same environment. The deployment history listing helps identify all pipelines that affect this environment and also helps visualize the sequence of deployments by each pipeline.
[!div class="mx-imgBorder"]
-
Drill down into the job details to see the list of commits and work items that were deployed to the environment. The list of commits and work items are the new items between deployments. Your first listing will include all of the commits and the following listings will just include changes. If multiple commits are tied to the same pull request, you'll see multiple results on the work items and changes tabs.
[!div class="mx-imgBorder"]
-
If multiple work items are tied to the same pull request, you'll see multiple results on the work items tab.
[!div class="mx-imgBorder"]
Control who can create, view, use, and manage the environments with user permissions. There are four roles - Creator (scope: all environments), Reader, User, and Administrator. In the specific environment's user permissions panel, you can set the permissions that are inherited and you can override the roles for each environment.
- Go to the specific Environment that you want to authorize.
- Select :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: > Security to view the settings.
- Select User permissions > +Add > User or group, and then select a suitable role.
[!INCLUDE temp]
Use pipeline permissions to authorize all or selected pipelines for deployment to the environment.
- To remove Open access on the environment or resource, select Restrict permission in Pipeline permissions.
- To allow specific pipelines to deploy to an environment or specific resource, select + and choose from the list of pipelines.
A: If you see the message "Access denied: {User} needs Create permissions to do the action", check your organization-level permissions. Go to Organization Settings > Users and check if you have the stakeholder role. The stakeholder role can't create environments. Change your access level and then check to see if you can create environments. For more information, see User and permissions management FAQ.
Q: Why am I getting error "Job XXXX: Environment XXXX could not be found. The environment does not exist or has not been authorized for use"?
A: These are some of the possible reasons of the failure:
-
When you author a YAML pipeline and refer to an environment that does not exist in the YAML file, Azure Pipelines automatically creates the environment in some cases:
- You use the YAML pipeline creation wizard in the Azure Pipelines web experience and refer to an environment that hasn't been created yet.
- You update the YAML file using the Azure Pipelines web editor and save the pipeline after adding a reference to an environment that does not exist.
-
In the following flows, Azure Pipelines does not have information about the user creating the environment: you update the YAML file using another external code editor, add a reference to an environment that does not exist, and then cause a manual or continuous integration pipeline to be triggered. In this case, Azure Pipelines does not know about the user. Previously, we handled this case by adding all the project contributors to the administrator role of the environment. Any member of the project could then change these permissions and prevent others from accessing the environment.
-
If you are using runtime parameters for creating the environment, it will fail as these parameters are expanded at run time. Environment creation happens at compile time, so we have to use variables to create the environment.
-
A user with stakeholder access level cannot create the environment as stakeholders do not have access to the repository.