ghapi

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

ghapi provides 100% always-updated coverage of the entire GitHub API. Because we automatically convert the OpenAPI spec to a Pythonic API, ghapi is always up to date with the latest changes to GitHub APIs. Furthermore, because this is all done dynamically, the entire package is only 35kB in size!

Using ghapi, you can automate nearly anything that you can do through the GitHub web interface or through the git client, such as:

• Open, list, comment on, or modify issues or pull requests
• Create, list, or modify git tags or GitHub releases, including uploading release assets
• Configure and run GitHub Actions and webhooks
• Set up GitHub users and organizations
• Manage your deployments
• …and much, much more.

There are two ways to use ghapi: either through Python, or from the command line. An overview of each is provided below.

Installation

To install, run either pip install ghapi or conda install -c fastai ghapi.

How to use - Python

Throughout this documentation, you will see code inputs and outputs shown in this format:

1+1

2

We recommend reading the documentation on the official site, rather than on GitHub, since not all the functionality described on this page is available through the GitHub viewer.

All of the documentation is available directly as Jupyter Notebooks, for instance the current page you’re reading is available as a notebook here. To open any page as an interactive notebook in Google Colab, click the Colab badge at the top of the page.

To access the GitHub API, first create a GhApi object:

from ghapi.all import GhApi
api = GhApi()

Every part of the API includes documentation directly in the api object itself. For instance, here’s how to explore the groups of functionality provided by the API by displaying the object:

api

• actions
• activity
• api_insights
• apps
• billing
• checks
• classroom
• code_scanning
• code_security
• codes_of_conduct
• codespaces
• copilot
• dependabot
• dependency_graph
• emojis
• gists
• git
• gitignore
• hosted_compute
• interactions
• issues
• licenses
• markdown
• meta
• migrations
• oidc
• orgs
• packages
• private_registries
• projects
• pulls
• rate_limit
• reactions
• repos
• search
• secret_scanning
• security_advisories
• teams
• users

Then we can explore the endpoints provided by the API in each group, e.g. for the git group:

api.git

• git.create_blob(owner, repo, content, encoding): Create a blob
• git.get_blob(owner, repo, file_sha): Get a blob
• git.create_commit(owner, repo, message, tree, parents, author, committer, signature): Create a commit
• git.get_commit(owner, repo, commit_sha): Get a commit object
• git.list_matching_refs(owner, repo, ref): List matching references
• git.get_ref(owner, repo, ref): Get a reference
• git.create_ref(owner, repo, ref, sha): Create a reference
• git.update_ref(owner, repo, ref, sha, force): Update a reference
• git.delete_ref(owner, repo, ref): Delete a reference
• git.create_tag(owner, repo, tag, message, object, type, tagger): Create a tag object
• git.get_tag(owner, repo, tag_sha): Get a tag
• git.create_tree(owner, repo, tree, base_tree): Create a tree
• git.get_tree(owner, repo, tree_sha, recursive): Get a tree

Here’s how to learn about an endpoint you want to use, e.g.:

api.git.get_ref

git.get_ref(owner, repo, ref): Get a reference

In Jupyter Notebook full tab completion, parameter lists, etc are provided for all endpoints. Endpoints are called as standard Python methods:

api.git.get_ref(owner='fastai', repo='fastcore', ref='heads/master')

{ 'node_id': 'MDM6UmVmMjI1NDYwNTk5OnJlZnMvaGVhZHMvbWFzdGVy',
  'object': { 'sha': 'c0608379fe60014534c8dffe2e381138e8160f53',
              'type': 'commit',
              'url': 'https://api.github.com/repos/AnswerDotAI/fastcore/git/commits/c0608379fe60014534c8dffe2e381138e8160f53'},
  'ref': 'refs/heads/master',
  'url': 'https://api.github.com/repos/AnswerDotAI/fastcore/git/refs/heads/master'}

To use ghapi to access authenticated operations (other than when running through GitHub Actions), you will need a GitHub personal access token, which is a secret code used to access your account. If you don’t have one, click here to create one. You’ll be asked to enter a name – choose anything you like, for instance “ghapi”. You’ll also be asked to choose “scopes”; this limits what you’ll be able to do with the API using this token. If you’re not sure, click “repo” “gist”, “notifications”, and “workflow”. Then click “Generate Token” at the bottom of the screen, and copy the token (the long string of letters and numbers shown). You can easily do that by clicking the little clipboard icon next to the token.

Rather than pasting that token into every script, it’s easiest to save it as an environment variable. If you save it as $GITHUB_TOKEN then it will be most convenient, so add this to the end of your .bashrc or .zshrc file:

export GITHUB_TOKEN=xxx

…replacing the xxx with the token you just copied. (Don’t forget to source that file after you change it.), pass a [GitHub token].

As well as your token, you can also pass any parameters you want auto-inserted into relevant methods, such as owner and repo:

api = GhApi(owner='fastai', repo='fastcore', token=github_token)

We can now repeat the previous method, but only need to pass ref:

api.git.get_ref('heads/master')

{ 'node_id': 'MDM6UmVmMjI1NDYwNTk5OnJlZnMvaGVhZHMvbWFzdGVy',
  'object': { 'sha': 'c0608379fe60014534c8dffe2e381138e8160f53',
              'type': 'commit',
              'url': 'https://api.github.com/repos/AnswerDotAI/fastcore/git/commits/c0608379fe60014534c8dffe2e381138e8160f53'},
  'ref': 'refs/heads/master',
  'u