Crate vcs_github 

vcs-github — automate GitHub from Rust by driving the gh CLI.

It shells out to the installed gh binary and parses its output into typed values — so you get gh’s own behaviour, auth, and host resolution, not a reimplementation of the GitHub REST/GraphQL API. The PR / issue / Actions / release lifecycle, async throughout, with structured errors, and mockable. Every command runs inside an OS job (via processkit) so a gh subprocess tree can never be orphaned, and honours an optional per-client timeout. Read-style methods ask gh for --json and deserialize it; nothing scrapes human-readable output.

The surface

• GitHubApi — the object-safe trait every operation lives on. Depend on &dyn GitHubApi (or generically on impl GitHubApi) so a test can swap the real client for a double. Repo-scoped methods take the working directory as the first argument and return typed results (PullRequest, Issue, Repo, CheckRun, WorkflowRun, Release, PrFeedback, …) or a structured Error.
• GitHub — the real client. GitHub::new uses the job-backed runner; GitHub::with_runner injects a fake one for tests. It is generic over the ProcessRunner seam, defaulting to the production runner.
• GitHubAt — a cwd-bound view (GitHub::at) whose methods drop the leading dir, so gh.at(dir).pr_list() reads as gh.pr_list(dir) — handy when one client drives one checkout.
• Method groups on the trait: PRs (pr_list, pr_view, pr_create, pr_merge, pr_review, pr_checks, pr_feedback, …); Actions runs (run_list, run_view, run_watch — blocking, bounded by the client timeout); issues & releases (issue_create, release_view, …); plus the escape hatches run / api for anything unmodelled.
• Builder specs for the multi-option commands — PrCreate (title/body with optional head/base), PrMerge (strategy MergeStrategy, --auto, --delete-branch), and ReviewAction (whose private fields make an empty-body request-changes unrepresentable) — each #[non_exhaustive], built with a constructor and chained setters, named after the flags they emit.

Recipes

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

use std::path::Path;
use vcs_github::{GitHub, GitHubApi};
let gh = GitHub::new();
let dir = Path::new(".");
let authed = gh.auth_status().await?;          // is `gh` logged in?
let open = gh.pr_list(dir).await?;             // up to 100 open PRs

Mutate through the builder specs — open a PR, approve it, then squash-merge:

use std::path::Path;
use vcs_github::{GitHub, GitHubApi, PrCreate, PrMerge, ReviewAction};
let dir = Path::new(".");
let url = gh.pr_create(dir, PrCreate::new("Add X", "…").base("main")).await?;
gh.pr_review(dir, 7, ReviewAction::approve().with_body("LGTM")).await?;
gh.pr_merge(dir, 7, PrMerge::squash().delete_branch()).await?;

Testing

Two seams: enable the mock feature for a mockall-generated MockGitHubApi (stub whole methods), or inject a ScriptedRunner with GitHub::with_runner to exercise the real argv-building and parsing against canned output — no gh binary or network needed, so it runs on CI. The cross-cutting testing patterns live in vcs-testkit’s guide.

Safety

Caller values placed in a bare positional argv slot (an api endpoint, a release tag) are refused before spawning if empty or starting with - — gh would parse them as flags. Flag-value slots (--body <b>, --branch <b>) are consumed verbatim and need no guard.

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_MockGitHubApi

__mock_MockGitHubApi_GitHubApi

guide

vcs-github — GitHub CLI guide

Structs

CancellationTokencancellation

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

CheckRun

One check on a PR (gh pr checks --json …).

Comment

A PR conversation comment (from gh pr view --json comments).

GitHub

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

GitHubAt

A GitHub client with a working directory bound, so its repo-scoped methods drop the leading dir argument (gh.at(dir).pr_list()). Construct one with GitHub::at.

Issue

An issue (gh issue list --json number,title,state; gh issue view additionally fills body/url).

MockGitHubApi

The GitHub operations this crate exposes — the interface consumers code against and mock in tests.

PrCreate

Options for GitHubApi::pr_create (gh pr create).

PrFeedback

The review/comment feedback on a PR (gh pr view --json reviews,comments).

PrMerge

Options for GitHubApi::pr_merge (gh pr merge).

ProcessResult

The captured result of running a process to completion.

PullRequest

A pull request (gh pr list/view --json number,title,state,headRefName,baseRefName,url).

Release

A release (gh release list/view --json …).

Repo

A repository (gh repo view --json name,owner,description,url,isPrivate,defaultBranchRef).

Review

A submitted PR review (from gh pr view --json reviews).

ReviewAction

What GitHubApi::pr_review submits (gh pr review).

WorkflowRun

A GitHub Actions workflow run (gh run list/view --json …).

Enums

Error

Errors produced when launching or running a child process.

MergeStrategy

How GitHubApi::pr_merge merges the PR — exactly one of gh’s mutually exclusive strategy flags.

ReviewKind

Which kind of review GitHubApi::pr_review submits — match on ReviewAction::kind to read it back.

Constants

BINARY

Name of the underlying CLI binary this crate drives.

Traits

GitHubApi

The GitHub operations this crate exposes — the interface consumers code against and mock in tests.

Type Aliases

Result

Crate result alias.