gettyimages/pwsh-gitlab

GitlabCli

‌

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