READMESource: main@8f147436
dsh-tool-gitlab
A Cordis tool plugin that gives DeepSeek Harness (dsh) enterprise-grade GitLab capabilities. Agents can review merge requests end-to-end (changes, discussions, approvals), observe and trigger CI/CD pipelines, audit group/project membership, and work their personal todo inbox — in natural language.
Built on the official "everything is a plugin" architecture via ctx.tools.register(defineTool(...)), following the official adding-a-tool contract. Designed for self-managed GitLab (baseUrl override) and enterprise governance workflows.
Install
Install directly from GitHub (no npm publish needed):
npm install github:LJH-snow/dsh-tool-gitlab
# or a specific branch/tag
npm install github:LJH-snow/dsh-tool-gitlab#main
Or from a local checkout:
git clone https://github.com/LJH-snow/dsh-tool-gitlab
cd dsh-tool-gitlab
npm install && npm run build # builds to lib/
npm install /path/to/dsh-tool-gitlab
Once published to npm, it will also be installable as
npm install @libai168/dsh-tool-gitlab.
Requires @deepseek-ai/cordis (^4.0.1) and @deepseek-ai/dsh-tools (^0.1.0-rc.6) as peer dependencies, provided by the host dsh runtime.
Configuration
Load the plugin in a dsh composition config (cordis.yml):
- name: 'dsh-tool-gitlab'
config:
token: 'glpat_xxx' # GitLab PAT (optional; required for write tools, approvals, CI triggers, and personal tools)
baseUrl: 'https://gitlab.com/api/v4' # optional; point at your self-managed GitLab, e.g. https://gitlab.example.com/api/v4
timeoutMs: 15000 # optional, request timeout in ms (default 15000)
Full example: examples/cordis.yml.
Security: read-only tools work without a token. Write tools, MR approval, pipeline triggering, code search on private projects, current-user, and todos require a token. Prefer a minimal-scope PAT (e.g.
api+read_repositoryscopes as needed) and never commit it.
Enterprise differentiators
| Area | GitLab plugin tools | What the GitHub plugin has |
|---|---|---|
| Merge Request lifecycle | gitlab_get_mr_changes (per-file diffs), gitlab_list_mr_discussions (review threads), gitlab_reply_mr_discussion, gitlab_resolve_mr_discussion, gitlab_get_mr_approvals (approval rules), gitlab_approve_mr, gitlab_merge_mr (squash) |
PR draft + merge only |
| CI/CD | gitlab_list_pipelines, gitlab_get_pipeline (stages), gitlab_get_job_log (full trace), gitlab_trigger_pipeline |
workflow run list only |
| Org & governance | gitlab_list_group_projects, gitlab_list_subgroups, gitlab_list_group_members, gitlab_list_project_members (Guest→Owner access levels), gitlab_add_*_member, gitlab_update_*_member, gitlab_remove_*_member |
— |
| Project management | gitlab_create_project, gitlab_delete_project (delete-kind UI cards) |
— |
| Group management | gitlab_create_group, gitlab_delete_group; gitlab_transfer_project, gitlab_archive_project, gitlab_unarchive_project |
— |
| Automation & CI config | gitlab_list/create/delete_project_webhook, gitlab_list/create/update/delete_project_variable (values never exposed) |
— |
| Personal workbench | gitlab_list_todos (assigned / approval-required / mentioned), gitlab_get_current_user |
— |
| Release & DevOps | gitlab_list_releases, gitlab_list_milestones, gitlab_list_environments, gitlab_list_labels |
releases list only |
| Self-managed | baseUrl override for on-premises GitLab |
GitHub Enterprise baseUrl |
| Review UX | search-card MR changes, diff-card file writes, terminal-card job logs |
generic/search cards |
Tools
Read-only
| Tool | Description | Token |
|---|---|---|
gitlab_get_project |
Project metadata (id, full path, stars, default branch, visibility) | no |
gitlab_search_projects |
Search projects by name (optionally scoped to a group) | no |
gitlab_list_group_projects |
Projects in a group, with optional subgroup inclusion | no |
gitlab_list_subgroups |
Subgroups of a group (org hierarchy) | no |
gitlab_list_group_members |
Group members with access levels (Guest/Reporter/Developer/Maintainer/Owner) | no |
gitlab_list_project_members |
Project members with access levels | no |
gitlab_list_issues |
List issues (state/assignee filters) | no |
gitlab_get_issue |
Issue details (description included) | no |
gitlab_list_mrs |
List merge requests (state filter, draft/conflict flags) | no |
gitlab_get_mr |
MR details: merge status, CI pipeline, conflicts, squash | no |
gitlab_get_mr_changes |
Changed files with per-file diff hunks | no |
gitlab_get_mr_approvals |
Approval status: approvers, required/left, per-rule state | no |
gitlab_list_mr_discussions |
Review threads with notes and resolution state | no |
gitlab_list_commits |
Commits (branch/author filters) | no |
gitlab_get_file |
Read a repository file (base64-decoded, ref support) | no |
gitlab_list_branches |
Branches with latest SHAs | no |
gitlab_list_labels |
Project labels with colors | no |
gitlab_list_milestones |
Milestones with due dates and states | no |
gitlab_list_releases |
Releases with tags, authors, and dates | no |
gitlab_list_environments |
Deployment environments with states and URLs | no |
gitlab_list_pipelines |
CI/CD pipelines (ref/status filters) | no |
gitlab_get_pipeline |
Pipeline details with stages | no |
gitlab_get_job_log |
Full job log trace (terminal card in UI) | no* |
gitlab_search_code |
Blob code search inside a project | private projects |
gitlab_get_current_user |
Authenticated user identity | yes |
gitlab_list_todos |
Pending todos (assigned, approval-required, mentioned) | yes |
gitlab_list_project_webhooks |
Webhook URLs and enabled event types (metadata only) | private projects |
gitlab_list_project_variables |
CI/CD variable keys and options — values are never returned | private projects |
Write operations
| Tool | Description | Token |
|---|---|---|
gitlab_create_issue |
Create an issue (labels supported) | yes |
gitlab_comment_issue |
Comment on an issue | yes |
gitlab_update_issue |
Open or close an issue | yes |
gitlab_create_mr |
Create a merge request (draft supported) | yes |
gitlab_comment_mr |
Comment on a merge request | yes |
gitlab_reply_mr_discussion |
Reply to a review discussion thread | yes |
gitlab_resolve_mr_discussion |
Resolve/unresolve a review discussion thread | yes |
gitlab_approve_mr |
Approve a merge request (approval flow) | yes |
gitlab_merge_mr |
Merge a merge request (squash supported) | yes |
gitlab_trigger_pipeline |
Trigger a CI/CD pipeline for a ref | yes |
gitlab_create_branch |
Create a branch from a ref | yes |
gitlab_write_file |
Create/update a file via a commit (diff card in UI) | yes |
gitlab_create_project |
Create a project (visibility, namespace, README init) | yes |
gitlab_delete_project |
Permanently delete a project (delete-kind UI card) | yes |
gitlab_add_group_member |
Add a member to a group (guest→owner) | yes |
gitlab_update_group_member |
Change a group member's access level | yes |
gitlab_remove_group_member |
Remove a member from a group (delete-kind UI card) | yes |
gitlab_add_project_member |
Add a member to a project (guest→owner) | yes |
gitlab_update_project_member |
Change a project member's access level | yes |
gitlab_remove_project_member |
Remove a member from a project (delete-kind UI card) | yes |
gitlab_create_group |
Create a group (visibility, path) | yes |
gitlab_delete_group |
Permanently delete a group and all its projects (delete-kind UI card) | yes |
gitlab_transfer_project |
Transfer a project to another namespace (move-kind UI card) | yes |
gitlab_archive_project |
Archive a project (read-only for everyone) | yes |
gitlab_unarchive_project |
Unarchive a project | yes |
gitlab_create_project_webhook |
Create a webhook that pushes events to a URL | yes |
gitlab_delete_project_webhook |
Delete a webhook (delete-kind UI card) | yes |
gitlab_create_project_variable |
Create a CI/CD variable (value sent once, never echoed) | yes |
gitlab_update_project_variable |
Update a CI/CD variable (value never echoed) | yes |
gitlab_delete_project_variable |
Delete a CI/CD variable (delete-kind UI card) | yes |
Behavior contract (per the official execute contract)
- Business failures are canonical values: missing project/issue/MR →
{ found: false }; MR creation failure (branch missing / MR exists) →{ created: false, reason }; merge blocked (conflicts/checks) →{ merged: false, reason }; no token → clearreason/authenticated: falsevalues. - Only infrastructure errors throw: invalid token (401), forbidden (403), rate limit (429).
- Cancellable: every request forwards
exec.signal, with a default 15s timeout.
Development
npm install
npm run typecheck # type check
npm test # unit tests (vitest)
npm run build # build to lib/
See DEVELOPMENT.md for plans and decisions.
Publishing
- The package is published under your npm scope:
@libai168/dsh-tool-gitlab(npm publishing requires a granular access token with 2FA bypass enabled, or trusted publishing). npm run build, thennpm publish --access public.- Add the
dsh-plugintopic to your GitHub repo for ecosystem discovery.
No comments yet. Be the first to write one.