README.md

github-fine-grained-token-client

Library and CLI tool for creating and managing fine-grained GitHub tokens.

Purpose

GitHub allows the creation of per-project access tokens with fine-grained permissions but doesn't currently have an API to do so.

This tool seeks to provide a client exposing this functionality anyway by whatever means necessary. More specifically, for now this means simulating requests to the relevant parts of the web interface closely enough to how a browser would perform them.

Installation

To install from PyPI:

pip3 install github-fine-grained-token-client

Command-line tool usage

To use the CLI tool, you'll need to install some optional dependencies first:

pip3 install 'github-fine-grained-token-client[cli]'

To create a token yourtokenname with read-only permissions (the default) for your public GitHub repository yourrepo:

github-fine-grained-token-client create --repositories yourrepo yourtokenname

There are more commands and options - please refer to the docs.

Usage as a library

Basic example script:

import asyncio
from datetime import timedelta
from os import environ

from github_fine_grained_token_client import (
    BlockingPromptTwoFactorOtpProvider,
    GithubCredentials,
    SelectRepositories,
    async_client,
)

credentials = GithubCredentials(environ["GITHUB_USER"], environ["GITHUB_PASS"])
assert credentials.username and credentials.password


async def main() -> str:
    async with async_client(
        credentials=credentials,
        # 2FA will be mandatory on GitHub starting at some point in 2023
        two_factor_otp_provider=BlockingPromptTwoFactorOtpProvider(),
    ) as session:
        token = await session.create_token(
            "my token",
            expires=timedelta(days=364),
            scope=SelectRepositories(["my-project"]),
        )
    return token


token = asyncio.run(main())

print(token)

More information

For more detailed usage information and the API reference, refer to the documentation.

License

MIT License, see LICENSE file.

Changelog

• 1.0.8: Add py.typed marker (allows typechecking when used as a dependency).
• 1.0.7: Fix expiration date parsing in presence of refresh advice.