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 iids:

  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. Use GitLab::new_insecure() to use http (or port() and sheme() setters on GitLab 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.