gitlab

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gitlab

Independent, unofficial connector for Gitlab. Not affiliated with, endorsed by, or sponsored by Gitlab. "Gitlab" is a trademark of its owner, used only to identify the service this connector works with.

Agent-callable tools for GitLab, the DevOps platform for source code, merge requests, and CI/CD. The connector wraps the GitLab REST API v4 (with one GraphQL island — the Work Items surface — reached through

POST /api/graphql

), giving an agent the ability to read and drive projects, issues, merge requests, repository contents, and pipelines. It is centered on the merge-request review loop and repository authoring: read an MR and its diffs and discussions, comment or approve, commit file changes atomically, and run or inspect CI. It targets GitLab SaaS (

gitlab.com

) by default; the host is configurable for self-managed and GitLab Dedicated instances.

独立的非官方GitLab连接器。与GitLab无关联、未获其认可或赞助。"GitLab"是其所有者的商标，仅用于标识本连接器所适配的服务。

适用于GitLab的Agent可调用工具，GitLab是一款面向源代码、合并请求和CI/CD的DevOps平台。该连接器封装了GitLab REST API v4（其中工作项（Work Items）模块通过

POST /api/graphql

访问的GraphQL接口），使Agent能够读取和管理项目、议题、合并请求、仓库内容以及流水线。它围绕合并请求评审流程和仓库创作功能构建：读取MR及其差异和讨论内容、添加评论或批准、原子性提交文件变更、运行或检查CI。默认适配GitLab SaaS（

gitlab.com

）；可配置主机地址以适配自托管和GitLab Dedicated实例。

When to use this

使用场景

An agent needs to drive the merge-request review loop: list and read MRs, fetch their diffs, commits, notes, and threaded discussions, comment inline on a diff line, approve or unapprove, and merge.
An agent needs to author repository changes: create a branch, commit many files in one atomic commit, read files and the repository tree, list commits, and compare two refs.
An agent needs to manage issues (REST): create, update, comment on, and close/reopen them — or manage work items like epics, tasks, and objectives (GraphQL): create, update, and close/reopen.
An agent needs to run and inspect CI/CD: trigger, list, get, retry, or cancel pipelines; list jobs, read a job log, and play a manual job.
An agent needs to search — globally, within a project, or within a group — across issues, merge requests, code, commits, users, and more, and resolve project, user, label, and milestone ids before writing.

Agent需要驱动合并请求评审流程：列出并读取MR、获取其差异、提交记录、评论和线程讨论、在差异的特定行添加内联评论、批准或取消批准、合并MR。
Agent需要创作仓库变更：创建分支、在单次原子提交中提交多个文件、读取文件和仓库目录结构、列出提交记录、比较两个引用。
Agent需要管理议题（REST接口）：创建、更新、添加评论、关闭/重新打开议题；或管理工作项（如史诗、任务、目标，通过GraphQL接口）：创建、更新、关闭/重新打开。
Agent需要运行和检查CI/CD：触发、列出、获取、重试或取消流水线；列出作业、读取作业日志、启动手动作业。
Agent需要进行搜索——全局搜索、项目内搜索或群组内搜索——涵盖议题、合并请求、代码、提交记录、用户等，并且在执行写入操作前解析项目、用户、标签和里程碑ID。

Setup

安装配置

This is an agentskills.io skill.

If the connector has not been installed as a skill yet, install it first with

npx skills add zapier/connectors --skill gitlab

(or your harness's own skill-install mechanism), then continue here. Installing the skill copies these files, not dependencies. Before running the CLI, a local MCP server, or

zapier-sdk

auth commands, run

npm install --omit=dev

here once. Importing the published package as a dependency in your own project instead? That

npm install

already resolves everything — see

references/use-as-sdk.md

The connector runs on Node.js 22.18+. Pick the reference that matches how you're running it, and load it before doing anything else:

You have...	Load
An MCP-aware client — tools may already be loaded (e.g. `mcp__gitlab__<tool>` ), or you can register a local server yourself (or guide the user to)	`references/use-as-mcp.md`
Terminal / subprocess access (you can run `node` )	`references/use-as-cli.md`
Only your own code, importing this package as a dependency	`references/use-as-sdk.md`
No tool access, no terminal, no ability to import this package — you write your own code that calls the Gitlab API directly (e.g. a code-execution sandbox)	`references/use-as-recipe.md`

这是一款agentskills.io技能。

如果尚未将该连接器作为技能安装，请先使用

npx skills add zapier/connectors --skill gitlab

（或你的工具链自带的技能安装机制）进行安装，然后继续后续操作。安装技能会复制这些文件，但不会安装依赖项。在运行CLI、本地MCP服务器或

zapier-sdk

认证命令前，请先在此目录执行一次

npm install --omit=dev

。如果你是在自己的项目中引入已发布的包作为依赖？此时

npm install

已经解决了所有依赖问题——详见

references/use-as-sdk.md

。

该连接器运行在**Node.js 22.18+**环境下。根据你的运行方式选择对应的参考文档，并在执行任何操作前加载它：

你的环境...	加载文档
支持MCP的客户端——工具可能已加载（例如 `mcp__gitlab__<tool>` ），或者你可以自行注册本地服务器（或引导用户注册）	`references/use-as-mcp.md`
可访问终端/子进程（可以运行 `node` ）	`references/use-as-cli.md`
仅使用自有代码，将此包作为依赖引入	`references/use-as-sdk.md`
无法访问工具、终端，也无法引入此包——你需要编写直接调用Gitlab API的代码（例如代码执行沙箱）	`references/use-as-recipe.md`

Scripts

脚本列表

All 47 scripts use the single connection

gitlab

. Project-scoped tools take a

projectId

(numeric id or URL-encoded

group/project

path); issues and MRs are addressed by their project-scoped

iid

, not the global id. The script's

inputSchema

outputSchema

(Zod) inside the file is the source of truth for its contract.

Projects & search

Script	Script name	Connections	Description
`scripts/listProjects.ts`	`listProjects`	`gitlab`	List or search projects the token can see (resolves `projectId` ).
`scripts/getProject.ts`	`getProject`	`gitlab`	Get one project's metadata by id or path (incl. `default_branch` ).
`scripts/search.ts`	`search`	`gitlab`	Search globally across projects, issues, MRs, milestones, users, code, or commits.
`scripts/searchProject.ts`	`searchProject`	`gitlab`	Search within one project across issues, MRs, milestones, users, code, or commits.
`scripts/searchGroup.ts`	`searchGroup`	`gitlab`	Search within one group across projects, issues, MRs, milestones, users, code, or commits.

Issues

Script	Script name	Connections	Description
`scripts/listIssues.ts`	`listIssues`	`gitlab`	List issues in a project, filterable by state, labels, assignee, or milestone.
`scripts/getIssue.ts`	`getIssue`	`gitlab`	Get one issue including its full markdown description.
`scripts/createIssue.ts`	`createIssue`	`gitlab`	Open a new issue with a markdown description.
`scripts/updateIssue.ts`	`updateIssue`	`gitlab`	Update an issue's fields, or close/reopen it.
`scripts/addIssueComment.ts`	`addIssueComment`	`gitlab`	Add a comment (note) to an issue.

Merge requests

Script	Script name	Connections	Description
`scripts/listMergeRequests.ts`	`listMergeRequests`	`gitlab`	List MRs assigned to or created by the token identity across all projects (global).
`scripts/listProjectMergeRequests.ts`	`listProjectMergeRequests`	`gitlab`	List merge requests in one project.
`scripts/listGroupMergeRequests.ts`	`listGroupMergeRequests`	`gitlab`	List merge requests across all projects in one group.
`scripts/getMergeRequest.ts`	`getMergeRequest`	`gitlab`	Get one merge request's full detail (the entry point to the review loop).
`scripts/createMergeRequest.ts`	`createMergeRequest`	`gitlab`	Open a merge request from a source branch into a target branch.
`scripts/updateMergeRequest.ts`	`updateMergeRequest`	`gitlab`	Update an MR's fields, or close/reopen it.
`scripts/mergeMergeRequest.ts`	`mergeMergeRequest`	`gitlab`	Merge a merge request (optionally squash, or guard with a head `sha` ).
`scripts/approveMergeRequest.ts`	`approveMergeRequest`	`gitlab`	Approve (or revoke approval on) a merge request.
`scripts/getMergeRequestDiffs.ts`	`getMergeRequestDiffs`	`gitlab`	Get the paginated file diffs for a merge request.
`scripts/listMergeRequestCommits.ts`	`listMergeRequestCommits`	`gitlab`	List the commits on a merge request.
`scripts/listMergeRequestNotes.ts`	`listMergeRequestNotes`	`gitlab`	List the comments (notes) on a merge request.
`scripts/addMergeRequestComment.ts`	`addMergeRequestComment`	`gitlab`	Add a top-level comment (note) to a merge request.
`scripts/addMergeRequestDiffComment.ts`	`addMergeRequestDiffComment`	`gitlab`	Add a review comment pinned to a specific line of an MR diff.
`scripts/listMergeRequestDiscussions.ts`	`listMergeRequestDiscussions`	`gitlab`	List discussion threads on an MR, incl. diff notes and resolved/resolvable status.

Repository

Script	Script name	Connections	Description
`scripts/listBranches.ts`	`listBranches`	`gitlab`	List (or search) a project's branches.
`scripts/createBranch.ts`	`createBranch`	`gitlab`	Create a branch from an existing ref (ref is required — no silent default).
`scripts/commitFiles.ts`	`commitFiles`	`gitlab`	Create, update, delete, or move multiple files in a single atomic commit.
`scripts/listCommits.ts`	`listCommits`	`gitlab`	List commits on a branch or across the repository.
`scripts/getFile.ts`	`getFile`	`gitlab`	Read a file's contents at a ref.
`scripts/listRepositoryTree.ts`	`listRepositoryTree`	`gitlab`	List files and directories in a repository path.
`scripts/compareRefs.ts`	`compareRefs`	`gitlab`	Compare two refs and return the diff between them.

CI/CD

Script	Script name	Connections	Description
`scripts/triggerPipeline.ts`	`triggerPipeline`	`gitlab`	Run a new pipeline on a ref, with optional CI/CD variables.
`scripts/listPipelines.ts`	`listPipelines`	`gitlab`	List pipelines for a project, filterable by ref or status.
`scripts/getPipeline.ts`	`getPipeline`	`gitlab`	Get one pipeline's status and metadata.
`scripts/listPipelineJobs.ts`	`listPipelineJobs`	`gitlab`	List the jobs in a pipeline.
`scripts/getJobLog.ts`	`getJobLog`	`gitlab`	Get the log (trace) output of a CI job.
`scripts/retryPipeline.ts`	`retryPipeline`	`gitlab`	Retry the failed and canceled jobs in a pipeline, keeping the passed ones.
`scripts/cancelPipeline.ts`	`cancelPipeline`	`gitlab`	Cancel a running pipeline, stopping its in-progress and pending jobs.
`scripts/playJob.ts`	`playJob`	`gitlab`	Start a manual job waiting on a manual action (a play button).

Work items (GraphQL)

Script	Script name	Connections	Description
`scripts/listWorkItems.ts`	`listWorkItems`	`gitlab`	List work items in a project or group, filterable by type and state.
`scripts/getWorkItem.ts`	`getWorkItem`	`gitlab`	Get one work item's full detail including its description and type.
`scripts/createWorkItem.ts`	`createWorkItem`	`gitlab`	Create a work item (epic, task, objective, etc.) in a project or group.
`scripts/updateWorkItem.ts`	`updateWorkItem`	`gitlab`	Update a work item's fields, or close/reopen it.

Metadata & resolvers

Script	Script name	Connections	Description
`scripts/listLabels.ts`	`listLabels`	`gitlab`	List a project's labels (resolves valid label names).
`scripts/listMilestones.ts`	`listMilestones`	`gitlab`	List a project's milestones (resolves `milestone_id` ).
`scripts/getCurrentUser.ts`	`getCurrentUser`	`gitlab`	Get the identity of the authenticated token (also the connection test).
`scripts/findUsers.ts`	`findUsers`	`gitlab`	Find users by username or search term (resolves assignee/reviewer ids).

全部47个脚本均使用单一连接

gitlab

。项目范围的工具需要传入

projectId

（数字ID或URL编码的

group/project

路径）；议题和MR通过其项目范围内的

iid

而非全局ID来定位。脚本文件内部的

inputSchema

outputSchema

（基于Zod）是其契约的权威来源。

项目与搜索

脚本	脚本名称	连接配置	描述
`scripts/listProjects.ts`	`listProjects`	`gitlab`	列出或搜索令牌可访问的项目（解析 `projectId` ）。
`scripts/getProject.ts`	`getProject`	`gitlab`	通过ID或路径获取单个项目的元数据（包含 `default_branch` ）。
`scripts/search.ts`	`search`	`gitlab`	在项目、议题、MR、里程碑、用户、代码或提交记录中进行全局搜索。
`scripts/searchProject.ts`	`searchProject`	`gitlab`	在单个项目内搜索议题、MR、里程碑、用户、代码或提交记录。
`scripts/searchGroup.ts`	`searchGroup`	`gitlab`	在单个群组内搜索项目、议题、MR、里程碑、用户、代码或提交记录。

议题

脚本	脚本名称	连接配置	描述
`scripts/listIssues.ts`	`listIssues`	`gitlab`	列出项目中的议题，可按状态、标签、经办人或里程碑筛选。
`scripts/getIssue.ts`	`getIssue`	`gitlab`	获取单个议题的完整信息，包括其Markdown描述。
`scripts/createIssue.ts`	`createIssue`	`gitlab`	新建一个带有Markdown描述的议题。
`scripts/updateIssue.ts`	`updateIssue`	`gitlab`	更新议题的字段，或关闭/重新打开议题。
`scripts/addIssueComment.ts`	`addIssueComment`	`gitlab`	向议题添加评论（备注）。

合并请求

脚本	脚本名称	连接配置	描述
`scripts/listMergeRequests.ts`	`listMergeRequests`	`gitlab`	列出令牌标识所分配或创建的所有项目中的MR（全局范围）。
`scripts/listProjectMergeRequests.ts`	`listProjectMergeRequests`	`gitlab`	列出单个项目中的合并请求。
`scripts/listGroupMergeRequests.ts`	`listGroupMergeRequests`	`gitlab`	列出单个群组下所有项目中的合并请求。
`scripts/getMergeRequest.ts`	`getMergeRequest`	`gitlab`	获取单个合并请求的完整细节（评审流程的入口）。
`scripts/createMergeRequest.ts`	`createMergeRequest`	`gitlab`	从源分支向目标分支发起合并请求。
`scripts/updateMergeRequest.ts`	`updateMergeRequest`	`gitlab`	更新MR的字段，或关闭/重新打开MR。
`scripts/mergeMergeRequest.ts`	`mergeMergeRequest`	`gitlab`	合并合并请求（可选压缩提交，或通过头部 `sha` 进行校验）。
`scripts/approveMergeRequest.ts`	`approveMergeRequest`	`gitlab`	批准（或撤销批准）合并请求。
`scripts/getMergeRequestDiffs.ts`	`getMergeRequestDiffs`	`gitlab`	获取合并请求的分页文件差异。
`scripts/listMergeRequestCommits.ts`	`listMergeRequestCommits`	`gitlab`	列出合并请求中的提交记录。
`scripts/listMergeRequestNotes.ts`	`listMergeRequestNotes`	`gitlab`	列出合并请求中的评论（备注）。
`scripts/addMergeRequestComment.ts`	`addMergeRequestComment`	`gitlab`	向合并请求添加顶级评论（备注）。
`scripts/addMergeRequestDiffComment.ts`	`addMergeRequestDiffComment`	`gitlab`	在MR差异的特定行添加评审评论。
`scripts/listMergeRequestDiscussions.ts`	`listMergeRequestDiscussions`	`gitlab`	列出MR上的讨论线程，包括差异评论和已解决/可解决状态。

仓库

脚本	脚本名称	连接配置	描述
`scripts/listBranches.ts`	`listBranches`	`gitlab`	列出（或搜索）项目的分支。
`scripts/createBranch.ts`	`createBranch`	`gitlab`	从现有引用创建分支（必须指定引用——无默认值）。
`scripts/commitFiles.ts`	`commitFiles`	`gitlab`	在单次原子提交中创建、更新、删除或移动多个文件。
`scripts/listCommits.ts`	`listCommits`	`gitlab`	列出分支或整个仓库的提交记录。
`scripts/getFile.ts`	`getFile`	`gitlab`	读取引用对应的文件内容。
`scripts/listRepositoryTree.ts`	`listRepositoryTree`	`gitlab`	列出仓库路径下的文件和目录。
`scripts/compareRefs.ts`	`compareRefs`	`gitlab`	比较两个引用并返回它们之间的差异。

CI/CD

脚本	脚本名称	连接配置	描述
`scripts/triggerPipeline.ts`	`triggerPipeline`	`gitlab`	在指定引用上运行新流水线，可传入可选的CI/CD变量。
`scripts/listPipelines.ts`	`listPipelines`	`gitlab`	列出项目的流水线，可按引用或状态筛选。
`scripts/getPipeline.ts`	`getPipeline`	`gitlab`	获取单个流水线的状态和元数据。
`scripts/listPipelineJobs.ts`	`listPipelineJobs`	`gitlab`	列出流水线中的作业。
`scripts/getJobLog.ts`	`getJobLog`	`gitlab`	获取CI作业的日志（跟踪）输出。
`scripts/retryPipeline.ts`	`retryPipeline`	`gitlab`	重试流水线中失败和取消的作业，保留已通过的作业。
`scripts/cancelPipeline.ts`	`cancelPipeline`	`gitlab`	取消正在运行的流水线，停止其进行中和待处理的作业。
`scripts/playJob.ts`	`playJob`	`gitlab`	启动等待手动操作的作业（即带有播放按钮的作业）。

工作项（GraphQL）

脚本	脚本名称	连接配置	描述
`scripts/listWorkItems.ts`	`listWorkItems`	`gitlab`	列出项目或群组中的工作项，可按类型和状态筛选。
`scripts/getWorkItem.ts`	`getWorkItem`	`gitlab`	获取单个工作项的完整细节，包括其描述和类型。
`scripts/createWorkItem.ts`	`createWorkItem`	`gitlab`	在项目或群组中创建工作项（如史诗、任务、目标等）。
`scripts/updateWorkItem.ts`	`updateWorkItem`	`gitlab`	更新工作项的字段，或关闭/重新打开工作项。

元数据与解析器

脚本	脚本名称	连接配置	描述
`scripts/listLabels.ts`	`listLabels`	`gitlab`	列出项目的标签（解析有效的标签名称）。
`scripts/listMilestones.ts`	`listMilestones`	`gitlab`	列出项目的里程碑（解析 `milestone_id` ）。
`scripts/getCurrentUser.ts`	`getCurrentUser`	`gitlab`	获取已认证令牌的身份信息（同时也是连接测试）。
`scripts/findUsers.ts`	`findUsers`	`gitlab`	通过用户名或搜索词查找用户（解析经办人/评审人ID）。

Disambiguation & refusals

歧义处理与拒绝规则

This connector resolves names to ids, then writes. Two situations trip up an action-biased agent — handle both before you write.

Before writing to a record you looked up by name — count how many returned records match the name the user gave exactly (case-insensitive). This applies to projects looked up by path/name via

listProjects

, users looked up by username via

findUsers

, and labels or milestones via

listLabels

listMilestones

One exact match (even among other fuzzy hits) → use it. Don't ask for confirmation you don't need.
No exact match but one clear fuzzy hit → use it.
Two or more that tie (two projects both pathed
```
.../api
```
, two users both named "Jordan Lee", two labels both "backend") → stop. List them with a distinguishing field (id +
```
path_with_namespace
```
/ username / description) and ask which one. Never pick one yourself and write against it.

Before fulfilling a request, check that a script actually does it:

A script does it → use it.
No script does it → say plainly it's unsupported and stop. There are no tools for project, group, or instance administration (creating or deleting a project, managing members, protected branches, runners, webhooks, or pipeline triggers) — these are out of scope. Work items (epics/tasks/objectives) require a Premium/Ultimate project — if a work-item call returns a tier/availability error, say so plainly and stop; don't fake success. Don't substitute a different script and call it done, and never report success for an action you didn't perform.

该连接器会将名称解析为ID，然后执行写入操作。有两种情况会导致偏向执行操作的Agent出错——在执行写入操作前需处理这两种情况。

在写入通过名称查找的记录之前——统计用户提供的名称（不区分大小写）精确匹配的记录数量。这适用于通过

listProjects

按路径/名称查找的项目、通过

findUsers

按用户名查找的用户，以及通过

listLabels

listMilestones

查找的标签或里程碑：

精确匹配1条记录（即使存在其他模糊匹配结果）→ 使用该记录。无需不必要的确认。
无精确匹配但有1条明确的模糊匹配结果→ 使用该记录。
两条或多条记录匹配度相同（两个项目路径均为
```
.../api
```
，两个用户均名为"Jordan Lee"，两个标签均为"backend"）→ 停止操作。列出这些记录并附带区分字段（ID +
```
path_with_namespace
```
/用户名/描述），询问用户选择哪一个。切勿自行选择并执行写入操作。

在执行请求之前，检查脚本是否实际支持该操作：

脚本支持该操作→ 使用脚本。
无脚本支持该操作→ 明确告知用户该操作不受支持并停止。本连接器不支持项目、群组或实例管理相关操作（创建或删除项目、管理成员、保护分支、运行器、Webhook或流水线触发器）——这些均超出范围。工作项（史诗/任务/目标）需要Premium/Ultimate级别的项目——如果工作项调用返回层级/可用性错误，明确告知用户并停止；切勿伪造成功。切勿替换为其他脚本并声称已完成操作，永远不要报告未执行操作的成功结果。

Auth

认证

Every shape passes auth as one connection selector, not the secret — a

[<resolver>:]<value>

string. This connector accepts two resolvers on its single

gitlab

connection:

env:GITLAB_TOKEN
— a long-lived GitLab access token (personal, project, or group), read from the named environment variable and sent as the
```
PRIVATE-TOKEN
```
header. Mint the token with the
```
api
```
scope for full read+write access, or
```
read_api
```
for a read-only agent (the list/get/search/diff/log tools). Set
```
GITLAB_HOST
```
(default
```
gitlab.com
```
) to point the connector at a self-managed or GitLab Dedicated instance; the token is only ever sent to that host.
zapier:<connection-id>
— Zapier-managed auth, which routes through Zapier's auth, retries, and governance layer and also supports OAuth. A UUID-shaped bare value always claims
```
zapier:
```
.

The

<resolver>:

prefix is optional; a bare value goes to the first resolver that claims it. Each script declares the connections it needs and the resolvers each accepts. The exact syntax for passing a connection (and how to see this connector's resolver list) differs by shape — see the reference you loaded above.

Checking what's already configured first? Don't dump environment values to do it —

env

env | grep <name>

prints the value along with the name, leaking a live credential into the transcript if one is set. Check names only (

env | cut -d= -f1 | grep -i <name>

) or test a known name directly (

[ -n "$VAR_NAME" ]

No connection yet? Pick one — and follow the reference's own flow to obtain it; never just ask the user for a connection id or token as if they already have one memorized:

	Load
Pass the credential directly	`references/use-without-zapier.md`
Route it through a Zapier connection	`references/use-with-zapier.md`

所有场景均通过单个连接选择器传递认证信息，而非密钥——格式为

[<resolver>:]<value>

的字符串。该连接器的单个

gitlab

连接接受两种解析器：

env:GITLAB_TOKEN
——长期有效的GitLab访问令牌（个人、项目或群组令牌），从指定环境变量读取，并作为
```
PRIVATE-TOKEN
```
头发送。创建令牌时，若需要完整的读写权限，请选择
```
api
```
范围；若仅需只读Agent（列表/获取/搜索/差异/日志工具），请选择
```
read_api
```
范围。设置
```
GITLAB_HOST
```
（默认值为
```
gitlab.com
```
）可将连接器指向自托管或GitLab Dedicated实例；令牌仅会发送至该主机。
zapier:<connection-id>
——由Zapier管理的认证，通过Zapier的认证、重试和治理层路由，同时支持OAuth。UUID格式的纯值默认使用
```
zapier:
```
解析器。

<resolver>:

前缀是可选的；纯值会被第一个声明支持它的解析器处理。每个脚本都会声明其所需的连接以及每个连接接受的解析器。传递连接的具体语法（以及如何查看该连接器的解析器列表）因场景而异——请参阅你之前加载的参考文档。

想要先检查已配置的内容？不要直接输出环境变量值——

env

或

env | grep <name>

会同时打印名称和值，如果已设置有效凭据，会将其泄露到日志中。请仅检查名称（

env | cut -d= -f1 | grep -i <name>

）或直接测试已知名称（

[ -n "$VAR_NAME" ]

）。

还没有连接？选择一种方式——并按照参考文档的流程获取连接；切勿直接向用户索要连接ID或令牌，仿佛他们已经记住了这些信息：

	加载文档
直接传递凭据	`references/use-without-zapier.md`
通过Zapier连接路由	`references/use-with-zapier.md`

Output format

输出格式

Every script returns a

{ data, meta }

envelope:

data
— the script's result (the shape its
```
outputSchema
```
declares; see the reference you loaded above for how to inspect a script's exact schema in your shape).
meta.outputDataValidation
— what validating
```
data
```
did:
- ```
{ skipped: false, droppedPaths: null }
```
  — validated, nothing removed.
- ```
{ skipped: false, droppedPaths: [...], instruction }
```
  — validated, but those paths were stripped from
```
data
```
  : fields the script returned from the API that the
```
outputSchema
```
  doesn't declare. If you need them, re-run with output validation skipped.
- ```
{ skipped: true }
```
  — validation was bypassed;
```
data
```
  is the raw, unchecked script output.

Reading dropped fields /
skipOutputDataValidation
. To receive the raw, unvalidated result, opt out of output validation (the exact syntax differs by shape — see the reference you loaded above). Input validation is never skipped.

Trimming the result /
filterOutputData
. To shrink a large result down to the fields you need, pass a jq expression that post-processes

data

(again, exact syntax per shape). The jq runs against

data

only, NOT the

{ data, meta }

envelope, so write it rooted at

data

(run the script's

--help

— or your shape's equivalent — to see its output schema). The transformed value replaces

data

meta

is preserved, and the result is NOT re-validated against the output schema.

每个脚本都会返回

{ data, meta }

格式的结果包：

data
——脚本的执行结果（其
```
outputSchema
```
声明的格式；请参阅你加载的参考文档，了解如何在你的场景中查看脚本的确切模式）。
meta.outputDataValidation
——对
```
data
```
的验证结果：
- ```
{ skipped: false, droppedPaths: null }
```
  ——已验证，未移除任何内容。
- ```
{ skipped: false, droppedPaths: [...], instruction }
```
  ——已验证，但这些路径已从
```
data
```
  中移除：脚本从API返回的字段未在
```
outputSchema
```
  中声明。如果需要这些字段，请跳过输出验证重新运行。
- ```
{ skipped: true }
```
  ——已跳过验证；
```
data
```
  是原始的、未经过检查的脚本输出。

读取被移除的字段 /
skipOutputDataValidation
。若要接收原始的、未验证的结果，请选择跳过输出验证（具体语法因场景而异——请参阅你加载的参考文档）。输入验证永远不会被跳过。

精简结果 /
filterOutputData
。若要将大型结果精简到你需要的字段，请传入一个jq表达式对

data

进行后处理（同样，具体语法因场景而异）。jq仅针对

data

运行，而非

{ data, meta }

结果包，因此请以

data

为根编写表达式（运行脚本的

--help

——或你的场景中的等效命令——查看其输出模式）。转换后的值会替换

data

，

meta

会被保留，且结果不会重新根据输出模式进行验证。

References

参考文档

Load the matching reference file before working in that area:

Reference	Covers	Load it when
`references/gitlab-api-gotchas.md`	Vendor behaviors that break a naive caller: `PRIVATE-TOKEN` vs OAuth Bearer auth and `api` / `read_api` scopes, numeric-id-vs-encoded-path and `iid` -vs-global-id, the JSON error shape and status codes, offset vs keyset pagination, gitlab.com rate limits, the singular `POST .../pipeline` , merge 405-when-not-mergeable and the `sha` guard, GraphQL-only work items.	Before any write, or when a call returns a non-2xx status, a 405 on merge, an empty/errored pipeline or work-item call, or an unexpected pagination result.
`references/gitlab-formatting.md`	GitLab Flavored Markdown: blank-line paragraph breaks, `#` / `!` / `@` references, task lists, tables, fenced code highlighting.	When composing a GitLab issue or merge-request description, a work-item body, or a note/diff comment.

在对应场景工作前，请加载匹配的参考文档：

参考文档	涵盖内容	加载时机
`references/gitlab-api-gotchas.md`	可能导致调用出错的厂商特性： `PRIVATE-TOKEN` 与OAuth Bearer认证、 `api` / `read_api` 范围、数字ID与编码路径、 `iid` 与全局ID、JSON错误格式和状态码、偏移分页与键集分页、gitlab.com速率限制、单数形式的 `POST .../pipeline` 、合并时的405错误（当不可合并时）与 `sha` 校验、仅支持GraphQL的工作项。	在执行任何写入操作前，或当调用返回非2xx状态码、合并时返回405错误、流水线或工作项调用返回空结果/错误、或分页结果不符合预期时。
`references/gitlab-formatting.md`	GitLab风格Markdown：空行段落分隔、 `#` / `!` / `@` 引用、任务列表、表格、带语法高亮的代码块。	撰写GitLab议题或合并请求描述、工作项内容、备注/差异评论时。