Skip to content

AzDoEnvironmentPermission

Jump to bottom
Michael Zanatta edited this page Aug 13, 2026 · 1 revision

AzDoEnvironmentPermission Resource

Description

The AzDoEnvironmentPermission DSC resource is used to manage permissions on deployment environments within an Azure DevOps project. Deployment environments are used in pipelines to define deployment targets with approval requirements and checks. This resource allows you to configure and enforce the desired state of permissions assigned to groups for specific environments, controlling who can deploy to and administer these environments.

Syntax

AzDoEnvironmentPermission [string] #ResourceName
{
    ProjectName = [String] $ProjectName
    EnvironmentName = [String] $EnvironmentName
    GroupName = [String] $GroupName
    [ isInherited = [Boolean] $isInherited ]
    [ Permissions = [Hashtable[]] $Permissions ]
    [ Ensure = [String] {'Present', 'Absent'} ]
    [ DependsOn = [String[]] ]
    [ PsDscRunAsCredential = [PSCredential] ]
}

Properties

Key Properties (Required)

  • ProjectName [String] - The name of the Azure DevOps project containing the environment.

Mandatory Properties

  • EnvironmentName [String] - The name of the deployment environment for which permissions are being configured. Environments define deployment targets and can have approvals and checks.

  • GroupName [String] - The name of the group to which permissions are assigned. The group must exist in the project or organization.

Optional Properties

  • isInherited [Boolean] - Specifies whether the permissions are inherited from the project level. Default is $true. When set to $false, only explicitly assigned permissions apply.

  • Permissions [Hashtable[]] - An array of hashtables specifying the environment permissions to be assigned. Each hashtable should contain:

    • Permission - The name of the permission (e.g., 'User', 'Admin')
    • Allow - Boolean value indicating whether the permission is allowed
    • Deny - Boolean value indicating whether the permission is explicitly denied

  • Ensure [String] - Desired state of the resource:

    • 'Present' - (default) Environment permissions should exist
    • 'Absent' - Environment permissions should be removed

Common Properties

  • DependsOn [String[]] - Dependencies on other resources. Use this to control the order of resource execution.

  • PsDscRunAsCredential [PSCredential] - Credentials to run this resource under.

Return Values

The resource returns the following properties:

  • ProjectName - The name of the project
  • EnvironmentName - The name of the environment
  • GroupName - The name of the group
  • isInherited - Whether permissions are inherited
  • Permissions - The current environment permissions assigned
  • Ensure - Current state ('Present' or 'Absent')

Examples

Example 1: Grant Deployment Access to Development Environment

Configuration GrantDevEnvironmentAccess {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoEnvironmentPermission 'DevelopersDevEnv' {
            ProjectName = 'MyProject'
            EnvironmentName = 'Development'
            GroupName = 'Developers'
            isInherited = $false
            Permissions = @(
                @{
                    Permission = 'User'
                    Allow = $true
                }
            )
            Ensure = 'Present'
        }
    }
}

GrantDevEnvironmentAccess
Start-DscConfiguration -Path ./GrantDevEnvironmentAccess -Wait -Verbose

Example 2: Configure Administrative Access to Production Environment

Configuration GrantProdEnvironmentAdmin {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoEnvironmentPermission 'AdminsProdEnv' {
            ProjectName = 'MyProject'
            EnvironmentName = 'Production'
            GroupName = 'Release Administrators'
            isInherited = $false
            Permissions = @(
                @{
                    Permission = 'User'
                    Allow = $true
                },
                @{
                    Permission = 'Admin'
                    Allow = $true
                }
            )
            Ensure = 'Present'
        }
    }
}

GrantProdEnvironmentAdmin
Start-DscConfiguration -Path ./GrantProdEnvironmentAdmin -Wait -Verbose

Example 3: Configure Multiple Environments with Tiered Access

Configuration ConfigureEnvironmentHierarchy {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        # Development environment - All developers can deploy
        AzDoEnvironmentPermission 'DevelopersDevEnv' {
            ProjectName = 'MyProject'
            EnvironmentName = 'Development'
            GroupName = 'Developers'
            isInherited = $false
            Permissions = @(
                @{ Permission = 'User'; Allow = $true }
            )
            Ensure = 'Present'
        }
        
        # Staging environment - QA can deploy
        AzDoEnvironmentPermission 'QAStagingEnv' {
            ProjectName = 'MyProject'
            EnvironmentName = 'Staging'
            GroupName = 'Quality Assurance'
            isInherited = $false
            Permissions = @(
                @{ Permission = 'User'; Allow = $true }
            )
            Ensure = 'Present'
        }
        
        # Production environment - Only Release team can deploy
        AzDoEnvironmentPermission 'ReleaseProdEnv' {
            ProjectName = 'MyProject'
            EnvironmentName = 'Production'
            GroupName = 'Release Team'
            isInherited = $false
            Permissions = @(
                @{ Permission = 'User'; Allow = $true }
            )
            Ensure = 'Present'
        }
        
        # Production environment admin - Release admins manage approvals/checks
        AzDoEnvironmentPermission 'AdminProdEnv' {
            ProjectName = 'MyProject'
            EnvironmentName = 'Production'
            GroupName = 'Release Administrators'
            isInherited = $false
            Permissions = @(
                @{ Permission = 'User'; Allow = $true },
                @{ Permission = 'Admin'; Allow = $true }
            )
            Ensure = 'Present'
        }
    }
}

ConfigureEnvironmentHierarchy
Start-DscConfiguration -Path ./ConfigureEnvironmentHierarchy -Wait -Verbose

Example 4: Restrict Environment Access to Specific Teams

Configuration RestrictEnvironmentAccess {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        # Only Release team can access production
        AzDoEnvironmentPermission 'RestrictProdEnv' {
            ProjectName = 'MyProject'
            EnvironmentName = 'Production'
            GroupName = 'Developers'
            isInherited = $false
            Permissions = @(
                @{ Permission = 'User'; Allow = $false },
                @{ Permission = 'Admin'; Allow = $false }
            )
            Ensure = 'Present'
        }
    }
}

RestrictEnvironmentAccess
Start-DscConfiguration -Path ./RestrictEnvironmentAccess -Wait -Verbose

Example 5: Using Invoke-DscResource to Manage Environment Permissions

# Get current environment permissions
$properties = @{
    ProjectName = 'MyProject'
    EnvironmentName = 'Production'
    GroupName = 'Release Team'
}

$result = Invoke-DscResource -Name 'AzDoEnvironmentPermission' `
    -Method Get `
    -Property $properties `
    -ModuleName 'AzureDevOpsDscNative'

$result | Select-Object ProjectName, EnvironmentName, GroupName, isInherited, Permissions

# Set new environment permissions
$setProperties = @{
    ProjectName = 'MyProject'
    EnvironmentName = 'Production'
    GroupName = 'Release Team'
    isInherited = $false
    Permissions = @(
        @{ Permission = 'User'; Allow = $true }
    )
    Ensure = 'Present'
}

Invoke-DscResource -Name 'AzDoEnvironmentPermission' `
    -Method Set `
    -Property $setProperties `
    -ModuleName 'AzureDevOpsDscNative'

Important Notes

Environment Permissions

  • User - Allows users/groups to deploy to the environment via pipelines
  • Admin - Allows users to manage approvals, checks, and permissions on the environment

Environment Types

  • Development - Often allows broad access; used for testing and experimental deployments
  • Staging/QA - Restricted access; used for quality assurance and validation
  • Production - Highly restricted access; typically requires approvals and checks

Approvals and Checks

  • Environments can have manual approvals required before deployment
  • Checks can validate conditions before allowing deployment
  • Admin permissions allow configuration of these controls
  • Approval and check settings complement permission settings

Deployment Pipeline Integration

  • Pipelines reference environments by name
  • Pipeline users need at least "User" permission to deploy to an environment
  • Multiple approval groups can be configured for sensitive environments
  • Parallel approvals can speed up deployment processes

Inheritance Behavior

  • When isInherited is $true, groups inherit permissions from project level
  • When isInherited is $false, only explicitly defined permissions apply
  • Production environments should carefully control inheritance
  • Most organizations set isInherited = $false for production environments

Troubleshooting

Issue: "Environment Not Found"

Cause: The specified environment does not exist in the project.

Solution:

# Verify the environment exists in the project
# Check Pipelines -> Environments section
# Ensure the exact environment name is used (case-sensitive)
# Create the environment first if it doesn't exist

Issue: "Group Cannot Deploy to Environment"

Cause: The group does not have "User" permission on the environment.

Solution:

# Grant "User" permission to the appropriate group
# Check pipeline definitions for environment references
# Verify the group exists and is valid
# Confirm pipeline execution identity has permission

Issue: "Cannot Manage Environment Approvals"

Cause: The group does not have "Admin" permission on the environment.

Solution:

# Grant "Admin" permission to groups that manage approvals
# Verify the user making configuration changes has Admin permission
# Check project administrator permissions

Issue: "Approval Conditions Not Enforced"

Cause: User has Admin permission but checks/approvals not properly configured.

Solution:

# Configure approvals and checks separately in environment settings
# Ensure environment is properly referenced in pipeline
# Verify pipeline is using the environment correctly
# Check for inherited permissions overriding specific settings

Related Resources

See Also

Clone this wiki locally