Crate vcs_gitlab 

vcs-gitlab — automate GitLab from Rust by driving the glab CLI.

It shells out to the installed glab binary, asks for --output json, and deserializes the result into typed values — so you get glab’s own behaviour, host config, and credential handling, not a reimplementation of the GitLab API client. Async throughout, structured errors, and mockable. Every command runs inside an OS job (via processkit) so a glab subprocess tree can never be orphaned, and honours an optional per-client timeout.

The surface

The modelled surface is the lean merge-request lifecycle — auth, project view, the MR lifecycle, plus issues and releases. It deserializes glab … --output json (GitLab’s REST JSON, which glab passes through) into typed structs; it never scrapes human-readable output. The sibling vcs-github and vcs-gitea wrappers mirror this shape, and the vcs-forge facade unifies all three.

• GitLabApi — the object-safe trait every operation lives on. Depend on &dyn GitLabApi (or generically on impl GitLabApi) so a test can swap the real client for a double. Project-scoped methods take the working directory as the first argument and return typed results (Project, MergeRequest, Issue, Release, CiStatus) or a structured Error. Unmodelled glab commands go through run.
• GitLab — the real client. GitLab::new uses the job-backed runner; GitLab::with_runner injects a fake one for tests. It is generic over the ProcessRunner seam, defaulting to the production runner.
• GitLabAt — a cwd-bound view (GitLab::at) whose project-scoped methods drop the leading dir, so glab.at(dir).mr_list() reads as glab.mr_list(dir) — handy when one client drives one checkout.
• Builder specs for the multi-option commands — MrCreate (title, body, optional source/target branch) and the MergeStrategy enum (Merge/Squash/Rebase) — #[non_exhaustive], built with a constructor + chained setters, named after the flags they emit.
• auth_status — a best-effort signal, not a guarantee: a long-standing glab bug can make glab auth status exit 0 even when unauthenticated, so a true means “probably”; a subsequent API call is the real test. A false, spawn failure, or timeout are faithful.

Recipes

Read state — depend on the trait so the same code takes a real client or a mock:

use std::path::Path;
use vcs_gitlab::{GitLab, GitLabApi};
let glab = GitLab::new();
let dir = Path::new(".");
for mr in glab.mr_list(dir).await? {                 // up to 100 open MRs
    println!("!{} [{}] {}", mr.iid, mr.state, mr.title);
}

Mutate through the builder specs — mr_merge merges immediately (--auto-merge=false) rather than enabling merge-when-pipeline-succeeds:

use std::path::Path;
use vcs_gitlab::{GitLab, GitLabApi, MergeStrategy, MrCreate};
let dir = Path::new(".");
let url = glab
    .mr_create(dir, MrCreate::new("Add streaming", "Implements …").target("main"))
    .await?;                                          // the new MR's URL
glab.mr_merge(dir, 12, MergeStrategy::Squash).await?;

Testing

Two seams: enable the mock feature for a mockall-generated MockGitLabApi (stub whole methods), or inject a ScriptedRunner with GitLab::with_runner to exercise the real argv-building and JSON parsing against canned output. The cross-cutting testing patterns live in vcs-testkit’s guide.

In-depth guide

Beyond this page, this crate ships a full how-to guide — rendered on docs.rs from docs/. See the guide module.

Modules

__mock_MockGitLabApi

__mock_MockGitLabApi_GitLabApi

guide

vcs-gitlab — GitLab CLI guide

Structs

CancellationTokencancellation

A token which can be used to signal a cancellation request to one or more tasks.

GitLab

The real GitLab client. Generic over the ProcessRunner so tests can inject a fake process executor; GitLab::new() uses the real job-backed runner.

GitLabAt

A GitLab client with a working directory bound, so its project-scoped methods drop the leading dir argument (glab.at(dir).mr_list()). Construct one with GitLab::at.

Issue

An issue (glab issue list/view --output json). The fields are GitLab’s REST Issue object, which glab passes through unchanged. Mirrors MergeRequest’s shape (project-scoped iid, tolerant optional fields).

MergeRequest

A merge request (glab mr list/view --output json). The fields are GitLab’s REST MergeRequest object, which glab passes through unchanged.

MockGitLabApi

The GitLab operations this crate exposes — the interface consumers code against and mock in tests. The lean MR lifecycle; reach unmodelled glab commands through run.

MrCreate

Options for GitLabApi::mr_create (glab mr create).

ProcessResult

The captured result of running a process to completion.

Project

A project (glab repo view --output json) — GitLab’s REST Project object.

Release

A release (glab release list/view --output json) — GitLab’s REST Release object, which glab passes through unchanged.

Enums

CiStatus

The coarse CI/pipeline outcome for an MR (glab mr view … --output json’s head_pipeline.status), bucketed into the four states a caller acts on.

Error

Errors produced when launching or running a child process.

MergeStrategy

How GitLabApi::mr_merge merges the MR. GitLab’s default is a merge commit; Squash/Rebase add the corresponding flag.

Constants

BINARY

Name of the underlying CLI binary this crate drives.

Traits

GitLabApi

The GitLab operations this crate exposes — the interface consumers code against and mock in tests. The lean MR lifecycle; reach unmodelled glab commands through run.

Type Aliases

Result

Crate result alias.