GitHubKit

https://github.com/yanyongyu/githubkit
Admin
GitHubKit is a modern, all-batteries-included, fully typed, and always up-to-date SDK for Python to...
Tokens:87,143
Snippets:667
Trust Score:9
License:MIT
Update:1 day ago
Show doc for...
Tokens:
Raw
### Setup development environment with uv

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/contributing.md

Installs all extras and sets up pre-commit hooks. Requires uv to be installed.

```bash
uv sync --all-extras && uv run pre-commit install
```

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

### Install githubkit with pip, poetry, pdm, or uv

Source: https://github.com/yanyongyu/githubkit/blob/master/README.md

Install githubkit using your preferred package manager. The example shows commands for pip, poetry, pdm, and uv.

```bash
pip install githubkit
# or, use poetry
poetry add githubkit
# or, use pdm
pdm add githubkit
# or, use uv
uv add githubkit
```

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

### Basic Installation with pip

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Installs githubkit using pip.

```bash
pip install githubkit
```

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

### Act on behalf of an installation (Async)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/github-app.md

Asynchronous workflow to find the installation ID for a repository and create a new client authenticated as that installation, then use it to create an issue comment.

```python
from githubkit import GitHub, AppAuthStrategy
from githubkit_schemas.latest.models import Installation, IssueComment

app_github = GitHub(
    AppAuthStrategy(
        app_id="your_app_id",
        private_key="your_private_key",
        client_id="your_client_id",
        client_secret="your_client_secret",
    )
)

# 2. Find the installation ID for a specific repository
resp = await app_github.rest.apps.async_get_repo_installation("owner", "repo")
repo_installation: Installation = resp.parsed_data

# 3. Create a new client authenticated as that installation
installation_github = app_github.with_auth(
    app_github.auth.as_installation(repo_installation.id)
)

# 4. Use the installation client to perform actions
resp = await installation_github.rest.issues.async_create_comment(
    "owner", "repo", 1, body="Hello"
)
issue: IssueComment = resp.parsed_data
```

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

### Act on behalf of an installation (Sync)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/github-app.md

Synchronous workflow to find the installation ID for a repository and create a new client authenticated as that installation, then use it to create an issue comment.

```python
from githubkit import GitHub, AppAuthStrategy
from githubkit_schemas.latest.models import Installation, IssueComment

app_github = GitHub(
    AppAuthStrategy(
        app_id="your_app_id",
        private_key="your_private_key",
        client_id="your_client_id",
        client_secret="your_client_secret",
    )
)

# 2. Find the installation ID for a specific repository
resp = app_github.rest.apps.get_repo_installation("owner", "repo")
repo_installation: Installation = resp.parsed_data

# 3. Create a new client authenticated as that installation
installation_github = app_github.with_auth(
    app_github.auth.as_installation(repo_installation.id)
)

# 4. Use the installation client to perform actions
resp = installation_github.rest.issues.create_comment("owner", "repo", 1, body="Hello")
issue: IssueComment = resp.parsed_data
```

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

### Basic Installation with uv

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Adds githubkit as a dependency using uv.

```bash
uv add githubkit
```

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

### Full Installation with pip

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Installs githubkit with all extra dependencies using pip.

```bash
pip install 'githubkit[all]'
```

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

### Switch from GitHub App to Installation Auth

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/getting-started/authentication.md

Create a new GitHub instance authenticated as a specific installation using the with_auth method, which shares the same configuration as the original client.

```python
from githubkit import GitHub, AppAuthStrategy

github = GitHub(AppAuthStrategy("<app_id>", "<private_key>"))

# Create a new client authenticated as a specific installation
installation_github = github.with_auth(github.auth.as_installation(installation_id))
```

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

### Basic Installation with pdm

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Adds githubkit as a dependency using pdm.

```bash
pdm add githubkit
```

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

### Full Installation with uv

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Adds githubkit with all extra dependencies using uv.

```bash
uv add 'githubkit[all]'
```

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

### Basic Installation with poetry

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Adds githubkit as a dependency using poetry.

```bash
poetry add githubkit
```

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

### Full Installation with pdm

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Adds githubkit with all extra dependencies using pdm.

```bash
pdm add 'githubkit[all]'
```

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

### Get a repository (Async)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/rest-api.md

Async version of the repository GET request using await and async_get.

```python
from githubkit import Response
from githubkit_schemas.latest.models import FullRepository

github = GitHub("<your_token_here>")
resp: Response[FullRepository] = await github.rest.repos.async_get("owner", "repo")
repo: FullRepository = resp.parsed_data
```

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

### Install auth-app Extra with pip

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Installs the auth-app extra dependencies for GitHub App authentication using pip.

```bash
pip install 'githubkit[auth-app]'
```

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

### Install Extra Schema Version with uv

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Installs the githubkit-schemas extra for schema version 2022-11-28 using uv.

```bash
uv add 'githubkit-schemas[2022-11-28]'
```

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

### Full Installation with poetry

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Adds githubkit with all extra dependencies using poetry.

```bash
poetry add 'githubkit[all]'
```

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

### Start pagination from initial cursor (Sync and Async)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/graphql.md

Provides an initial cursor value to start pagination from a specific point by including it in the `variables` dictionary.

```python
for result in github.graphql.paginate(
    query, variables={"owner": "owner", "repo": "repo", "cursor": "initial_cursor"}
):
    print(result)
```

```python
async for result in github.graphql.paginate(
    query, variables={"owner": "owner", "repo": "repo", "cursor": "initial_cursor"}
):
    print(result)
```

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

### Get a repository (Sync)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/rest-api.md

Creates a GitHub client with a token and calls the REST API to get a repository. The response is typed with FullRepository and accessed via parsed_data.

```python
from githubkit import GitHub, Response
from githubkit_schemas.latest.models import FullRepository

github = GitHub("<your_token_here>")
resp: Response[FullRepository] = github.rest.repos.get("owner", "repo")
repo: FullRepository = resp.parsed_data
```

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

### Authenticate as GitHub App installation with AppInstallationAuthStrategy

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/getting-started/authentication.md

Use AppInstallationAuthStrategy to authenticate as a specific installation of a GitHub App. Provide the app ID (or None to use client ID), private key, installation ID, and optional client ID and secret. This grants access to repositories and permissions approved for that installation.

```python
from githubkit import GitHub, AppInstallationAuthStrategy

# Using app ID
github = GitHub(
    AppInstallationAuthStrategy(
        "<app_id>",
        "<private_key>",
        installation_id,
        "<optional_client_id>",
        "<optional_client_secret>",
    )
)

# Using client ID instead of app ID
github = GitHub(
    AppInstallationAuthStrategy(
        None,
        "<private_key>",
        installation_id,
        "<client_id>",
        "<optional_client_secret>",
    )
)

```

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

### Install Extra Schema Version with poetry

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Installs the githubkit-schemas extra for schema version 2022-11-28 using poetry.

```bash
poetry add 'githubkit-schemas[2022-11-28]'
```

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

### Sync: Store and refresh OAuth token with expiration

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/oauth-web-flow.md

Synchronous example using OAuthAppAuthStrategy and OAuthTokenAuthStrategy. Exchange the user code, store the refresh_token, restore it, refresh manually, and then act as the user to get authenticated user data.

```python
from githubkit_schemas.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthAppAuthStrategy, OAuthTokenAuthStrategy

github = GitHub(OAuthAppAuthStrategy("<client_id>", "<client_secret>"))

# redirect user to github oauth page and get the code from callback

auth: OAuthTokenAuthStrategy = github.auth.as_web_user("<code>").exchange_token(
    github
)  # (1)!
refresh_token = auth.refresh_token

auth = OAuthTokenAuthStrategy(
    "<client_id>", "<client_secret>", refresh_token=refresh_token
)  # (2)!
auth.refresh(github)  # (3)!
refresh_token = auth.refresh_token

user_github = github.with_auth(auth)

# now you can act as the user
resp = user_github.rest.users.get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# you can get the user name and id now
username = user.login
user_id = user.id
```

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

### Install auth-app Extra with uv

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Adds the auth-app extra dependencies for GitHub App authentication using uv.

```bash
uv add 'githubkit[auth-app]'
```

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

### GraphQL query to get current login user

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/graphql.md

Example query to fetch the current user's login. This query is used as the basis for the subsequent GraphQL API calls.

```python
query = """
{
  viewer {
    login
  }
}
"""
```

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

### Install Extra Schema Version with pdm

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Installs the githubkit-schemas extra for schema version 2022-11-28 using pdm.

```bash
pdm add 'githubkit-schemas[2022-11-28]'
```

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

### Install Extra Schema Version with pip

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Installs the githubkit-schemas extra for schema version 2022-11-28 using pip.

```bash
pip install 'githubkit-schemas[2022-11-28]'
```

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

### Install auth-app Extra with poetry

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Adds the auth-app extra dependencies for GitHub App authentication using poetry.

```bash
poetry add 'githubkit[auth-app]'
```

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

### Sync: Authenticate as a User and Create a Comment

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/github-app.md

Use AppAuthStrategy to create an app client, find the user's installation ID, and create a new client authenticated as that user. Then use the user client to create an issue comment.

```python
from githubkit import GitHub, AppAuthStrategy
from githubkit_schemas.latest.models import Installation, IssueComment

app_github = GitHub(
    AppAuthStrategy(
        app_id="your_app_id",
        private_key="your_private_key",
        client_id="your_client_id",
        client_secret="your_client_secret",
    )
)

# 2. Find the installation ID for a specific user
resp = app_github.rest.apps.get_user_installation("username")
user_installation: Installation = resp.parsed_data

# 3. Create a new client authenticated as that user
user_github = app_github.with_auth(
    app_github.auth.as_installation(user_installation.id)
)

# 4. Use the user client to perform actions on a repository
resp = user_github.rest.issues.create_comment("owner", "repo", 1, body="Hello")
issue: IssueComment = resp.parsed_data
```

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

### Install auth-app Extra with pdm

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Adds the auth-app extra dependencies for GitHub App authentication using pdm.

```bash
pdm add 'githubkit[auth-app]'
```

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

### Sync: Initialize GitHub client with PAT and call REST/GraphQL APIs

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/calling-api-with-pat.md

Use this synchronous example to authenticate with a Personal Access Token and fetch the authenticated user's info via REST and GraphQL. Replace '<your_token_here>' with your actual token. The REST call returns a PublicUser or PrivateUser object, and the GraphQL call returns a dict.

```python
from githubkit import GitHub
from githubkit_schemas.latest.models import PublicUser, PrivateUser

# Initialize the client with your Personal Access Token
github = GitHub("<your_token_here>")

# Call GitHub rest api
resp = github.rest.users.get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# Call GitHub graphql api
data: dict = github.graphql("{ viewer { login } }")
```

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

### Async: Initialize GitHub client with PAT and call REST/GraphQL APIs

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/calling-api-with-pat.md

Use this asynchronous example to authenticate with a Personal Access Token and fetch the authenticated user's info via REST and GraphQL. Replace '<your_token_here>' with your actual token. The REST call returns a PublicUser or PrivateUser object, and the GraphQL call returns a dict.

```python
from githubkit import GitHub
from githubkit_schemas.latest.models import PublicUser, PrivateUser

# Initialize the client with your Personal Access Token
github = GitHub("<your_token_here>")

# Call GitHub rest api
resp = await github.rest.users.async_get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# Call GitHub graphql api
data: dict = await github.async_graphql("{ viewer { login } }")
```

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

### Async: Authenticate as a User and Create a Comment

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/github-app.md

Use AppAuthStrategy to create an app client, find the user's installation ID, and create a new client authenticated as that user. Then use the user client to create an issue comment asynchronously.

```python
from githubkit import GitHub, AppAuthStrategy
from githubkit_schemas.latest.models import Installation, IssueComment

app_github = GitHub(
    AppAuthStrategy(
        app_id="your_app_id",
        private_key="your_private_key",
        client_id="your_client_id",
        client_secret="your_client_secret",
    )
)

# 2. Find the installation ID for a specific user
resp = await app_github.rest.apps.async_get_user_installation("username")
user_installation: Installation = resp.parsed_data

# 3. Create a new client authenticated as that user
user_github = app_github.with_auth(
    app_github.auth.as_installation(user_installation.id)
)

# 4. Use the user client to perform actions on a repository
resp = await user_github.rest.issues.async_create_comment(
    "owner", "repo", 1, body="Hello"
)
issue: IssueComment = resp.parsed_data
```

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

### Initialize GitHub App client with AppAuthStrategy

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/github-app.md

Creates a GitHub client authenticated as the GitHub App using app credentials. This client can only access app-level APIs, such as querying installations.

```python
from githubkit import GitHub, AppAuthStrategy

# 1. Authenticate as the GitHub App
# This client is used to get information about your app's installations.
app_github = GitHub(
    AppAuthStrategy(
        app_id="your_app_id",
        private_key="your_private_key",
        client_id="your_client_id",
        client_secret="your_client_secret",
    )
)
```

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

### Sync: Exchange and store token with OAuthDeviceAuthStrategy

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/oauth-device-flow.md

Synchronous example that exchanges the device code for an access token, stores it, and restores it to authenticate as the user. The callback displays the user code. The access token is obtained via exchange_token and then used to create a new GitHub instance with OAuthTokenAuthStrategy.

```python
from githubkit_schemas.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthDeviceAuthStrategy, OAuthTokenAuthStrategy


# sync/async func for displaying user code to user
def callback(data: dict):
    print(data["user_code"])


github = GitHub(OAuthDeviceAuthStrategy("<client_id>", callback))

auth: OAuthTokenAuthStrategy = github.auth.exchange_token(github)  # (1)!
access_token = auth.token

user_github = github.with_auth(
    OAuthTokenAuthStrategy("<client_id>", token=access_token)
)  # (2)!

# now you can act as the user
resp = user_github.rest.users.get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# you can get the user name and id now
username = user.login
user_id = user.id
```

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

### Exchange code for token and restore token (Async)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/oauth-web-flow.md

Asynchronous example: exchange the OAuth code for an access token, store it, and then restore it to authenticate as the user. Uses async_exchange_token and async_get_authenticated.

```python
from githubkit_schemas.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthAppAuthStrategy, OAuthTokenAuthStrategy

github = GitHub(OAuthAppAuthStrategy("<client_id>", "<client_secret>"))

# redirect user to github oauth page and get the code from callback

auth: OAuthTokenAuthStrategy = await github.auth.as_web_user(
    "<code>"
).async_exchange_token(github)  # (1)!
access_token = auth.token

user_github = github.with_auth(
    OAuthTokenAuthStrategy("<client_id>", "<client_secret>", token=access_token)
)  # (2)!

# now you can act as the user
resp = await user_github.rest.users.async_get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# you can get the user name and id now
username = user.login
user_id = user.id
```

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

### Strong reference warning example

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/rest-api.md

Shows that calling a method on a temporary client instance fails; you must hold a strong reference to the client.

```python
from githubkit import GitHub


def get_client() -> GitHub:
    return GitHub()


# This will cause error
get_client().rest.repos.get("owner", "repo")

# This is ok
client = get_client()
client.rest.repos.get("owner", "repo")
```

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

### One-Time Usage with OAuthDeviceAuthStrategy (Sync)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/oauth-device-flow.md

Use this synchronous example to authenticate as a user via the device flow. The callback function displays the user_code to the user. After authorization, you can access the authenticated user's data.

```python
from githubkit_schemas.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthDeviceAuthStrategy, OAuthTokenAuthStrategy


# sync/async func for displaying user code to user
def callback(data: dict):
    print(data["user_code"])


user_github = GitHub(OAuthDeviceAuthStrategy("<client_id>", callback))

# now you can act as the user
resp = user_github.rest.users.get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# you can get the user name and id now
username = user.login
user_id = user.id
```

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

### Async: Exchange and store token with OAuthDeviceAuthStrategy

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/oauth-device-flow.md

Asynchronous version of the token exchange example. Uses async_exchange_token and async_get_authenticated. The callback is async and prints the user code. The access token is stored and then used to create a new GitHub instance with OAuthTokenAuthStrategy.

```python
from githubkit_schemas.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthDeviceAuthStrategy, OAuthTokenAuthStrategy


# sync/async func for displaying user code to user
async def callback(data: dict):
    print(data["user_code"])


github = GitHub(OAuthDeviceAuthStrategy("<client_id>", callback))

auth: OAuthTokenAuthStrategy = await github.auth.async_exchange_token(github)  # (1)!
access_token = auth.token

user_github = github.with_auth(
    OAuthTokenAuthStrategy("<client_id>", token=access_token)
)  # (2)!

# now you can act as the user
resp = await user_github.rest.users.async_get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# you can get the user name and id now
username = user.login
user_id = user.id
```

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

### One-Time Usage - Sync (OAuthAppAuthStrategy)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/oauth-web-flow.md

Synchronous example showing how to exchange the OAuth code for a user token and fetch the authenticated user's profile. Replace <code> with the code from the callback. The code is one-time use and short-lived.

```python
from githubkit_schemas.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthAppAuthStrategy, OAuthTokenAuthStrategy

github = GitHub(OAuthAppAuthStrategy("<client_id>", "<client_secret>"))

# redirect user to github oauth page and get the code from callback

user_github = github.with_auth(github.auth.as_web_user("<code>"))

# now you can act as the user
resp = user_github.rest.users.get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# you can get the user name and id now
username = user.login
user_id = user.id
```

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

### One-Time Usage with OAuthDeviceAuthStrategy (Async)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/oauth-device-flow.md

Use this asynchronous example to authenticate as a user via the device flow. The callback function displays the user_code to the user. After authorization, you can access the authenticated user's data using the async API.

```python
from githubkit_schemas.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthDeviceAuthStrategy, OAuthTokenAuthStrategy


# sync/async func for displaying user code to user
def callback(data: dict):
    print(data["user_code"])


user_github = GitHub(OAuthDeviceAuthStrategy("<client_id>", callback))

# now you can act as the user
resp = await user_github.rest.users.async_get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# you can get the user name and id now
username = user.login
user_id = user.id
```

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

### Async: Store and refresh OAuth token with expiration

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/oauth-device-flow.md

Asynchronous example using OAuthDeviceAuthStrategy and OAuthTokenAuthStrategy. It exchanges the user token, stores the refresh_token, restores it, and refreshes manually. The code then uses the authenticated client to fetch the user profile.

```python
from githubkit_schemas.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthDeviceAuthStrategy, OAuthTokenAuthStrategy


# sync/async func for displaying user code to user
async def callback(data: dict):
    print(data["user_code"])


github = GitHub(OAuthDeviceAuthStrategy("<client_id>", callback))

auth: OAuthTokenAuthStrategy = await github.auth.async_exchange_token(github)  # (1)!
refresh_token = auth.refresh_token

auth = OAuthTokenAuthStrategy("<client_id>", refresh_token=refresh_token)  # (2)!
await auth.async_refresh(github)  # (3)!
refresh_token = auth.refresh_token

user_github = github.with_auth(auth)

# now you can act as the user
resp = user_github.rest.users.get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# you can get the user name and id now
username = user.login
user_id = user.id
```

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

### GraphQL query for pagination with cursor

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/graphql.md

Example query that accepts a `cursor` parameter and returns a `pageInfo` object. This is required for using the pagination helper.

```graphql
query ($owner: String!, $repo: String!, $cursor: String) {
  repository(owner: $owner, name: $repo) {
    issues(first: 10, after: $cursor) {
      nodes {
        number
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

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

### Async: Store and refresh OAuth token with expiration

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/oauth-web-flow.md

Asynchronous version of the sync example. Uses async_exchange_token and async_refresh to handle token exchange and refresh. Store the refresh_token, restore it, refresh, and fetch authenticated user data asynchronously.

```python
from githubkit_schemas.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthAppAuthStrategy, OAuthTokenAuthStrategy

github = GitHub(OAuthAppAuthStrategy("<client_id>", "<client_secret>"))

# redirect user to github oauth page and get the code from callback

auth: OAuthTokenAuthStrategy = await github.auth.as_web_user(
    "<code>"
).async_exchange_token(github)  # (1)!
refresh_token = auth.refresh_token

auth = OAuthTokenAuthStrategy(
    "<client_id>", "<client_secret>", refresh_token=refresh_token
)  # (2)!
await auth.async_refresh(github)  # (3)!
refresh_token = auth.refresh_token

user_github = github.with_auth(auth)

# now you can act as the user
resp = await user_github.rest.users.async_get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# you can get the user name and id now
username = user.login
user_id = user.id
```

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

### Exchange code for token and restore token (Sync)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/oauth-web-flow.md

Synchronous example: exchange the OAuth code for an access token, store it, and then restore it to authenticate as the user. Uses OAuthAppAuthStrategy and OAuthTokenAuthStrategy.

```python
from githubkit_schemas.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthAppAuthStrategy, OAuthTokenAuthStrategy

github = GitHub(OAuthAppAuthStrategy("<client_id>", "<client_secret>"))

# redirect user to github oauth page and get the code from callback

auth: OAuthTokenAuthStrategy = github.auth.as_web_user("<code>").exchange_token(
    github
)  # (1)!
access_token = auth.token

user_github = github.with_auth(
    OAuthTokenAuthStrategy("<client_id>", "<client_secret>", token=access_token)
)  # (2)!

# now you can act as the user
resp = user_github.rest.users.get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# you can get the user name and id now
username = user.login
user_id = user.id
```

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

### Sync: Store and refresh OAuth token with expiration

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/oauth-device-flow.md

Synchronous example using OAuthDeviceAuthStrategy and OAuthTokenAuthStrategy. It exchanges the user token, stores the refresh_token, restores it, and refreshes manually. The code then uses the authenticated client to fetch the user profile.

```python
from githubkit_schemas.latest.models import PublicUser, PrivateUser
from githubkit import GitHub, OAuthDeviceAuthStrategy, OAuthTokenAuthStrategy


# sync/async func for displaying user code to user
def callback(data: dict):
    print(data["user_code"])


github = GitHub(OAuthDeviceAuthStrategy("<client_id>", callback))

auth: OAuthTokenAuthStrategy = github.auth.exchange_token(github)  # (1)!
refresh_token = auth.refresh_token

auth = OAuthTokenAuthStrategy("<client_id>", refresh_token=refresh_token)  # (2)!
auth.refresh(github)  # (3)!
refresh_token = auth.refresh_token

user_github = github.with_auth(auth)

# now you can act as the user
resp = user_github.rest.users.get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# you can get the user name and id now
username = user.login
user_id = user.id
```

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

### Call REST API to get a repository

Source: https://github.com/yanyongyu/githubkit/blob/master/README.md

Use the GitHub instance to call the REST API and retrieve a repository. The response is typed with Response[FullRepository] and the parsed data is accessed via resp.parsed_data.

```python
from githubkit import Response
from githubkit_schemas.latest.models import FullRepository

resp: Response[FullRepository] = github.rest.repos.get("owner", "repo")
repo: FullRepository = resp.parsed_data
print(repo.full_name)
```

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

### Sync mock transport test with GitHub client

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/unit-test.md

Creates a GitHub client with a synchronous mock transport that returns a fake response for GET /repos/owner/repo. The test function target_sync_func calls the API and asserts the response is a FullRepository instance.

```python
import json
from pathlib import Path

import httpx
import pytest

from githubkit import GitHub
from githubkit_schemas.latest.models import FullRepository

FAKE_RESPONSE = json.loads(Path("fake_response.json").read_text())


def target_sync_func(github: GitHub):
    resp = github.rest.repos.get("owner", "repo")
    return resp.parsed_data


def mock_transport_handler(request: httpx.Request) -> httpx.Response:
    if request.method == "GET" and request.url.path == "/repos/owner/repo":
        return httpx.Response(status_code=200, json=FAKE_RESPONSE)
    raise RuntimeError(f"Unexpected request: {request.method} {request.url.path}")


def test_sync_mock():
    g = GitHub("xxxxx", transport=httpx.MockTransport(mock_transport_handler))
    repo = target_sync_func(g)
    assert isinstance(repo, FullRepository)
```

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

### Async mock transport test with GitHub client

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/unit-test.md

Creates a GitHub client with an asynchronous mock transport that returns a fake response for GET /repos/owner/repo. The test function target_async_func awaits the API call and asserts the response is a FullRepository instance.

```python
import json
from pathlib import Path

import httpx
import pytest

from githubkit import GitHub
from githubkit_schemas.latest.models import FullRepository

FAKE_RESPONSE = json.loads(Path("fake_response.json").read_text())


async def target_async_func(github: GitHub):
    resp = await github.rest.repos.async_get("owner", "repo")
    return resp.parsed_data


def mock_transport_handler(request: httpx.Request) -> httpx.Response:
    if request.method == "GET" and request.url.path == "/repos/owner/repo":
        return httpx.Response(status_code=200, json=FAKE_RESPONSE)
    raise RuntimeError(f"Unexpected request: {request.method} {request.url.path}")


@pytest.mark.anyio
async def test_async_mock():
    g = GitHub("xxxxx", async_transport=httpx.MockTransport(mock_transport_handler))
    repo = await target_async_func(g)
    assert isinstance(repo, FullRepository)
```

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

### Configure GitHub with keyword arguments

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/getting-started/configuration.md

Pass configuration options directly to the GitHub constructor. All parameters are optional and shown with their default values.

```python
from githubkit import GitHub

github = GitHub(
    base_url="https://api.github.com/",
    accept_format=None,
    previews=None,
    user_agent="GitHubKit/Python",
    follow_redirects=True,
    timeout=None,
    ssl_verify=True,
    trust_env=True,
    proxy=None,
    transport=None,
    async_transport=None,
    event_hooks=None,
    async_event_hooks=None,
    cache_strategy=None,
    http_cache=True,
    throttler=None,
    auto_retry=True,
    rest_api_validate_body=True,
)
```

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

### Get latest version and version mapping

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/rest-api.md

Import LATEST_VERSION and VERSIONS from githubkit_schemas to get the latest GitHub API version name and the version-module mapping.

```python
from githubkit_schemas import LATEST_VERSION, VERSIONS
```

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

### Create a GitHub instance with a Personal Access Token

Source: https://github.com/yanyongyu/githubkit/blob/master/README.md

Create a GitHub instance by passing your Personal Access Token (PAT) to the GitHub constructor. This is the first step to using githubkit.

```python
from githubkit import GitHub

github = GitHub("<your_token_here>")
```

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

### Get raw unvalidated JSON response

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/rest-api.md

Shows how to get the raw response data using `resp.json()`, which returns typed but unvalidated data. Useful when the schema is incorrect or you need raw data.

```python
from typing import Any
from githubkit import Response
from githubkit_schemas.latest.models import FullRepository
from githubkit_schemas.latest.types import FullRepositoryType

resp: Response[FullRepository, FullRepositoryType] = github.rest.repos.get(
    "owner", "repo"
)
repo: FullRepositoryType = resp.json()
```

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

### Set accept_format and previews

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/getting-started/configuration.md

Control the Accept header. accept_format sets a media type suffix like 'raw+json' (leading dot optional). previews enables API preview features without the '-preview' suffix.

```python
# Request raw markdown content as JSON
github = GitHub(accept_format="raw+json")

# Enable an API preview feature
github = GitHub(previews=["starfox"])
```

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

### Initialize OAuthDeviceAuthStrategy with callback

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/getting-started/authentication.md

Creates a GitHub client using OAuthDeviceAuthStrategy with a callback that displays the user code and verification URL. githubkit handles the polling loop automatically.

```python
from githubkit import GitHub, OAuthDeviceAuthStrategy


def callback(data: dict):
    """Display the user code and verification URL to the user."""
    print(f"Open {data['verification_uri']} and enter code: {data['user_code']}")


github = GitHub(OAuthDeviceAuthStrategy("<client_id>", callback))
```

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

### Pin Schema Version with uv

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Pins githubkit-schemas to version 26.5.12 using uv.

```bash
uv add 'githubkit-schemas==26.5.12'
```

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

### Configure with Config object and pass via config parameter

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/getting-started/configuration.md

Build a Config object to share the same configuration across multiple GitHub instances. The config parameter is mutually exclusive with individual keyword arguments.

```python
import httpx
from githubkit import GitHub, Config
from githubkit.retry import RETRY_DEFAULT
from githubkit.cache import DEFAULT_CACHE_STRATEGY

config = Config(
    base_url="https://api.github.com/",
    accept="application/vnd.github+json",
    user_agent="GitHubKit/Python",
    follow_redirects=True,
    timeout=httpx.Timeout(None),
    ssl_verify=True,
    trust_env=True,
    proxy=None,
    transport=None,
    async_transport=None,
    event_hooks=None,
    async_event_hooks=None,
    cache_strategy=DEFAULT_CACHE_STRATEGY,
    http_cache=True,
    throttler=None,
    auto_retry=RETRY_DEFAULT,
    rest_api_validate_body=True,
)

github = GitHub(config=config)
```

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

### Create an issue with keyword arguments (Async)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/rest-api.md

Async version of the issue creation using async_create.

```python
from githubkit import GitHub, Response
from githubkit_schemas.latest.models import Issue

github = GitHub("<your_token_here>")
resp: Response[Issue] = await github.rest.issues.async_create(
    "owner",
    "repo",
    title="New Issue",
    body="This is issue body",
)
issue: Issue = resp.parsed_data
```

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

### Use REST and GraphQL APIs with schema version (Async)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/quickstart/connecting-to-github-enterprise.md

Demonstrates calling the REST API with a specific schema version and the GraphQL API asynchronously. Uses async methods and await.

```python
# Call the GitHub REST API with a specific schema version
resp = await github.rest("ghec-2022-11-28").users.async_get_authenticated()
user: PublicUser | PrivateUser = resp.parsed_data

# Call the GitHub GraphQL API
data: dict = await github.async_graphql("{ viewer { login } }")
```

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

### Without context manager

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/getting-started/reusing-client.md

Use GitHub without a context manager to create a new HTTP client per request. Convenient for one-off calls but less efficient for multiple requests.

```python
from githubkit import GitHub

github = GitHub("<your_token_here>")
resp = github.rest.repos.get(owner="owner", repo="repo")
```

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

### Sync context manager with GitHub

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/getting-started/reusing-client.md

Wrap a GitHub instance in a `with` block to create a single HTTP client shared across all requests inside the block, automatically closed on exit. Recommended for multiple API calls or long-running processes to avoid memory leaks. Cannot be entered twice; nesting will raise a RuntimeError.

```python
from githubkit import GitHub, Response
from githubkit_schemas.latest.models import FullRepository

with GitHub("<your_token_here>") as github:
    resp: Response[FullRepository] = github.rest.repos.get(owner="owner", repo="repo")
    repo: FullRepository = resp.parsed_data
```

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

### Pin Schema Version with pdm

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Pins githubkit-schemas to version 26.5.12 using pdm.

```bash
pdm add 'githubkit-schemas==26.5.12'
```

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

### GitHub App Authentication with AppAuthStrategy

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/getting-started/authentication.md

Authenticate as a GitHub App using a JWT signed with the app's private key. Identify the app by app ID or client ID. Client ID and client secret are optional unless using OAuth features. The first example uses app ID, the second uses client ID instead.

```python
from githubkit import GitHub, AppAuthStrategy

# Using app ID (client ID and secret are optional)
github = GitHub(
    AppAuthStrategy(
        "<app_id>", "<private_key>", "<optional_client_id>", "<optional_client_secret>"
    )
)

# Using client ID instead of app ID
github = GitHub(
    AppAuthStrategy(None, "<private_key>", "<client_id>", "<optional_client_secret>")
)
```

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

### Async context manager with GitHub

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/getting-started/reusing-client.md

Wrap a GitHub instance in an `async with` block to create a single HTTP client shared across all requests inside the block, automatically closed on exit. Recommended for multiple API calls or long-running processes to avoid memory leaks. Cannot be entered twice; nesting will raise a RuntimeError.

```python
from githubkit import GitHub, Response
from githubkit_schemas.latest.models import FullRepository

async with GitHub("<your_token_here>") as github:
    resp: Response[FullRepository] = await github.rest.repos.async_get(
        owner="owner", repo="repo"
    )
    repo: FullRepository = resp.parsed_data
```

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

### Mock synchronous GitHub API request with mock_request

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/unit-test.md

Use this snippet to mock the `request` method of the `GitHub` class for synchronous code. It patches `GitHub.request` with a custom function that returns a fake response for a GET request to `/repos/owner/repo`. The mock raises a `RuntimeError` for unexpected requests. The test uses `pytest.MonkeyPatch` to apply the patch and verifies the returned object is an instance of `FullRepository`.

```python
import json
from pathlib import Path
from typing import Any, Type

import httpx
import pytest

from githubkit import GitHub
from githubkit.utils import UNSET
from githubkit.response import Response
from githubkit.typing import URLTypes, UnsetType
from githubkit_schemas.latest.models import FullRepository

FAKE_RESPONSE = json.loads(Path("fake_response.json").read_text())


def target_sync_func() -> FullRepository:  # (1)!
    github = GitHub("xxxxx")
    resp = github.rest.repos.get("owner", "repo")
    return resp.parsed_data


def mock_request(
    g: GitHub,
    method: str,
    url: URLTypes,
    *,
    response_model: Type[Any] | UnsetType = UNSET,
    **kwargs: Any,  # (2)!
) -> Response[Any]:
    if method == "GET" and url == "/repos/owner/repo":  # (3)!
        return Response(
            httpx.Response(status_code=200, json=FAKE_RESPONSE),
            Any if response_model is UNSET else response_model,
        )
    raise RuntimeError(f"Unexpected request: {method} {url}")


# Test the target function
def test_sync_mock():
    with pytest.MonkeyPatch.context() as m:
        # Patch the request method with the mock
        m.setattr(GitHub, "request", mock_request)

        repo = target_sync_func()
        assert isinstance(repo, FullRepository)

```

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

### Mock asynchronous GitHub API request with mock_arequest

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/unit-test.md

Use this snippet to mock the `arequest` method of the `GitHub` class for asynchronous code. It patches `GitHub.arequest` with a custom function that returns a fake response for a GET request to `/repos/owner/repo`. The mock raises a `RuntimeError` for unexpected requests. The test uses `pytest.MonkeyPatch` and `pytest.mark.anyio` to apply the patch and verify the returned object is an instance of `FullRepository`.

```python
import json
from pathlib import Path
from typing import Any, Type

import httpx
import pytest

from githubkit import GitHub
from githubkit.utils import UNSET
from githubkit.response import Response
from githubkit.typing import URLTypes, UnsetType
from githubkit_schemas.latest.models import FullRepository

FAKE_RESPONSE = json.loads(Path("fake_response.json").read_text())


async def target_async_func() -> FullRepository:  # (1)!
    async with GitHub("xxxxx") as github:
        resp = await github.rest.repos.get("owner", "repo")
        return resp.parsed_data


async def mock_arequest(
    g: GitHub,
    method: str,
    url: URLTypes,
    *,
    response_model: Type[Any] | UnsetType = UNSET,
    **kwargs: Any,  # (2)!
) -> Response[Any]:
    if method == "GET" and url == "/repos/owner/repo":  # (3)!
        return Response(
            httpx.Response(status_code=200, json=FAKE_RESPONSE),
            Any if response_model is UNSET else response_model,
        )
    raise RuntimeError(f"Unexpected request: {method} {url}")


# Test the target function
@pytest.mark.anyio
async def test_async_mock():
    with pytest.MonkeyPatch.context() as m:
        # Patch the request method with the mock
        m.setattr(GitHub, "arequest", mock_arequest)

        repo = await target_async_func()
        assert isinstance(repo, FullRepository)

```

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

### Call GraphQL API with query (Sync and Async)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/graphql.md

Calls the GraphQL API with the query using the sync `github.graphql` and async `github.async_graphql` methods. The response data is a dict and the user login is extracted.

```python
data: dict[str, Any] = github.graphql(query)
user_login: str = data["viewer"]["login"]
```

```python
data: dict[str, Any] = await github.async_graphql(query)
user_login: str = data["viewer"]["login"]
```

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

### Pin Schema Version with pip

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Pins githubkit-schemas to version 26.5.12 using pip.

```bash
pip install 'githubkit-schemas==26.5.12'
```

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

### Pin Schema Version with poetry

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/installation.md

Pins githubkit-schemas to version 26.5.12 using poetry.

```bash
poetry add 'githubkit-schemas==26.5.12'
```

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

### Device Flow to Token

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/getting-started/authentication.md

Authenticate using the device flow. You can either make a request first to trigger the flow automatically, or exchange the token directly. Shows how to retrieve tokens for persistence and create a reusable client.

```python
from githubkit import GitHub, OAuthDeviceAuthStrategy, OAuthTokenAuthStrategy


def callback(data: dict):
    print(data["user_code"])


user_github = GitHub(OAuthDeviceAuthStrategy("<client_id>", callback))

# Option 1: Make a request first (triggers the device flow automatically)
resp = user_github.rest.users.get_authenticated()
user = resp.parsed_data

# Retrieve the tokens for persistence
user_token = user_github.auth.token
user_token_expire_time = user_github.auth.expire_time
refresh_token = user_github.auth.refresh_token
refresh_token_expire_time = user_github.auth.refresh_token_expire_time

# you can also exchange the token directly without making a request
auth: OAuthTokenAuthStrategy = github.auth.exchange_token(github)
# or asynchronously
auth: OAuthTokenAuthStrategy = await github.auth.async_exchange_token(github)

user_token = auth.token
user_token_expire_time = auth.expire_time
refresh_token = auth.refresh_token
refresh_token_expire_time = auth.refresh_token_expire_time

# Create a reusable client with the token
token_github = user_github.with_auth(auth)
```

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

### Switch between pydantic v1 and v2

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/contributing.md

Commands to sync dependencies for pydantic v1 or v2. Use the appropriate group to switch versions.

```bash
# Pydantic v1
uv sync --all-extras --group pydantic-v1
```

```bash
# Pydantic v2
uv sync --all-extras --group pydantic-v2
```

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

### MemCacheStrategy: default and isolated cache instances

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/getting-started/configuration.md

Shows two ways to configure the default in-memory cache strategy. The global default is shared across GitHub instances; creating a MemCacheStrategy instance gives an isolated cache. Call cleanup() or await acleanup() in long-running processes to release memory.

```python
from githubkit import GitHub
from githubkit.cache import DEFAULT_CACHE_STRATEGY, MemCacheStrategy

# Use the global default (shared across all GitHub instances)
github = GitHub(cache_strategy=DEFAULT_CACHE_STRATEGY)

# Or create an isolated cache instance
github = GitHub(cache_strategy=MemCacheStrategy())
```

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

### Upload release asset with github.arequest (Async)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/rest-api.md

Uses the asynchronous github.arequest method to upload a release asset. First fetches the release by tag using async_get_release_by_tag, then posts the asset to the upload URL with the template part removed. Requires the release upload_url template handling.

```python
from githubkit import GitHub
from githubkit_schemas.latest.models import Release, ReleaseAsset

github = GitHub()

resp = await github.rest.repos.async_get_release_by_tag("owner", "repo", "tag_name")
release: Release = resp.parsed_data

resp = await github.arequest(
    "POST",
    release.upload_url.split("{")[0],  # (1)!
    params={"name": "test", "label": "description"},
    content=b"file content",
    headers={"Content-Type": "application/zip"},
    response_model=ReleaseAsset,
)
asset: ReleaseAsset = resp.parsed_data

```

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

### Render raw markdown (Async)

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/rest-api.md

Async version of the raw markdown rendering using async_render_raw.

```python
from githubkit import GitHub

github = GitHub("<your_token_here>")
resp = await github.rest.markdown.async_render_raw(
    data="Hello **world**",
)
rendered_html = resp.text
```

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

### GitHub(cache_strategy=MemCacheStrategy())

Source: https://github.com/yanyongyu/githubkit/blob/master/docs/usage/getting-started/configuration.md

Creates an isolated in-memory cache instance for the GitHub client.

```APIDOC
## GitHub(cache_strategy=MemCacheStrategy())

### Description
Creates an isolated in-memory cache instance for the GitHub client.

### Method
Constructor parameter

### Parameters
#### cache_strategy
- **cache_strategy** (MemCacheStrategy) - Required - An instance of `MemCacheStrategy`.

### Request Example
```python
from githubkit import GitHub
from githubkit.cache import MemCacheStrategy

github = GitHub(cache_strategy=MemCacheStrategy())
```

### Notes
- Each `MemCacheStrategy` instance maintains its own cache.
```
Tokens:
Raw