2018-10-02 15:54:39 +02:00
This is ghub.info, produced by makeinfo version 6.5 from ghub.texi.
2018-09-10 20:51:14 +02:00
Copyright (C) 2017-2018 Jonas Bernoulli <jonas@bernoul.li>
You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version.
This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Ghub: (ghub). Minuscule client library for the Github API.
END-INFO-DIR-ENTRY
File: ghub.info, Node: Top, Next: Introduction, Up: (dir)
Ghub User and Developer Manual
******************************
2018-10-02 15:54:39 +02:00
Ghub provides basic support for using the APIs of various Git forges
from Emacs packages. Originally it only supported the Github REST API,
but now it also supports the Github GraphQL API as well as the REST APIs
of Gitlab, Gitea, Gogs and Bitbucket.
2018-09-10 20:51:14 +02:00
2018-10-02 15:54:39 +02:00
Ghub abstracts access to API resources using only a handful of basic
functions such as ‘ ‘
‘ ‘ ‘ ‘
‘ ‘ ‘ ‘ ‘ ‘
not provide any resource-specific functions, with the exception of
‘ ‘
When accessing Github, then Ghub handles the creation and storage of
access tokens using a setup wizard to make it easier for users to get
started. The tokens for other forges have to be created manually.
2018-09-10 20:51:14 +02:00
Ghub is intentionally limited to only provide these two essential
features — basic request functions and guided setup — to avoid being too
opinionated, which would hinder wide adoption. It is assumed that wide
adoption would make life easier for users and maintainers alike, because
2018-10-02 15:54:39 +02:00
then all packages that talk to forge APIs could be configured the same
way.
2018-09-10 20:51:14 +02:00
2018-10-02 15:54:39 +02:00
This manual is for Ghub version 2.0.1 (v2.0.1-48-g87701ea+1).
2018-09-10 20:51:14 +02:00
Copyright (C) 2017-2018 Jonas Bernoulli <jonas@bernoul.li>
You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version.
This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
* Menu:
* Introduction::
* Getting Started::
* Using Ghub in Personal Scripts::
* Using Ghub in a Package::
* API::
2018-10-02 15:54:39 +02:00
* GraphQL Support::
* Support for Other Forges::
2018-09-10 20:51:14 +02:00
— The Detailed Node Listing —
Getting Started
* Setting the Username::
* Interactively Creating and Storing a Token::
* Manually Creating and Storing a Token::
* How Ghub uses Auth-Source::
API
* Making Requests::
* Authentication::
* Configuration Variables::
2018-10-02 15:54:39 +02:00
Support for Other Forges
* Forge Functions and Variables::
* Forge Limitations and Notes::
2018-09-10 20:51:14 +02:00
File: ghub.info, Node: Introduction, Next: Getting Started, Prev: Top, Up: Top
1 Introduction
**************
2018-10-02 15:54:39 +02:00
Ghub provides basic support for using the APIs of various Git forges
from Emacs packages. Originally it only supported the Github REST API,
but now it also supports the Github GraphQL API as well as the REST APIs
of Gitlab, Gitea, Gogs and Bitbucket.
2018-09-10 20:51:14 +02:00
2018-10-02 15:54:39 +02:00
Ghub abstracts access to API resources using only a handful of basic
functions such as ‘ ‘
‘ ‘ ‘ ‘
‘ ‘ ‘ ‘ ‘ ‘
not provide any resource-specific functions, with the exception of
‘ ‘
When accessing Github, then Ghub handles the creation and storage of
access tokens using a setup wizard to make it easier for users to get
started. The tokens for other forges have to be created manually.
2018-09-10 20:51:14 +02:00
Ghub is intentionally limited to only provide these two essential
features — basic request functions and guided setup — to avoid being too
opinionated, which would hinder wide adoption. It is assumed that wide
adoption would make life easier for users and maintainers alike, because
2018-10-02 15:54:39 +02:00
then all packages that talk to forge APIs could be configured the same
way.
2018-09-10 20:51:14 +02:00
Fancier interfaces can be implemented on top of Ghub, and one such
wrapper — named simply Ghub+ — has already been implemented. The
benefit of basing various opinionated interfaces on top of a single
library that provides only the core functionality is that choosing the
programming interface no longer dictates how access tokens are handled.
Users can then use multiple packages that access the Github API without
having to learn the various incompatible ways packages expect the
appropriate token to be made available to them.
Ghub uses the built-in ‘ ’
That library is very flexible and supports multiple backends, which
means that it is up to the user how secrets are stored. They can, among
other things, choose between storing secrets in plain text for ease of
use, or encrypted for better security.
Previously (as in until this library is widely adopted) it was up to
package authors to decide if things should be easy or secure. (Note
that ‘ ’
Ghub expects package authors to use a dedicated access token instead
of sharing a single token between all packages that rely on it. That
means that users cannot configure Ghub once and later start using a new
package without any additional setup. But Ghub helps with that.
When the user invokes some command that ultimately results in
‘ ’
yet, then the user is guided through the process of creating and storing
a new token, and at the end of that process the request is carried out
as if the token had been available to begin with.
File: ghub.info, Node: Getting Started, Next: Using Ghub in Personal Scripts, Prev: Introduction, Up: Top
2 Getting Started
*****************
Each package that uses Ghub uses its own token. Despite that, chances
are good that after successfully configuring one package you can just
start using another package pretty much instantly.
2018-10-02 15:54:39 +02:00
If the necessary token to access a Github instance is not available
when a package makes an API request, then a setup wizard pops up, and
after answering a few questions you are good to go. Even the request
that caused the wizard to be summoned should succeed and for most users
this should be true even when configuring the very first token.
2018-09-10 20:51:14 +02:00
However, in some situations some manual configuration is necessary
*before* using the wizard, or the wizard cannot be used at all:
• If you don’ ’
create tokens manually as described in *note Manually Creating and
Storing a Token::.
2018-10-02 15:54:39 +02:00
• Unfortunately only Github supports the creation of tokens by using
the API. If you want to access another forge, then you have to
create the token manually as describe in *note Manually Creating
and Storing a Token::. Also see *note Support for Other Forges::.
2018-09-10 20:51:14 +02:00
• If you want to access a Github Enterprise instance, then you have
to tell Ghub about that before the wizard makes its appearance by
setting the Git variable ‘ ’
your username for that instance using the variable
‘ ’
• If the variable ‘ ’ ‘ ’
Enterprise instance) is unset when the wizard is first summoned,
then you are asked to provide your username. That value is then
stored *globally* to avoid having to ask you that question once per
2018-10-02 15:54:39 +02:00
repository. If you have multiple accounts on Github.com (or a
Github Enterprise instance), then you have to explicitly tell Ghub
about that. This can be done by setting the repository-local
values of the appropriate variable *before* the wizard is invoked.
2018-09-10 20:51:14 +02:00
• You might forget to do the above, which is why it is important to
carefully read the output of the wizard. If it turns out that you
forgot to set a variable, then you must abort, set the variable,
and repeat the request to trigger the wizard again.
• The setup wizard should work even if you have enabled two-factor
authentication. However if your Github Enterprise instance
enforces Single Sign-On as an additional security measure, then you
are out of luck and have to create the token manually as described
in *note Manually Creating and Storing a Token::.
The variables mentioned above — and others — are documented in *note
Configuration Variables:: and the setup wizard is documented in *note
Interactively Creating and Storing a Token::.
* Menu:
* Setting the Username::
* Interactively Creating and Storing a Token::
* Manually Creating and Storing a Token::
* How Ghub uses Auth-Source::
File: ghub.info, Node: Setting the Username, Next: Interactively Creating and Storing a Token, Up: Getting Started
2.1 Setting the Username
========================
If you haven’ ‘ ’
request, then you will be asked:
Git variable `github.user' is unset. Set to:
You are expected to provide your Github username here. The provided
value will be saved globally (using ‘
USERNAME’
If you need to identify as another user in a particular repository,
then you have to set that variable locally, *before* making a request:
cd /path/to/repo
git config github.user USERNAME
For Github Enterprise instances you have to specify where the API can
be accessed *before* you try to access it and a different variable has
to be used to set the username. For example if the API is available at
‘ ’
# Do this once
git config --global github.example.com/api/v3.user EMPLOYEE
# Do this for every corporate repository
cd /path/to/repo
git config github.host example.com/api/v3
If you do not set ‘ ’
asked to provide the value when trying to make a request, but you do
have to manually set ‘ ’
to access ‘ ’
File: ghub.info, Node: Interactively Creating and Storing a Token, Next: Manually Creating and Storing a Token, Prev: Setting the Username, Up: Getting Started
2.2 Interactively Creating and Storing a Token
==============================================
Ghub uses a different token for every package as well as for every
machine from which you access the Github API (and obviously also for
every Github instance and user). This allows packages to only request
the scopes that they actually need and also gives users the opportunity
to refuse access to certain scopes if they expect to not use the
features that need them.
Usually you don’
yourself and can just make a request. Note however that you don’
to use the setup wizard described below. Alternatively you can perform
the setup manually as described in the next section.
If you make a request and the required token is not available yet,
then the setup wizard will first ask you something like this:
Such a Github API token is not available:
Host: api.github.com
User: USERNAME
Package: PACKAGE
Scopes requested in `PACKAGE-github-token-scopes':
repo
Store on Github as:
"Emacs package PACKAGE @ LOCAL-MACHINE"
Store locally according to option `auth-sources':
("~/.authinfo" "~/.authinfo.gpg" "~/.netrc")
If in doubt, then abort and first view the section of the Ghub
documentation called "Manually Creating and Storing a Token".
Create and store such a token? (yes or no)
If you don’
of the doubts that you might have:
• ‘ ’
want. If you are trying to access a Github Enterprise instance,
then it should be something else and you have to set the value
manually before the setup wizard is summoned, as described in the
parent section.
• ‘ ’
username. If it is something else and it doesn’
simple typo, then you should read the parent section again. In
either case you have to abort.
• ‘ ’
the Github API.
If it is ‘ ’
convention and you should probably report a bug in the issue
tracker of that package.
Or you yourself are using ‘ ’
directly, in which case this is expected and perfectly fine. In
that case you might however want to abort and change the value of
the variable ‘ ’
wizard again.
• Each ‘ ’
variable named ‘ ’
that variable should document why the various scopes are needed.
The meaning of the various scopes are documented at
<https://magit.vc/goto/f63aeb0a>.
• The value of ‘ ’
secrets to be stored in plain text. Because this might be
unexpected, Ghub additionally displays a warning when appropriate.
WARNING: The token will be stored unencrypted in "~/.authinfo".
If you don't want that, you have to abort and customize
2018-10-02 15:54:39 +02:00
the `auth-sources' option.
2018-09-10 20:51:14 +02:00
Whether that is something that needs fixing, is up to you. If your
answer is yes, then you should abort and see *note How Ghub uses
Auth-Source:: for instructions on how to save the token more
securely.
• When creating a token it is necessary to provide a token
description. Ghub uses descriptions that have the form "Emacs
package PACKAGE @ LOCAL-MACHINE".
Github uses the token description to identify the token, not merely
as something useful to humans. Token descriptions therefore have
to be unique and in rare cases you get an additional prompt, asking
you something like:
A token named "Emacs package PACKAGE @ LOCAL-MACHINE"
already exists on Github. Replace it?
You might see this message when you have lost the old token and
want to replace it with a new one, in which case you should
obviously just proceed.
Or two of your computers have the same hostname, which is bad
practice because it gains you nothing but leads to issues such as
this. Or you are dual-booting on this machine and use the same
hostname in all operating systems, which is a somewhat reasonable
thing to do, but never-the-less leads to issues like this.
In either case you will have to use something other than the value
returned by ‘ ’
operating system. Or you can continue to identify different things
using the same identifier, in which case you have to manually
distribute the token.
The former is recommended and also easier to do, using the variable
‘ ’
for details.
After the above prompt you are also asked for you username and
password. If you have enabled two-factor authentication, then you also
have to provide the authentication code at least twice. If you make
sure the code is still good for a while when asked for it first, then
you can just press ‘ ’
File: ghub.info, Node: Manually Creating and Storing a Token, Next: How Ghub uses Auth-Source, Prev: Interactively Creating and Storing a Token, Up: Getting Started
2.3 Manually Creating and Storing a Token
=========================================
If you cannot or don’
figure out what scopes a package wants, (2) create such a token using
the web interface and (3) store the token where Ghub expects to find it.
A package named ‘ ’
the variable named ‘ ’
variables should document what the various scopes are needed for.
To create or edit a token go to <https://github.com/settings/tokens>.
For Gitlab.com use <https://gitlab.com/profile/personal_access_tokens>.
Finally store the token in a place where Ghub looks for it, as
described in *note How Ghub uses Auth-Source::.
If you store the token in a file like ‘ ’
‘ ’ ’
ends with a newline character, that there are no empty or invalid lines,
and that all comments are prefixed with ‘ ’
File: ghub.info, Node: How Ghub uses Auth-Source, Prev: Manually Creating and Storing a Token, Up: Getting Started
2.4 How Ghub uses Auth-Source
=============================
Please see *note (auth)Top:: for all the gory details about Auth-Source.
Some Ghub-specific information and important notes follow.
The variable ‘ ’
new secrets and where it looks for known secrets. The default value is
‘ ’
looks in all of these files in order to find secrets and that it stores
new secrets in ‘ ’
list. It doesn’ ’
storing a new secret, the first file is always used.
Secrets are stored in ‘ ’ ’
that (good choice), then you have to customize ‘ ’
flipping the positions of the first two elements.
Auth-Source also supports storing secrets in various key-chains.
Refer to its documentation for more information.
Some Auth-Source backends only support storing three values per
entry, the "machine", the "login" and the "password". Because Ghub uses
separate tokens for each package, it has to squeeze four values into
those three slots, and it does that by using "USERNAME^PACKAGE" as the
"login".
Assuming your username is "ziggy",the package is named "stardust",
and you want to access *Github.com* an entry in one of the three
mentioned files would then look like this:
machine api.github.com login ziggy^stardust password 012345abcdef...
Assuming your username is "ziggy",the package is named "stardust",
and you want to access *Gitlab.com* an entry in one of the three
mentioned files would then look like this:
machine gitlab.com/api/v4 login ziggy^stardust password 012345abcdef...
File: ghub.info, Node: Using Ghub in Personal Scripts, Next: Using Ghub in a Package, Prev: Getting Started, Up: Top
3 Using Ghub in Personal Scripts
********************************
You can use ‘ ’
scripts, of course. Unlike when you use Ghub from a package that you
distribute for others to use, you don’
personal scripts.
;; This is perfectly acceptable in personal scripts ...
(ghub-get "/user")
;; ... and actually equal to
(ghub-get "/user" nil :auth 'ghub)
;; In packages you have to specify the package using AUTH.
(ghub-get "/user" nil :auth 'foobar)
When you do not specify the ‘ ’
on behalf of the ‘ ’
Ghub, ‘ ’
the variable ‘ ’
The default value of that variable is ‘ ’
add additional scopes. You can later add additional scopes to an
existing token, using the web interface at
<https://github.com/settings/tokens>.
If you do that, then you might want to also set the variable
accordingly, but note that Ghub only consults that when *creating* a new
token. If you want to know a token’
‘ ’
File: ghub.info, Node: Using Ghub in a Package, Next: API, Prev: Using Ghub in Personal Scripts, Up: Top
4 Using Ghub in a Package
*************************
Every package should use its own token. This allows you as the author
of some package to only request access to API scopes that are actually
needed, which in turn might make it easier for users to trust your
package not to do unwanted things.
The scopes used by ‘ ’
‘ ’ ‘ ’
behalf of which package a request is being made by passing the symbol
‘ ’ ‘ ’
(ghub-request "GET" "/user" nil :auth 'PACKAGE)
-- Variable: PACKAGE-github-token-scopes
This variable defines the token scopes requested by the package
named ‘ ’
scopes are needed for to prevent users from giving ‘ ’
permissions than it absolutely needs and also to give them greater
confidence that ‘ ’
it actually needs.
The value of this variable does not necessarily correspond to the
scopes that the respective token actually gives access to. There
is nothing that prevents users from changing the value *after*
creating the token or from editing the token’
So it is pointless to check the value of this variable before
making a request. You also should not query the API to reliably
determine the supported tokens before making a query. Doing the
latter would mean that every request becomes two requests and that
the first request would have to be done using the user’
instead of a token.
-- Command: ghub-token-scopes
Because we cannot be certain that the user hasn’
scopes, Ghub provides this command to make it easy to debug such
issues without having to rely on users being thoughtful enough to
correctly determine the used scopes manually.
Just tell users to run ‘ ’
correct values for the ‘ ’ ‘ ’ ‘ ’
prompted, and to then post the output.
It is to be expected that users will occasionally mess that up so
this command outputs not only the scopes but also the user input so
that you can have greater confidence in the validity of the user’
answer.
Scopes for USERNAME^PACKAGE@HOST: (SCOPE...)
2018-10-02 15:54:39 +02:00
File: ghub.info, Node: API, Next: GraphQL Support, Prev: Using Ghub in a Package, Up: Top
2018-09-10 20:51:14 +02:00
5 API
*****
This section describes the Ghub API. In other words it describes the
2018-10-02 15:54:39 +02:00
public functions and variables provided by the Ghub package and not the
APIs of the supported forges, which can be accessed by using those
functions. The forge APIs are documented at:
• Github: <https://developer.github.com/v3>
• Gitlab: <https://docs.gitlab.com/ee/api/README.html>
• Gitea: <https://docs.gitea.io/en-us/api-usage> and
<https://try.gitea.io/api/swagger>
• Gogs: <https://github.com/gogs/go-gogs-client/wiki>
• Bitbucket:
<https://developer.atlassian.com/bitbucket/api/2/reference>
2018-09-10 20:51:14 +02:00
* Menu:
* Making Requests::
* Authentication::
* Configuration Variables::
File: ghub.info, Node: Making Requests, Next: Authentication, Up: API
5.1 Making Requests
===================
-- Function: ghub-request method resource &optional params &key query
payload headers unpaginate noerror reader username auth host
callback errorback url value error extra method*
This function makes a request for ‘ ’ ‘ ’
‘ ’ ‘ ’ ‘ ’ ‘ ’
additional request data. The response body is returned and the
response header is stored in the variable ‘ ’
• ‘ ’
• ‘ ’
beginning with a slash.
• ‘ ’ ‘ ’ ‘ ’ ‘ ’
used to specify request data. All these arguments are alists
that resemble the JSON expected and returned by the Github
API. The keys are symbols and the values stored in the ‘ ’
(not the ‘ ’
and integers.
The Github API documentation is vague on how data has to be
transmitted and for a particular resource usually just talks
about "parameters". Generally speaking when the ‘ ’
"HEAD" or "GET", then they have to be transmitted as a query,
otherwise as a payload.
• Use ‘ ’ ‘ ’
‘ ’ ‘ ’
• Use ‘ ’
• Use ‘ ’
Instead of an alist, ‘ ’
which case it gets encoded as UTF-8 but is otherwise
transmitted as-is.
• Use ‘ ’
the data is transmitted as headers instead of as a query
or payload. When that is the case, then the Github API
documentation usually mentions it explicitly.
• If ‘ ’
not messaged.
• If ‘ ’
as necessary to get all values. If ‘ ’
number, then it gets at most that many pages. For any other
non-nil value it raises an error.
• If ‘ ’
request fails and ‘ ’ ‘ ’
‘ ’ ‘ ’
• If ‘ ’
from the response buffer. The default is
‘ ’
not return JSON, you might want to use ‘ ’
• If ‘ ’
of that user. It is better to specify the user using the Git
variable ‘ ’
‘ ’
instance.
• Each package that uses Ghub should use its own token. If
‘ ’ ‘ ’ ‘ ’
is used instead. This is only acceptable for personal
utilities. A packages that is distributed to other users
should always use this argument to identify itself, using a
symbol matching its name.
Package authors who find this inconvenient should write a
wrapper around this function and possibly for the
method-specific functions as well.
Beside ‘ ’
‘ ’ ‘ ’
to make a password based request. If the value is a string,
then it is assumed to be a valid token. ‘ ’
explicit token string are only intended for internal and
debugging uses.
If ‘ ’
using the variable ‘ ’
if that is not specified. See ‘ ’
an example.
• If ‘ ’
This defaults to "api.github.com". When a repository is
connected to a Github Enterprise instance, then it is better
to specify that using the Git variable ‘ ’
of using this argument.
• If ‘ ’ ‘ ’
depending on ‘ ’
intended for internal use. Instead of using this argument you
should use function ‘ ’ ‘ ’
functions.
• If ‘ ’ ‘ ’
function makes one or more asynchronous requests and calls
‘ ’ ‘ ’
occurred, then it calls ‘ ’ ‘ ’
‘ ’ ‘ ’
When making asynchronous requests, then no errors are
signaled, regardless of the value of ‘ ’
Both callbacks are called with four arguments.
• For ‘ ’
pages. For ‘ ’
retrieving the last page.
• The headers of the last page as an alist.
• Status information provided by ‘ ’
‘ ’
argument to ‘ ’
• A ‘ ’
‘ ’
any.
-- Function: ghub-continue args
If there is a next page, then this function retrieves that.
This function is only intended to be called from callbacks. If
there is a next page, then that is retrieve and the buffer that the
result will be loaded into is returned, or t if the process has
already completed. If there is no next page, then return nil.
Callbacks are called with four arguments (see ‘ ’
forth argument is a ‘ ’
2018-10-02 15:54:39 +02:00
this function. A callback may use the struct’ ‘ ’
2018-09-10 20:51:14 +02:00
pass additional information to the callback that will be called
after the next request. Use the function ‘ ’
and set the value of that slot.
As an example, using ‘ ’
(ghub-get "/users/tarsius/repos" nil
:callback (lambda (value _headers _status req)
(unless (ghub-continue req)
(setq my-value value))))
is equivalent to:
(ghub-get "/users/tarsius/repos" nil
:unpaginate t
:callback (lambda (value _headers _status _req)
(setq my-value value)))
To demonstrate how to pass information from one callback to the
next, here we record when we start fetching each page:
(ghub-get "/users/tarsius/repos" nil
:extra (list (current-time))
:callback (lambda (value _headers _status req)
(push (current-time) (ghub-req-extra req))
(unless (ghub-continue req)
(setq my-times (ghub-req-extra req))
(setq my-value value))))
-- Variable: ghub-response-headers
A select few Github API resources respond by transmitting data in
the response header instead of in the response body. Because there
are so few of these inconsistencies, ‘ ’
the response body.
To access the response headers use this variable after
‘ ’
2018-10-02 15:54:39 +02:00
-- Function: ghub-response-link-relations req headers payload
2018-09-10 20:51:14 +02:00
This function returns an alist of the link relations in ‘ ’
or if optional ‘ ’
‘ ’
2018-10-02 15:54:39 +02:00
When accessing a Bitbucket instance then the link relations are in
‘ ’ ‘ ’
forcing this function to append those relations to the value of
‘ ’
with ‘ ’ ‘ ’
2018-09-10 20:51:14 +02:00
-- Variable: ghub-override-system-name
If non-nil, the value of this variable is used to override the
value returned by ‘ ’
local machine, which is necessary because Ghub uses separate tokens
for each machine. Also see *note Configuration Variables::.
-- Variable: ghub-github-token-scopes
-- Variable: PACKAGE-github-token-scopes
Such a variable defines the token scopes requested by the
respective package ‘ ’
variable name. ‘ ’
Also see *note Using Ghub in a Package::.
-- Function: ghub-head resource &optional params &key query payload
headers unpaginate noerror reader username auth host callback
errorback
-- Function: ghub-get resource &optional params &key query payload
headers unpaginate noerror reader username auth host callback
errorback
These functions are simple wrappers around ‘ ’
signature is identical to that of the latter, except that they do
not have an argument named ‘ ’
given by the second word in the function name.
As described in the documentation for ‘ ’
the used method whether the value of the ‘ ’
as the query or the payload. For the "HEAD" and "GET" methods it
is used as the query.
-- Function: ghub-put resource &optional params &key query payload
headers unpaginate noerror reader username auth host callback
errorback
-- Function: ghub-post resource &optional params &key query payload
headers unpaginate noerror reader username auth host callback
errorback
-- Function: ghub-patch resource &optional params &key query payload
headers unpaginate noerror reader username auth host callback
errorback
-- Function: ghub-delete resource &optional params &key query payload
headers unpaginate noerror reader username auth host callback
errorback
These functions are simple wrappers around ‘ ’
signature is identical to that of the latter, except that they do
not have an argument named ‘ ’
given by the second word in the function name.
As described in the documentation for ‘ ’
the used method whether the value of the ‘ ’
as the query or the payload. For the "PUT", "POST", "PATCH" and
"DELETE" methods it is used as the payload.
-- Function: ghub-wait resource &optional duration &key username auth
host
Some API requests result in an immediate successful response even
when the requested action has not actually been carried out yet.
An example is the request for the creation of a new repository,
which doesn’
The Github API documentation usually mentions this when describing
an affected resource.
If you want to do something with some resource right after making a
request for its creation, then you might have to wait for it to
actually be created. This function can be used to do so. It
repeatedly tries to access the resource until it becomes available
or until the timeout exceeds. In the latter case it signals
‘ ’
‘ ’
‘ ’
defaulting to 64 seconds. Emacs will block during that time, but
the user can abort using ‘ ’
The first attempt is made immediately and will often succeed. If
not, then another attempt is made after two seconds, and each
subsequent attempt is made after waiting as long as we already
waited between all preceding attempts combined.
See ‘ ’ ’
other arguments.
-- Function: ghub-graphql graphql &optional variables &key username
auth host callback
This function makes a GraphQL request using ‘ ’
‘ ’ ‘ ’ ‘ ’
is a JSON-like alist. The other arguments behave as for
‘ ’
The response is returned as a JSON-like alist. Even if the
response contains ‘ ’
Cursor-handling is likewise left to the caller.
File: ghub.info, Node: Authentication, Next: Configuration Variables, Prev: Making Requests, Up: API
5.2 Authentication
==================
-- Command: ghub-create-token
This command creates a new token using the values it reads from the
user and then stores it according to the variable ‘ ’
It can also be called non-interactively, but you shouldn’
yourself.
This is useful if you want to fully setup things before attempting
to make the initial request, if you want to provide fewer than the
requested scopes or customize ‘ ’
has gone wrong when using the wizard that is used when making a
request without doing this first. (Note that instead of using this
command you can also just repeat the initial request after making
the desired adjustments — that is easier.)
This command reads, in order, the ‘ ’
‘ ’ ‘ ’ ‘ ’
providing reasonable default choices. ‘ ’
scopes that ‘ ’
‘ ’
-- Command: ghub-token-scopes
Users are free to give a token access to fewer scopes than what the
respective package requested. That can, of course, lead to issues,
and package maintainers have to be able to quickly determine if
such a (mis-)configuration is the root cause when users report
issues.
This command reads the required values in the minibuffer and then
shows a message containing these values along with the scopes of
the respective token. It also returns the scopes (only) when
called non-interactively. Also see *note Using Ghub in a
Package::.
File: ghub.info, Node: Configuration Variables, Prev: Authentication, Up: API
5.3 Configuration Variables
===========================
The username and, unless you only use Github.com itself, the Github
Enterprise instance have to be configured using Git variables. In rare
cases it might also be necessary to specify the identity of the local
machine, which is done using a lisp variable.
-- Variable: github.user
The Github.com username. This should be set globally and if you
have multiple Github.com user accounts, then you should set this
locally only for those repositories that you want to access using
the secondary identity.
-- Variable: github.HOST.user
This variable serves the same purpose as ‘ ’
Github Enterprise instance identified by ‘ ’
The reason why separate variables are used is that this makes it
possible to set both values globally instead of having to set one
of the values locally in each and every repository that is
connected to the Github Enterprise instance, not Github.com.
-- Variable: github.host
This variable should only be set locally for a repository and
specifies the Github Enterprise edition that that repository is
connected to. You should not set this globally because then each
and every repository becomes connected to the specified Github
Enterprise instance, including those that should actually be
connected to Github.com.
When this is undefined, then "api.github.com" is used (defined in
the constant ‘ ’
change.)
-- Variable: ghub-override-system-name
Ghub uses a different token for each quadruple ‘
HOST LOCAL-MACHINE)’
extent but that would be more difficult to implement, less
flexible, and less secure (though slightly more convenient).
A token is identified on the respective Github instance (Github.com
or a Github Enterprise instance) using the pair ‘
LOCAL-MACHINE)’
PACKAGE @ LOCAL-MACHINE". ‘ ’ ‘ ’
encoded because the token is stored for ‘ ’ ‘ ’
cannot be used by another user and/or on another instance.
There is one potential problem though; for any given ‘
LOCAL-MACHINE)’
package PACKAGE @ LOCAL-MACHINE"; Github does not allow multiple
tokens with the same description because it uses the description as
the identifier (it could use some hash instead, but alas it does
not).
If you have multiple machines and some of them have the same name,
then you should probably change that as this is not how things
ought to be. However if you dual-boot, then it might make sense to
give that machine the same name regardless of what operating system
you have booted into.
You could use the same token on both operating systems, but setting
that up might be somewhat difficult because it is not possible to
download an existing token from Github. You could, of course,
locally copy the token, but that is inconvenient and would make it
harder to only revoke the token used on your infected Windows
installation without also revoking it for your totally safe *BSD
installation.
Alternatively you can set this variable to a unique value, that
will then be used to identify the local machine instead of the
value returned by ‘ ’
2018-10-02 15:54:39 +02:00
File: ghub.info, Node: GraphQL Support, Next: Support for Other Forges, Prev: API, Up: Top
6 GraphQL Support
*****************
-- Function: ghub-graphql graphql &optional variables &key username
auth host callback silent callback errorback value extra
This function makes a GraphQL request using ‘ ’
‘ ’ ‘ ’ ‘ ’
is a JSON-like alist. The other arguments behave as for
‘ ’
The response is returned as a JSON-like alist. Even if the
response contains ‘ ’
Cursor-handling is likewise left to the caller.
‘ ’ ‘ ’
similar to ‘ ’
value of the ‘ ’ ‘ ’
and constructs ‘ ’ ‘ ’ ‘ ’
‘ ’ ‘ ’ ‘ ’
JSON) and ‘ ’
‘ ’
differently in GraphQL than it does in REST, so users of this function
have to deal with that themselves. Likewise error handling works
differently and has to be done by the caller too.
An early attempt at implementing automatic unpaginating for GraphQL
can be found in the ‘ ’ ’
deleted that by now. On that branch I try to do things as intended by
the designers of GraphQL, using variables and fragments, and drowning in
a sea of boilerplate.
The problem with that approach is that it only works for applications
that fetch specific information on demand and actually want things to be
paginated. I am convinced that GraphQL is very nice for web apps.
However the Forge package for which I am implementing all of this has
very different needs. It wants to fetch "all the data" and "cache" it
locally, so that it is available even when there is no internet
connection. GraphQL was designed around the idea that you should be
able to "ask for what you need and get exactly that". But when that
boils down to "look, if I persist, then you are going to hand me over
all the data anyway, so just caught it up already", then things start to
fall apart. If Github’
completely, then teaching ‘ ’
enough.
But it doesn’
huge amounts of repetitive boilerplate, which is so boring to write that
doing it without introducing bugs left and right is near impossible; so
I decided to give up on GraphQL variables, fragments and conditions, and
instead implement something more powerful, though also more opinionated.
-- Function: ghub--graphql-vacuum query variables callback &optional
until &key narrow username auth host forge
This function is an opinionated alternative to ‘ ’
relies and dark magic to get the job done.
It makes an initial request using ‘ ’
paginated edges in the returned data and makes more requests to
resolve them. In order to do so it automatically transforms the
initial ‘ ’
edge. The data retrieved by subsequent requests is then injected
into the data of the original request before that is returned or
passed to the callback. If subsequently retrieved data features
new paginated edges, then those are followed recursively.
The end result is essentially the same as using ‘ ’
only it were possible to say "do not paginate anything". The
implementation is much more complicated because it is not possible
to do that.
‘ ’
‘ ’
but the format is somewhat different than as documented for that
package. Also only a subset of the GraphQL features are supported;
fragments for example are not, and magical stuff happens to
variables. This is not documented yet, I am afraid. Look at
existing callers.
‘ ’ ‘ ’
‘ ’ ‘ ’
‘ ’
the value ‘ ’
elements from the retrieved data if necessary. Look at
‘ ’
you "cache" the response locally and want to avoid fetching data
again that you already have.
Other arguments behave as for ‘ ’ ‘ ’
more or less.
Using ‘ ’
functions are implemented. These functions are not part of the public
API yet and are very much subject to change.
-- Function: ghub-fetch-repository owner name callback &optional until
&key username auth host forge
This function asynchronously fetches forge data about the specified
repository. Once all data has been collected, ‘ ’
with the data as the only argument.
-- Function: ghub-fetch-issue owner name callback &optional until &key
username auth host forge
This function asynchronously fetches forge data about the specified
issue. Once all data has been collected, ‘ ’
the data as the only argument.
-- Function: ghub-fetch-pullreq owner name callback &optional until
&key username auth host forge
This function asynchronously fetches forge data about the specified
pull-request. Once all data has been collected, ‘ ’
called with the data as the only argument.
Note that in order to avoid duplication all of these functions base
their initial query on the query stored in ‘ ’
latter two pass that query through ‘ ’
then used ‘ ’
interested in. These two functions are also used internally, when
unpaginating, but as demonstrated here they can be useful even before
making an initial request.
File: ghub.info, Node: Support for Other Forges, Prev: GraphQL Support, Up: Top
7 Support for Other Forges
**************************
* Menu:
* Forge Functions and Variables::
* Forge Limitations and Notes::
File: ghub.info, Node: Forge Functions and Variables, Next: Forge Limitations and Notes, Up: Support for Other Forges
7.1 Forge Functions and Variables
=================================
Originally Ghub supported only Github but now it also supports Gitlab,
Gitea, Gogs and Bitbucket. The function ‘ ’
‘ ’
but can be told to act on another forge using their FORGE argument.
The FORGE argument only specifies what kind of forge to act on, not
which instance. The HOST argument can be used to select the instance.
For some forges a default instance is defined:
• Forge ‘ ’ ‘ ’
• Forge ‘ ’ ‘ ’
• Forge ‘ ’ ‘ ’
• No canonical host exists for the ‘ ’ ‘ ’
‘ ’
Together the FORGE and HOST arguments specify the forge type and
instance. In addition to that, it is also necessary to specify on whose
behalf the request is being made, which can be done using the USERNAME
and AUTH arguments.
Having to specify these arguments for every request is inconvenient.
Additional variables and convenience functions can be used to make that
unnecessary in most cases.
These variables can be set globally and/or for a specific repository
as explained in *note Configuration Variables:: with a focus on Github
instances. To summarize:
• For <https://github.com> the Git variable ‘ ’
the user.
• For another ‘ ’ ‘ ’
specifies the user. The HOST in that variable name is the same as
the value of the HOST argument of the called function.
• Instead of specifying the HOST in every function call, the Git
variable ‘ ’
locally.
For ‘ ’ ‘ ’
• ‘ ’
• ‘ ’ ‘ ’
instance.
• ‘ ’ ‘ ’
is non-nil
• ‘ ’
• ‘ ’ ‘ ’
instance.
• ‘ ’ ‘ ’
argument is non-nil.
For ‘ ’ ‘ ’
however for some of the ‘ ’
for these two forges:
• ‘ ’ ‘ ’
exists.
• ‘ ’ ‘ ’
• ‘ ’ ‘ ’
is non-nil
• ‘ ’ ‘ ’
exists.
• ‘ ’ ‘ ’
• ‘ ’ ‘ ’
non-nil
‘ ’ ‘ ’
any of the supported forge types, but except when making a request for a
‘ ’
To avoid that, functions named ‘ ’ ‘ ’
also available. The following forms are equivalent, for example:
(ghub-get ... :auth 'PACKAGE :forge 'gitlab)
(glab-get ... :auth 'PACKAGE)
These forms would remain equivalent even if you did not specify a
value for the AUTH arguments — but you should not do that if you plan to
share your code with others (see *note Using Ghub in a Package::). If
you do omit AUTH, then the request is made on behalf of the ‘ ’
package, *regardless* of the symbol prefix of the function you use to do
so.
All ‘ ’ ‘ ’
limited to ‘ ’
‘ ’ ‘ ’
instead pass constant values for the arguments METHOD and/or FORGE.
File: ghub.info, Node: Forge Limitations and Notes, Prev: Forge Functions and Variables, Up: Support for Other Forges
7.2 Forge Limitations and Notes
===============================
• The token creation wizard is only available for ‘ ’
because all other forges do not support using the API to create an
API token. As a consequence, if the user makes a request and the
necessary token cannot be found, then that results in an error.
Tokens can be created at:
• Gitlab: <https://gitlab.com/profile/personal_access_tokens>
• Bitbucket:
<https://bitbucket.org/account/user/tarsius/app-passwords>
• Gitea: <https://localhost:3000/user/settings/applications>
2018-09-10 20:51:14 +02:00
2018-10-02 15:54:39 +02:00
• Gogs: <https://localhost:3000/user/settings/applications>
2018-09-10 20:51:14 +02:00
2018-10-02 15:54:39 +02:00
Also see *note Manually Creating and Storing a Token:: and *note
How Ghub uses Auth-Source::.
2018-09-10 20:51:14 +02:00
2018-10-02 15:54:39 +02:00
• As mentioned in the previous node, the variables ‘ ’
‘ ’
2018-09-10 20:51:14 +02:00
2018-10-02 15:54:39 +02:00
• Gitea and Gogs do not support limiting a token to certain scopes.
2018-09-10 20:51:14 +02:00
2018-10-02 15:54:39 +02:00
• The Bitbucket API is fairly broken. Some resources only work if a
slash is appended while others only work if no slash is appended.
I am unable to access any private repositories and some resources
don’
information is part of the response body instead of the header.
Due to such issues it is possible that I will eventually have to
remove support for Bitbucket altogether.
2018-09-10 20:51:14 +02:00
2018-10-02 15:54:39 +02:00
• The Gitlab API documentation is not always accurate, though I don’
have an example at hand. It also isn’
occationally difficult to find the information one is looking for.
2018-09-10 20:51:14 +02:00
2018-10-02 15:54:39 +02:00
• Where one would use ‘ ’
has to use ‘ ’
2018-09-10 20:51:14 +02:00
2018-10-02 15:54:39 +02:00
(glab-get "/projects/python-mode-devs%2Fpython-mode")
2018-09-10 20:51:14 +02:00
Tag Table:
Node: Top
2018-10-02 15:54:39 +02:00
Node: Introduction
Node: Getting Started
Node: Setting the Username
Node: Interactively Creating and Storing a Token
Node: Manually Creating and Storing a Token
Node: How Ghub uses Auth-Source
Node: Using Ghub in Personal Scripts
Node: Using Ghub in a Package
Node: API
Node: Making Requests
Node: Authentication
Node: Configuration Variables
Node: GraphQL Support
Node: Support for Other Forges
Node: Forge Functions and Variables
Node: Forge Limitations and Notes
2018-09-10 20:51:14 +02:00
End Tag Table
Local Variables:
coding: utf-8
End:
