Skip to content

AzDoIterationPermission

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

AzDoIterationPermission Resource

Description

The AzDoIterationPermission DSC resource is used to manage permissions for specific iterations (sprints) within an Azure DevOps project. It allows you to configure which groups or users have access to work items in specific iterations and control their ability to edit, view, or manage iteration-related operations.

Syntax

AzDoIterationPermission [string] #ResourceName
{
    ProjectName = [String] $ProjectName
    [ IterationPath = [String] $IterationPath ]
    [ 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.

Optional Properties

  • IterationPath [String] - The path of the iteration within the project (e.g., 'MyProject\Sprint 1'). If not specified, applies to project root iteration.

  • isInherited [Boolean] - Whether the permissions are inherited from the parent iteration. Default is $true.

  • Permissions [HashTable[]] - An array of permission hashtables, each containing:

    • Identity - The group or user identity
    • Permission - The permission type (e.g., 'Edit', 'View', 'Delete')
    • Allow - Boolean indicating if permission is allowed
    • Deny - Boolean indicating if permission is denied

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

    • 'Present' - (default) Permissions should be configured
    • 'Absent' - 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
  • IterationPath - The iteration path
  • isInherited - Whether permissions are inherited
  • Permissions - The configured permissions
  • Ensure - Current state ('Present' or 'Absent')

Examples

Example 1: Grant Iteration Permissions to Team

Configuration GrantIterationPermissions {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoIterationPermission 'SprintPermissions' {
            ProjectName   = 'MyProject'
            IterationPath = 'MyProject\Sprint 1'
            isInherited   = $false
            Permissions   = @(
                @{
                    Identity   = 'Development Team'
                    Permission = 'Edit'
                    Allow      = $true
                },
                @{
                    Identity   = 'QA Team'
                    Permission = 'View'
                    Allow      = $true
                },
                @{
                    Identity   = 'Contractors'
                    Permission = 'Edit'
                    Allow      = $false
                    Deny       = $true
                }
            )
            Ensure = 'Present'
        }
    }
}

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

Example 2: Configure Multiple Sprint Permissions

Configuration ConfigureSprintPermissions {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoIterationPermission 'Sprint1' {
            ProjectName   = 'MyProject'
            IterationPath = 'MyProject\Sprint 1'
            isInherited   = $false
            Permissions   = @(
                @{
                    Identity   = 'Sprint 1 Team'
                    Permission = 'Edit'
                    Allow      = $true
                }
            )
            Ensure = 'Present'
        }
        
        AzDoIterationPermission 'Sprint2' {
            ProjectName   = 'MyProject'
            IterationPath = 'MyProject\Sprint 2'
            isInherited   = $false
            Permissions   = @(
                @{
                    Identity   = 'Sprint 2 Team'
                    Permission = 'Edit'
                    Allow      = $true
                }
            )
            Ensure = 'Present'
        }
    }
}

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

Example 3: Disable Iteration Permission Inheritance

Configuration DisableIterationInheritance {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoIterationPermission 'RestrictedSprint' {
            ProjectName   = 'MyProject'
            IterationPath = 'MyProject\Restricted Sprint'
            isInherited   = $false
            Permissions   = @(
                @{
                    Identity   = 'Project Admins'
                    Permission = 'Edit'
                    Allow      = $true
                },
                @{
                    Identity   = 'Developers'
                    Permission = 'View'
                    Allow      = $true
                }
            )
            Ensure = 'Present'
        }
    }
}

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

Example 4: Query Iteration Permissions

# Get the current state of iteration permissions
$properties = @{
    ProjectName   = 'MyProject'
    IterationPath = 'MyProject\Sprint 1'
}

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

$result | Select-Object ProjectName, IterationPath, isInherited, Permissions

Example 5: Restrict Archived Sprint Access

Configuration RestrictArchivedSprint {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoIterationPermission 'ArchivedSprintRead' {
            ProjectName   = 'MyProject'
            IterationPath = 'MyProject\Archived\Sprint 2024-Q1'
            isInherited   = $false
            Permissions   = @(
                @{
                    Identity   = 'Team Leads'
                    Permission = 'View'
                    Allow      = $true
                },
                @{
                    Identity   = 'Developers'
                    Permission = 'Edit'
                    Allow      = $false
                    Deny       = $true
                }
            )
            Ensure = 'Present'
        }
    }
}

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

Example 6: Remove Iteration Permissions

Configuration RemoveIterationPermissions {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoIterationPermission 'RemovePermissions' {
            ProjectName   = 'MyProject'
            IterationPath = 'MyProject\OldSprint'
            Ensure        = 'Absent'
        }
    }
}

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

Important Notes

Permission Types

  • Edit - Ability to edit work items in the iteration
  • View - Ability to view work items in the iteration
  • Delete - Ability to delete work items from the iteration
  • Create Child Items - Ability to create child work items
  • Manage Test Plans - Ability to manage test plans for the iteration

Iteration Hierarchy

  • Iterations are organized in a hierarchy (parent/child relationships)
  • Permissions cascade from parent to child iterations
  • Setting isInherited to $false allows custom permissions per iteration

Iteration Path Format

  • Use backslash as separator (e.g., 'Project\Iteration1\Sprint1')
  • Project name is typically the root
  • Paths are case-sensitive

Troubleshooting

Issue: "Iteration Path Not Found"

Cause: The specified iteration does not exist

Solution:

# Verify the iteration exists in the project
# Use AzDoIterationNodes resource to create iterations first
# Check the exact spelling and case of the iteration path

Issue: "Cannot Set Iteration Permissions"

Cause: Insufficient permissions or group does not exist

Solution:

  • Verify user has project administrator permissions
  • Check that the group exists in the organization or project
  • Ensure the personal access token has sufficient scope

Issue: "Permissions Not Applying Correctly"

Cause: Inheritance conflicts or parent permissions override

Solution:

# Set isInherited to $false to override parent permissions
# Explicitly configure all required permissions
# Check for conflicting permission rules

Related Resources

See Also

Clone this wiki locally