octocrab 0.54.3

A modern, extensible GitHub API client.
Documentation

Octocrab: A modern, extensible GitHub API client.

Rust crates.io Help Wanted Documentation Crates.io

Octocrab is a third party GitHub API client, allowing you to easily build your own GitHub integrations or bots in Rust. Octocrab comes with two primary sets of APIs for communicating with GitHub, a high level strongly typed semantic API, and a lower level HTTP API for extending behaviour.

Adding Octocrab

Run this command in your terminal to add the latest version of Octocrab.

cargo add octocrab

Semantic API

The semantic API provides strong typing around GitHub's API, a set of models that maps to GitHub's types, and auth functions that are useful for GitHub apps. Currently, the following modules are available as of version 0.54.

Getting a Pull Request

// Get pull request #5 from `XAMPPRocky/octocrab`.
let issue = octocrab::instance().pulls("XAMPPRocky", "octocrab").get(5).await?;

All methods with multiple optional parameters are built as Builder structs, allowing you to easily specify parameters.

Listing issues

let octocrab = octocrab::instance();
// Returns the first page of all issues.
let mut page = octocrab
    .issues("XAMPPRocky", "octocrab")
    .list()
    // Optional Parameters
    .creator("XAMPPRocky")
    .state(params::State::All)
    .per_page(50)
    .send()
    .await?;

// Go through every page of issues. Warning: There's no rate limiting so
// be careful.
loop {
    for issue in &page {
        println!("{}", issue.title);
    }
    page = match octocrab
        .get_page::<models::issues::Issue>(&page.next)
        .await?
    {
        Some(next_page) => next_page,
        None => break,
    }
}

HTTP API

The typed API currently doesn't cover all of GitHub's API at this time, and even if it did GitHub is in active development and this library will likely always be somewhat behind GitHub at some points in time. However that shouldn't mean that in order to use those features, you have to fork or replace octocrab with your own solution.

Instead octocrab exposes a suite of HTTP methods allowing you to easily extend Octocrab's existing behaviour. Using these HTTP methods allows you to keep using the same authentication and configuration, while having control over the request and response. There is a method for each HTTP method, get, post, patch, put, delete, all of which accept a relative route and a optional body.

let user: octocrab::models::User = octocrab::instance()
    .get("/user", None::<&()>)
    .await?;

Each of the HTTP methods expects a body, formats the URL with the base URL, and errors if GitHub doesn't return a successful status, but this isn't always desired when working with GitHub's API, sometimes you need to check the response status or headers. As such there are companion methods _get, _post, etc. that perform no additional pre or post-processing to the request.

let octocrab = octocrab::instance();
let response = octocrab
    ._get("https://api.github.com/organizations")
    .await?;

// You can also use `Uri::builder().authority("<my custom base>").path_and_query("<my custom path>")` if you want to customize the base uri and path.
let response =  octocrab
    ._get(Uri::builder().path_and_query("/organizations").build().expect("valid uri"))
    .await?;

You can use the those HTTP methods to easily create your own extensions to Octocrab's typed API.

use octocrab::{Octocrab, Page, Result, models};

trait OrganisationExt {
  async fn list_every_organisation(&self) -> Result<Page<models::Organization>>;
}

impl OrganisationExt for Octocrab {
  async fn list_every_organisation(&self) -> Result<Page<models::Organization>> {
    self.get("/organizations", None::<&()>).await
  }
}

You can also easily access new properties that aren't available in the current models using serde.

#[derive(Deserialize)]
struct RepositoryWithVisibility {
    #[serde(flatten)]
    inner: octocrab::models::Repository,
    visibility: String,
}

let my_repo = octocrab::instance()
    .get::<RepositoryWithVisibility>("https://api.github.com/repos/XAMPPRocky/octocrab", None::<&()>)
    .await?;

Static API

Octocrab also provides a statically reference counted version of its API, allowing you to easily plug it into existing systems without worrying about having to integrate and pass around the client.

// Initialises the static instance with your configuration and returns an
// instance of the client.
octocrab::initialise(octocrab::Octocrab::builder());
// Gets a instance of `Octocrab` from the static API. If you call this
// without first calling `octocrab::initialise` a default client will be
// initialised and returned instead.
let octocrab = octocrab::instance();

GitHub Webhook Support

octocrab provides deserializable datatypes for the payloads received by a GitHub application responding to webhooks. This allows you to write a typesafe application using Rust with pattern-matching/enum-dispatch to respond to events.

Note: Webhook support in octocrab is still beta, not all known webhook events are strongly typed.

use http::request::Request;
use tracing::{warn, info};
use octocrab::models::webhook_events::*;

let request_from_github = Request::post("https://my-webhook-url.com").body(vec![0_u8]).unwrap();
// request_from_github is the HTTP request your webhook handler received
let (parts, body) = request_from_github.into_parts();
let header = parts.headers.get("X-GitHub-Event").unwrap().to_str().unwrap();

let event = WebhookEvent::try_from_header_and_body(header, &body).unwrap();
// Now you can match on event type and call any specific handling logic
match event.kind {
    WebhookEventType::Ping => info!("Received a ping"),
    WebhookEventType::PullRequest => info!("Received a pull request event"),
    // ...
    _ => warn!("Ignored event"),
};

Feature Flags

Octocrab provides configurable feature flags to adapt to different runtime environments and cryptographic requirements:

Cryptographic & JWT Backends

Octocrab supports authenticating as a GitHub App via JWT (using the jwt feature, included in default):

  • jwt-aws-lc-rs (default): Enables JWT support and uses AWS-LC (aws-lc-rs) for JWT cryptography. Recommended for most environments and prevents RUSTSEC-2023-0071 (Marvin Attack timing advisory in rsa 0.9.x).
  • jwt-rust-crypto: Enables JWT support and uses pure Rust cryptography (RustCrypto). Useful for targets without C compiler toolchains or for wasm32-unknown-unknown. Note: Pulls in rsa 0.9.x which triggers RUSTSEC-2023-0071.
  • Minimal builds without JWT: If your application only uses personal access tokens, OAuth, or unauthenticated requests, you can disable default features and omit JWT support entirely to eliminate all JWT/crypto dependencies and minimize build times: 
    [dependencies]
octocrab = { version = "...", default-features = false, features = ["default-client", "rustls", "rustls-ring"] }

TLS Providers

  • rustls-ring (default): Uses rustls with the ring cryptography provider.
  • rustls-aws-lc-rs: Uses rustls with AWS-LC.
  • opentls: Uses native system TLS via OpenSSL / Security-Framework / SChannel.