GitLab API handler

Description

PowerShell functions to easily interact with the GitLab API. When importing the module, you should supply the GitLabPrivateToken. Include any non-default parameters as well.

Alternatively, all parameters can be stored in $env:GitLabApi (See Examples); which will overwrite any supplied parameters.

Write-Log is supported. If $env:Write-Log is not set, all log output will got to Write-Debug instead.

Parameters

GitLabProtocol

The API protocol. ie: http, https

GitLabDomain

The domain name of the GitLab server. More info

GitLabApiVersion

The API version as defined 'lib/api.rb'. More info

GitLabPrivateToken

The Private Token provides the required authentication. More info

If the GitLabPrivateToken parameter is not supplied, $env:GitLabPrivateToken is audited with the Test-GitLabPrivateToken function to see if a valid SecureString is stored. If one does not exist as an Environment Variable, the user will be prompted to supply one.

If module is used in scripts, you should pass the GitLabPrivateToken in as a SecureString or ensure $env:GitLabPrivateToken is set permanently on the system.

Examples

Basic Import

Import-Module .\gitlab-api.psm1

Will prompt user to set their private token:

Enter your GitLab Private Token (https://git.cas.unt.edu/profile/account): ********************
Set permanently? [Y|n]: y

Import-Module with 1 Argument

$PrivateTokenAsPlainText = 'QVy1PB7sTxfy4pqfZM1U'
$PrivateTokenAsSecureString = ConvertTo-SecureString -String $PrivateTokenAsPlainText -AsPlainText -Force
Import-Module .\gitlab-api.psm1 -ArgumentList $PrivateTokenAsSecureString

Import-Module with 2 Arguments

$PrivateTokenAsPlainText = 'QVy1PB7sTxfy4pqfZM1U'
$PrivateTokenAsSecureString = ConvertTo-SecureString -String $PrivateTokenAsPlainText -AsPlainText -Force
Import-Module .\gitlab-api.psm1 -ArgumentList $PrivateTokenAsSecureString,'example.com'

Import-Module with 3 Arguments

$PrivateTokenAsPlainText = 'QVy1PB7sTxfy4pqfZM1U'
$PrivateTokenAsSecureString = ConvertTo-SecureString -String $PrivateTokenAsPlainText -AsPlainText -Force
Import-Module .\gitlab-api.psm1 -ArgumentList $PrivateTokenAsSecureString,'example.com','http'

Import-Module with 4 Arguments

$PrivateTokenAsPlainText = 'QVy1PB7sTxfy4pqfZM1U'
$PrivateTokenAsSecureString = ConvertTo-SecureString -String $PrivateTokenAsPlainText -AsPlainText -Force
Import-Module .\gitlab-api.psm1 -ArgumentList $PrivateTokenAsSecureString,'example.com','http','v2'

Import-Module with 4 Argument Array

$ArgumentList = @(
    (ConvertTo-SecureString -String 'QVy1PB7sTxfy4pqfZM1U' -AsPlainText -Force),
    'example.com',
    'http',
    'v2'
)
Import-Module .\gitlab-api.psm1 -ArgumentList $ArgumentList

Import-Module with Environment Variable

$env:GitLabApi = ConvertTo-Json @{
    'GitLabProtocol' = 'http';
    'GitLabDomain' = 'example.com';
    'GitLabVersion' = 'v2';
} -Compress
Import-Module .\gitlab-api.psm1

Note: You can also set $env:GitLabPrivateToken. For details on how, you should review the code for Set-GitLabPrivateToken

Notes

Code is repo'd on GitHub.com and GitLab.com:

• https://github.com/Vertigion/GitLab-API
• https://gitlab.com/Vertigion/GitLab-API

Other tools used:

• REQUIREMENTS.json
• Write-Log

All .Tests.ps1 files are run using Pester.