add parameter to deploy new unified environment in early release cycle #128

[FH-Inway]

This pull request adds support for creating early release environments in the New-UnifiedEnvironment PowerShell function. The main changes introduce a new -EarlyRelease switch parameter, update documentation and examples, and ensure the early release option is properly handled in the environment creation payload.

implements #128

[Copilot]

Pull request overview

Adds early-release-cycle provisioning support to New-UnifiedEnvironment.

Changes:

• Adds the -EarlyRelease switch and help example.
• Adds cluster.category = "FirstRelease" to creation payloads.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[FH-Inway]

@Splaxi I have another version that uses the api.powerplatform.com API here: FH-Inway@f068105

Since that API is documented, I would rather use it. However, it introduces an unrelated change for the parameter region, which is now called Macro Region instead of Azure Region. It also cannot be used together with location and it seems to be a tenant setting if it can be used at all (see https://learn.microsoft.com/en-us/rest/api/power-platform/environmentmanagement/environment-provisioning/get-supported-locations). Let me know if that is a blocker for you, otherwise I would prepare the api.powerplatform.com version for merge.

I also noticed there is no workflow yet to update the documentation and signature tests like there is for d365fo.tools. Anything I should know before trying to add it?

[Splaxi]

I think I remember at IsPresent will actually trigger - if you do EarlyRelease:$false

Normal if - just on the var is what we are after.

Make a local test function - and prove me wrong 😉

[FH-Inway]

Copilot gave me this, which convinces me:

function Test-EarlyReleaseSwitch {
    param(
        [switch] $EarlyRelease
    )

    $result = [ordered]@{
        IsPresent = $EarlyRelease.IsPresent
        ToString  = $EarlyRelease.ToString()
    }

    [pscustomobject]$result
}

Write-Host "No switch passed:"
Test-EarlyReleaseSwitch

Write-Host "Switch passed explicitly false:" 
Test-EarlyReleaseSwitch -EarlyRelease:$false

Write-Host "Switch passed explicitly true:" 
Test-EarlyReleaseSwitch -EarlyRelease:$true

Output:

No switch passed:

Switch passed explicitly false:
Switch passed explicitly true:
IsPresent ToString
--------- --------
    False False
    False False
     True True

[FH-Inway]

But yeah, let me remove it, doesn't make sense in this context.

[Splaxi]

IsPresent was discussed further down - this might not be what you are after

[Splaxi]

I'm not sure.

We are focused on getting things to west europe - so that why we have the current support for that. If the new API - it the "right" one to use, and we lose that option - then maybe that is what we should support.

What does your gut feeling say ?

[FH-Inway]

My gut feeling says I should not trust my gut on this 😄
This seems to be a new concept that is still evolving, so I have to do some reading.

However, my test environments that I deployed using api.powerplatform.com give me a weird redirect error when trying to access the D365FO url. So either something is missing or the API is not yet fit for duty.

https://gw.eu-il301.gateway.prod.island.powerapps.com/replyurl/v1
Redirect invalid. Correlation id 8a3135f7-c2be-42f1-8184-f93c409f27a1. Timestamp 2026-08-14 09:22:37Z. Error code 1011.

[Splaxi]

Let's stick with what we have for now 😉

[FH-Inway]

Ok, here we go.

The cleanup was a bit of a pain, since no scripts to format the comment based help or update the unit tests and docs existed. I copied them over from d365fo.tools. Since they are pretty stable, I think we can live with the redundancy.
The validate workflow currently runs mostly on Windows PowerShell, which was an issue for the individual unit tests. I switched it to PowerShell 7, but we probably want all tests to run in that.