Crate vcs_gitea 

vcs-gitea — automate Gitea (and Forgejo) from Rust by driving the tea CLI.

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

The surface

• GiteaApi — the object-safe trait every operation lives on. Depend on &dyn GiteaApi (or generically on impl GiteaApi) so a test can swap the real client for a double. The repo-scoped methods take the working directory as the first argument and return typed results (PullRequest, Issue, Release) or a structured Error; unmodelled tea commands go through run.
• Gitea — the real client. Gitea::new uses the job-backed runner; Gitea::with_runner injects a fake one for tests. It is generic over the ProcessRunner seam, defaulting to the production runner.
• GiteaAt — a cwd-bound view (Gitea::at) whose repo-scoped methods drop the leading dir, so tea.at(dir).pr_list() reads as tea.pr_list(dir) — handy when one client drives one checkout.
• Specs & enums — PrCreate (#[non_exhaustive], a constructor plus chained .head / .base setters named after the flags they emit) and MergeStrategy (Merge / Squash / Rebase → tea pr merge --style).

The exposed operations are the lean lifecycle tea actually supports: auth (auth_status), the PR lifecycle (list / view / create / merge / close), issues (list / view / create), and release listing. It is deliberately narrower than vcs-github / vcs-gitlab: tea has no single-PR view, no current-repo view, no draft toggle, no PR-checks command, and no single-release view (tea releases ignores any positional and always lists), so those operations are simply absent here (the vcs-forge facade reports them Unsupported for the Gitea backend). pr_view is synthesized by listing with --state all and filtering by number; issue_view, by contrast, is a first-class tea issues <index>.

One shape caveat: tea’s --output json is not the Gitea REST shape. Its list commands emit tea’s print-table — a JSON array of string-maps whose keys are snake-cased column headers and whose values are all strings (no html_url, no nested branch objects, no typed bools); we pick columns with --fields. Its detail view (issues <n>) is a separate typed object. The parsers model both (the #[ignore] real-tea tests in tests/cli.rs are the contract check).

Recipes

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

use std::path::Path;
use vcs_gitea::{Gitea, GiteaApi};
let tea = Gitea::new();
let repo = Path::new(".");
let authed = tea.auth_status().await?;             // any login configured?
for pr in tea.pr_list(repo).await? {               // up to 100 open PRs
    println!("#{} [{}] {}", pr.number, pr.state, pr.title);
}

Drive the PR lifecycle — pr_create takes the PrCreate spec; merge picks a MergeStrategy:

use std::path::Path;
use vcs_gitea::{Gitea, GiteaApi, MergeStrategy, PrCreate};
tea.pr_create(repo, PrCreate::new("Add streaming", "Implements …")
        .head("feat/streaming").base("main")).await?;
tea.pr_merge(repo, 7, MergeStrategy::Squash).await?;

Testing

Two seams: enable the mock feature for a mockall-generated MockGiteaApi (stub whole methods), or inject a ScriptedRunner with Gitea::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_MockGiteaApi

__mock_MockGiteaApi_GiteaApi

guide

vcs-gitea — Gitea CLI guide

Structs

CancellationTokencancellation

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

Gitea

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

GiteaAt

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

Issue

An issue (tea issues list --output json / tea issues <index> --output json). The two tea paths differ — the list is a string-table row, the detail view a typed object — but both flatten into this struct.

MockGiteaApi

The Gitea operations this crate exposes — the interface consumers code against and mock in tests. The lean PR lifecycle tea supports; reach unmodelled tea commands through run.

PrCreate

Options for GiteaApi::pr_create (tea pr create).

ProcessResult

The captured result of running a process to completion.

PullRequest

A pull request (tea pr list --output json), flattened from tea’s table columns (index/title/state/head/base/url).

Release

A release (tea releases list --output json), flattened from tea’s fixed release-table columns. tea releases exposes no web-page URL (only a combined tar/zip download URL, which we deliberately don’t surface), so url is always empty for Gitea — see the field doc.

Enums

Error

Errors produced when launching or running a child process.

MergeStrategy

How GiteaApi::pr_merge merges the PR — maps to tea pr merge --style (Gitea’s default is a merge commit).

Constants

BINARY

Name of the underlying CLI binary this crate drives.

Traits

GiteaApi

The Gitea operations this crate exposes — the interface consumers code against and mock in tests. The lean PR lifecycle tea supports; reach unmodelled tea commands through run.

Type Aliases

Result

Crate result alias.