octocrab

The HTTP API is a lower-level interface used to extend Octocrab when the Semantic API does not yet support a specific GitHub feature.

There are two types of HTTP methods:

1. Standard methods (get, post, patch, put, delete): These accept a relative route and an optional body. They automatically format the URL with the base URL and return an error if GitHub does not return a successful status.
2. Companion methods (_get, _post, etc.): These perform no additional pre or post-processing, allowing you to manually inspect response status or headers.

Octocrab provides a statically reference-counted version of its API. This allows you to access the client globally without passing the instance through your entire application.

• octocrab::initialise(builder): Sets up the global instance with specific configuration.
• octocrab::instance(): Retrieves the global instance. If initialise hasn't been called, it returns a default 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();

The Semantic API provides a high-level, strongly typed interface for interacting with GitHub. It uses a set of models that map directly to GitHub's types and provides specialized handlers for different GitHub features.

Many methods that require multiple optional parameters use the Builder pattern, allowing you to chain configuration methods before calling .send().await.

To use Octocrab in your Rust project, add it via cargo:

cargo add octocrab

Use the current() handler to access data related to the authenticated user or the authenticated GitHub App. Note that all methods in this handler require authentication (e.g., a personal access token).

// Example: Fetching the current user
let user = octocrab
    .current()
    .user()
    .await?;

// Example: Fetching the currently authenticated app
let app = octocrab
    .current()
    .app()
    .await?;

The RepoSecretsHandler (accessed via .repos(owner, repo).secrets()) provides an interface to manage GitHub Actions repository secrets.

Important Security Note: To create or update secrets, you must first retrieve the repository's public key using get_public_key() and encrypt your secret value (e.g., using the crypto_box crate) before sending it to GitHub.

Permissions Required:

• Most operations require an access token with the repo scope or a GitHub App with secrets repository permissions.
• delete_secret requires admin:org scope or secrets organization permissions.
• get_public_key is public for open repositories but requires repo scope for private ones.

The NotificationsHandler provides methods to interact with GitHub's notifications API. All methods require an authenticated Octocrab instance with appropriate GitHub Access Token privileges. You can access this handler via octocrab.activity().notifications().

Key capabilities include:

• Retrieving specific notifications.
• Marking notifications as read (individually, per repository, or globally).
• Managing thread subscriptions (checking, setting, or deleting/muting).
• Listing notifications using a builder pattern for filtering.

let notifications = octocrab::instance()
    .activity()
    .notifications();

The IssueHandler provides a high-level API for interacting with GitHub's Issues. It allows you to create, list, update, and retrieve individual issues.

Note on Pull Requests: GitHub's REST API v3 treats every pull request as an issue. Consequently, endpoints for 'Issues' may return both issues and pull requests. You can distinguish them by checking for the presence of the pull_request key in the response object.

let issue = octocrab.issues("owner", "repo").get(3).await?;