Command Invoke DscPipelineRunner

Invoke-DscPipelineRunner

Synopsis

Invokes the DSC Pipeline Runner against an Azure DevOps organization.

Description

The Invoke-DscPipelineRunner function is the Azure DevOps entry point to the runner. It resolves a configuration source (a local directory or a git URL), compiles it with Datum, establishes an Azure DevOps authentication provider, and runs each compiled configuration.

Authentication is selected by parameter set, not by a separate switch:

• ManagedIdentity (default) - authenticates with the agent's managed identity.
• PAT - supply -PATToken; the PAT parameter set is chosen implicitly.

New callers should prefer Invoke-DscRunner, which is provider-agnostic and exposes the Source/Connect/Engine action seams directly.

Parameters

Name	Type	Required	Description
AzureDevopsOrganizationName	String	Yes	Specifies the name of the Azure DevOps organization. This parameter is mandatory.
ExportConfigDir	String	Yes	Specifies the directory where configuration files are exported by Datum. This parameter is mandatory and must be an existing directory.
ConfigurationSourcePath	String	Yes	Specifies the URL or directory path for the configuration source. This parameter is mandatory. Only https and ssh remotes are accepted; a plain http:// URL is rejected. SECURITY: the configuration is executed as arbitrary PowerShell — a Datum/DSC Configuration block is code, not just data — in the runner's own process and security context. There is no sandbox or content validation. Treat the configuration repository (or the cloned URL) as fully-trusted code and protect it with the same controls as the runner's own source: branch protection, required reviews, and (ideally) signed commits. See SECURITY.md, "Trust model".
ConfigurationRevision	String	No	Optional branch, tag, or commit to pin a cloned configuration to. A full 40-character commit SHA makes the pin exact: the clone's HEAD is verified against it and a mismatch is an error. Ignored when -ConfigurationSourcePath is a local directory.
JITToken	Object	No	Optional Just-In-Time access token used to authenticate the git clone. Accepts a [SecureString] (preferred) or a plain string. When omitted, $env:SYSTEM_ACCESSTOKEN is used if it is set; a public repository needs neither.
Mode	String	No	Specifies the mode of operation. Valid values are 'Test' and 'Set'. The default value is 'Test'.
PATToken	String	Yes	Specifies the Personal Access Token. Supplying it selects the PAT parameter set, so the PAT is always the credential actually used for the Azure DevOps connection.
ReportPath	String	No	Specifies the directory to write the run report into. Optional; must be an existing directory.
FailOnError	SwitchParameter	No	Set a non-zero process exit code when the run reports a failure, so a pipeline step fails loudly instead of silently succeeding.
KeepTemporaryDirectory	SwitchParameter	No	Leave a cloned configuration directory on disk after the run instead of deleting it. A caller-supplied local configuration directory is never deleted, with or without this switch.

Examples

Example 1

Invoke-DscPipelineRunner -AzureDevopsOrganizationName "MyOrg" -ExportConfigDir "C:\Configs" `
                         -ConfigurationSourcePath "https://dev.azure.com/MyOrg/Project/_git/config" `
                         -Mode Set -PATToken $pat

Runs in Set mode against a cloned configuration, authenticating with a Personal Access Token.

Example 2

Invoke-DscPipelineRunner -AzureDevopsOrganizationName "MyOrg" -ExportConfigDir "C:\Configs" `
                         -ConfigurationSourcePath "C:\config"

Runs in the default Test mode against a local directory, authenticating with the agent's
managed identity.

Notes

Ensure that a cache directory environment variable is set before running this function. The generic PIPELINERUNNER_CACHE_DIRECTORY is preferred; the legacy AZDODSC_CACHE_DIRECTORY is still honoured as a back-compat alias. The function will throw an error if neither is set.

BREAKING CHANGE (#17): -exportConfigDir is now -ExportConfigDir, and -AuthenticationType has been removed in favour of the parameter set implied by -PATToken. -Mode is no longer mandatory and defaults to 'Test'. -JITToken is no longer mandatory.