GitlabCli

‌

Interact with GitLab via PowerShell

Getting Started

Module

Install-Module -Name GitlabCli

Docker Image

docker run -it ghcr.io/chris-peterson/pwsh-gitlab/gitlab-cli

Configuration

Environment Variables

$env:GITLAB_ACCESS_TOKEN

Obtain a "Personal Access Token" (PAT) for your GitLab instance

https://<your gitlab instance>/-/profile/personal_access_tokens

Make the value available via

$env:GITLAB_ACCESS_TOKEN='<your pat>'.

One way to do this would be to add a line to your $PROFILE

$env:GITLAB_URL

(Optional) If using a gitlab instance that is not gitlab.com, provide it via:

$env:GITLAB_URL='<your gitlab instance>'

Example PowerShell Profile

$env:GITLAB_URL='gitlab.mydomain.com'
$env:GITLAB_ACCESS_TOKEN='<my token>'
Import-Module GitlabCli

Configuration File

The following commands can be used to configure your system for use with multiple gitlab sites.

• Add-GitlabSite
• Remove-GitlabSite
• Set-DefaultGitlabSite

Global Switches

The following switches are supported when possible:

-WhatIf : For mutable operations (or for some complex query operations), gives a preview of what actions would be taken

-Select : Select into a property of the response. A shortcut for | Select-Object -ExpandProperty or select multiple properties separated by commas

-SiteUrl : Optional. By default, site url is inferred from the local git context. Providing a value overrides this value. The provided value must match a configured site's url (e.g. gitlab.com)

-Follow : For operations that create a resource, follow the the URL after creation

-MaxPages: For query operations, maximum number of pages to return. Typically defaults to 1

-Recurse: For tree-based operations, opt-in to recurse children (e.g. Get-GitlabProject -GroupId 'mygroup' -Recurse)

-CopyToClipboard : For token-based operations, copy the resultant token to the clipboard rather than displaying in the terminal

Global Behaviors

If invoking commands from within a git repository, . can be used for ProjectId / BranchName to use the local context.

Most objects returned from commands have a Url property. This makes it so you can pipe one or more objects to Open-InBrowser (aka go)

Examples

Groups

Get-GitlabGroup

Get-GitlabGroup 'mygroup'

  ID Name     Url
  -- ----     ---
  23 mygroup  https://gitlab.mydomain.com/mygroup

Remove-GitlabGroup

Remove-GitlabGroup 'mygroup'

Clone-GitlabGroup (aka Copy-GitlabGroupToLocalFileSystem)

Clone-GitlabGroup 'mygroup'

Projects

Get-GitlabProject (by id)

Get-GitlabProject 'mygroup/myproject'
# OR
Get-GitlabProject 42
# OR
Get-GitlabProject # use local context

  ID Name        Group     Url
  -- ----        -----     ---
  42 myproject   mygroup   https://gitlab.mydomain.com/mygroup/myproject

Get-GitlabProject (by group)

Get-GitlabProject -GroupId 'mygroup/subgroup'

  ID Name        Group             Url
  -- ----        -----             ---
   1 database    mygroup/subgroup  https://gitlab.mydomain.com/mygroup/subgroup/database
   2 infra       mygroup/subgroup  https://gitlab.mydomain.com/mygroup/subgroup/infra
   3 service     mygroup/subgroup  https://gitlab.mydomain.com/mygroup/subgroup/service
   4 website     mygroup/subgroup  https://gitlab.mydomain.com/mygroup/subgroup/website

Optional Parameters

-IncludeArchived - Set this switch to include archived projects. By default, archived projects are not returned

Transfer-GitlabProject (aka Move-GitlabProject)

Transfer-GitlabProject -ProjectId 'this-project' -DestinationGroup 'that-group'

Merge Requests

New-GitlabMergeRequest

New-GitlabMergeRequest

Optional Parameters

-ProjectId - Defaults to local git context

-SourceBranch - Defaults to local git context

-TargetBranch - Defaults to the default branch set in repository config (typically main)

-Title - Defaults to space-delimited source branch name

Other Examples

mr

Create or get merge request for current git context

Get Deployment

Get-GitlabDeployment -Status 'created' -Environment 'nuget.org'

        ID Status     EnvironmentName      Ref                     CreatedAt
        -- ------     ---------------      ---                     ---------
 196679897 created    nuget.org            main         9/26/2021 5:56:57 AM

Open Web Browser

~/src/your-project> Get-GitlabProject |
  pipelines -Latest -Branch 'main' -Status 'success' | go

Opens latest successful pipeline in browser.

Resolve Variable

Resolve-GitlabVariable (aka var) checks a project or group for a variable. Walks up the group hierarchy until found, or no other nodes to check. Automatically expands the value.

Example

Get-GitlabProject | var APPLICATION_NAME

Your application

Get pipeline for latest deployement

envs -Search prod | deploys -Latest -Select Pipeline [| go]

Deploy To Production

~/src/your-project> pipelines -Branch 'main' -Status 'success' -Latest |
  jobs -Stage deploy -Name prod |
  Play-GitlabJob

Get Pipeline Schedule

~/src/your-project> schedule

   ID Active Description                              Cron         NextRunAt
   -- ------ -----------                              ----         ---------
 1948 True   Weekly restore for database              0 3 * * 0    9/26/2021 10:04:00 AM

References / Acknowledgements

• PSGitLab (now archived)
• python-gitlab CLI documentation
• GitLab API docs
• powershell-yaml