API Reference
Command
New-ConfigurationExecute
Creates a module pipeline lifecycle action.
Remarks
Lifecycle actions run PowerShell at a named module pipeline context point such as AfterStaging, AfterManifest, or BeforePublish. PowerForge writes a stable JSON context file before each action and exposes its path through the POWERFORGE_CONTEXT environment variable. Use lifecycle actions for project-specific preparation, generated-file adjustments, artifact checks, and release guardrails that need a precise pipeline context. Configuration segment order does not control execution order; the At value does.
Examples
Run an inline action after staging
PS>
New-ConfigurationExecute -Name 'Inspect staged module' -At AfterStaging -InlineScript '$ctx = Get-Content $env:POWERFORGE_CONTEXT | ConvertFrom-Json; Get-ChildItem $ctx.ModuleRoot'
Runs the inline PowerShell after the module staging context exists.
Run a script file before publishing
PS>
New-ConfigurationExecute -Name 'Release guard' -At BeforePublish -FilePath '.\Build\Test-ReleaseReady.ps1' -TimeoutSeconds 120
Runs a repository script before publish steps execute.
Common Parameters
This command supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.
For more information, see about_CommonParameters.
Syntax
New-ConfigurationExecute [-At <BeforeDependencies>] [-ContinueOnError] [-Disabled] [-Environment <Hashtable>] -InlineScript <String> [-Name <String>] [-PreferWindowsPowerShell] [-TimeoutSeconds <Int32>] [-WorkingDirectory <String>] [<CommonParameters>]Parameter set:
InlineParameters
- At ModulePipelineActionStage
- Stable module pipeline lifecycle point where the action runs.
- Possible values:
BeforeDependencies,AfterDependencies,BeforeVersioning,AfterVersioning,BeforeStaging,AfterStaging,BeforeBuild,AfterBuild,BeforeManifest,AfterManifest,BeforeDocumentation,AfterDocumentation,BeforeFormatting,AfterFormatting,BeforeValidation,AfterValidation,BeforeTests,AfterTests,BeforeSigning,AfterSigning,BeforeArtefacts,AfterArtefacts,BeforePublish,AfterPublish,BeforeInstall,AfterInstall - ContinueOnError SwitchParameter
- When set, logs a failed action and lets the pipeline continue.
- Disabled SwitchParameter
- When set, disables the action while keeping it in configuration.
- Environment Hashtable
- Environment variable overrides passed to the action process.
- InlineScript String
- Inline PowerShell script text.
- Name String
- Friendly action name shown in progress and result output.
- PreferWindowsPowerShell SwitchParameter
- When set, prefer Windows PowerShell before pwsh on Windows.
- TimeoutSeconds Int32
- Action timeout in seconds. Defaults to five minutes.
- WorkingDirectory String
- Optional working directory. Relative paths resolve from the project root.
Outputs
PowerForge.ConfigurationActionSegment
New-ConfigurationExecute [-At <BeforeDependencies>] [-ContinueOnError] [-Disabled] [-Environment <Hashtable>] -FilePath <String> [-Name <String>] [-PreferWindowsPowerShell] [-TimeoutSeconds <Int32>] [-WorkingDirectory <String>] [<CommonParameters>]Parameter set:
FileParameters
- At ModulePipelineActionStage
- Stable module pipeline lifecycle point where the action runs.
- Possible values:
BeforeDependencies,AfterDependencies,BeforeVersioning,AfterVersioning,BeforeStaging,AfterStaging,BeforeBuild,AfterBuild,BeforeManifest,AfterManifest,BeforeDocumentation,AfterDocumentation,BeforeFormatting,AfterFormatting,BeforeValidation,AfterValidation,BeforeTests,AfterTests,BeforeSigning,AfterSigning,BeforeArtefacts,AfterArtefacts,BeforePublish,AfterPublish,BeforeInstall,AfterInstall - ContinueOnError SwitchParameter
- When set, logs a failed action and lets the pipeline continue.
- Disabled SwitchParameter
- When set, disables the action while keeping it in configuration.
- Environment Hashtable
- Environment variable overrides passed to the action process.
- FilePath String
- Path to a PowerShell script file. Relative paths resolve from the project root.
- Name String
- Friendly action name shown in progress and result output.
- PreferWindowsPowerShell SwitchParameter
- When set, prefer Windows PowerShell before pwsh on Windows.
- TimeoutSeconds Int32
- Action timeout in seconds. Defaults to five minutes.
- WorkingDirectory String
- Optional working directory. Relative paths resolve from the project root.
Outputs
PowerForge.ConfigurationActionSegment
New-ConfigurationExecute [-At <BeforeDependencies>] [-ContinueOnError] [-Disabled] [-Environment <Hashtable>] [-Name <String>] [-PreferWindowsPowerShell] -ScriptBlock <ScriptBlock> [-TimeoutSeconds <Int32>] [-WorkingDirectory <String>] [<CommonParameters>]Parameter set:
ScriptBlockParameters
- At ModulePipelineActionStage
- Stable module pipeline lifecycle point where the action runs.
- Possible values:
BeforeDependencies,AfterDependencies,BeforeVersioning,AfterVersioning,BeforeStaging,AfterStaging,BeforeBuild,AfterBuild,BeforeManifest,AfterManifest,BeforeDocumentation,AfterDocumentation,BeforeFormatting,AfterFormatting,BeforeValidation,AfterValidation,BeforeTests,AfterTests,BeforeSigning,AfterSigning,BeforeArtefacts,AfterArtefacts,BeforePublish,AfterPublish,BeforeInstall,AfterInstall - ContinueOnError SwitchParameter
- When set, logs a failed action and lets the pipeline continue.
- Disabled SwitchParameter
- When set, disables the action while keeping it in configuration.
- Environment Hashtable
- Environment variable overrides passed to the action process.
- Name String
- Friendly action name shown in progress and result output.
- PreferWindowsPowerShell SwitchParameter
- When set, prefer Windows PowerShell before pwsh on Windows.
- ScriptBlock ScriptBlock
- Inline PowerShell script block. The script block text is executed out-of-process.
- TimeoutSeconds Int32
- Action timeout in seconds. Defaults to five minutes.
- WorkingDirectory String
- Optional working directory. Relative paths resolve from the project root.
Outputs
PowerForge.ConfigurationActionSegment