# GitLab on boxd

> A web-based DevOps lifecycle tool that provides a Git repository manager providing wiki, issue-tracking, and CI/CD pipeline features.

- Page: https://boxd.sh/integrations/gitlab/
- CLI: `run gitlab` (116 commands, 56 marked common)
- SDK: `import { gitlab } from "@boxd/run"`; every parameter and response type is at `@boxd/run/gitlab`
- Triggers: none
- Connect: `run auth gitlab` (Sign in with GitLab), or https://app.boxd.sh/integrations/detail/gitlab
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth gitlab      # once: prints a link to connect your account
run gitlab           # list its commands
run gitlab get-current-user
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { every, gitlab } from "@boxd/run";

every("1 hour", async () => {
  const result = await gitlab.getCurrentUser();
  console.log(result);
});
```

Run it with `run gitlab.run.ts`. GitLab has no triggers; `every()` polls on a schedule, keeps the script running as a job, and wakes the machine when it is due.

## Commands

Required flags are listed; `run gitlab <command> --help` lists the optional ones. "common" marks what `run gitlab` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-spent-time` ·common | `gitlab.addSpentTime()` | `--duration` `--id` `--issue-iid` | 1 | Adds spent time to a GitLab issue for time tracking purposes |
| `approve-merge-request` ·common | `gitlab.approveMergeRequest()` | `--id` `--merge-request-iid` | 2 | Approves a merge request in a GitLab project |
| `archive-project` ·common | `gitlab.archiveProject()` | `--id` | 0 | Archive a project |
| `cancel-job` ·common | `gitlab.cancelJob()` | `--job-id` `--project-id` | 1 | Cancel a GitLab CI/CD job within a specified project |
| `cancel-pipeline` | `gitlab.cancelPipeline()` | `--pipeline-id` `--project-id` | 0 | Cancel a running pipeline in a GitLab project |
| `create-commit` ·common | `gitlab.createCommit()` | `--actions` `--branch` `--commit-message` `--project-id` | 7 | Creates a new commit with multiple file operations in a GitLab project |
| `create-commit-comment` ·common | `gitlab.createCommitComment()` | `--note` `--project-id` `--sha` | 3 | Posts a comment to a specific commit in a GitLab project repository |
| `create-file` ·common | `gitlab.createFile()` | `--branch` `--commit-message` `--content` `--file-path` `--project-id` | 5 | Creates a new file in a GitLab repository at the specified path with the given content |
| `create-group` ·common | `gitlab.createGroup()` | `--name` `--path` | 24 | Create a new group in GitLab |
| `create-issue-note` ·common | `gitlab.createIssueNote()` | `--body` `--id` `--issue-iid` | 3 | Creates a new note (comment) on a project issue in GitLab |
| `create-label` ·common | `gitlab.createLabel()` | `--color` `--id` `--name` | 3 | Creates a new label for a GitLab project with specified name, color, and optional attributes |
| `create-merge-request` ·common | `gitlab.createMergeRequest()` | `--id` `--source-branch` `--target-branch` `--title` | 11 | Creates a new merge request in a GitLab project to propose changes from a source branch into a target branch |
| `create-milestone` ·common | `gitlab.createMilestone()` | `--id` `--title` | 3 | Creates a new milestone in a GitLab project |
| `create-pipeline` ·common | `gitlab.createPipeline()` | `--project-id` `--ref` | 2 | Create a new pipeline for a specific branch or tag in a GitLab project |
| `create-project` ·common | `gitlab.createProject()` | `--name` `--path` | 10 | Create a new project in GitLab |
| `create-project-issue` ·common | `gitlab.createProjectIssue()` | `--id` `--title` | 15 | Create a new issue in a GitLab project |
| `create-repository-branch` ·common | `gitlab.createRepositoryBranch()` | `--branch-name` `--project-id` `--ref` | 0 | Create a new branch in a project |
| `create-webhook` ·common | `gitlab.createWebhook()` | `--id` `--url` | 26 | Creates a new webhook (project hook) for a GitLab project to receive real-time event notifications |
| `delete-group` ·common | `gitlab.deleteGroup()` | `--id` | 2 | Deletes a GitLab group by its ID or URL-encoded path |
| `delete-issue-note` | `gitlab.deleteIssueNote()` | `--id` `--issue-iid` `--note-id` | 0 | Deletes a note (comment) from an issue in a GitLab project |
| `delete-label` | `gitlab.deleteLabel()` | `--id` `--label-id` | 0 | Deletes a label from a GitLab project by its ID or title |
| `delete-merge-request` | `gitlab.deleteMergeRequest()` | `--id` `--merge-request-iid` | 0 | Permanently delete a merge request from a GitLab project |
| `delete-milestone` | `gitlab.deleteMilestone()` | `--id` `--milestone-id` | 0 | Deletes a project milestone by its ID |
| `delete-pipeline` | `gitlab.deletePipeline()` | `--pipeline-id` `--project-id` | 0 | Delete a CI/CD pipeline by its ID within a specified project |
| `delete-project` | `gitlab.deleteProject()` | `--id` | 2 | Delete a GitLab project by its ID |
| `delete-repository-branch` | `gitlab.deleteRepositoryBranch()` | `--branch-name` `--project-id` | 0 | Delete a branch from a GitLab project repository |
| `delete-repository-file` | `gitlab.deleteRepositoryFile()` | `--branch` `--commit-message` `--file-path` `--project-id` | 4 | Deletes a file from a GitLab repository by creating a new commit |
| `delete-webhook` | `gitlab.deleteWebhook()` | `--hook-id` `--id` | 0 | Deletes a project webhook/hook permanently from a GitLab project, removing the integration and stopping all event notifications |
| `download-project-avatar` | `gitlab.downloadProjectAvatar()` | `--id` | 0 | Download a project's avatar image |
| `erase-job` | `gitlab.eraseJob()` | `--job-id` `--project-id` | 0 | Erase the content of a specified job within a project |
| `fork-project` ·common | `gitlab.forkProject()` | `--id` | 6 | Forks a GitLab project to a specified namespace or the current user's namespace |
| `get-commit-refs` | `gitlab.getCommitRefs()` | `--project-id` `--sha` | 1 | Get all references (branches or tags) a commit is pushed to |
| `get-commit-sequence` | `gitlab.getCommitSequence()` | `--project-id` `--sha` | 1 | Get the sequence number of a commit in a project by following parent links from the given commit |
| `get-current-user` ·common | `gitlab.getCurrentUser()` | — | 0 | Retrieves information about the currently authenticated user |
| `get-file` ·common | `gitlab.getFile()` | `--file-path` `--project-id` `--ref` | 0 | Retrieves a single file from a GitLab repository at a specific ref (branch, tag, or commit) |
| `get-group` | `gitlab.getGroup()` | `--id` | 2 | Retrieve information about a specific group by its ID |
| `get-group-member` | `gitlab.getGroupMember()` | `--id` `--user-id` | 0 | Retrieve details for a specific group member |
| `get-groups` | `gitlab.getGroups()` | — | 13 | Get Groups |
| `get-issue` ·common | `gitlab.getIssue()` | `--id` `--issue-iid` | 0 | Retrieves a single issue from a GitLab project by its internal ID (iid) |
| `get-issue-note` ·common | `gitlab.getIssueNote()` | `--id` `--issue-iid` `--note-id` | 0 | Retrieves a single comment (note) from a GitLab issue by its ID |
| `get-job-details` | `gitlab.getJobDetails()` | `--job-id` `--project-id` | 0 | Retrieve details of a single job by its ID within a specified project |
| `get-job-trace` | `gitlab.getJobTrace()` | `--job-id` `--project-id` | 0 | Retrieves the trace (log output) for a specific CI/CD job within a project |
| `get-label` ·common | `gitlab.getLabel()` | `--id` `--label-id` | 1 | Retrieves a single project label by its ID or title |
| `get-merge-request-notes` ·common | `gitlab.getMergeRequestNotes()` | `--id` `--merge-request-iid` | 2 | Fetch comments on a merge request |
| `get-milestone` ·common | `gitlab.getMilestone()` | `--id` `--milestone-id` | 0 | Retrieves a single milestone by its ID for a specific project |
| `get-project` ·common | `gitlab.getProject()` | `--id` | 0 | Get a single project by ID or URL-encoded path |
| `get-project-languages` | `gitlab.getProjectLanguages()` | `--id` | 0 | List programming languages used in a project with percentages |
| `get-project-member` | `gitlab.getProjectMember()` | `--id` `--user-id` | 0 | Retrieve details for a specific project member |
| `get-project-member-all` | `gitlab.getProjectMemberAll()` | `--id` `--user-id` | 0 | Retrieve details for a specific project member (including inherited and invited members) |
| `get-project-merge-request` ·common | `gitlab.getProjectMergeRequest()` | `--id` `--merge-request-iid` | 3 | Fetch full details for a single merge request when the MR IID is known |
| `get-project-merge-request-commits` | `gitlab.getProjectMergeRequestCommits()` | `--id` `--merge-request-iid` | 0 | Get commits of a merge request |
| `get-project-merge-requests` | `gitlab.getProjectMergeRequests()` | `--id` | 35 | Retrieve a list of merge requests for a specific project |
| `get-projects` ·common | `gitlab.getProjects()` | — | 19 | List all projects accessible to the authenticated user |
| `get-projects-id-merge-requests-iid-diffs` | `gitlab.getProjectsIdMergeRequestsIidDiffs()` | `--id` `--merge-request-iid` | 0 | List all diff versions of a merge request |
| `get-raw-file` ·common | `gitlab.getRawFile()` | `--file-path` `--project-id` `--ref` | 1 | Retrieves the raw contents of a file from a GitLab repository without Base64 encoding |
| `get-repository-branch` ·common | `gitlab.getRepositoryBranch()` | `--branch-name` `--project-id` | 0 | Retrieve information about a specific branch in a project |
| `get-repository-branches` | `gitlab.getRepositoryBranches()` | `--project-id` | 2 | Retrieves a list of repository branches for a project |
| `get-single-commit` | `gitlab.getSingleCommit()` | `--id` `--sha` | 1 | Get a specific commit identified by the commit hash or name of a branch or tag |
| `get-single-pipeline` | `gitlab.getSinglePipeline()` | `--pipeline-id` `--project-id` | 0 | Retrieve details of a single pipeline by its ID within a specified project |
| `get-time-stats` | `gitlab.getTimeStats()` | `--id` `--issue-iid` | 0 | Retrieves time tracking statistics for a specific issue in a project |
| `get-user` | `gitlab.getUser()` | `--id` | 0 | Retrieve information about a specific user by their ID |
| `get-user-preferences` | `gitlab.getUserPreferences()` | — | 0 | Get the current user's preferences |
| `get-user-status` | `gitlab.getUserStatus()` | — | 0 | Get the current user's status |
| `get-user-support-pin` | `gitlab.getUserSupportPin()` | — | 0 | Get details of the current user's Support PIN |
| `get-users` ·common | `gitlab.getUsers()` | — | 24 | Retrieve a list of users from GitLab |
| `get-users-id-status` | `gitlab.getUsersIdStatus()` | `--user-id` | 0 | Get a user's status by ID |
| `get-webhook` ·common | `gitlab.getWebhook()` | `--hook-id` `--project-id` | 0 | Retrieves detailed information about a specific project webhook by its ID |
| `import-project-members` | `gitlab.importProjectMembers()` | `--id` `--project-id` | 0 | Import members from one project to another |
| `list-all-group-members` | `gitlab.listAllGroupMembers()` | `--id` | 2 | List all members of a group including direct, inherited, and invited members |
| `list-all-project-members` | `gitlab.listAllProjectMembers()` | `--id` | 6 | List all members of a project (direct, inherited, invited) |
| `list-billable-group-members` | `gitlab.listBillableGroupMembers()` | `--id` | 4 | List billable members of a top-level group (including its subgroups and projects) |
| `list-commit-comments` | `gitlab.listCommitComments()` | `--project-id` `--sha` | 0 | Retrieves all comments associated with a specific commit in a GitLab project |
| `list-group-members` | `gitlab.listGroupMembers()` | `--id` | 9 | List direct members of a group |
| `list-group-projects` ·common | `gitlab.listGroupProjects()` | `--id` | 17 | List projects within a GitLab group by group ID or full path |
| `list-issue-notes` ·common | `gitlab.listIssueNotes()` | `--id` `--issue-iid` | 5 | Retrieves all notes (comments and activity) for a specific project issue in GitLab |
| `list-labels` ·common | `gitlab.listLabels()` | `--id` | 6 | Lists all labels for a project with optional filtering by name, archived status, and ancestor inclusion |
| `list-merge-requests` ·common | `gitlab.listMergeRequests()` | — | 38 | Retrieves a list of merge requests from across all accessible projects based on scope and filters |
| `list-milestones` ·common | `gitlab.listMilestones()` | `--id` | 7 | Lists all milestones for a specific project with optional filtering by state, title, or search terms |
| `list-pending-group-members` | `gitlab.listPendingGroupMembers()` | `--id` | 2 | List pending members of a group and its subgroups and projects |
| `list-pipeline-jobs` | `gitlab.listPipelineJobs()` | `--id` `--pipeline-id` | 4 | Retrieve a list of jobs for a specified pipeline within a project |
| `list-project-groups` | `gitlab.listProjectGroups()` | `--id` | 7 | List ancestor groups of a project |
| `list-project-invited-groups` | `gitlab.listProjectInvitedGroups()` | `--id` | 2 | List groups invited to a project |
| `list-project-issues` ·common | `gitlab.listProjectIssues()` | `--id` | 27 | List issues for a project with filtering options (state, labels, search, assignee, author, etc.) |
| `list-project-pipelines` | `gitlab.listProjectPipelines()` | `--id` | 16 | Retrieve a list of pipelines for a specified project |
| `list-project-shareable-groups` | `gitlab.listProjectShareableGroups()` | `--id` | 4 | List groups that can be shared with a project |
| `list-project-tags` | `gitlab.listProjectTags()` | `--id` | 5 | Retrieve a list of repository tags for a specified project |
| `list-project-transfer-locations` | `gitlab.listProjectTransferLocations()` | `--id` | 3 | List namespaces available for project transfer |
| `list-project-users` ·common | `gitlab.listProjectUsers()` | `--id` | 4 | List users of a project |
| `list-repository-commits` | `gitlab.listRepositoryCommits()` | `--project-id` | 12 | Get a list of repository commits in a project |
| `list-user-projects` | `gitlab.listUserProjects()` | `--id` | 21 | List projects owned by a specific user |
| `list-webhooks` ·common | `gitlab.listWebhooks()` | `--project-id` | 2 | List all webhooks configured for a GitLab project |
| `move-issue` ·common | `gitlab.moveIssue()` | `--id` `--issue-iid` `--to-project-id` | 0 | Moves an issue from one project to another in GitLab |
| `play-job` ·common | `gitlab.playJob()` | `--job-id` `--project-id` | 2 | Triggers execution of a manual job in a GitLab project |
| `post-user-support-pin` | `gitlab.postUserSupportPin()` | — | 0 | Create a support PIN for your authenticated user |
| `protect-branch` ·common | `gitlab.protectBranch()` | `--name` `--project-id` | 8 | Protects a repository branch in a GitLab project by setting access controls for push, merge, and unprotect operations |
| `put-user-preferences` | `gitlab.putUserPreferences()` | `--pass-user-identities-to-ci-jwt` `--show-whitespace-in-diffs` `--view-diffs-file-by-file` | 0 | Update the current user's preferences |
| `reset-spent-time` | `gitlab.resetSpentTime()` | `--id` `--issue-iid` | 0 | Resets the total spent time for a specified GitLab issue to 0 seconds |
| `reset-time-estimate` | `gitlab.resetTimeEstimate()` | `--id` `--issue-iid` | 0 | Resets the estimated time for a specified issue to 0 seconds |
| `retry-pipeline` ·common | `gitlab.retryPipeline()` | `--pipeline-id` `--project-id` | 0 | Retries failed or canceled jobs in a pipeline |
| `set-time-estimate` | `gitlab.setTimeEstimate()` | `--duration` `--id` `--issue-iid` | 0 | Sets the estimated time to complete an issue in a GitLab project |
| `set-user-status` | `gitlab.setUserStatus()` | — | 3 | Set the current user's status |
| `share-project-with-group` | `gitlab.shareProjectWithGroup()` | `--group-access` `--group-id` `--id` | 1 | Share a project with a group |
| `star-project` ·common | `gitlab.starProject()` | `--id` | 0 | Stars a project in GitLab, marking it as a favorite for the authenticated user |
| `start-project-housekeeping` | `gitlab.startProjectHousekeeping()` | `--id` | 1 | Start the housekeeping task for a project |
| `unapprove-merge-request` | `gitlab.unapproveMergeRequest()` | `--id` `--merge-request-iid` | 0 | Removes the approval from the currently authenticated user for a specified merge request |
| `unprotect-branch` | `gitlab.unprotectBranch()` | `--branch-name` `--project-id` | 0 | Remove protection from a branch in a GitLab project |
| `unstar-project` ·common | `gitlab.unstarProject()` | `--id` | 0 | Unstar a previously starred GitLab project to remove it from your favorites list |
| `update-group` ·common | `gitlab.updateGroup()` | `--id` | 27 | Updates an existing GitLab group's settings and properties |
| `update-issue-note` ·common | `gitlab.updateIssueNote()` | `--id` `--issue-iid` `--note-id` | 1 | Updates an existing note (comment) on a GitLab issue |
| `update-label` ·common | `gitlab.updateLabel()` | `--id` `--label-id` | 5 | Updates an existing label in a GitLab project by modifying its name, color, description, priority, or archived status |
| `update-merge-request` ·common | `gitlab.updateMergeRequest()` | `--id` `--merge-request-iid` | 16 | Updates an existing merge request in a GitLab project (title, description, assignees, reviewers, labels, state, etc.) |
| `update-milestone` ·common | `gitlab.updateMilestone()` | `--id` `--milestone-id` | 5 | Updates an existing milestone in a GitLab project, allowing you to modify the title, description, dates, or state |
| `update-project-issue` ·common | `gitlab.updateProjectIssue()` | `--id` `--issue-iid` | 15 | Update an existing issue in a GitLab project (title, description, labels, assignees, state, etc.) |
| `update-repository-file` ·common | `gitlab.updateRepositoryFile()` | `--branch` `--commit-message` `--content` `--file-path` `--id` | 6 | Updates an existing file in a GitLab repository |
| `update-webhook` ·common | `gitlab.updateWebhook()` | `--hook-id` `--id` `--url` | 12 | Updates an existing project webhook configuration including URL, event triggers, SSL verification, and authentication token |
| `validate-credential` ·common | `gitlab.validateCredential()` | — | 0 | Validates the authentication credentials by retrieving the currently authenticated user's information |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.