Skip to content

AzDoProjectPermission

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

AzDoProjectPermission Resource

Description

The AzDoProjectPermission DSC resource is used to manage permissions at the project level in Azure DevOps. It allows you to configure and enforce the desired state of permissions assigned to groups for an entire project, controlling high-level access to project features and administration capabilities. These permissions cascade to project-level resources unless overridden by more specific permissions.

Syntax

AzDoProjectPermission [string] #ResourceName
{
    ProjectName = [String] $ProjectName
    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. This is the unique identifier for the project at which permissions are managed.

Mandatory Properties

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

Optional Properties

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

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

    • Permission - The name of the permission (e.g., 'Read', 'Edit', 'Delete', 'Administer', 'Contribute', 'Rename')
    • 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) Project permissions should exist
    • 'Absent' - Project 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
  • GroupName - The name of the group
  • isInherited - Whether permissions are inherited
  • Permissions - The current project-level permissions assigned
  • Ensure - Current state ('Present' or 'Absent')

Examples

Example 1: Grant Read-Only Access to Project

Configuration GrantProjectRead {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoProjectPermission 'ReadersProjectAccess' {
            ProjectName = 'MyProject'
            GroupName = 'Readers'
            isInherited = $false
            Permissions = @(
                @{
                    Permission = 'Read'
                    Allow = $true
                }
            )
            Ensure = 'Present'
        }
    }
}

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

Example 2: Configure Contributor Permissions

Configuration GrantProjectContribute {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoProjectPermission 'ContributorsProjectAccess' {
            ProjectName = 'MyProject'
            GroupName = 'Contributors'
            isInherited = $false
            Permissions = @(
                @{
                    Permission = 'Read'
                    Allow = $true
                },
                @{
                    Permission = 'Contribute'
                    Allow = $true
                },
                @{
                    Permission = 'Edit'
                    Allow = $true
                }
            )
            Ensure = 'Present'
        }
    }
}

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

Example 3: Configure Project Administration Access

Configuration GrantProjectAdmin {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoProjectPermission 'AdminsProjectAccess' {
            ProjectName = 'MyProject'
            GroupName = 'Project Administrators'
            isInherited = $false
            Permissions = @(
                @{
                    Permission = 'Read'
                    Allow = $true
                },
                @{
                    Permission = 'Edit'
                    Allow = $true
                },
                @{
                    Permission = 'Delete'
                    Allow = $true
                },
                @{
                    Permission = 'Administer'
                    Allow = $true
                }
            )
            Ensure = 'Present'
        }
    }
}

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

Example 4: Configure Role-Based Project Permissions

Configuration ConfigureRoleBasedProjectPermissions {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        # Readers group - View-only access
        AzDoProjectPermission 'ReadersAccess' {
            ProjectName = 'MyProject'
            GroupName = 'Readers'
            isInherited = $false
            Permissions = @(
                @{ Permission = 'Read'; Allow = $true }
            )
            Ensure = 'Present'
        }
        
        # Developers group - Read and contribute
        AzDoProjectPermission 'DevelopersAccess' {
            ProjectName = 'MyProject'
            GroupName = 'Developers'
            isInherited = $false
            Permissions = @(
                @{ Permission = 'Read'; Allow = $true },
                @{ Permission = 'Contribute'; Allow = $true },
                @{ Permission = 'Edit'; Allow = $true }
            )
            Ensure = 'Present'
        }
        
        # Leads group - Full project access except deletion
        AzDoProjectPermission 'LeadsAccess' {
            ProjectName = 'MyProject'
            GroupName = 'Project Leads'
            isInherited = $false
            Permissions = @(
                @{ Permission = 'Read'; Allow = $true },
                @{ Permission = 'Edit'; Allow = $true },
                @{ Permission = 'Contribute'; Allow = $true },
                @{ Permission = 'Rename'; Allow = $true },
                @{ Permission = 'Delete'; Allow = $false }
            )
            Ensure = 'Present'
        }
        
        # Administrators group - Full control
        AzDoProjectPermission 'AdminsAccess' {
            ProjectName = 'MyProject'
            GroupName = 'Project Administrators'
            isInherited = $false
            Permissions = @(
                @{ Permission = 'Read'; Allow = $true },
                @{ Permission = 'Edit'; Allow = $true },
                @{ Permission = 'Delete'; Allow = $true },
                @{ Permission = 'Administer'; Allow = $true }
            )
            Ensure = 'Present'
        }
    }
}

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

Example 5: Using Invoke-DscResource to Manage Permissions

# Get current project permissions
$properties = @{
    ProjectName = 'MyProject'
    GroupName = 'Developers'
}

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

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

# Set new project permissions
$setProperties = @{
    ProjectName = 'MyProject'
    GroupName = 'Developers'
    isInherited = $false
    Permissions = @(
        @{ Permission = 'Read'; Allow = $true },
        @{ Permission = 'Edit'; Allow = $true },
        @{ Permission = 'Contribute'; Allow = $true }
    )
    Ensure = 'Present'
}

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

Important Notes

Project-Level Permissions

Project-level permissions control access to core project features:

  • Read - Allows users to view project contents, work items, and repositories
  • Contribute - Allows users to contribute to the project (work items, code)
  • Edit - Allows users to edit project settings and configurations
  • Delete - Allows users to delete the project
  • Rename - Allows users to rename the project
  • Administer - Provides full administrative control over the project

Permission Hierarchy

  • Organization-level permissions provide the baseline
  • Project-level permissions override organization permissions
  • Specific resource permissions (repository, pipeline, etc.) override project permissions
  • Inheritance follows the principle of least privilege when properly configured

Cascading Behavior

  • Project-level permissions cascade to most project resources
  • Repository, pipeline, and variable group permissions can override project permissions
  • Area and iteration permissions are independent
  • Team/group permissions may further restrict access

Common Permission Patterns

  • Read-Only Teams: Grant only Read permission
  • Development Teams: Grant Read, Contribute, Edit permissions
  • Team Leads: Grant Read, Edit, Contribute permissions
  • Administrators: Grant all permissions including Administer

Troubleshooting

Issue: "Project Not Found"

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

Solution:

# Verify the project name exists
# Check Azure DevOps Projects page
# Ensure the exact project name is used (case-sensitive)

Issue: "Group Not Found"

Cause: The specified group does not exist in the project or organization.

Solution:

# Create the group using AzDoProjectGroup or AzDoOrganizationGroup first
# Verify the group name is correct
# Check group existence in project or organization settings

Issue: "Permissions Affecting Subresources Unexpectedly"

Cause: Permission inheritance is affecting resource-specific permissions.

Solution:

# Set isInherited = $false for precise control
# Configure resource-specific permissions to override project permissions
# Document permission hierarchy in your configuration

Related Resources

See Also

Clone this wiki locally