Package: ghapi
ghapighapiprovides 100%
always-updated coverage of the entireGitHub
API. Because we automatically convert theOpenAPI
specto a
Pythonic API,ghapiis 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!Usingghapi, you can automate
nearly anything that you can do through the GitHub web interface or
through thegitclient, such as:Open, list, comment on, or modifyissuesorpull
requestsCreate, list, or modifygit
tagsorGitHub
releases,
including uploading release assetsConfigure and run GitHubActionsandwebhooksSet up GitHubusersandorganizationsManage yourdeployments…and much, much more.There are two ways to useghapi: either through Python,
or from the command line. An overview of each is provided below.InstallationTo install, run eitherpip install ghapiorconda install -c fastai ghapi.How to use - PythonThroughout this documentation, you will see code inputs and outputs
shown in this format:1+12We recommend reading the documentation on theofficial
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 notebookhere. To open
any page as an interactive notebook in Google Colab, click theColabbadge at the top of the page.To access the GitHub API, first create aGhApiobject:fromghapi.allimportGhApiapi=GhApi()Every part of the API includes documentation directly in theapiobject itself. For instance, here’s how to explore the groups of
functionality provided by the API by displaying the object:apiactionsactivityappsbillingcheckscode_scanningcodes_of_conductemojisenterprise_admingistsgitgitignoreinteractionsissueslicensesmarkdownmetamigrationsoauth_authorizationsorgsprojectspullsrate_limitreactionsreposscimsearchsecret_scanningteamsusersThen we can explore the endpoints provided by the API in each group,
e.g. for thegitgroup:api.gitgit.create_blob(owner,
repo, content, encoding):Create a blobgit.get_blob(owner,
repo, file_sha):Get a blobgit.create_commit(owner,
repo, message, tree, parents, author, committer, signature):Create a
commitgit.get_commit(owner,
repo, commit_sha):Get a commitgit.list_matching_refs(owner,
repo, ref, per_page, page):List matching referencesgit.get_ref(owner,
repo, ref):Get a referencegit.create_ref(owner,
repo, ref, sha, key):Create a referencegit.update_ref(owner,
repo, ref, sha, force):Update a referencegit.delete_ref(owner,
repo, ref):Delete a referencegit.create_tag(owner,
repo, tag, message, object, type, tagger):Create a tag objectgit.get_tag(owner,
repo, tag_sha):Get a taggit.create_tree(owner,
repo, tree, base_tree):Create a treegit.get_tree(owner,
repo, tree_sha, recursive):Get a treeHere’s how to learn about an endpoint you want to use, e.g.:api.git.get_refgit.get_ref(owner,
repo, ref):Get a referenceIn 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')ref: refs/heads/masternode_id: MDM6UmVmMjI1NDYwNTk5OnJlZnMvaGVhZHMvbWFzdGVyurl:https://api.github.com/repos/fastai/fastcore/git/refs/heads/masterobject:sha: 0e3084ed009baa51db38a640ae7c23d638af2756type: commiturl:https://api.github.com/repos/fastai/fastcore/git/commits/0e3084ed009baa51db38a640ae7c23d638af2756To useghapito access
authenticated operations (other than when running through GitHub
Actions), you will need a GitHubpersonal access
token,
which is a secret code used to access your account. If you don’t have
one,click hereto 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_TOKENthen it
will be most convenient, so add this to the end of your.bashrcor.zshrcfile:export GITHUB_TOKEN=xxx…replacing thexxxwith the token you just copied. (Don’t forget tosourcethat file after you change it.), pass a [GitHub token].As well as yourtoken, you can also pass any parameters you want
auto-inserted into relevant methods, such asownerandrepo:api=GhApi(owner='fastai',repo='fastcore',token=github_token)We can now repeat the previous method, but only need to passref:api.git.get_ref('heads/master')ref: refs/heads/masternode_id: MDM6UmVmMjI1NDYwNTk5OnJlZnMvaGVhZHMvbWFzdGVyurl:https://api.github.com/repos/fastai/fastcore/git/refs/heads/masterobject:sha: 0e3084ed009baa51db38a640ae7c23d638af2756type: commiturl:https://api.github.com/repos/fastai/fastcore/git/commits/0e3084ed009baa51db38a640ae7c23d638af2756Now that we’ve provided our token, we can use authenticated endpoints
such as creating an issue:issue=api.issues.create("Remember to check out GhApi!")Since we’ve now checked out GhApi, let’s close this issue. 😎api.issues.update(issue.number,state='closed')How to use - command lineYou can useGhApivia the
command line, and can access nearly everything in theGitHub
API. We provide an overview here of one
of the command line programs,ghapi– see the full CLI docs
page for details on all the programs available.We strongly recommend enabling tab completion forghapi, which you can do by
placing the following command at the end of your~/.bashrcor~/.zshrcfile:eval"$(completion-ghapi--install)"To get started with theghapicommand, first find the name of the operation you wish to perform, for
instance by searching thefull API
reference.To useghapi, pass the method
name (exactly the same as you’d use in the Python API) as the first
parameter, followed by any positional parameters required, and then
keyword arguments with “--” before each parameter name.For instance,git.get_reftakes three parameters:owner,repo, andref. If we wish to pass
the first two as positional parameters, and the last as a named
argument, then we’d call:ghapigit.get_reffastaighapi-test--refheads/masterIf you have enabled tab completion, then after you’ve typedghapi gtry pressingTab, and you’ll see all the operation groups
available in the GitHub API that start withg. If you keep typing,
e.g.ghapi git., and hitTabagain, you’ll now see all the
operations available in thegitgroup, i.e:git.create_blob git.create_commit git.create_ref git.create_tag git.create_tree git.delete_ref git.get_blob git.get_commit git.get_ref git.get_tag git.get_tree git.list_matching_refs git.name git.update_ref git.verbsIf you pass just--helpafter the operation name, you’ll see a full
list of all parameters accepted, and a link to the official GitHub
documentation.ghapigit.get_ref--help
>>>git.get_ref(owner,repo,ref)>>>https://docs.github.com/rest/reference/git#get-a-referenceIn addition to--helpand the GitHub operation parameters, you can
also pass the following:--headers: A list of extra headers to pass, JSON-encoded--token: A GitHub authentation token--debug: Print requests before sending them