From 114ab85faae789c586e59751dd592d34f3bc790b Mon Sep 17 00:00:00 2001 From: Robin Malik <8790561+robinmalik@users.noreply.github.com> Date: Sun, 22 Oct 2023 15:39:15 +0100 Subject: [PATCH 1/2] Add comment based help for all functions --- Source/Public/Connect-Semaphore.ps1 | 22 ++++++ Source/Public/Disable-SemaphoreUserToken.ps1 | 19 +++++ Source/Public/Get-SemaphoreProject.ps1 | 24 ++++++ .../Get-SemaphoreProjectEnvironment.ps1 | 27 +++++++ .../Public/Get-SemaphoreProjectInventory.ps1 | 27 +++++++ Source/Public/Get-SemaphoreProjectKey.ps1 | 27 +++++++ .../Public/Get-SemaphoreProjectRepository.ps1 | 27 +++++++ Source/Public/Get-SemaphoreProjectTask.ps1 | 30 ++++++++ .../Public/Get-SemaphoreProjectTemplate.ps1 | 30 ++++++++ Source/Public/Get-SemaphoreUserToken.ps1 | 18 ++++- Source/Public/New-SemaphoreProject.ps1 | 33 ++++++++ .../New-SemaphoreProjectEnvironment.ps1 | 22 ++++++ .../Public/New-SemaphoreProjectInventory.ps1 | 39 ++++++++++ Source/Public/New-SemaphoreProjectKey.ps1 | 28 +++++++ .../Public/New-SemaphoreProjectRepository.ps1 | 10 ++- .../Public/New-SemaphoreProjectTemplate.ps1 | 50 ++++++++++-- Source/Public/New-SemaphoreUserToken.ps1 | 15 ++++ Source/Public/Remove-SemaphoreProject.ps1 | 17 +++++ .../Remove-SemaphoreProjectEnvironment.ps1 | 22 ++++++ .../Remove-SemaphoreProjectInventory.ps1 | 22 ++++++ Source/Public/Remove-SemaphoreProjectKey.ps1 | 22 ++++++ .../Remove-SemaphoreProjectRepository.ps1 | 22 ++++++ .../Remove-SemaphoreProjectTemplate.ps1 | 22 ++++++ Source/Public/Start-SemaphoreProjectTask.ps1 | 76 ++++++++++++++----- 24 files changed, 624 insertions(+), 27 deletions(-) diff --git a/Source/Public/Connect-Semaphore.ps1 b/Source/Public/Connect-Semaphore.ps1 index bdff0eb..9c208b9 100644 --- a/Source/Public/Connect-Semaphore.ps1 +++ b/Source/Public/Connect-Semaphore.ps1 @@ -1,5 +1,27 @@ function Connect-Semaphore { + <# + .SYNOPSIS + Connects to Semaphore. + + .DESCRIPTION + This function connects to Semaphore. + + .PARAMETER Url + The URL of the Semaphore instance to connect to. + + .PARAMETER Credential + The credentials to use to connect to Semaphore. + + .EXAMPLE + Connect-Semaphore -Url https://semaphore.example.com -Credential (Get-Credential) + + Connects to the Semaphore instance at https://semaphore.example.com using the credentials provided. + + .NOTES + N/A + #> + [CmdletBinding()] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/Disable-SemaphoreUserToken.ps1 b/Source/Public/Disable-SemaphoreUserToken.ps1 index a846371..cc0f04a 100644 --- a/Source/Public/Disable-SemaphoreUserToken.ps1 +++ b/Source/Public/Disable-SemaphoreUserToken.ps1 @@ -1,5 +1,24 @@ function Disable-SemaphoreUserToken { + <# + .SYNOPSIS + Disables a Semaphore user token for the currently authenticated user. + + .DESCRIPTION + This function disables a Semaphore user token for the currently authenticated user. + + .PARAMETER TokenId + The ID of the token to disable. + + .EXAMPLE + Disable-SemaphoreUserToken -TokenId 1 + + Disables the token with ID 1. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding(SupportsShouldProcess)] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess', '', Justification = 'Does not alter system state.')] param ( diff --git a/Source/Public/Get-SemaphoreProject.ps1 b/Source/Public/Get-SemaphoreProject.ps1 index 920d003..5bcb096 100644 --- a/Source/Public/Get-SemaphoreProject.ps1 +++ b/Source/Public/Get-SemaphoreProject.ps1 @@ -1,5 +1,29 @@ function Get-SemaphoreProject { + <# + .SYNOPSIS + Returns projects for the current Semaphore instance. + + .DESCRIPTION + This function returns projects for the current Semaphore instance. + + .PARAMETER Name + (Optional) The name of the project to retrieve. If specified, only the project with a matching name will be returned. + + .EXAMPLE + Get-SemaphoreProject + + Retrieves information about all projects. + + .EXAMPLE + Get-SemaphoreProject -Name "MyProject" + + Retrieves information about the project with the name "MyProject." + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding()] param ( [Parameter(Mandatory = $false)] diff --git a/Source/Public/Get-SemaphoreProjectEnvironment.ps1 b/Source/Public/Get-SemaphoreProjectEnvironment.ps1 index 29be6b3..c2942a7 100644 --- a/Source/Public/Get-SemaphoreProjectEnvironment.ps1 +++ b/Source/Public/Get-SemaphoreProjectEnvironment.ps1 @@ -1,5 +1,32 @@ function Get-SemaphoreProjectEnvironment { + <# + .SYNOPSIS + Returns project environments for the given project. + + .DESCRIPTION + This function retrieves information about environments associated with a project. + + .PARAMETER ProjectId + The ID of the project for which you want to retrieve environments. + + .PARAMETER Name + (Optional) The name of the environment to retrieve. If specified, only the environment with a matching name will be returned. + + .EXAMPLE + Get-SemaphoreProjectEnvironment -ProjectId 2 + + Retrieves all environments under the project with ID 2. + + .EXAMPLE + Get-SemaphoreProjectEnvironment -ProjectId 5 -Name "Production" + + Retrieves the "Production" environment for the project with ID 5. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding()] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/Get-SemaphoreProjectInventory.ps1 b/Source/Public/Get-SemaphoreProjectInventory.ps1 index f7aadbf..556b69e 100644 --- a/Source/Public/Get-SemaphoreProjectInventory.ps1 +++ b/Source/Public/Get-SemaphoreProjectInventory.ps1 @@ -1,5 +1,32 @@ function Get-SemaphoreProjectInventory { + <# + .SYNOPSIS + Returns inventories for the given project. + + .DESCRIPTION + This function retrieves information about inventories associated with a project. + + .PARAMETER ProjectId + The ID of the project for which you want to retrieve environments. + + .PARAMETER Name + (Optional) The name of the inventory to retrieve. If specified, only the inventory with a matching name will be returned. + + .EXAMPLE + Get-SemaphoreProjectInventory -ProjectId 2 + + Retrieves all inventories under the project with ID 2. + + .EXAMPLE + Get-SemaphoreProjectInventory -ProjectId 5 -Name "AllHosts" + + Retrieves the "AllHosts" inventory for the project with ID 5. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding()] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/Get-SemaphoreProjectKey.ps1 b/Source/Public/Get-SemaphoreProjectKey.ps1 index 70c4d1f..81c0727 100644 --- a/Source/Public/Get-SemaphoreProjectKey.ps1 +++ b/Source/Public/Get-SemaphoreProjectKey.ps1 @@ -1,5 +1,32 @@ function Get-SemaphoreProjectKey { + <# + .SYNOPSIS + Returns keys for the given project. + + .DESCRIPTION + This function retrieves information about keys associated with a project. + + .PARAMETER ProjectId + The ID of the project for which you want to retrieve keys. + + .PARAMETER Name + (Optional) The name of the key to retrieve. If specified, only the key with a matching name will be returned. + + .EXAMPLE + Get-SemaphoreProjectKey -ProjectId 2 + + Retrieves all keys under the project with ID 2. + + .EXAMPLE + Get-SemaphoreProjectKey -ProjectId 5 -Name "MyAccount" + + Retrieves the "MyAccount" key for the project with ID 5. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding()] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/Get-SemaphoreProjectRepository.ps1 b/Source/Public/Get-SemaphoreProjectRepository.ps1 index 805ce1b..2cc8cb4 100644 --- a/Source/Public/Get-SemaphoreProjectRepository.ps1 +++ b/Source/Public/Get-SemaphoreProjectRepository.ps1 @@ -1,5 +1,32 @@ function Get-SemaphoreProjectRepository { + <# + .SYNOPSIS + Returns repositories for the given project. + + .DESCRIPTION + This function retrieves information about repositories associated with a project. + + .PARAMETER ProjectId + The ID of the project for which you want to retrieve repositories. + + .PARAMETER Name + (Optional) The name of the repository to retrieve. If specified, only the repository with a matching name will be returned. + + .EXAMPLE + Get-SemaphoreProjectRepository -ProjectId 2 + + Retrieves all repositories under the project with ID 2. + + .EXAMPLE + Get-SemaphoreProjectRepository -ProjectId 5 -Name "AnsiblePlaybooks" + + Retrieves the "AnsiblePlaybooks" repository for the project with ID 5. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding()] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/Get-SemaphoreProjectTask.ps1 b/Source/Public/Get-SemaphoreProjectTask.ps1 index 032267f..2e94528 100644 --- a/Source/Public/Get-SemaphoreProjectTask.ps1 +++ b/Source/Public/Get-SemaphoreProjectTask.ps1 @@ -1,5 +1,35 @@ function Get-SemaphoreProjectTask { + <# + .SYNOPSIS + Returns tasks for the given project and optionally, template. + + .DESCRIPTION + This function retrieves information about tasks associated with a project and optionally, template. + + .PARAMETER ProjectId + The ID of the project for which you want to retrieve tasks. + + .PARAMETER Id + (Optional) The ID of the task to retrieve. If specified, only the task with a matching ID will be returned. + + .PARAMETER TemplateId + (Optional) The ID of the template to retrieve tasks for. If specified, only tasks associated with the template with a matching ID will be returned. + + .EXAMPLE + Get-SemaphoreProjectTask -ProjectId 2 + + Retrieves all tasks under the project with ID 2. + + .EXAMPLE + Get-SemaphoreProjectTask -ProjectId 5 -TemplateId 2 + + Retrieves all tasks for the template with ID 2 under the project with ID 5. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding()] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/Get-SemaphoreProjectTemplate.ps1 b/Source/Public/Get-SemaphoreProjectTemplate.ps1 index 3ae6df8..68443dd 100644 --- a/Source/Public/Get-SemaphoreProjectTemplate.ps1 +++ b/Source/Public/Get-SemaphoreProjectTemplate.ps1 @@ -1,5 +1,35 @@ function Get-SemaphoreProjectTemplate { + <# + .SYNOPSIS + Returns templates for the given project. + + .DESCRIPTION + This function retrieves information about templates associated with a project. + + .PARAMETER ProjectId + The ID of the project for which you want to retrieve templates. + + .PARAMETER Id + (Optional) The ID of the template to retrieve. If specified, only the template with a matching ID will be returned. + + .PARAMETER Name + (Optional) The name of the template to retrieve. If specified, only the template with a matching name will be returned. + + .EXAMPLE + Get-SemaphoreProjectTemplate -ProjectId 2 + + Retrieves all templates under the project with ID 2. + + .EXAMPLE + Get-SemaphoreProjectTemplate -ProjectId 5 -TemplateId 2 + + Retrieves all templates for the template with ID 2 under the project with ID 5. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding(DefaultParameterSetName = 'Default')] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/Get-SemaphoreUserToken.ps1 b/Source/Public/Get-SemaphoreUserToken.ps1 index b44d38e..9061bf1 100644 --- a/Source/Public/Get-SemaphoreUserToken.ps1 +++ b/Source/Public/Get-SemaphoreUserToken.ps1 @@ -1,6 +1,22 @@ function Get-SemaphoreUserToken { - [CmdletBinding(SupportsShouldProcess)] + <# + .SYNOPSIS + Returns user tokens for the given project. + + .DESCRIPTION + This function retrieves user tokens for the logged in user. + + .EXAMPLE + Get-SemaphoreUserToken + + Retrieves all user tokens for the logged in user. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + + [CmdletBinding()] param ( ) diff --git a/Source/Public/New-SemaphoreProject.ps1 b/Source/Public/New-SemaphoreProject.ps1 index 4a225d4..73366d9 100644 --- a/Source/Public/New-SemaphoreProject.ps1 +++ b/Source/Public/New-SemaphoreProject.ps1 @@ -1,5 +1,38 @@ function New-SemaphoreProject { + <# + .SYNOPSIS + Creates a new project. + + .DESCRIPTION + Creates a new project. + + .PARAMETER Name + The name of the project to create. + + .PARAMETER Alert + (Optional) Whether to send alerts for this project. + + .PARAMETER TelegramChatId + (Optional) The Telegram chat ID to send alerts to. + + .PARAMETER MaxParallelTasks + (Optional) The maximum number of parallel tasks to run. + + .EXAMPLE + New-SemaphoreProject -Name "My Project" + + Creates a new project with the name "My Project". + + .EXAMPLE + New-SemaphoreProject -Name "My Project" -Alert -TelegramChatId "123456789" -MaxParallelTasks 5 + + Creates a new project with the name "My Project", with alerts enabled, sending alerts to the Telegram chat with ID "123456789", and with a maximum of 5 parallel tasks. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding()] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/New-SemaphoreProjectEnvironment.ps1 b/Source/Public/New-SemaphoreProjectEnvironment.ps1 index 386bcec..a4c2722 100644 --- a/Source/Public/New-SemaphoreProjectEnvironment.ps1 +++ b/Source/Public/New-SemaphoreProjectEnvironment.ps1 @@ -1,5 +1,27 @@ function New-SemaphoreProjectEnvironment { + <# + .SYNOPSIS + Creates a new environment for the given project. + + .DESCRIPTION + This function creates a new environment for the given project. + + .PARAMETER ProjectId + The ID of the project to create the environment for. + + .PARAMETER Name + The name of the environment to create. + + .EXAMPLE + New-SemaphoreProjectEnvironment -ProjectId 2 -Name "Production" + + Creates a new environment with the name "Production" for the project with ID 2. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding()] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/New-SemaphoreProjectInventory.ps1 b/Source/Public/New-SemaphoreProjectInventory.ps1 index 11e7bf5..713ef8f 100644 --- a/Source/Public/New-SemaphoreProjectInventory.ps1 +++ b/Source/Public/New-SemaphoreProjectInventory.ps1 @@ -1,5 +1,44 @@ function New-SemaphoreProjectInventory { + <# + .SYNOPSIS + Creates a new inventory for the given project. + + .DESCRIPTION + This function creates a new inventory for the given project. + + .PARAMETER ProjectId + The ID of the project to create the inventory for. + + .PARAMETER KeyId + The ID of the key to use for the inventory. + + .PARAMETER Name + The name of the inventory to create. + + .PARAMETER Hostnames + (Optional) The hostnames to use for the inventory. If not specified, the InventoryFile parameter must be specified. + + .PARAMETER WinRMConnection + (Optional) Whether to use WinRM for the connection. This works by adding specific variables to the static inventory. + + .PARAMETER InventoryFile + (Optional) The path to the inventory file to use. If not specified, the Hostnames parameter must be specified. + + .EXAMPLE + New-SemaphoreProjectInventory -ProjectId 2 -KeyId 1 -Name "Production" -Hostnames "server1", "server2" + + Creates a new inventory with the name "Production" for the project with ID 2, using the key with ID 1, and with the hostnames "server1" and "server2". + + .EXAMPLE + New-SemaphoreProjectInventory -ProjectId 2 -KeyId 1 -Name "Test" -InventoryFile "/usr/share/ansible/inventories/webhosts.ini" + + Creates a new inventory with the name "Test" for the project with ID 2, using the key with ID 1, and using the inventory file "/usr/share/ansible/inventories/webhosts.ini". + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding(SupportsShouldProcess)] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/New-SemaphoreProjectKey.ps1 b/Source/Public/New-SemaphoreProjectKey.ps1 index ea3be63..69b6eec 100644 --- a/Source/Public/New-SemaphoreProjectKey.ps1 +++ b/Source/Public/New-SemaphoreProjectKey.ps1 @@ -1,5 +1,33 @@ function New-SemaphoreProjectKey { + <# + .SYNOPSIS + Creates a new key for the given project. + + .DESCRIPTION + This function creates a new key for the given project. + + .PARAMETER ProjectId + The ID of the project to create the key for. + + .PARAMETER Name + The name of the key to create. + + .PARAMETER Type + The type of key to create. Valid values are "UserNamePassword", "SSHKey", and "Empty". + + .PARAMETER Credential + The credential to use. This parameter is only used if the Type parameter is set to "UserNamePassword" or "SSHKey". + + .EXAMPLE + New-SemaphoreProjectKey -ProjectId 2 -Name "MyAccount" -Type "UserNamePassword" -Credential $Credential + + Creates a new key with the name "MyAccount" for the project with ID 2, using the username and password in the $Credential variable. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding(SupportsShouldProcess, DefaultParameterSetName = 'EmptyCredentials')] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/New-SemaphoreProjectRepository.ps1 b/Source/Public/New-SemaphoreProjectRepository.ps1 index d1d6f7e..b01e1cb 100644 --- a/Source/Public/New-SemaphoreProjectRepository.ps1 +++ b/Source/Public/New-SemaphoreProjectRepository.ps1 @@ -50,9 +50,13 @@ function New-SemaphoreProjectRepository ssh_key_id = $KeyId project_id = $ProjectId } | ConvertTo-Json -Compress - Invoke-RestMethod -Uri "$($Script:Config.url)/project/$ProjectId/repositories" -Method Post -Body $Body -ContentType 'application/json' -WebSession $Script:Session | Out-Null - # Return the created object: - Get-SemaphoreProjectRepository -ProjectId $ProjectId -Name $Name + + if($PSCmdlet.ShouldProcess("Project $ProjectId", "Create repository $Name")) + { + Invoke-RestMethod -Uri "$($Script:Config.url)/project/$ProjectId/repositories" -Method Post -Body $Body -ContentType 'application/json' -WebSession $Script:Session | Out-Null + # Return the created object: + Get-SemaphoreProjectRepository -ProjectId $ProjectId -Name $Name + } } catch { diff --git a/Source/Public/New-SemaphoreProjectTemplate.ps1 b/Source/Public/New-SemaphoreProjectTemplate.ps1 index f8e6a74..8d4ea4a 100644 --- a/Source/Public/New-SemaphoreProjectTemplate.ps1 +++ b/Source/Public/New-SemaphoreProjectTemplate.ps1 @@ -1,5 +1,43 @@ function New-SemaphoreProjectTemplate { + <# + .SYNOPSIS + Creates a new Semaphore project template. + + .DESCRIPTION + This function creates a new Semaphore project template. + + .PARAMETER ProjectId + The ID of the project to create the key for. + + .PARAMETER InventoryId + The ID of the inventory to use for the template. + + .PARAMETER RepositoryId + The ID of the repository to use for the template. + + .PARAMETER EnvironmentId + The ID of the environment to use for the template. + + .PARAMETER KeyId + The ID of the key to use for the template. + + .PARAMETER Playbook + The playbook to use for the template. + + .PARAMETER Name + The name of the template to create. + + .PARAMETER Description + (Optional) The description of the template to create. + + .EXAMPLE + New-SemaphoreProjectTemplate -ProjectId 2 -InventoryId 1 -RepositoryId 1 -EnvironmentId 1 -KeyId 1 -Playbook "/usr/share/ansible/playbooks/test.yml" -Name "Test" + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding(SupportsShouldProcess)] param ( [Parameter(Mandatory = $true)] @@ -73,8 +111,6 @@ function New-SemaphoreProjectTemplate } #> - - #Region Construct body and send the request try { @@ -91,9 +127,13 @@ function New-SemaphoreProjectTemplate 'suppress_success_alerts' = $SuppressSuccessAlerts 'allow_override_args_in_task' = $AllowOverrideArgsInTask } | ConvertTo-Json - Invoke-RestMethod -Uri "$($Script:Config.url)/project/$ProjectId/templates" -Method Post -Body $Body -ContentType 'application/json' -WebSession $Script:Session | Out-Null - # Return the created object: - Get-SemaphoreProjectTemplate -ProjectId $ProjectId -Name $Name + + if($PSCmdlet.ShouldProcess("Project $ProjectId", "Create template $Name")) + { + Invoke-RestMethod -Uri "$($Script:Config.url)/project/$ProjectId/templates" -Method Post -Body $Body -ContentType 'application/json' -WebSession $Script:Session | Out-Null + # Return the created object: + Get-SemaphoreProjectTemplate -ProjectId $ProjectId -Name $Name + } } catch { diff --git a/Source/Public/New-SemaphoreUserToken.ps1 b/Source/Public/New-SemaphoreUserToken.ps1 index 0556d35..40814a9 100644 --- a/Source/Public/New-SemaphoreUserToken.ps1 +++ b/Source/Public/New-SemaphoreUserToken.ps1 @@ -1,5 +1,20 @@ function New-SemaphoreUserToken { + <# + .SYNOPSIS + Creates a new token for the logged in user. + + .DESCRIPTION + This function creates a new token for the logged in user. + + .EXAMPLE + New-SemaphoreUserToken + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + + [CmdletBinding(SupportsShouldProcess)] param ( ) diff --git a/Source/Public/Remove-SemaphoreProject.ps1 b/Source/Public/Remove-SemaphoreProject.ps1 index f414b4b..5105d54 100644 --- a/Source/Public/Remove-SemaphoreProject.ps1 +++ b/Source/Public/Remove-SemaphoreProject.ps1 @@ -1,5 +1,22 @@ function Remove-SemaphoreProject { + <# + .SYNOPSIS + Removes a Semaphore project. + + .DESCRIPTION + This function removes a Semaphore project. + + .PARAMETER ProjectId + The ID of the project to remove. + + .EXAMPLE + Remove-SemaphoreProject -ProjectId 2 + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding(SupportsShouldProcess)] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/Remove-SemaphoreProjectEnvironment.ps1 b/Source/Public/Remove-SemaphoreProjectEnvironment.ps1 index e3000a5..de7d843 100644 --- a/Source/Public/Remove-SemaphoreProjectEnvironment.ps1 +++ b/Source/Public/Remove-SemaphoreProjectEnvironment.ps1 @@ -1,5 +1,27 @@ function Remove-SemaphoreProjectEnvironment { + <# + .SYNOPSIS + Removes an environment from a Semaphore project. + + .DESCRIPTION + This function removes an environment from a Semaphore project. + + .PARAMETER ProjectId + The ID of the project. + + .PARAMETER Id + The ID of the environment to remove. + + .EXAMPLE + Remove-SemaphoreProjectEnvironment -ProjectId 2 -Id 1 + + Removes the environment with ID 1 from the project with ID 2. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding(SupportsShouldProcess)] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/Remove-SemaphoreProjectInventory.ps1 b/Source/Public/Remove-SemaphoreProjectInventory.ps1 index 56b1985..3b85b7f 100644 --- a/Source/Public/Remove-SemaphoreProjectInventory.ps1 +++ b/Source/Public/Remove-SemaphoreProjectInventory.ps1 @@ -1,5 +1,27 @@ function Remove-SemaphoreProjectInventory { + <# + .SYNOPSIS + Removes an inventory from a Semaphore project. + + .DESCRIPTION + This function removes an inventory from a Semaphore project. + + .PARAMETER ProjectId + The ID of the project. + + .PARAMETER Id + The ID of the inventory to remove. + + .EXAMPLE + Remove-SemaphoreProjectInventory -ProjectId 2 -Id 1 + + Removes the inventory with ID 1 from the project with ID 2. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding(SupportsShouldProcess)] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/Remove-SemaphoreProjectKey.ps1 b/Source/Public/Remove-SemaphoreProjectKey.ps1 index c7a22d2..c3381fe 100644 --- a/Source/Public/Remove-SemaphoreProjectKey.ps1 +++ b/Source/Public/Remove-SemaphoreProjectKey.ps1 @@ -1,5 +1,27 @@ function Remove-SemaphoreProjectKey { + <# + .SYNOPSIS + Removes a Semaphore project key. + + .DESCRIPTION + This function removes a Semaphore project key. + + .PARAMETER ProjectId + The ID of the project. + + .PARAMETER Id + The ID of the key to remove. + + .EXAMPLE + Remove-SemaphoreProjectKey -ProjectId 2 -Id 1 + + Removes the key with ID 1 from the project with ID 2. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding(SupportsShouldProcess)] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/Remove-SemaphoreProjectRepository.ps1 b/Source/Public/Remove-SemaphoreProjectRepository.ps1 index 2e07ff9..d3e24d5 100644 --- a/Source/Public/Remove-SemaphoreProjectRepository.ps1 +++ b/Source/Public/Remove-SemaphoreProjectRepository.ps1 @@ -1,5 +1,27 @@ function Remove-SemaphoreProjectRepository { + <# + .SYNOPSIS + Removes a Semaphore project repository. + + .DESCRIPTION + This function removes a Semaphore project repository. + + .PARAMETER ProjectId + The ID of the project. + + .PARAMETER Id + The ID of the repository to remove. + + .EXAMPLE + Remove-SemaphoreProjectRepository -ProjectId 2 -Id 1 + + Removes the repository with ID 1 from the project with ID 2. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding(SupportsShouldProcess)] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/Remove-SemaphoreProjectTemplate.ps1 b/Source/Public/Remove-SemaphoreProjectTemplate.ps1 index 6052bb8..70e58db 100644 --- a/Source/Public/Remove-SemaphoreProjectTemplate.ps1 +++ b/Source/Public/Remove-SemaphoreProjectTemplate.ps1 @@ -1,5 +1,27 @@ function Remove-SemaphoreProjectTemplate { + <# + .SYNOPSIS + Removes a Semaphore project template. + + .DESCRIPTION + This function removes a Semaphore project template. + + .PARAMETER ProjectId + The ID of the project. + + .PARAMETER Id + The ID of the template to remove. + + .EXAMPLE + Remove-SemaphoreProjectTemplate -ProjectId 2 -Id 1 + + Removes the template with ID 1 from the project with ID 2. + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding(SupportsShouldProcess)] param ( [Parameter(Mandatory = $true)] diff --git a/Source/Public/Start-SemaphoreProjectTask.ps1 b/Source/Public/Start-SemaphoreProjectTask.ps1 index cde4598..d4ea497 100644 --- a/Source/Public/Start-SemaphoreProjectTask.ps1 +++ b/Source/Public/Start-SemaphoreProjectTask.ps1 @@ -1,5 +1,38 @@ function Start-SemaphoreProjectTask { + <# + .SYNOPSIS + Triggers a run of a Semaphore template task. + + .DESCRIPTION + This function triggers a new execution of a task via a Semaphore project template. + + .PARAMETER ProjectId + The ID of the project. + + .PARAMETER TemplateId + The ID of the template to run. + + .PARAMETER CLIArguments + Any CLI arguments to pass to the task. + + .PARAMETER Wait + Whether to wait for the task to complete before returning. + + .EXAMPLE + Start-SemaphoreProjectTask -ProjectId 2 -TemplateId 1 + + Triggers a run of the template with ID 1 in the project with ID 2. + + .EXAMPLE + Start-SemaphoreProjectTask -ProjectId 2 -TemplateId 1 -Wait + + Triggers a run of the template with ID 1 in the project with ID 2 + + .NOTES + To use this function, make sure you have already connected using the Connect-Semaphore function. + #> + [CmdletBinding(SupportsShouldProcess)] param ( [Parameter(Mandatory = $true)] @@ -30,36 +63,41 @@ function Start-SemaphoreProjectTask } process { - $Body = @{ - "template_id" = $TemplateId - "environment" = "{}" - "project_id" = $ProjectId - } - - if($CLIArguments) - { - $Body.Add("cli_arguments", $CLIArguments) - } - + #Region Create the body and send the request try { + $Body = @{ + "template_id" = $TemplateId + "environment" = "{}" + "project_id" = $ProjectId + } + + if($CLIArguments) + { + $Body.Add("cli_arguments", $CLIArguments) + } + $Data = Invoke-RestMethod -Uri "$($Script:Config.url)/project/$ProjectId/tasks" -Method Post -Body $Body -ContentType 'application/json' -WebSession $Script:Session if(!$Data) { return $Null } + + # If we're not waiting and polling the task, return data and exit: + if(!$Wait) + { + return $Data + } } catch { throw $_ } + #EndRegion - if(!$Wait) - { - return $Data - } - else + #Region If Wait, poll the task until it is complete + if($Wait) { # Start a loop that calls Get-SemaphoreProjectTask with the Id returned from the previous call. If the status property is running or success # break out of the loop and return the task object. Attempt the loop for a maximum of 50 attempts with 5 seconds wait between each attempt. @@ -98,9 +136,11 @@ function Start-SemaphoreProjectTask } } until($AttemptCount -eq $MaxAttempts) - } - return $Task + + return $Task + } + #EndRegion } end { From 4f3b9dc2ad3ab713d684f512764ea97a302cd896 Mon Sep 17 00:00:00 2001 From: Robin Malik <8790561+robinmalik@users.noreply.github.com> Date: Sun, 22 Oct 2023 15:56:09 +0100 Subject: [PATCH 2/2] Bump version and update changelog --- CHANGELOG.md | 8 ++++++++ Source/PSSemaphore.psd1 | 2 +- ToDo.md | 1 - 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 85402ad..a08b9b7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,11 @@ +## [0.0.3] - 2023-10-22 + +* 📚 [Added] Documented all functions with comment-based help. + +## [0.0.2] - 2023-10-21 + +* ✨ [New] Add a GitHub workflow for publishing to the PowerShell Gallery. + ## [0.0.1] - 2023-10-21 * 🎉 Initial release. \ No newline at end of file diff --git a/Source/PSSemaphore.psd1 b/Source/PSSemaphore.psd1 index a2a9ad4..61e807b 100644 --- a/Source/PSSemaphore.psd1 +++ b/Source/PSSemaphore.psd1 @@ -12,7 +12,7 @@ RootModule = 'PSSemaphore.psm1' # Version number of this module. - ModuleVersion = '0.0.2' + ModuleVersion = '0.0.3' # Supported PSEditions # CompatiblePSEditions = @() diff --git a/ToDo.md b/ToDo.md index e96cb8f..41e3bb5 100644 --- a/ToDo.md +++ b/ToDo.md @@ -2,7 +2,6 @@ ### Priority Tasks: -* All functions: Add comment-based help / syntax blocks. * `Start-SemaphoreProjectTask -Wait` can only parse output if the following is set in ansible.cfg: ``` [defaults]