Skip to content

Commit c03b10c

Browse files
chris-petersonchris-peterson
committed
WIP
1 parent e4bc88e commit c03b10c

41 files changed

Lines changed: 1326 additions & 459 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 56 additions & 205 deletions
Original file line numberDiff line numberDiff line change
@@ -7,261 +7,112 @@
77
[![GitHub license](https://img.shields.io/github/license/chris-peterson/pwsh-gitlab.svg)](LICENSE)
88
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/chris-peterson/pwsh-gitlab/ci.yml?branch=main&label=ci)](https://github.com/chris-peterson/pwsh-gitlab/actions/workflows/ci.yml)
99

10-
Interact with [GitLab](https://about.gitlab.com/) via [PowerShell](https://github.com/powershell/powershell#-powershell)
10+
Interact with [GitLab](https://about.gitlab.com/) via [PowerShell](https://github.com/powershell/powershell#-powershell).
1111

12-
## Getting Started
12+
📖 **[Full Documentation](https://chris-peterson.github.io/pwsh-gitlab)** — Browse cmdlets, examples, and guides.
1313

14-
### Module
14+
## Installation
15+
16+
### PowerShell Gallery
1517

1618
```powershell
1719
Install-Module -Name GitlabCli
1820
```
1921

20-
### Docker Image
22+
### Docker
2123

2224
```sh
2325
docker run -it ghcr.io/chris-peterson/pwsh-gitlab/gitlab-cli
2426
```
2527

26-
### Configuration
27-
28-
#### Environment Variables
29-
30-
##### `$env:GITLAB_ACCESS_TOKEN`
31-
32-
Obtain a "Personal Access Token" (PAT) for your GitLab instance
33-
34-
`https://<your gitlab instance>/-/profile/personal_access_tokens`
35-
36-
<img width=600 src="PersonalAccessToken.jpg"/>
37-
38-
Make the value available via
39-
40-
`$env:GITLAB_ACCESS_TOKEN='<your pat>'`.
41-
42-
One way to do this would be to add a line to your `$PROFILE`
43-
44-
##### `$env:GITLAB_URL`
45-
46-
(Optional) If using a gitlab instance that is not `gitlab.com`, provide it via:
47-
48-
`$env:GITLAB_URL='<your gitlab instance>'`
49-
50-
#### Example PowerShell Profile
51-
52-
```powershell
53-
$env:GITLAB_URL='gitlab.mydomain.com'
54-
$env:GITLAB_ACCESS_TOKEN='<my token>'
55-
Import-Module GitlabCli
56-
```
57-
58-
#### Configuration File
59-
60-
The following commands can be used to configure your system for use with **multiple** gitlab sites.
61-
62-
* `Add-GitlabSite`
63-
* `Remove-GitlabSite`
64-
* `Set-DefaultGitlabSite`
65-
66-
## Common Parameters: Paging
67-
68-
The following parameters control pagination for query operations:
69-
70-
| Parameter | Description |
71-
| --- | --- |
72-
| `-MaxPages` | Maximum number of pages to return _(default: `$global:GitlabDefaultMaxPages`)_ |
73-
| `-All` | Return all pages. _NOTE:_ Overrides `-MaxPages` |
74-
| `-Recurse` | Recurse child objects (e.g. `Get-GitlabProject -GroupId 'mygroup' -Recurse`). _NOTE:_ Implies `-All` pages |
75-
76-
## Common Parameters: Safety
77-
78-
Mutable operations in this module support ["should process"](https://learn.microsoft.com/en-us/powershell/scripting/learn/deep-dives/everything-about-shouldprocess?view=powershell-7.5).
79-
80-
| Parameter | Description |
81-
| --- | --- |
82-
| `-WhatIf` | Preview what actions would be taken without executing them |
83-
| `-Confirm` | Prompt for confirmation before executing mutable operations |
84-
85-
## Common Parameters: Navigation
86-
87-
The following parameters control post-operation behavior:
88-
89-
| Parameter | Description |
90-
| --- | --- |
91-
| `-Follow` | For operations that create a resource, follow the URL after creation |
92-
| `-Wait` | For long-running operations (e.g. running a job/pipeline), wait for operation to complete. In the meantime, the status is polled and reported to the terminal |
93-
94-
## Common Parameters: Other
95-
96-
The following parameters are supported when possible:
97-
98-
| Parameter | Description |
99-
| --- | --- |
100-
| `-Select` | Select subset of response. A shortcut for `\| Select-Object -ExpandProperty`. _NOTE:_ can select multiple properties (comma-separated) |
101-
| `-SiteUrl` | Override site url _(default: inferred from local git context)_ |
102-
103-
## Global Behaviors
104-
105-
If invoking commands from within a git repository, `.` can be used for `ProjectId` / `BranchName` to use the local context.
106-
107-
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`)
108-
109-
## Examples
110-
111-
### Groups
112-
113-
#### `Get-GitlabGroup`
114-
115-
```powershell
116-
Get-GitlabGroup 'mygroup'
117-
```
118-
119-
```plaintext
120-
ID Name Url
121-
-- ---- ---
122-
23 mygroup https://gitlab.mydomain.com/mygroup
123-
```
124-
125-
#### `Remove-GitlabGroup`
126-
127-
```powershell
128-
Remove-GitlabGroup 'mygroup'
129-
```
28+
## Quick Start
13029

131-
#### `Clone-GitlabGroup` (aka `Copy-GitlabGroupToLocalFileSystem`)
30+
### 1. Get a Personal Access Token
13231

133-
```powershell
134-
Clone-GitlabGroup 'mygroup'
135-
```
32+
Create a PAT at `https://<your-gitlab-instance>/-/profile/personal_access_tokens`
13633

137-
### Projects
34+
### 2. Configure
13835

139-
#### `Get-GitlabProject` (by id)
36+
**Option A: Environment Variables** (simple)
14037

14138
```powershell
142-
Get-GitlabProject 'mygroup/myproject'
143-
# OR
144-
Get-GitlabProject 42
145-
# OR
146-
Get-GitlabProject # use local context
39+
$env:GITLAB_ACCESS_TOKEN = '<your-token>'
40+
$env:GITLAB_URL = 'gitlab.example.com' # optional, defaults to gitlab.com
14741
```
14842

149-
```plaintext
150-
ID Name Group Url
151-
-- ---- ----- ---
152-
42 myproject mygroup https://gitlab.mydomain.com/mygroup/myproject
153-
```
154-
155-
#### `Get-GitlabProject` (by group)
43+
**Option B: Configuration File** (multiple sites)
15644

15745
```powershell
158-
Get-GitlabProject -GroupId 'mygroup/subgroup'
159-
```
160-
161-
```plaintext
162-
ID Name Group Url
163-
-- ---- ----- ---
164-
1 database mygroup/subgroup https://gitlab.mydomain.com/mygroup/subgroup/database
165-
2 infra mygroup/subgroup https://gitlab.mydomain.com/mygroup/subgroup/infra
166-
3 service mygroup/subgroup https://gitlab.mydomain.com/mygroup/subgroup/service
167-
4 website mygroup/subgroup https://gitlab.mydomain.com/mygroup/subgroup/website
46+
Add-GitlabSite -Url 'https://gitlab.example.com' -AccessToken '<your-token>' -IsDefault
16847
```
16948

170-
_Optional Parameters_
171-
172-
`-IncludeArchived` - Set this switch to include archived projects. _By default, archived projects are not returned_
173-
174-
#### `Transfer-GitlabProject` (aka `Move-GitlabProject`)
49+
### 3. Start Using
17550

17651
```powershell
177-
Transfer-GitlabProject -ProjectId 'this-project' -DestinationGroup 'that-group'
178-
```
179-
180-
### Merge Requests
52+
# Get the current project (from local git context)
53+
Get-GitlabProject
18154
182-
#### `New-GitlabMergeRequest`
183-
184-
```powershell
55+
# Create a merge request from your current branch
18556
New-GitlabMergeRequest
186-
```
187-
188-
_Optional Parameters_
18957
190-
`-ProjectId` - Defaults to local git context
58+
# Trigger a pipeline
59+
New-GitlabPipeline
19160
192-
`-SourceBranch` - Defaults to local git context
193-
194-
`-TargetBranch` - Defaults to the default branch set in repository config (typically `main`)
61+
# Search for code
62+
Search-Gitlab 'TODO'
63+
```
19564

196-
`-Title` - Defaults to space-delimited source branch name
65+
## Features at a Glance
19766

198-
## Other Examples
67+
| Category | What You Can Do |
68+
|----------|-----------------|
69+
| **[Projects](https://chris-peterson.github.io/pwsh-gitlab/#/Projects/)** | Create, clone, archive, manage variables and settings |
70+
| **[Merge Requests](https://chris-peterson.github.io/pwsh-gitlab/#/MergeRequests/)** | Create, review, approve, and merge |
71+
| **[Pipelines](https://chris-peterson.github.io/pwsh-gitlab/#/Pipelines/)** | Trigger, monitor, and manage CI/CD |
72+
| **[Groups](https://chris-peterson.github.io/pwsh-gitlab/#/Groups/)** | Organize projects, manage membership |
73+
| **[And more...](https://chris-peterson.github.io/pwsh-gitlab)** | Issues, Runners, Environments, GraphQL, etc. |
19974

200-
### `mr`
75+
## Highlights
20176

202-
Create or get merge request for current git context
77+
### Context-Aware Commands
20378

204-
### Get Deployment
79+
Run commands from within a git repo — the module automatically detects your project:
20580

20681
```powershell
207-
Get-GitlabDeployment -Status 'created' -Environment 'nuget.org'
82+
~/src/myproject> Get-GitlabPipeline -Latest
83+
~/src/myproject> New-GitlabMergeRequest
20884
```
20985

210-
```plaintext
211-
ID Status EnvironmentName Ref CreatedAt
212-
-- ------ --------------- --- ---------
213-
196679897 created nuget.org main 9/26/2021 5:56:57 AM
214-
```
215-
216-
### Open Web Browser
86+
### Convenient Aliases
21787

21888
```powershell
219-
~/src/your-project> Get-GitlabProject |
220-
pipelines -Latest -Branch 'main' -Status 'success' | go
89+
pipelines # Get-GitlabPipeline
90+
jobs # Get-GitlabJob
91+
mr # Get or create merge request
92+
build # New-GitlabPipeline
93+
go # Open-InBrowser
22194
```
22295

223-
Opens latest successful pipeline in browser.
224-
225-
### Resolve Variable
96+
### Pipeline to Browser
22697

227-
`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.
228-
Automatically expands the value.
229-
230-
Example
23198
```powershell
232-
Get-GitlabProject | var APPLICATION_NAME
233-
```
234-
```text
235-
Your application
99+
Get-GitlabProject | Get-GitlabPipeline -Latest | Open-InBrowser
236100
```
237101

238-
### Get pipeline for latest deployement
239-
240-
```powershell
241-
envs -Search prod | deploys -Latest -Select Pipeline [| go]
242-
```
102+
## Documentation
243103

244-
### Deploy To Production
104+
📖 **[chris-peterson.github.io/pwsh-gitlab](https://chris-peterson.github.io/pwsh-gitlab)**
245105

246-
```powershell
247-
~/src/your-project> pipelines -Branch 'main' -Status 'success' -Latest |
248-
jobs -Stage deploy -Name prod |
249-
Play-GitlabJob
250-
```
106+
- [Configuration Guide](https://chris-peterson.github.io/pwsh-gitlab/#/Config/)
107+
- [All Cmdlets by Category](https://chris-peterson.github.io/pwsh-gitlab)
108+
- [CI/CD: Pipelines & Jobs](https://chris-peterson.github.io/pwsh-gitlab/#/Pipelines/)
109+
- [Working with Merge Requests](https://chris-peterson.github.io/pwsh-gitlab/#/MergeRequests/)
251110

252-
### Get Pipeline Schedule
253-
254-
```powershell
255-
~/src/your-project> schedule
111+
## Contributing
256112

257-
ID Active Description Cron NextRunAt
258-
-- ------ ----------- ---- ---------
259-
1948 True Weekly restore for database 0 3 * * 0 9/26/2021 10:04:00 AM
260-
```
113+
Contributions welcome! Please see the [GitHub repository](https://github.com/chris-peterson/pwsh-gitlab) for issues and pull requests.
261114

262-
## References / Acknowledgements
115+
## References
263116

264-
* [PSGitLab](https://github.com/ngetchell/PSGitLab) (now archived)
265-
* [python-gitlab CLI documentation](https://python-gitlab.readthedocs.io/en/stable)
266-
* [GitLab API docs](https://docs.gitlab.com/ee/api/rest/index.html)
267-
* [powershell-yaml](https://github.com/cloudbase/powershell-yaml)
117+
* [GitLab REST API Documentation](https://docs.gitlab.com/ee/api/rest/index.html)
118+
* [PowerShell Gallery Package](https://www.powershellgallery.com/packages/GitlabCli)

‎docs/AuditEvents/README.md‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,26 @@
11
# AuditEvents
22

3-
Track important actions within GitLab
3+
Track important actions within GitLab including user authentication, permission changes, and project/group modifications.
44

5-
- [Get-GitlabAuditEvent](AuditEvents/Get-GitlabAuditEvent.md)
5+
## Overview
6+
7+
Audit events provide a detailed log of security-relevant actions in your GitLab instance. This is essential for compliance, security monitoring, and troubleshooting. You can query audit events at the instance level (requires admin), group level, or project level.
8+
9+
## Quick Start
10+
11+
```powershell
12+
# Get audit events for a group
13+
Get-GitlabAuditEvent -GroupId 'mygroup'
14+
15+
# Get audit events filtered by date range
16+
Get-GitlabAuditEvent -GroupId 'mygroup' -After '2024-01-01' -Before '2024-12-31'
17+
18+
# Get audit events with author information
19+
Get-GitlabAuditEvent -ProjectId 'mygroup/myproject' -FetchAuthors
20+
```
21+
22+
## Cmdlets
23+
24+
| Cmdlet | Description |
25+
|--------|-------------|
26+
| [Get-GitlabAuditEvent](AuditEvents/Get-GitlabAuditEvent.md) | Retrieves audit events at instance, group, or project level |

‎docs/Branches/README.md‎

Lines changed: 32 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,34 @@
11
# Branches
22

3-
Manage repository branches
4-
5-
- [Get-GitlabBranch](Branches/Get-GitlabBranch.md)
6-
- [Get-GitlabProtectedBranch](Branches/Get-GitlabProtectedBranch.md)
7-
- [New-GitlabBranch](Branches/New-GitlabBranch.md)
8-
- [Protect-GitlabBranch](Branches/Protect-GitlabBranch.md)
9-
- [Remove-GitlabBranch](Branches/Remove-GitlabBranch.md)
10-
- [UnProtect-GitlabBranch](Branches/UnProtect-GitlabBranch.md)
3+
Manage repository branches including creation, deletion, and protection rules.
4+
5+
## Overview
6+
7+
Branch management is fundamental to Git workflows. These cmdlets allow you to list, create, and delete branches, as well as configure branch protection rules to enforce code review policies and prevent direct pushes to critical branches.
8+
9+
## Quick Start
10+
11+
```powershell
12+
# List all branches in the current project
13+
Get-GitlabBranch
14+
15+
# Search for branches containing 'feature'
16+
Get-GitlabBranch -Search 'feature'
17+
18+
# Create a new branch from main
19+
New-GitlabBranch -Name 'feature/my-feature' -Ref 'main'
20+
21+
# Protect the main branch
22+
Protect-GitlabBranch -Branch 'main' -PushAccessLevel 'maintainer' -MergeAccessLevel 'developer'
23+
```
24+
25+
## Cmdlets
26+
27+
| Cmdlet | Description |
28+
|--------|-------------|
29+
| [Get-GitlabBranch](Branches/Get-GitlabBranch.md) | Gets branches from a project repository |
30+
| [Get-GitlabProtectedBranch](Branches/Get-GitlabProtectedBranch.md) | Gets protected branch configurations |
31+
| [New-GitlabBranch](Branches/New-GitlabBranch.md) | Creates a new branch |
32+
| [Protect-GitlabBranch](Branches/Protect-GitlabBranch.md) | Configures branch protection rules |
33+
| [Remove-GitlabBranch](Branches/Remove-GitlabBranch.md) | Deletes a branch |
34+
| [UnProtect-GitlabBranch](Branches/UnProtect-GitlabBranch.md) | Removes branch protection |

0 commit comments

Comments
 (0)