Octocrab

https://github.com/xampprocky/octocrab
Admin
Octocrab is a modern, extensible third-party GitHub API client written in Rust, designed for...
Tokens:67,491
Snippets:572
Trust Score:9.4
Update:3 months ago
Show doc for...
Tokens:
Raw
### GitHub App Installation Token Management

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/QUICK-REFERENCE.md

Demonstrates how to obtain an Octocrab client for a specific GitHub App installation and how to refresh its installation token with a buffer.

```rust
// From app client
let installation = app_octocrab.installation(InstallationId(123))?;
```

```rust
// Get and cache token
let (crab, token) = app_octocrab
    .installation_and_token(InstallationId(123))
    .await?;
```

```rust
// Refresh token with buffer
let token = crab
    .installation_token_with_buffer(
        chrono::Duration::minutes(5)
    )
    .await?;
```

--------------------------------

### Webhooks and Code Examples

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/README.md

Guide to handling webhooks, including deserialization and signature validation, along with comprehensive code examples for various Octocrab operations.

```APIDOC
## Webhooks and Code Examples

### Description
This section provides guidance on working with webhooks and offers a collection of code examples for common Octocrab operations. It covers webhook event deserialization, lists all supported webhook event types, and explains webhook signature validation. The code examples demonstrate various functionalities, including authentication and initialization, repository information retrieval, issue and PR creation/listing/merging, file management, search operations, GraphQL queries, rate limit checking, error handling with retry mechanisms, web framework integration (e.g., Axum), and webhook handler implementation.

### API Surface
- Webhook event deserialization
- All supported webhook event types
- Webhook signature validation
- Complete code examples:
  - Authentication and initialization
  - Repository information retrieval
  - Issue creation and listing
  - PR creation and merging
  - File management
  - Search operations
  - GraphQL queries
  - Rate limit checking
  - Error handling with retry
  - Web framework integration (Axum)
  - Webhook handlers
```

--------------------------------

### Authenticate as GitHub App Installation

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/07-authentication-configuration.md

After authenticating as a GitHub App, create a client for a specific installation using its Installation ID. This client uses an installation access token.

```rust
// First, authenticate as app
let app_octocrab = Octocrab::builder()
    .app(AppId(12345), key)
    .build()?;

// Get installation ID (from webhook or list installations)
let installation_id = InstallationId(98765);

// Create new client for this installation
let installation_octocrab = app_octocrab.installation(installation_id)?;

// Now all requests use installation access token (1 hour expiry)
let repo = installation_octocrab.repos("owner", "repo").get().await?;
```

--------------------------------

### Repository ID Example Usage

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/05-types.md

Demonstrates how to use the common methods on a RepositoryId, such as converting to its inner u64 value or getting a reference to it.

```rust
let repo_id = RepositoryId(12345);
let inner: u64 = repo_id.into_inner();
let id_ref = repo_id.as_ref();
```

--------------------------------

### Search Repositories Example

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/06-additional-apis.md

Search for repositories based on a query, sort by stars in descending order, and set the number of results per page. This example demonstrates chaining builder methods.

```rust
let results = octocrab.search()
    .repos("language:rust stars:>1000")
    .sort("stars")
    .order("desc")
    .per_page(30)
    .send()
    .await?;
```

--------------------------------

### Get GitHub App Installation Token with Caching

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/07-authentication-configuration.md

Retrieve the installation token for a GitHub App, which can be cached and used for HTTPS git operations. The token is exposed securely.

```rust
// Get and cache installation token with buffer
let (crab, token) = app_octocrab
    .installation_and_token(installation_id)
    .await?;

// Token can be used for HTTPS git operations
println!("Token for git: {}", token.expose_secret());
```

--------------------------------

### Get Repository License

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/QUICK-REFERENCE.md

Fetch the license information for a repository.

```Rust
octocrab.repos("owner", "repo").license().await?;
```

--------------------------------

### Customize GitHub App Installation Token Refresh Buffer

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/07-authentication-configuration.md

Configure a custom buffer duration for refreshing the installation token. The default buffer is 30 seconds.

```rust
// Default buffer: 30 seconds
let token = crab.installation_token().await?;

// Custom buffer: refresh if expiring in < 5 minutes
use chrono::Duration;
let token = crab
    .installation_token_with_buffer(Duration::minutes(5))
    .await?;
```

--------------------------------

### Pagination Builder Example

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/09-parameters-builders.md

Demonstrates how to use `per_page` and `page` methods to control pagination when listing items. Shows fetching a specific page and how to retrieve the next page.

```rust
let page = octocrab.issues("owner", "repo")
    .list()
    .per_page(100)  // Fetch maximum items
    .page(1)        // First page
    .send()
    .await?;

// Get next page via page.next URL
let next_page = octocrab
    .get_page::<Issue>(&page.next)
    .await?;
```

--------------------------------

### Perform GraphQL Queries

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/08-webhooks-examples.md

An example demonstrating how to perform GraphQL queries against the GitHub API. Note that using the `graphql_client` crate is recommended for more complex queries.

```rust
use serde::{Deserialize, Serialize};

#[derive(Serialize)]
struct MyQuery {
    query: String,
}

#[derive(Deserialize)]
struct QueryResponse {
    data: QueryData,
}

#[derive(Deserialize)]
struct QueryData {
    repository: RepositoryData,
}

#[derive(Deserialize)]
struct RepositoryData {
    name: String,
    description: Option<String>,
    stargazers: StargazerConnection,
}

#[derive(Deserialize)]
struct StargazerConnection {
    #[serde(rename = "totalCount")]
    total_count: i32,
}

async fn graphql_example(
    octocrab: &octocrab::Octocrab,
) -> Result<()> {
    // Using graphql_client crate would be better
    // This is a minimal example
    
    let query = r#" 
        query {
            repository(owner: "rust-lang", name: "rust") {
                name
                description
                stargazers {
                    totalCount
                }
            }
        } 
    "#;
    
    // Octocrab::graphql() expects graphql_client::GraphQLQuery
    // This is simplified for demonstration
    
    Ok(())
}
```

--------------------------------

### GraphQL Query Example

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/README.md

Executes a GraphQL query against the GitHub API. Use for complex data retrieval.

```rust
use octocrab::Octocrab;

#[tokio::main]
async fn main() -> octocrab::Result<()> {
    let github = Octocrab::default().await?;

    let query = r#"{
        viewer { 
            login
        }
    }"#;

    let response: serde_json::Value = github.graphql(query).await?;

    println!("GraphQL response: {}", response);

    Ok(())
}

```

--------------------------------

### Check and Star Repository Activity

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/06-additional-apis.md

Examples demonstrating how to check if a user has starred a repository and how to star a repository using the Activity API.

```rust
// Check if user starred a repo
let is_starred = octocrab.activity().check_starred("owner", "repo").await?;

// Star a repo
octocrab.activity().star("owner", "repo").await?;
```

--------------------------------

### Low-Level HTTP GET Request

Source: https://github.com/xampprocky/octocrab/blob/main/README.md

Demonstrates using the `_get` method for a raw HTTP GET request, bypassing Octocrab's pre/post-processing.

```APIDOC
```rust
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?;
```
```

--------------------------------

### File Operations

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/QUICK-REFERENCE.md

Examples of how to perform common file operations on GitHub repositories using OctoCRAB.

```APIDOC
## Create File

### Description
Creates a new file in a specified repository.

### Method
`repos.create_file`

### Parameters
- `owner` (string): The owner of the repository.
- `repo` (string): The name of the repository.
- `path` (string): The path to the file within the repository.
- `message` (string): The commit message.
- `content` (bytes): The content of the file.
- `author` (CommitAuthor): The author of the commit.
- `committer` (CommitAuthor): The committer of the commit.

### Request Example
```rust
octocrab.repos("owner", "repo")
    .create_file("path.txt", "commit msg", b"content")
    .author(CommitAuthor { name: "", email: "", date: "" })
    .commiter(CommitAuthor { name: "", email: "", date: "" })
    .send().await?;
```
```

```APIDOC
## Update File

### Description
Updates an existing file in a specified repository. Requires the SHA of the file to be updated.

### Method
`repos.update_file`

### Parameters
- `owner` (string): The owner of the repository.
- `repo` (string): The name of the repository.
- `path` (string): The path to the file within the repository.
- `message` (string): The commit message.
- `content` (bytes): The new content of the file.
- `sha` (string): The SHA of the file to update.
- `branch` (string, optional): The branch to commit to. Defaults to the repository's default branch.

### Request Example
```rust
octocrab.repos("owner", "repo")
    .update_file("path.txt", "msg", b"new content", sha)
    .branch("main")
    .send().await?;
```
```

```APIDOC
## Delete File

### Description
Deletes a file from a specified repository. Requires the SHA of the file to be deleted.

### Method
`repos.delete_file`

### Parameters
- `owner` (string): The owner of the repository.
- `repo` (string): The name of the repository.
- `path` (string): The path to the file within the repository.
- `message` (string): The commit message.
- `sha` (string): The SHA of the file to delete.

### Request Example
```rust
octocrab.repos("owner", "repo")
    .delete_file("path.txt", "msg", sha)
    .send().await?;
```
```

```APIDOC
## Get File Content

### Description
Retrieves the content of a file from a specified repository.

### Method
`repos.get_content`

### Parameters
- `owner` (string): The owner of the repository.
- `repo` (string): The name of the repository.
- `path` (string): The path to the file within the repository.
- `ref` (string, optional): The name of the commit/branch/tag. Defaults to the repository’s default reference.

### Request Example
```rust
octocrab.repos("owner", "repo")
    .get_content()
    .path("path.txt")
    .r#ref("main")
    .send().await?;
```
```

--------------------------------

### Initialize Octocrab with Personal Token and Custom Timeout

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/01-octocrab-client.md

Example of building an Octocrab client using a personal access token, enabling a preview feature, and setting a connection timeout. Requires the `personal_token` and `timeout` features.

```rust
use octocrab::Octocrab;

let octocrab = Octocrab::builder()
    .personal_token(secrecy::SecretString::new("ghp_xxxxx".to_string()))
    .add_preview("machine-man")
    .set_connect_timeout(std::time::Duration::from_secs(30))
    .build()?;
```

--------------------------------

### Handling GitHub App Authentication Errors

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/04-errors.md

Demonstrates checking for and handling the specific `Installation` error variant when an operation requires GitHub App authentication.

```rust
let result = octocrab.installation(InstallationId(12345));
if let Err(octocrab::Error::Installation { .. }) = result {
    eprintln!("Must authenticate as GitHub App first");
}
```

--------------------------------

### Minimal Octocrab Example with Personal Token

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/00-index.md

This snippet shows the most basic way to create an Octocrab client using a personal access token and perform common operations like fetching a repository and listing issues.

```rust
use octocrab::Octocrab;
use secrecy::SecretString;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client
    let octocrab = Octocrab::builder()
        .personal_token(SecretString::new(
            std::env::var("GITHUB_TOKEN")?
        ))
        .build()?;
    
    // Get repository
    let repo = octocrab.repos("XAMPPRocky", "octocrab").get().await?;
    println!("Repository: {}", repo.full_name);
    println!("Stars: {}", repo.stargazers_count);
    
    // List issues
    let issues = octocrab
        .issues("XAMPPRocky", "octocrab")
        .list()
        .send()
        .await?;
    
    for issue in issues {
        println!("#{}: {}", issue.number, issue.title);
    }
    
    Ok(())
}
```

--------------------------------

### Create Release

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/02-repositories-api.md

Initiates the creation of a new release, starting with a tag name.

```APIDOC
## create()

### Description
Create a new release.

### Method
`create(tag_name: impl Into<String>)`

### Parameters
#### Path Parameters
- **tag_name** (String) - Required - The tag name for the new release.
```

--------------------------------

### Octocrab Static Instance Initialization and Usage

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/00-index.md

This example demonstrates how to initialize a static Octocrab instance for global access and then use it within an asynchronous function to fetch user information.

```rust
fn main() {
    octocrab::initialise(
        octocrab::Octocrab::builder()
            .personal_token(secrecy::SecretString::new(
                std::env::var("GITHUB_TOKEN").unwrap()
            ))
            .build()
            .unwrap()
    );
}

#[tokio::main]
async fn handle_request() {
    let octocrab = octocrab::instance();
    let user = octocrab.current().user().await.unwrap();
    println!("Hello, {}", user.login);
}
```

--------------------------------

### Authentication and Configuration

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/README.md

Guide to authentication methods (PAT, GitHub App, User tokens) and various configuration options for Octocrab, including timeouts, retries, and custom headers.

```APIDOC
## Authentication and Configuration

### Description
This section details the authentication mechanisms and configuration options available for Octocrab. It covers various authentication methods including Personal Access Tokens (PAT), GitHub App authentication (JWT and installations), User Access Tokens, and Basic authentication. It also addresses unauthenticated access, timeout and retry configurations, TLS/SSL options, enabling preview APIs, setting custom headers, rate limiting behavior, environment variable usage, and security best practices.

### API Surface
- Personal access token authentication
- GitHub App authentication (JWT + installations)
- User access tokens
- Basic authentication
- Unauthenticated access
- Timeout configuration
- Retry configuration
- TLS/SSL options
- Preview API enabling
- Custom headers
- Rate limiting
- Environment variable patterns
- Security best practices
```

--------------------------------

### Initialize Pull Requests Handler

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/03-issues-pulls-api.md

Get a handler for managing pull requests for a specific repository.

```rust
let handler = octocrab.pulls("owner", "repo");
```

--------------------------------

### Releases Handler Methods

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/02-repositories-api.md

Interact with the releases sub-API to get, create, update, delete, and list releases.

```rust
pub struct ReleasesHandler { ... }

impl ReleasesHandler {
    pub async fn get_latest(&self) -> Result<Release>
    pub async fn get_by_tag(&self, tag: impl AsRef<str>) -> Result<Release>
    pub async fn get(&self, id: impl Into<ReleaseId>) -> Result<Release>
    pub fn create(&self, tag_name: impl Into<String>) -> CreateReleaseBuilder
    pub fn update(&self, id: impl Into<ReleaseId>) -> UpdateReleaseBuilder
    pub async fn delete(&self, id: impl Into<ReleaseId>) -> Result<()>
    pub fn list() -> ListReleasesBuilder
}
```

--------------------------------

### Initialize and Get Static Octocrab Instance

Source: https://github.com/xampprocky/octocrab/blob/main/README.md

Initializes the static Octocrab instance with a builder configuration and retrieves it for use. If not initialized, a default client is created upon first access.

```rust
// 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();
```

--------------------------------

### format_preview

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/01-octocrab-client.md

Formats a preview name into the appropriate `Accept` header value for GitHub API previews. For example, `machine-man` is converted to `application/vnd.github.machine-man-preview`.

```APIDOC
## format_preview

### Description
Formats a preview name into the `Accept` header value.

### Signature
`pub fn format_preview(preview: impl AsRef<str>) -> String`
```

--------------------------------

### Handle Push Webhook Event

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/08-webhooks-examples.md

Example handler for processing `Push` events. It demonstrates accessing push-specific payload details like the ref, commit count, and individual commit messages.

```rust
use octocrab::models::webhook_events::{WebhookEvent, WebhookEventType};
use std::str;

async fn handle_webhook(
    headers: &http::HeaderMap,
    body: &[u8],
) -> Result<String> {
    // Get event type from header
    let event_type = headers
        .get("X-GitHub-Event")
        .and_then(|v| v.to_str().ok())
        .unwrap_or("unknown");
    
    // Parse webhook event
    let event = WebhookEvent::try_from_header_and_body(event_type, body)?;
    
    match event.kind {
        WebhookEventType::Push => {
            // Access push payload
            if let Some(push_payload) = event.payload.as_push() {
                println!("Pushed to {}", push_payload.r#ref);
                println!("Commits: {}", push_payload.size);
                
                for commit in &push_payload.commits {
                    println!("  - {}: {}", commit.id, commit.message);
                }
            }
            Ok("Push processed".to_string())
        }
        WebhookEventType::PullRequest => {
            if let Some(pr_payload) = event.payload.as_pull_request() {
                println!("PR #{}: {}", pr_payload.number, pr_payload.title);
                println!("Action: {}", event.action.unwrap_or_default());
            }
            Ok("PR processed".to_string())
        }
        _ => Ok("Event ignored".to_string()),
    }
}
```

--------------------------------

### Get Repository Information

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/08-webhooks-examples.md

Fetches and prints details about a specific GitHub repository, including its full name, star count, fork count, primary language, and creation date.

```rust
use octocrab::Octocrab;

async fn get_repo_info(
    octocrab: &Octocrab,
    owner: &str,
    repo: &str,
) -> Result<()> {
    let repo = octocrab.repos(owner, repo).get().await?;
    
    println!("Repository: {}", repo.full_name);
    println!("Stars: {}", repo.stargazers_count);
    println!("Forks: {}", repo.forks_count);
    println!("Language: {}", repo.language.unwrap_or_else(|| "None".to_string()));
    println!("Created: {}", repo.created_at);
    
    Ok(())
}
```

--------------------------------

### Octocrab Client Initialization with Token

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/README.md

Shows how to initialize the Octocrab client using a personal access token. Essential for authenticated requests.

```rust
use octocrab::Octocrab;

#[tokio::main]
async fn main() -> octocrab::Result<()> {
    let github = Octocrab::builder()
        .personal_access_token("YOUR_TOKEN".to_string())
        .build()
        .await?;

    // Use the github client...

    Ok(())
}

```

--------------------------------

### Initializing and Using Static Octocrab Instance

Source: https://github.com/xampprocky/octocrab/blob/main/README.md

Shows how to initialize and retrieve a statically managed Octocrab client instance.

```APIDOC
## Static API

```rust
// 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();
```
```

--------------------------------

### Direct HTTP GET Request

Source: https://github.com/xampprocky/octocrab/blob/main/README.md

Shows how to make a direct GET request to the GitHub API using Octocrab's `get` method.

```APIDOC
## HTTP API

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

--------------------------------

### GET Request with Headers

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/01-octocrab-client.md

Performs a GET request and returns both the deserialized response body and the response headers.

```APIDOC
## GET Request with Headers

### Description
Performs a GET request, returning both the deserialized response body and the response headers.

### Method
GET

### Endpoint
`/route` (or a full `Uri`)

### Parameters
#### Path Parameters
None explicitly defined, but `route` can be a full URI.

#### Query Parameters
- **parameters** (`Option<&P>`) - Optional - Query parameters to be serialized as URL encoding.

#### Request Body
Not applicable for GET requests.

### Response
#### Success Response (200)
- **(R, HeaderMap)** (`Result<(R, HeaderMap)>`) - A tuple containing the deserialized response body and the `HeaderMap`.

### Request Example
```rust
// Example usage (assuming client is an instance of Octocrab)
let (user_data, headers): (User, HeaderMap) = client.get_with_headers("/user", None).await?;
```

### Response Example
```json
{
  "example": "Deserialized response data",
  "headers": {
    "content-type": "application/json"
  }
}
```
```

--------------------------------

### Octocrab Client Initialization

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/README.md

Demonstrates basic initialization of the Octocrab client. Use this for standard API interactions.

```rust
use octocrab::Octocrab;

#[tokio::main]
async fn main() -> octocrab::Result<()> {
    let github = Octocrab::default().await?;

    // Use the github client...

    Ok(())
}

```

--------------------------------

### Get Repository README

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/02-repositories-api.md

Build a request to get the README file for a repository. This is a convenience method for retrieving the default README.

```APIDOC
## GET /repos/{owner}/{repo}/readme

### Description
Retrieves the README file for the repository.

### Method
GET

### Endpoint
`/repos/{owner}/{repo}/readme`

### Parameters
#### Query Parameters
- **ref** (string) - Optional - The name of the commit/branch or tag. Default: the repository’s default branch.

### Request Example
```rust
let readme = octocrab.repos("owner", "repo")
    .get_readme()
    .send()
    .await?;
```

### Response
#### Success Response (200)
- **content** (string) - Content of the README file.
- **encoding** (string) - Encoding of the README content.
- **name** (string) - Name of the README file.
- **path** (string) - Path of the README file.
- **sha** (string) - SHA of the README file.
- **size** (integer) - Size of the README file in bytes.
- **url** (string) - URL to the README content.
- **html_url** (string) - URL to the HTML view of the README.
- **git_url** (string) - URL to the git object.
- **download_url** (string) - URL to download the raw README content.
- **_links** (object) - Links related to the README.
```

--------------------------------

### Octocrab Initialization

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/01-octocrab-client.md

Demonstrates how to create a new Octocrab client instance using the builder pattern with personal access token authentication and custom timeouts.

```APIDOC
## Octocrab Initialization Example

### Description
This example shows how to build an `Octocrab` client using its builder. It configures authentication with a personal access token and sets a custom connection timeout.

### Method
`Octocrab::builder()` followed by builder methods and `build()`

### Parameters
- `personal_token(token: SecretString)`: Sets the personal access token for authentication.
- `set_connect_timeout(timeout: Option<Duration>)`: Sets the TCP connection timeout.

### Request Example
```rust
use octocrab::Octocrab;

let octocrab = Octocrab::builder()
    .personal_token(secrecy::SecretString::new("ghp_xxxxx".to_string()))
    .add_preview("machine-man")
    .set_connect_timeout(std::time::Duration::from_secs(30))
    .build()?;
```

### Response
- `Result<Octocrab, Infallible>`: Returns the configured `Octocrab` instance on success.
```

--------------------------------

### Raw GET Request

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/01-octocrab-client.md

Performs a GET request and returns the raw `Response` object without automatic error mapping or deserialization.

```APIDOC
## Raw GET Request

### Description
Performs a GET request and returns the raw `Response` object, allowing for manual processing of the response and headers.

### Method
GET

### Endpoint
`uri` (must be convertible to `Uri`)

### Parameters
#### Path Parameters
None.

#### Query Parameters
None explicitly defined for this raw method.

#### Request Body
Not applicable for GET requests.

### Response
#### Success Response (200)
- **Response** (`Result<Response>`) - The raw HTTP response.

### Request Example
```rust
// Example usage (assuming client is an instance of Octocrab)
let raw_response: Response = client._get(uri).await?;
```

### Response Example
```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "Raw response content"
}
```
```

--------------------------------

### Get File Content

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/02-repositories-api.md

Build a request to get the content of a file or directory within a repository. You can specify the path and a reference (branch or tag).

```APIDOC
## GET /repos/{owner}/{repo}/contents/{path}

### Description
Retrieves the content of a file or directory.

### Method
GET

### Endpoint
`/repos/{owner}/{repo}/contents/{path}`

### Parameters
#### Query Parameters
- **ref** (string) - Optional - The name of the commit/branch or tag. Default: the repository’s default branch.

### Request Example
```rust
let content = octocrab.repos("owner", "repo")
    .get_content()
    .path("path/to/file.txt")
    .r#ref("main")
    .send()
    .await?;
```

### Response
#### Success Response (200)
- **content** (array) - Array of file/directory contents if path is a directory, or file content if path is a file.
- **encoding** (string) - Encoding of the file content.
- **name** (string) - Name of the file or directory.
- **path** (string) - Path of the file or directory.
- **sha** (string) - SHA of the file or directory.
- **size** (integer) - Size of the file in bytes.
- **type** (string) - Type of the content (file or dir).
- **url** (string) - URL to the content.
- **html_url** (string) - URL to the HTML view of the content.
- **git_url** (string) - URL to the git object.
- **download_url** (string) - URL to download the raw file content.
- **_links** (object) - Links related to the content.
```

--------------------------------

### GET Request

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/01-octocrab-client.md

Performs a GET request. It can deserialize the response into a specified type `R` and handle errors, or accept optional query parameters.

```APIDOC
## GET Request

### Description
Performs a GET request with response deserialization and error handling. Supports optional query parameters.

### Method
GET

### Endpoint
`/route` (or a full `Uri`)

### Parameters
#### Path Parameters
None explicitly defined, but `route` can be a full URI.

#### Query Parameters
- **parameters** (`Option<&P>`) - Optional - Query parameters to be serialized as URL encoding.

#### Request Body
Not applicable for GET requests.

### Response
#### Success Response (200)
- **R** (`Result<R>`) - The deserialized response body if successful.

### Request Example
```rust
// Example usage (assuming client is an instance of Octocrab)
let user_data: User = client.get("/user", None).await?;
let repos: Vec<Repo> = client.get("/users/octocat/repos", Some(&query_params)).await?;
```

### Response Example
```json
{
  "example": "Deserialized response data"
}
```
```

--------------------------------

### Initialize OctoKit with Environment Variables

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/07-authentication-configuration.md

Configure OctoKit using environment variables for the GitHub token, and optionally for GitHub App ID and private key. This function returns a configured OctoKit instance.

```rust
use std::env;
use octocrab::Octocrab;
use secrecy::SecretString;

fn init_octocrab() -> octocrab::Result<Octocrab> {
    // GitHub Token
    let token = env::var("GITHUB_TOKEN")
        .expect("GITHUB_TOKEN env var required");
    
    // Optional: GitHub App
    let app_id = env::var("GITHUB_APP_ID").ok();
    let app_key = env::var("GITHUB_APP_KEY").ok();
    
    let mut builder = Octocrab::builder()
        .personal_token(SecretString::new(token));
    
    if let (Some(id), Some(key_pem)) = (app_id, app_key) {
        let app_id = id.parse::<u64>()?;
        let encoding_key = jsonwebtoken::EncodingKey::from_rsa_pem(key_pem.as_bytes())?;
        builder = builder.app(
            octocrab::models::AppId(app_id),
            encoding_key,
        );
    }
    
    builder.build()
}
```

--------------------------------

### Make Raw HTTP GET Request with Octocrab

Source: https://github.com/xampprocky/octocrab/blob/main/README.md

Performs a raw HTTP GET request to a specified GitHub API endpoint using the Octocrab client. Useful for accessing API features not yet covered by the typed API.

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

--------------------------------

### Get an Organization

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves information about a specific organization by its name.

```rust
// Get org
octocrab.orgs("org-name").get().await?;
```

--------------------------------

### Create a File

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/README.md

Creates a new file in a repository. Use for adding new files or configuration.

```rust
use octocrab::Octocrab;

#[tokio::main]
async fn main() -> octocrab::Result<()> {
    let github = Octocrab::default().await?;

    let new_file = github
        .repos("owner", "repo")
        .create_file("path/to/new_file.txt", "Initial commit message", "File content here.")
        .branch("main")
        .send()
        .await?;

    println!("File created: {}", new_file.content.path);

    Ok(())
}

```

--------------------------------

### Get a User

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves information about a specific user by username.

```rust
// Get user
octocrab.users("username").get().await?;
```

--------------------------------

### Get Latest Release

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/02-repositories-api.md

Retrieves the latest release of the repository.

```APIDOC
## get_latest()

### Description
Get the latest release.

### Method
`get_latest()`

### Returns
`Result<Release>`
```

--------------------------------

### Get Current User

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves information about the currently authenticated user.

```rust
// Get current user
octocrab.current().user().await?;
```

--------------------------------

### Update and Create Files in Repository

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/08-webhooks-examples.md

Demonstrates how to update an existing file and create a new file within a GitHub repository. Requires obtaining the file's SHA for updates.

```rust
use octocrab::models::repos::CommitAuthor;

async fn update_file(
    octocrab: &octocrab::Octocrab,
    owner: &str,
    repo: &str,
) -> Result<()> {
    // Get current file content to obtain SHA
    let content = octocrab
        .repos(owner, repo)
        .get_content()
        .path("README.md")
        .send()
        .await?;
    
    // Update the file
    octocrab
        .repos(owner, repo)
        .update_file(
            "README.md",
            "Update README with new instructions",
            b"# New README content\n",
            &content.sha,
        )
        .author(CommitAuthor {
            name: "Bot".to_string(),
            email: Some("bot@example.com".to_string()),
            date: None,
        })
        .commiter(CommitAuthor {
            name: "Bot".to_string(),
            email: Some("bot@example.com".to_string()),
            date: None,
        })
        .send()
        .await?;
    
    Ok(())
}

async fn create_file(
    octocrab: &octocrab::Octocrab,
    owner: &str,
    repo: &str,
) -> Result<()> {
    octocrab
        .repos(owner, repo)
        .create_file(
            "docs/guide.md",
            "Add installation guide",
            b"# Installation\n\nRun: cargo install mylib",
        )
        .branch("main")
        .author(CommitAuthor {
            name: "Bot".to_string(),
            email: Some("bot@example.com".to_string()),
            date: None,
        })
        .send()
        .await?;
    
    Ok(())
}
```

--------------------------------

### Get a Pull Request

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves a specific pull request by its number.

```rust
// Get PR
octocrab.pulls("owner", "repo").get(42).await?;
```

--------------------------------

### Get Release by ID

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/02-repositories-api.md

Retrieves a specific release by its unique ID.

```APIDOC
## get()

### Description
Get a release by its ID.

### Method
`get(id: impl Into<ReleaseId>)`

### Parameters
#### Path Parameters
- **id** (ReleaseId) - Required - The ID of the release to retrieve.
```

--------------------------------

### Initialize Octocrab with Default (No Auth)

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/QUICK-REFERENCE.md

Create a default Octocrab instance without any authentication.

```Rust
let octocrab = octocrab::Octocrab::default();
```

--------------------------------

### Initialize Octocrab Static Instance

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/QUICK-REFERENCE.md

Set up a static instance of Octocrab for global access.

```Rust
octocrab::initialise(octocrab);
let crab = octocrab::instance();
```

--------------------------------

### Get Release by Tag

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/02-repositories-api.md

Retrieves a specific release by its tag name.

```APIDOC
## get_by_tag()

### Description
Get a release by its tag.

### Method
`get_by_tag(tag: impl AsRef<str>)`

### Parameters
#### Path Parameters
- **tag** (string) - Required - The tag name of the release to retrieve.
```

--------------------------------

### Get Pull Request

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/03-issues-pulls-api.md

Retrieves a specific pull request by its number.

```APIDOC
## GET /repos/{owner}/{repo}/pulls/{pull_number}

### Description
Get a pull request by its number.

### Method
GET

### Endpoint
`/repos/{owner}/{repo}/pulls/{pull_number}`

### Parameters
#### Path Parameters
- **owner** (string) - Required - The owner of the repository.
- **repo** (string) - Required - The name of the repository.
- **pull_number** (u64) - Required - The number of the pull request.

### Response
#### Success Response (200)
- **PullRequest** - Details of the pull request.
```

--------------------------------

### Get a Specific Issue

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/03-issues-pulls-api.md

Retrieve a single issue from a repository by its number.

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

--------------------------------

### Create File in Repository

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/QUICK-REFERENCE.md

Create a new file in a repository with specified path, message, and content.

```Rust
octocrab.repos("owner", "repo")
    .create_file("path.txt", "message", b"content")
    .send().await?;
```

--------------------------------

### Get a Specific Commit

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/06-additional-apis.md

Retrieve a commit by its SHA. Ensure the SHA is correctly formatted.

```rust
let commit = octocrab.commits("owner", "repo")
    .get("abc123...")
    .await?;

println!("Author: {}", commit.commit.author.name);
```

--------------------------------

### Production Configuration with App Token

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/07-authentication-configuration.md

Set up OctoKit for production using an App ID and private key loaded from environment variables. Configures longer timeouts and retry logic for robustness.

```rust
let octocrab = Octocrab::builder()
    .app(
        octocrab::models::AppId(
            std::env::var("GITHUB_APP_ID")?.parse()? 
        ),
        jsonwebtoken::EncodingKey::from_rsa_pem(
            std::env::var("GITHUB_APP_PRIVATE_KEY")?.as_bytes()
        )?
    )
    .set_connect_timeout(Some(Duration::from_secs(10)))
    .set_read_timeout(Some(Duration::from_secs(30)))
    .add_retry_config(RetryConfig {
        max_retries: 5,
        ..Default::default()
    })
    .build()?;
```

--------------------------------

### Get Organization Details

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/06-additional-apis.md

Retrieve details for a specific organization. Requires an existing organization handler.

```rust
let org = octocrab.orgs("rust-lang").get().await?;
println!("Public repos: {}", org.public_repos);
```

--------------------------------

### Create File

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/02-repositories-api.md

Create a new file in the repository with a commit message. You can specify author and committer details. The content must be provided as a byte slice.

```rust
use octocrab::models::repos::CommitAuthor;

octocrab.repos("owner", "repo")
    .create_file(
        "docs/guide.md",
        "Add installation guide",
        b"# Installation\n\nRun: cargo install mylib",
    )
    .author(CommitAuthor {
        name: "Bot".to_string(),
        email: Some("bot@example.com".to_string()),
        date: None,
    })
    .send()
    .await?;
```

--------------------------------

### Octocrab with Tokio Runtime

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/08-webhooks-examples.md

Initializes Octocrab with a GitHub token and demonstrates fetching repository details and creating an issue within a Tokio async main function. Ensure the GITHUB_TOKEN environment variable is set.

```rust
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize Octocrab
    let octocrab = octocrab::Octocrab::builder()
        .personal_token(secrecy::SecretString::new(
            std::env::var("GITHUB_TOKEN")?
        ))
        .build()?;
    
    // Fetch repository
    let repo = octocrab.repos("owner", "repo").get().await?;
    println!("Repository: {}", repo.full_name);
    
    // Create issue
    let issue = octocrab
        .issues("owner", "repo")
        .create("Example issue")
        .body("This is an example")
        .send()
        .await?;
    println!("Created issue #{}", issue.number);
    
    Ok(())
}
```

--------------------------------

### Initialize Octocrab with GitHub App

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/QUICK-REFERENCE.md

Initialize Octocrab for a GitHub App using its ID and private key.

```Rust
let octocrab = octocrab::Octocrab::builder()
    .app(AppId(123), key)
    .build()?;
```

--------------------------------

### Get Issue

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/03-issues-pulls-api.md

Retrieves a specific issue by its number. This is useful for fetching the details of an existing issue.

```APIDOC
## GET /repos/{owner}/{repo}/issues/{number}

### Description
Get issue by number

### Method
GET

### Endpoint
`/repos/{owner}/{repo}/issues/{number}`

### Parameters
#### Path Parameters
- **owner** (string) - Required - The owner of the repository.
- **repo** (string) - Required - The name of the repository.
- **number** (u64) - Required - The number of the issue.

### Response
#### Success Response (200)
- **Issue** (object) - Details of the issue.

### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Basic Octocrab Builder Configuration

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/07-authentication-configuration.md

Configure Octocrab with a personal access token, add a preview API, a custom header, and set connection and read timeouts.

```rust
let octocrab = Octocrab::builder()
    .personal_token(token)
    .add_preview("machine-man")
    .add_header(HeaderName::from_static("x-custom"), "value".to_string())
    .set_connect_timeout(Duration::from_secs(10))
    .set_read_timeout(Duration::from_secs(30))
    .add_retry_config(retry_config)
    .build()?;
```

--------------------------------

### Apps API

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/06-additional-apis.md

Provides methods for interacting with the GitHub Apps API, allowing you to manage apps and their installations.

```APIDOC
## Apps API

### AppsRequestHandler Creation

```rust
let handler = octocrab.apps();
```

### App Methods

#### `get_authenticated()`

##### Description
Get authenticated app details.

##### Signature
`pub async fn get_authenticated(&self) -> Result<App>`

##### Returns
`App`

#### `list_installations()`

##### Description
List app installations.

##### Signature
`pub fn list_installations() -> ListInstallationsBuilder<'_>`

##### Returns
`ListInstallationsBuilder`

#### `get_installation()`

##### Description
Get specific installation.

##### Signature
`pub async fn get_installation(&self, installation_id: InstallationId) -> Result<Installation>`

##### Parameters
* **installation_id** (InstallationId) - Required - The ID of the installation.

##### Returns
`Installation`

#### `get_org_installation()`

##### Description
Get organization installation.

##### Signature
`pub async fn get_org_installation(&self, org: impl Into<String>) -> Result<Installation>`

##### Parameters
* **org** (impl Into<String>) - Required - The organization name.

##### Returns
`Installation`

#### `get_repo_installation()`

##### Description
Get repository installation.

##### Signature
`pub async fn get_repo_installation(&self, owner: impl Into<String>, repo: impl Into<String>) -> Result<Installation>`

##### Parameters
* **owner** (impl Into<String>) - Required - The repository owner.
* **repo** (impl Into<String>) - Required - The repository name.

##### Returns
`Installation`

**Example:**
```rust
let app = octocrab.apps().get_authenticated().await?;
println!("App name: {}", app.name);
```
```

--------------------------------

### Create Licenses API Handler

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/06-additional-apis.md

Instantiate the Licenses API handler. Use this to interact with GitHub's license information.

```rust
let handler = octocrab.licenses();
```

--------------------------------

### Octocrab Client Authentication Methods

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/01-octocrab-client.md

Methods available on the Octocrab client for authentication and managing installation tokens.

```APIDOC
## Octocrab Client Authentication Methods

### `installation()`

Create a new client authenticated as a GitHub App installation.

### Method

`pub fn installation(&self, id: InstallationId) -> Result<Octocrab>`

### `installation_and_token()`

Get installation client and eagerly cache its token.

### Method

`pub async fn installation_and_token(&self, id: InstallationId) -> Result<(Octocrab, SecretString)>`

### `installation_token()`

Get or refresh installation access token (30-second buffer).

### Method

`pub async fn installation_token(&self) -> Result<SecretString>`

### `installation_token_with_buffer()`

Get installation token with custom expiration buffer.

### Method

`pub async fn installation_token_with_buffer(&self, buffer: chrono::Duration) -> Result<SecretString>`

### `user_access_token()`

Create new client authenticated with user access token.

### Method

`pub fn user_access_token<S: Into<SecretString>>(&self, token: S) -> Result<Self>`
```

--------------------------------

### Create Search Handler

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/06-additional-apis.md

Instantiate the SearchHandler to begin making search requests.

```rust
let handler = octocrab.search();
```

--------------------------------

### Get Repository Code of Conduct

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/06-additional-apis.md

Retrieve the code of conduct for a specific repository using its owner and name.

```rust
let repo_coc = octocrab.codes_of_conduct().get_repo_coc("owner", "repo").await?;
```

--------------------------------

### Get User Profile

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/06-additional-apis.md

Retrieve a user's profile information. Requires an existing user handler.

```rust
let user = octocrab.users("octocat").get().await?;
println!("Followers: {}", user.followers);
```

--------------------------------

### List Collaborators Builder Options

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/02-repositories-api.md

Configure options for listing repository collaborators, such as affiliation and pagination.

```rust
pub struct ListCollaboratorsBuilder { ... }

impl ListCollaboratorsBuilder {
    pub fn affiliation(mut self, affiliation: Affiliation) -> Self
    pub fn per_page(mut self, n: impl Into<u8>) -> Self
    pub fn page(mut self, page: impl Into<u8>) -> Self
    pub async fn send(self) -> Result<Page<Collaborator>>
}

pub enum Affiliation {
    Outside,
    Direct,
    All,
}
```

--------------------------------

### Get Repository Information

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/02-repositories-api.md

Retrieve metadata, license, public key, or community profile metrics for a repository.

```APIDOC
## GET /repos/{owner}/{repo}/... (Methods)

### Description
Provides methods to get repository metadata, license file, public key for secrets, or community profile metrics.

### Methods
- `get()`: Get repository metadata.
- `license()`: Get repository's license file.
- `public_key()`: Get public key for secrets encryption.
- `get_community_profile_metrics()`: Get community profile metrics.

### Parameters
This method operates on a repository identified by owner and name, or by repository ID.

### Request Example
```rust
let repo = octocrab.repos("XAMPPRocky", "octocrab").get().await?;
println!("Stars: {}", repo.stargazers_count);
```

### Response
- `Repository`: Repository metadata.
- `Content`: Content of the license file.
- `PublicKey`: Public key for secrets encryption.
- `RepositoryMetrics`: Community profile metrics.
```

--------------------------------

### Create Apps API Handler

Source: https://github.com/xampprocky/octocrab/blob/main/_autodocs/06-additional-apis.md

Instantiate the Apps API handler. This is the entry point for interacting with app-related GitHub functionalities.

```rust
let handler = octocrab.apps();
```
Tokens:
Raw