gitlab-api-rs
Rust wrapper to the GitLab API.
NOTE: Requires Rust 1.15 (stable) since this crate is using custom derive for Serde.
Synopsis
GitLab is an amazing tool. For most of the tasks, the web UI is more than enough but for some tasks nothing beats scripting them. The GitLab API is there to allow scripting actions on the GitLab server.
The excellent python-gitlab allows to use the API from Python, but when playing with it I find myself missing Rust's static typing. Hence this implementation in Rust.
The (v3) API is quite long, so the parts I need will be implemented first.
What Works
- Read-only listing:
- Groups;
- Issues;
- Merge Requests;
- Projects (admin all, user's, specific id, owned, search);
What Doesn't Work
-
Any write commands (
POST
,PUT
, etc.) -
Any Enterprise Edition-specific features.
-
API elements using arrays.
For example listing merge requests, filtering with multiple
iid
s:GET /projects/:id/merge_requests?iid[]=42&iid[]=43
-
Some projects listing:
- branch;
- branches;
- events;
- hook;
- hooks;
- starred;
- visible;
Usage
[dependencies]
gitlab-api = "0.6"
This crate uses a builder pattern to add filters to a query. Once the query is built, list()
will commit it by contacting the GitLab server and performing the request.
extern crate gitlab_api as gitlab;
fn main() {
let gl = gitlab::GitLab::new(&"gitlab.com", &"GITLAB_TOKEN_XXXXXXX").unwrap();
// Get GitLab's version.
let gitlab_version = gl.version().unwrap();
println!("gitlab_version: {:?}", gitlab_version);
// Low level methods
// Get projects, owned by authenticated user and which are archived.
let projects = gl.projects().owned().archived(true).list().unwrap();
println!("projects: {:?}", projects);
// Get groups owned by authenticated user.
let owned_groups = gl.groups().owned().list().unwrap();
println!("owned_groups: {:?}", owned_groups);
// Get closed issues.
let closed_issues = gl.issues().state(gitlab::issues::State::Closed).list().unwrap();
println!("closed_issues: {:?}", closed_issues);
// Higher level methods
// Get a specific project
let project = gl.get_project("nbigaouette1", "gitlab-api-rs").chain_err(|| "cannot get project")?;
// Get a specific issue
let issue = gl.get_issue("nbigaouette1", "gitlab-api-rs", 1).chain_err(|| "cannot get issue")?;
// Get a specific merge request
let merge_request = gl.get_merge_request("nbigaouette1", "gitlab-api-rs", 1).chain_err(|| "cannot get merge_request")?;
}
NOTES:
- Crate uses
https
by default. UseGitLab::new_insecure()
to usehttp
(orport()
andsheme()
setters onGitLab
struct). - Sending your token in clear over
http
is dangerous! - See [examples/list_projects.rs] for an example of how to load the token (and the hostname) from an environment variable.
- See the
examples
directory for many more examples on how to use this crate.
Dependencies
Thanks cargo-graph
for the graph!
Licensing
gitlab-api-rs is distributed under the terms of both the MIT license and the Apache License (Version 2.0).
See LICENSE-APACHE and LICENSE-MIT for details.