Kokomikke

Kokomikke (koh•koh•mi•ke) is a Python library that looks up GitHub access tokens from various sources.

Installation

pip install kokomikke

Usage

Basic usage is as simple as:

import kokomikke

token = kokomikke.search()

By default, this will look for a GitHub token in the following locations, in order, returning as soon as one is found:

1. The GITHUB_API_TOKEN environment variable
2. The GITHUB_TOKEN environment variable
3. The GH_TOKEN environment variable
4. The GITHUB_PAT environment variable
5. The GH_PAT environment variable
6. GitHub CLI via gh auth token
7. GitHub CLI via hosts.yml

If no token is found, kokomikke.search() will return None.

Sources

In order to search for token, Kokomikke needs sources. A source is an object of a class that inherits from kokomikke.sources.Source and implements the lookup() method:

from kokomikke.sources import Source

class MySource(Source):
    def lookup(self) -> str | None:
        # lookup logic goes here

Kokomikke comes with the following sources built-in:

kokomikke.sources.EnvironmentVariableSource

Searches a list of environment variables, in order, for a non-empty value.

It takes the following arguments:

• variables (list[str], keyword-only, default: [GITHUB_API_TOKEN, GITHUB_TOKEN, GH_TOKEN, GITHUB_PAT, GH_PAT]): The variables to search.

kokomikke.sources.GitHubCLISource

Runs gh auth token and, if there is no error, returns its output.

It takes the following arguments:

• hostname (str, keyword-only, default: github.com): The hostname of the GitHub instance to get a token for.

kokomikke.sources.GitHubCLIYamlSource

Reads GitHub CLI's hosts.yml file and returns a token if one is present.

It takes the following arguments:

• hostname (str, keyword-only, default: github.com): The hostname of the GitHub instance to get a token for.

kokomikke.sources.GitSource

Calls git credential fill and returns a token if one is present in the output.

It takes the following arguments:

• hostname (str, keyword-only, default: github.com): The hostname of the GitHub instance to get a token for.

kokomikke.sources.CommandSource

Runs an arbitrary command and, if there is no error, returns its output.

It takes the folowing arguments:

• command: (list, keyword-only): Command arguments.

kokomikke.search() takes an optional sources argument, which expects a list of sources, each of which will be evaluated in order. For example, to first look for a token via gh auth token, but fall back to pass if that fails:

import kokomikke
from kokomikke.sources import CommandSource, GitHubCLISource

pass_source = CommandSource(command=["pass", "github.com/mona"])

token = kokomikke.search([GitHubCLISource, pass_source])