Skip to content

AzDoGitPermission

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

AzDoGitPermission Resource

Description

The AzDoGitPermission DSC resource is used to manage permissions on Git repositories within an Azure DevOps project. It allows you to define and enforce the desired state of permissions assigned to groups or users for specific repositories or repository paths, including whether permissions are inherited from parent scopes.

Syntax

AzDoGitPermission [string] #ResourceName
{
    ProjectName = [String] $ProjectName
    [ RepositoryName = [String] $RepositoryName ]
    [ 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 in which the Git permissions are managed.

Optional Properties

  • RepositoryName [String] - The name of the Git repository within the project. If not specified, permissions apply to all repositories in the project. Default is $null.

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

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

    • Permission - The name of the Git permission (e.g., 'Read', 'Contribute', 'ForcePush', 'CreateBranch', 'CreateTag', 'Administer')
    • 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) Repository permissions should exist
    • 'Absent' - Repository 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
  • RepositoryName - The name of the repository (if specified)
  • isInherited - Whether permissions are inherited
  • Permissions - The current Git permissions assigned
  • Ensure - Current state ('Present' or 'Absent')

Examples

Example 1: Configure Read-Only Access to All Repositories

Configuration ConfigureRepositoryRead {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoGitPermission 'AllReposRead' {
            ProjectName = 'MyProject'
            RepositoryName = $null
            isInherited = $false
            Permissions = @(
                @{
                    Permission = 'Read'
                    Allow = $true
                }
            )
            Ensure = 'Present'
        }
    }
}

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

Example 2: Configure Contributor Permissions for a Specific Repository

Configuration ConfigureRepositoryContribute {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoGitPermission 'MainRepoContribute' {
            ProjectName = 'MyProject'
            RepositoryName = 'MainRepository'
            isInherited = $false
            Permissions = @(
                @{
                    Permission = 'Read'
                    Allow = $true
                },
                @{
                    Permission = 'Contribute'
                    Allow = $true
                },
                @{
                    Permission = 'CreateBranch'
                    Allow = $true
                }
            )
            Ensure = 'Present'
        }
    }
}

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

Example 3: Configure Advanced Permissions with Restrictions

Configuration ConfigureAdvancedRepositoryPermissions {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoGitPermission 'DevelopmentRepoAdvanced' {
            ProjectName = 'MyProject'
            RepositoryName = 'DevelopmentRepository'
            isInherited = $false
            Permissions = @(
                @{
                    Permission = 'Read'
                    Allow = $true
                },
                @{
                    Permission = 'Contribute'
                    Allow = $true
                },
                @{
                    Permission = 'ForcePush'
                    Allow = $false
                },
                @{
                    Permission = 'Administer'
                    Allow = $false
                },
                @{
                    Permission = 'CreateTag'
                    Allow = $true
                }
            )
            Ensure = 'Present'
        }
    }
}

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

Example 4: Using Invoke-DscResource to Query and Configure

# Get current Git repository permissions
$properties = @{
    ProjectName = 'MyProject'
    RepositoryName = 'MainRepository'
}

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

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

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

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

Important Notes

Repository Scope

  • When RepositoryName is not specified ($null), permissions apply to all Git repositories in the project
  • When RepositoryName is specified, permissions apply only to that specific repository
  • Repository names are case-sensitive and must match exactly

Git-Specific Permissions

  • Read - Allows users to clone and pull from the repository
  • Contribute - Allows users to push commits to the repository
  • ForcePush - Allows users to force push changes (bypass merge restrictions)
  • CreateBranch - Allows users to create new branches
  • CreateTag - Allows users to create tags
  • DeleteRepository - Allows deletion of the entire repository
  • Administer - Provides full administrative control over the repository

Inheritance Behavior

  • Permissions set at the project level cascade to all repositories unless explicitly overridden
  • Repository-level permissions override project-level permissions
  • Branch-level permissions can provide additional granularity

Troubleshooting

Issue: "Repository Not Found"

Cause: The specified repository name does not exist in the project.

Solution:

# Verify the repository name exists in the project
# Check in Azure DevOps Repos section
# Ensure you are using the exact repository name (case-sensitive)

Issue: "Invalid Git Permission"

Cause: The specified permission name is not a valid Git permission.

Solution:

# Use valid Git permissions:
# Read, Contribute, ForcePush, CreateBranch, CreateTag, DeleteRepository, Administer

Issue: "Permissions Not Applied to Specific Repository Paths"

Cause: The resource manages permissions at the repository level, not individual file paths.

Solution:

  • Use Azure DevOps branch policies and protection rules for path-specific access control
  • Configure repository-wide permissions using this resource
  • Consider multiple repositories if different teams need different access levels

Related Resources

See Also

Clone this wiki locally