<!-- BusyBot node reference — https://busybot.net/tools/gitlab/ -->

> Node: GitLab (`gitlab`) · Action (binary) · v1
> Category: Development · Credentials: GitLab API (`gitlabApi`)
> Updated: 2026-08-16

# GitLab

> Manage GitLab files, issues, releases, repositories, and users

## Overview

The GitLab tool provides full CRUD operations against the GitLab REST API v4. Supports five resources: (1) File -- create, edit, delete, get (with binary download), list repository tree. (2) Issue -- create, createComment, edit, get, lock. (3) Release -- create, delete, get, getAll, update. (4) Repository -- get project info, getIssues. (5) User -- getRepositories. File operations support binary data: file:get downloads file content (base64-decoded) to the binary store; file:create/edit can upload binary content (base64-encoded) from an item's binary property. Supports self-hosted GitLab instances via configurable server URL in credentials. Uses PRIVATE-TOKEN header authentication.

**Category:** Development  
**Tool Name:** `gitlab`  
**Version:** 1

**Appearance:** Icon: `si-gitlab` | Color: `#FC6D26`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **GitLab API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/gitlab-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| File | `file` |
| Issue | `issue` |
| Release | `release` |
| Repository | `repository` |
| User | `user` |

### Operations

Each resource has its own Operation list, and several resources reuse the same operation values (`create`, `delete`, `edit`, `get`). Pick the resource first, then the operation.

| Resource | Operation | Value | Description |
|----------|-----------|-------|-------------|
| File | Create | `create` | Create a new file in the repository |
| File | Delete | `delete` | Delete a file from the repository |
| File | Edit | `edit` | Edit an existing file in the repository |
| File | Get | `get` | Get a file from the repository |
| File | List | `list` | List files and directories in a repository path |
| Issue | Create | `create` | Create a new issue |
| Issue | Create Comment | `createComment` | Create a comment on an issue |
| Issue | Edit | `edit` | Edit an issue |
| Issue | Get | `get` | Get an issue |
| Issue | Lock | `lock` | Lock an issue |
| Release | Create | `create` | Create a new release |
| Release | Delete | `delete` | Delete a release |
| Release | Get | `get` | Get a release |
| Release | Get Many | `getAll` | Get many releases |
| Release | Update | `update` | Update a release |
| Repository | Get | `get` | Get repository information |
| Repository | Get Issues | `getIssues` | Get repository issues |
| User | Get Repositories | `getRepositories` | Get a user's repositories |

### Parameters

Every parameter accepts expressions, so identifiers, paths and message text can all come from the incoming item. Where a parameter is left empty, the node also falls back to a field of the same name on the input item — an item carrying `owner`, `repository`, `filePath`, `issueNumber`, `projectId` or `tagName` can drive the node without those fields being filled in at all.

`Repository: Get` and `User: Get Repositories` take no parameters of their own — see All Operations.

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Project Owner (`owner`) | `string` | Yes | — | User, group, or namespace of the project. For subgroups, use slashes (e.g., "group/subgroup"). On User: Get Repositories this is the user whose projects you want. |
| Project Name (`repository`) | `string` | Yes | — | The name of the project. _(hidden when Resource is `user` and Operation is `getRepositories`)_ |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently (1–100). |

#### File: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| File Path (`filePath`) | `string` | No | — | The file path within the repository. |
| Binary File (`binaryData`) | `boolean` | No | `false` | Whether the data to upload should be taken from a binary field. |
| File Content | `string` | No | — | The text content of the file. _(shown when Binary File is `false`)_ |
| Input Binary Field (`binaryPropertyName`) | `string` | No | `data` | The name of the input binary field containing the file to upload. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. _(shown when Binary File is `true`)_ |
| Commit Message | `string` | Yes | — | The commit message for the file operation. |
| Branch | `string` | Yes | — | Name of the branch to commit to. |
| Additional Parameters (`additionalParameters`) | `collection` | No | `{}` | Optional commit settings. |
| — Start Branch (`startBranch`) | `string` | No | — | Name of the base branch to create the new branch from. |
| — Author Name (`authorName`) | `string` | No | — | The name of the commit author. |
| — Author Email (`authorEmail`) | `string` | No | — | The email of the commit author. |
| — Encoding (`encoding`) | `string` | No | `text` | Change encoding to base64. Default is text. |

#### File: Edit

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| File Path (`filePath`) | `string` | No | — | The file path within the repository. |
| Binary File (`binaryData`) | `boolean` | No | `false` | Whether the data to upload should be taken from a binary field. |
| File Content | `string` | No | — | The text content of the file. _(shown when Binary File is `false`)_ |
| Input Binary Field (`binaryPropertyName`) | `string` | No | `data` | The name of the input binary field containing the file to upload. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. _(shown when Binary File is `true`)_ |
| Commit Message | `string` | Yes | — | The commit message for the file operation. |
| Branch | `string` | Yes | — | Name of the branch to commit to. |
| Additional Parameters (`additionalParameters`) | `collection` | No | `{}` | Optional commit settings. |
| — Start Branch (`startBranch`) | `string` | No | — | Name of the base branch to create the new branch from. |
| — Author Name (`authorName`) | `string` | No | — | The name of the commit author. |
| — Author Email (`authorEmail`) | `string` | No | — | The email of the commit author. |
| — Encoding (`encoding`) | `string` | No | `text` | Change encoding to base64. Default is text. |

#### File: Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| File Path (`filePath`) | `string` | No | — | The file path within the repository. |
| Commit Message | `string` | Yes | — | The commit message for the file operation. |
| Branch | `string` | Yes | — | Name of the branch to commit to. |
| Additional Parameters (`additionalParameters`) | `collection` | No | `{}` | Optional commit settings. |
| — Start Branch (`startBranch`) | `string` | No | — | Name of the base branch to create the new branch from. |
| — Author Name (`authorName`) | `string` | No | — | The name of the commit author. |
| — Author Email (`authorEmail`) | `string` | No | — | The email of the commit author. |
| — Encoding (`encoding`) | `string` | No | `text` | Change encoding to base64. Default is text. |

#### File: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| File Path (`filePath`) | `string` | No | — | The file path within the repository. |
| As Binary Property (`asBinaryProperty`) | `boolean` | No | `true` | Whether to decode the file content and store it as binary data instead of returning the raw API response. |
| Put Output File in Field (`binaryPropertyName`) | `string` | Yes | `data` | The name of the output binary field to put the file in. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. _(shown when As Binary Property is `true`)_ |
| Additional Parameters (`additionalParameters`) | `collection` | No | `{}` | Optional lookup settings. |
| — Reference (`reference`) | `string` | No | — | The name of the commit/branch/tag. Defaults to the repository's default branch. |

#### File: List

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Path (`filePath`) | `string` | No | — | The path of the folder to list. Leave empty for root. |
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `20` | Max number of results to return (1–100). _(shown when Return All is `false`)_ |
| Additional Parameters (`additionalParameters`) | `collection` | No | `{}` | Optional listing settings. |
| — Reference (`ref`) | `string` | No | — | The name of the commit/branch/tag. Defaults to the repository's default branch. |
| — Recursive (`recursive`) | `boolean` | No | `false` | Whether to get a recursive file tree. |

#### Issue: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Title | `string` | Yes | — | The title of the issue. |
| Body | `string` | No | — | The description body of the issue. |
| Due Date | `dateTime` | No | — | Due date for the issue (YYYY-MM-DD). |
| Labels | `string` | No | — | Comma-separated list of label names to add to the issue. |
| Assignee IDs | `string` | No | — | Comma-separated list of user IDs to assign to the issue. |

#### Issue: Create Comment

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Issue Number | `number` | Yes | `0` | The IID of the issue — the number shown in the issue's URL, not its global ID. |
| Body | `string` | No | — | The body of the comment. |

#### Issue: Edit

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Issue Number | `number` | Yes | `0` | The IID of the issue — the number shown in the issue's URL, not its global ID. |
| Edit Fields | `collection` | No | `{}` | Fields to update on the issue. Only the fields you add are sent. |
| — Title (`title`) | `string` | No | — | New issue title. |
| — Description (`description`) | `string` | No | — | New issue description. |
| — State (`state`) | `options` | No | `open` | The state to set. |
| | | | | Options: `closed`, `open` |
| — Labels (`labels`) | `string` | No | — | Comma-separated label names. |
| — Assignee IDs (`assignee_ids`) | `string` | No | — | Comma-separated user IDs. |
| — Due Date (`due_date`) | `dateTime` | No | — | Due date for the issue. |

#### Issue: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Issue Number | `number` | Yes | `0` | The IID of the issue — the number shown in the issue's URL, not its global ID. |

#### Issue: Lock

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Issue Number | `number` | Yes | `0` | The IID of the issue — the number shown in the issue's URL, not its global ID. |
| Lock Reason | `options` | No | `resolved` | The reason for locking the issue. |
| | | | | Options: `off-topic`, `too heated`, `resolved`, `spam` |

#### Release: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Tag (`releaseTag`) | `string` | Yes | — | The tag name for the release. |
| Additional Fields (`additionalFields`) | `collection` | No | `{}` | Optional release properties. |
| — Name (`name`) | `string` | No | — | The name of the release. |
| — Description (`description`) | `string` | No | — | Release description (supports Markdown). |
| — Ref (`ref`) | `string` | No | — | If the tag doesn't exist, the release will be created from this ref (commit SHA, tag, or branch). |

#### Release: Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Project ID | `string` | Yes | — | The ID or URL-encoded path of the project. |
| Tag Name (`tagName`) | `string` | Yes | — | The Git tag the release is associated with. |

#### Release: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Project ID | `string` | Yes | — | The ID or URL-encoded path of the project. |
| Tag Name (`tagName`) | `string` | Yes | — | The Git tag the release is associated with. |

#### Release: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Project ID | `string` | Yes | — | The ID or URL-encoded path of the project. |
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `20` | Max number of results to return (1–100). _(shown when Return All is `false`)_ |
| Additional Fields (`additionalFields`) | `collection` | No | `{}` | Ordering options for the listing. |
| — Order By (`order_by`) | `options` | No | `released_at` | The field to use for ordering. |
| | | | | Options: `created_at`, `released_at` |
| — Sort (`sort`) | `options` | No | `desc` | The direction of the order. |
| | | | | Options: `asc`, `desc` |

#### Release: Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Project ID | `string` | Yes | — | The ID or URL-encoded path of the project. |
| Tag Name (`tagName`) | `string` | Yes | — | The Git tag the release is associated with. |
| Additional Fields (`additionalFields`) | `collection` | No | `{}` | Fields to change on the release. Only the fields you add are sent. |
| — Name (`name`) | `string` | No | — | The release name. |
| — Description (`description`) | `string` | No | — | The description of the release (supports Markdown). |
| — Milestones (`milestones`) | `string` | No | — | Comma-separated milestone titles to associate with the release. |
| — Released At (`released_at`) | `dateTime` | No | — | The date when the release is/was ready. |

#### Repository: Get Issues

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `20` | Max number of results to return (1–100). _(shown when Return All is `false`)_ |
| Filters (`getRepositoryIssuesFilters`) | `collection` | No | `{}` | Filters for repository issues. |
| — Assignee (`assignee_username`) | `string` | No | — | Return only issues assigned to a specific user. |
| — Creator (`author_username`) | `string` | No | — | Return only issues created by a specific user. |
| — Search (`search`) | `string` | No | — | Search issues against title and description. |
| — Labels (`labels`) | `string` | No | — | Return only issues with given labels (comma-separated). |
| — Updated After (`updated_after`) | `dateTime` | No | — | Return only issues updated at or after this time. |
| — State (`state`) | `options` | No | `opened` | Issue state filter. |
| | | | | Options: `opened`, `closed`, and an empty value for All |
| — Sort (`order_by`) | `options` | No | `created_at` | The order the issues should be returned in. |
| | | | | Options: `created_at`, `updated_at`, `priority` |
| — Direction (`sort`) | `options` | No | `desc` | The sort direction. |
| | | | | Options: `asc`, `desc` |

## Output Data

How the output item is built depends on whether the operation returns one record or a list — the two behave differently, and mixing them up is the usual surprise:

- **Single-record operations replace the item JSON.** File Create, Edit and Delete; every Issue operation; Release Create, Delete, Get and Update; Repository Get — each writes the GitLab response as the whole output item JSON. Fields the input item carried are **gone** unless GitLab happens to return them, so copy anything you still need onto the item after this node, not before.
- **List operations merge and fan out.** File List, Release Get Many, Repository Get Issues and User Get Repositories emit **one output item per entry**, each entry merged onto the input item's JSON. A result with no entries produces **no output items at all** for that input item.
- **File Get is the exception.** With As Binary Property on (the default) the file lands in the binary field you named and the item JSON keeps its existing fields plus `file_name`, `file_path`, `size`, `encoding`, `content_sha256`, `ref`, `blob_id`, `commit_id` and `last_commit_id`. With it off, the raw API response replaces the item JSON and the content stays base64-encoded inside it.

**Binary data is always forwarded.** Binary on the input item is carried through every operation; File Get with As Binary Property on adds the downloaded file alongside it rather than replacing it.

Delete operations that GitLab answers with no body produce `success: true` — plus `deleted` naming the file path or release tag.

## Usage Examples

- Download a file from a GitLab repository as binary
- Create a new file in a GitLab repository from binary data
- Create a GitLab issue with labels and assignees
- List all files in a GitLab repository folder
- Create a new release for a GitLab project
- Get all issues for a GitLab repository

## Example Configuration

Open an issue with labels, assignees and a due date:

```json
{
  "type": "gitlab",
  "parameters": {
    "resource": "issue",
    "operation": "create",
    "owner": "mygroup",
    "repository": "my-repo",
    "title": "{{ $json.summary }}",
    "body": "{{ $json.details }}",
    "dueDate": "2026-12-31T00:00:00Z",
    "labels": "bug,high-priority",
    "assigneeIds": "1,2"
  }
}
```

Close an issue and relabel it:

```json
{
  "type": "gitlab",
  "parameters": {
    "resource": "issue",
    "operation": "edit",
    "owner": "mygroup",
    "repository": "my-repo",
    "issueNumber": 123,
    "editFields": {
      "title": "Updated bug report",
      "state": "closed",
      "labels": "bug,resolved"
    }
  }
}
```

Commit a text file:

```json
{
  "type": "gitlab",
  "parameters": {
    "resource": "file",
    "operation": "create",
    "owner": "mygroup",
    "repository": "my-repo",
    "filePath": "src/main.py",
    "binaryData": false,
    "fileContent": "print('Hello World')",
    "commitMessage": "Add main.py file",
    "branch": "main"
  }
}
```

Commit a binary file coming from an upstream node:

```json
{
  "type": "gitlab",
  "parameters": {
    "resource": "file",
    "operation": "create",
    "owner": "mygroup",
    "repository": "my-repo",
    "filePath": "assets/image.png",
    "binaryData": true,
    "binaryPropertyName": "imageData",
    "commitMessage": "Add image asset",
    "branch": "main"
  }
}
```

Download a file into a binary field for a downstream node:

```json
{
  "type": "gitlab",
  "parameters": {
    "resource": "file",
    "operation": "get",
    "owner": "mygroup",
    "repository": "my-repo",
    "filePath": "docs/handbook.pdf",
    "asBinaryProperty": true,
    "binaryPropertyName": "data",
    "additionalParameters": {
      "reference": "main"
    }
  }
}
```

Cut a release from a branch:

```json
{
  "type": "gitlab",
  "parameters": {
    "resource": "release",
    "operation": "create",
    "owner": "mygroup",
    "repository": "my-repo",
    "releaseTag": "v1.0.0",
    "additionalFields": {
      "name": "Version 1.0.0",
      "description": "First stable release",
      "ref": "main"
    }
  }
}
```

List open bugs, newest first, one item per issue:

```json
{
  "type": "gitlab",
  "parameters": {
    "resource": "repository",
    "operation": "getIssues",
    "owner": "mygroup",
    "repository": "my-repo",
    "returnAll": false,
    "limit": 50,
    "getRepositoryIssuesFilters": {
      "state": "opened",
      "labels": "bug",
      "order_by": "updated_at",
      "sort": "desc"
    }
  }
}
```

Walk a folder tree:

```json
{
  "type": "gitlab",
  "parameters": {
    "resource": "file",
    "operation": "list",
    "owner": "mygroup",
    "repository": "my-repo",
    "filePath": "src",
    "returnAll": true,
    "additionalParameters": {
      "ref": "main",
      "recursive": true
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Manage GitLab files (with binary download/upload), issues, releases, repositories, and users via the GitLab API v4.

- **Owner plus Project Name identify the project** for File, Issue, Repository and User operations; the Release operations other than Create identify it with Project ID instead, which accepts either the numeric project ID or its URL-encoded path.
- **Issue Number is the IID.** Use the number from the issue's URL, not the globally unique issue ID.
- **Binary uploads are capped at 50 MB.** Larger files fail the item — the whole file has to fit in one API request.
- **Self-hosted GitLab works** — set the server URL on the credential; it defaults to gitlab.com.
- **Return All can be a lot of items.** File List, Release Get Many and Repository Get Issues page through everything GitLab has, one output item each, so leave Return All off and set Limit while you are still building the workflow.