Test‑ShpCiReadiness

SYNOPSIS

Reports whether this session is configured to run ShellPilot unattended.

SYNTAX

Test-ShpCiReadiness [[-ApiBase] <String>] [[-TokenPath] <String>] [[-GitHubHost] <String>] [-NonInteractive]
 [<CommonParameters>]

DESCRIPTION

Resolves the whole CI profile - credential, backend and interactive-capability - and reports it as one object, without sending a chat request or exchanging a token. Nothing is called, nothing is billed and nothing is written; the cmdlet only asks the same resolvers a real call would ask.

It exists because the three things an unattended run needs are decided by three different precedence chains, each with a silent fallback. A pipeline that gets one of them wrong does not fail at the point of the mistake - it fails at the first Invoke-Shp, which is minutes later, in a log nobody opens, with an error about whichever chain happened to give out first. Running this as the first step of a job turns that into a readiness check with named issues.

Ready is true when a credential resolves AND the backend gate lets the call through. An Alternative backend needs no GitHub credential at all, so its TokenSource is reported as NotRequired and readiness turns only on the backend gate. Ready is not a promise that the endpoint answers or that the credential is still valid - only a network call can establish either, and this cmdlet deliberately makes none. Issue carries one line per problem found, in the words the fix is written in.

No secret is returned. The credential is reported by SOURCE only, the API key by source only, and the endpoint has any URL credentials redacted - a readiness object is exactly the sort of thing that ends up pasted into a build log or an issue.

EXAMPLES

EXAMPLE 1

Test-ShpCiReadiness

Reports the resolved token source, backend, interactive capability and overall readiness for the current session.

EXAMPLE 2

$readiness = Test-ShpCiReadiness
if (-not $readiness.Ready) { $readiness.Issue | Write-Error; exit 1 }

The pipeline pre-flight. Fails the job at the configuration step with an actionable message, instead of at the first prompt with whichever error surfaced first.

PARAMETERS

-ApiBase

Test a specific alternative backend instead of the one the session and environment resolve to. Same precedence as Invoke-Shp -ApiBase.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-GitHubHost

Test an explicit GitHub authentication origin instead of Session context or SHELLPILOT_GITHUB_HOST. Reports the resolved origin and its source without sending a request. Invalid host configuration makes Ready false.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-NonInteractive

Report the profile as it would be for a call that stated this explicitly, rather than letting $env:CI decide it.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-TokenPath

Test a specific token file instead of letting the credential resolve through the session context, the environment and the default file.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

System.Management.Automation.PSCustomObject

IsCI, TokenSource (a resolved source, None, or NotRequired for an

Alternative backend), Backend, ApiBase (redacted), BackendSource,

ApiKeySource, NonInteractive, NonInteractiveSource, CanPrompt,

CopilotBackendAllowedInCI, Ready and Issue.

NOTES

RELATED LINKS

Set-ShpContext

Invoke-Shp