Skip to content

chris-peterson/pwsh-gitlab

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

GitlabCli

‌ PowerShell Gallery Version Platforms PowerShell Gallery GitHub license GitHub Workflow Status

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