Create and target an environment

Azure Pipelines | Azure DevOps Server 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.

Create an environment

  1. Sign in to your organization:{yourorganization} and select your project.

  2. Select Pipelines > Environments > Create environment.


  3. Enter information for the environment, and then select Create. Resources can be added to an existing environment later.

    Screenshot of creating a new environment.

Use a Pipeline to create and deploy to environments, too. For more information, see the how-to guide.


You can create an empty environment and reference it from deployment jobs. This lets you record the deployment history against the environment.

Target an environment from a deployment job

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
  - deployment: DeployWeb
    displayName: deploy Web App
      vmImage: 'Ubuntu-latest'
    # creates an environment if it doesn't exist
    environment: 'smarthotel-dev'
          - script: echo Hello world

If the specified environment doesn't already exist, an empty environment gets created using the environment name provided.

Target a specific resource within an environment from deployment job

You 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'
     - task: KubernetesManifest@0
       displayName: Deploy to Kubernetes cluster
         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 input

Environment in run details

All 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.

Environments in run details

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.

Deployment history

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.

    Deployment history

  • Drill down into the job details to see the list of commits and work items that were newly deployed to the environment.

    Commits under deployment history


User permissions

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.

  1. Go to the specific Environment that you want to authorize.
  2. Select > Security to view the settings.
  3. Select User permissions > +Add > User or group, and then select a suitable role.
Role Description
Creator Global role, available from environments hub security option. Members of this role can create the environment in the project. Contributors are added as members by default. Required to trigger a YAML pipeline when the environment does not already exist.
Reader Members of this role can view the environment.
User Members of this role can use the environment when creating or editing YAML pipelines.
Administrator In addition to using the environment, members of this role can manage membership of all other roles for the environment. Creators are added as members by default.


  • If you create an environment within a YAML, contributors and project administrators are granted the Administrator role. This is typically used in provisioning Dev/Test environments.
  • If you create an environment through the UI, only the creator is granted the Administrator role. You should use the UI to create protected environments like for a production environment.

Pipeline permissions

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.

Next steps

Define approvals and checks


Q: Why do I get an error message when I try to create an environment?

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.