Create and target an environment

Azure DevOps Services | 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: https://dev.azure.com/{yourorganization} and select your project.

  2. Select Pipelines > Environments > Create environment.

    Environments

  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.

Tip

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
  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 world

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

Approvals

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.

    Screenshot of deployment history listing.

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

    Screenshot of commits under deployment history.

  • If multiple work items are tied to the same pull request, you'll see multiple results on the work items tab.

    Screenshot of work items under deployment history.

Security

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.

Note

  • 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

FAQ

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.

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 access to repository.