en-US/about_AzDoBuildRetentionSettings.help.txt
|
.NAME
AzDoBuildRetentionSettings .SYNOPSIS DSC resource for managing Azure DevOps project run and artifact retention settings. .DESCRIPTION The AzDoBuildRetentionSettings resource manages a project's pipeline retention policy (the Project Settings -> Pipelines -> Settings -> Retention page) via the Build REST API (_apis/build/retention). Only the settings explicitly specified in the configuration are reconciled; unspecified settings are left untouched. Each setting is validated against the org's own min/max bounds, read live from the API rather than hard-coded, before it is ever written - a value outside those bounds is refused with no PATCH sent. The settings are intrinsic to a project and cannot be removed, so Ensure = 'Absent' is a no-op. Test()/Set() are inherited from the AzDevOpsDscResourceBase class. Out of scope: the classic-pipeline-era 'maximum retention policy' and 'default retention policy' values exposed at _apis/build/settings are not managed here. They only apply to the classic build/release pipeline experience being retired alongside classic release management (see issue #86), while this resource targets the current per-setting retention page that applies to both YAML and classic pipelines. .PARAMETER ProjectName Key - System.String The name of the Azure DevOps project. .PARAMETER DaysToKeepRuns Write - Nullable[System.Int32] The number of days to keep pipeline runs before they are purged (API field 'purgeRuns' when read, 'runRetention' when written). Rejected if outside the org's live min/max range for this setting. .PARAMETER DaysToKeepArtifacts Write - Nullable[System.Int32] The number of days to keep build artifacts, symbols and attachments before they are purged (API field 'purgeArtifacts' when read, 'artifactsRetention' when written). Rejected if outside the org's live min/max range for this setting. .PARAMETER DaysToKeepPullRequestRuns Write - Nullable[System.Int32] The number of days to keep runs triggered by pull requests before they are purged (API field 'purgePullRequestRuns' when read, 'pullRequestRunRetention' when written). Rejected if outside the org's live min/max range for this setting. .PARAMETER RunsToRetainPerProtectedBranch Write - Nullable[System.Int32] The minimum number of runs to always retain per protected branch, regardless of age (API field 'retainRunsPerProtectedBranch', the same when read and written). Rejected if outside the org's live min/max range for this setting. .EXAMPLE 1 This example sets a project's run and artifact retention policy. Only the settings you specify are compared and applied; any omitted here are left untouched. Each value is validated against the organization's own live min/max range for that setting - an out-of-range value is refused rather than silently clamped or ignored. The classic-pipeline-era 'maximum retention policy' / 'default retention policy' values at `_apis/build/settings` are not managed by this resource - see docs/ResourceRoadmap.md. Configuration Example { Import-DscResource -ModuleName 'AzureDevOpsDscNative' node localhost { AzDoBuildRetentionSettings 'ProjectRetention' { Ensure = 'Present' ProjectName = 'MyProject' DaysToKeepRuns = 30 DaysToKeepArtifacts = 14 DaysToKeepPullRequestRuns = 10 RunsToRetainPerProtectedBranch = 3 } } } |