866 lines
36 KiB
Plaintext
866 lines
36 KiB
Plaintext
This is ghub.info, produced by makeinfo version 5.2 from ghub.texi.
|
||
|
||
Copyright (C) 2017 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
|
||
******************************
|
||
|
||
Ghub is a library that provides basic support for using the Github API
|
||
from Emacs packages. It abstracts access to API resources using only a
|
||
handful of functions that are not resource-specific.
|
||
|
||
It also handles the creation, storage and use of access tokens using
|
||
a setup wizard, to make it easier for users to get started and to reduce
|
||
the support burden imposed on package maintainers. It also comes with a
|
||
comprehensive manual to address the cases when things don’t just work as
|
||
expected.
|
||
|
||
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 adaption. It is assumed that wide
|
||
adoption would make life easier for users and maintainers alike, because
|
||
then all packages that talk to the Github API could be configured the
|
||
same way.
|
||
|
||
This manual is for Ghub version 1.3.0 (v1.3.0-31-g6443c4f+1).
|
||
|
||
Copyright (C) 2017 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::
|
||
* Limitations::
|
||
* Getting Started::
|
||
* Using Ghub in Personal Scripts::
|
||
* Using Ghub in a Package::
|
||
* API::
|
||
|
||
— 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::
|
||
|
||
|
||
|
||
File: ghub.info, Node: Introduction, Next: Limitations, Prev: Top, Up: Top
|
||
|
||
1 Introduction
|
||
**************
|
||
|
||
Ghub is a library that provides basic support for using the Github API
|
||
from Emacs packages. It abstracts access to API resources using only a
|
||
handful of functions that are not resource-specific.
|
||
|
||
It also handles the creation, storage and use of access tokens using
|
||
a setup wizard, to make it easier for users to get started and to reduce
|
||
the support burden imposed on package maintainers. It also comes with a
|
||
comprehensive manual to address the cases when things don’t just work as
|
||
expected.
|
||
|
||
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 adaption.
|
||
|
||
Fancier interfaces can 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 does no longer also dictate 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
|
||
expects the appropriate token to be made available to them.
|
||
|
||
Ghub uses the built-in ‘auth-source’ library to store access tokens.
|
||
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 adapted) it was up to
|
||
package authors to decide if things should be easy or secure. (Note
|
||
that ‘auth-source’ defaults to "easy" — you have been warned.)
|
||
|
||
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 defined in some package and that
|
||
ultimately results in ‘ghub-request’ being called and the appropriate
|
||
token is not available 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: Limitations, Next: Getting Started, Prev: Introduction, Up: Top
|
||
|
||
2 Limitations
|
||
*************
|
||
|
||
As mentioned, Ghub restricts itself to provide core functionality and
|
||
leaves it to other libraries to do opinionated things on top of that.
|
||
But currently there also are some limitations that concern the core
|
||
parts. Obviously these limitations have to be lifted to maximize
|
||
adaption and so they will.
|
||
|
||
These secondary features already exist (just mentioning them, so you
|
||
don’t assume that they don’t):
|
||
|
||
• Support for Github Enterprise instances.
|
||
|
||
• Support for token scope validation.
|
||
|
||
These features will likely never be implemented in Ghub:
|
||
|
||
• Functions for particular resources.
|
||
|
||
• Using something other than json-like alists to handle what the
|
||
Github API calls "parameters".
|
||
|
||
• Retrieving an existing token. Github does not support it so we
|
||
cannot do it. If you lose your local copy of a token, then you
|
||
have to replace it with a new one.
|
||
|
||
These features are not supported yet:
|
||
|
||
• Asynchronous requests are not supported yet.
|
||
|
||
• The Github GraphQL API is not supported yet.
|
||
|
||
• If a request fails due to a missing scope, then that isn’t handled
|
||
by ‘ghub-request’ yet. For now package authors just have to hope
|
||
that users don’t mess with scopes or handle such errors themselves.
|
||
|
||
Likewise, other errors too should be handled by Ghub.
|
||
|
||
• Packages cannot request additional scopes.
|
||
|
||
Once a token has been created a package cannot request new scopes
|
||
that it previously did not need. I am not quite sure yet whether
|
||
Ghub should support that. An alternative would be to let packages
|
||
at least invalidate their own tokens.
|
||
|
||
• Other Git forges (Gitlab, Bitbucket…) are not supported.
|
||
|
||
Support for other forges will likely be implemented using *other*
|
||
libraries that are very similar to this library. Whether common
|
||
code will be factored out into a library to be used by all these
|
||
libraries or whether some code duplication is to be preferred, has
|
||
not been decided yet.
|
||
|
||
|
||
File: ghub.info, Node: Getting Started, Next: Using Ghub in Personal Scripts, Prev: Limitations, Up: Top
|
||
|
||
3 Getting Started
|
||
*****************
|
||
|
||
If you would like to use a package that uses this library, then just do
|
||
so. If the necessary information isn’t available when it attempts to
|
||
make a request, then you will be asked to provide it.
|
||
|
||
* 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
|
||
|
||
3.1 Setting the Username
|
||
========================
|
||
|
||
If you haven’t set the Git variable ‘github.user’ yet when making a
|
||
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 ‘git config --global github.user
|
||
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
|
||
‘https://example.com/api/v3’, then you should do this:
|
||
|
||
# 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 ‘github.example.com/api/v3.user’, then you will be
|
||
asked to provide the value when trying to make a request, but you do
|
||
have to manually set ‘github.host’, or Ghub assumes that you are trying
|
||
to access ‘api.github.com’.
|
||
|
||
|
||
File: ghub.info, Node: Interactively Creating and Storing a Token, Next: Manually Creating and Storing a Token, Prev: Setting the Username, Up: Getting Started
|
||
|
||
3.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’t have to worry about creating and storing a token
|
||
yourself and can just make a request. Note however that you don’t have
|
||
to use the setup wizard described below. Alternatively you can perform
|
||
the setup manually as described in the next section.
|
||
|
||
Unfortunately the wizard does not work (yet?) if you have enabled
|
||
two-factor authentication, in which case the token has to be created and
|
||
stored manually.
|
||
|
||
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 locally according to `auth-sources':
|
||
("~/.authinfo" "~/.authinfo.gpg" "~/.netrc")
|
||
Store on Github as:
|
||
"Emacs package FOO @ LOCAL-MACHINE"
|
||
|
||
WARNING: If you have enabled two-factor authentication
|
||
then you have to create the token manually.
|
||
|
||
If in doubt, then abort and view the documentation first.
|
||
|
||
Create and store such a token? (yes or no)
|
||
|
||
If you don’t have any doubts, then answer "yes". Lets address some
|
||
of the doubts that you might have:
|
||
|
||
• Unfortunately Ghub cannot know whether you have enabled two-factor
|
||
authentication without making a request using basic (password)
|
||
authentication, which it cannot do if you have enabled two-factor
|
||
authentication. It also cannot determine whether you have enabled
|
||
two-factor authentication depending on whether a request fails or
|
||
not because there are other reasons why a request might fail.
|
||
|
||
So this warning is always displayed and you are expected to know
|
||
whether you have enabled two-factor authentication or not. If you
|
||
have, then you must abort and see *note Manually Creating and
|
||
Storing a Token::.
|
||
|
||
• ‘Host’ usually is "api.github.com" and that’s usually what you
|
||
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 as described in the next section.
|
||
|
||
• ‘User’ should be your Github.com (or Github Enterprise instance)
|
||
username. If it is something else, then you made a mistake at the
|
||
first prompt or during the step describe in the previous section
|
||
and have to refer to that in order to fix this issue.
|
||
|
||
• ‘Package’ should be the name of the package you are using to access
|
||
the Github API.
|
||
|
||
If it is ‘ghub’, then the package author disregarded that
|
||
convention and you should probably report a bug in the issue
|
||
tracker of that package.
|
||
|
||
Or you yourself are using ‘ghub-request’ or one of its wrappers
|
||
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 ‘ghub-github-token-scopes’ before triggering the
|
||
wizard again.
|
||
|
||
• Each PACKAGE has to specify the tokens that it needs using a
|
||
variable named ‘PACKAGE-github-token-scopes’. The doc-string of
|
||
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 ‘auth-sources’ is shown. The default value causes
|
||
secrets to be stored in plain text. Because this might be
|
||
unexpected, Ghub additionally displays a warning when appropriate.
|
||
|
||
WARNING: ... unencrypted ... TODO implement ...
|
||
|
||
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 used 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 FOO @ 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.
|
||
|
||
In either case you will have to use something other than the value
|
||
returned by ‘system-name’ to identify the current machine or
|
||
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
|
||
‘ghub-override-system-name’. See *note Configuration Variables::
|
||
for details.
|
||
|
||
|
||
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
|
||
|
||
3.3 Manually Creating and Storing a Token
|
||
=========================================
|
||
|
||
If you have enabled two-factor authentication, then you have to create
|
||
and store access tokens yourself. You might also prefers to always do
|
||
it manually to have more control than when relying on the setup wizard.
|
||
|
||
If you cannot or don’t want to use the wizard then you have to (1)
|
||
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 PACKAGE has to specify the scopes that it wants in
|
||
the variable named ‘PACKAGE-ghub-token-scopes’. The doc-string of such
|
||
variables should document what the various scopes are needed for.
|
||
|
||
To create or edit a token go to <https://github.com/settings/tokens>.
|
||
|
||
Finally store the token in a place where Ghub looks for it as
|
||
describe in *note How Ghub uses Auth-Source::.
|
||
|
||
|
||
File: ghub.info, Node: How Ghub uses Auth-Source, Prev: Manually Creating and Storing a Token, Up: Getting Started
|
||
|
||
3.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 ‘auth-sources’ controls how and where Auth-Source stores
|
||
new secrets and where it looks for known secrets. The default value is
|
||
‘("~/.authinfo" "~/.authinfo.gpg" "~/.netrc")’, which means that it
|
||
looks in all of these files in order to find secrets and that it stores
|
||
new secrets in ‘~/.authinfo’ because that is the first element of the
|
||
list. It doesn’t matter which files already do or don’t exist when
|
||
storing a new secret, the first file is always used.
|
||
|
||
Secrets are stored in ‘~/.authinfo’ in plain text. If you don’t want
|
||
that (good choice), then you have to customize ‘auth-sources’ e.g. by
|
||
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" and the package is named
|
||
"stardust", an entry in one of the three mentioned files would then look
|
||
like this:
|
||
|
||
machine api.github.com 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
|
||
|
||
4 Using Ghub in Personal Scripts
|
||
********************************
|
||
|
||
You can use ‘ghub-request’ and its wrapper functions in your personal
|
||
scripts of course. Unlike when you use Ghub from a package that you
|
||
distribute for others to use, you don’t have to specify a package in
|
||
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 AUTH argument, then a request is made on
|
||
behalf of the ‘ghub’ package itself. Like for any package that uses
|
||
Ghub, ‘ghub’ has to declare what scopes it needs, using, in this case,
|
||
the variable ‘ghub-github-token-scopes’.
|
||
|
||
The default value of that variable is ‘(repo)’ and you might want to
|
||
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’s effective scopes use the command
|
||
‘ghub-token-scopes’, described in the next section.
|
||
|
||
|
||
File: ghub.info, Node: Using Ghub in a Package, Next: API, Prev: Using Ghub in Personal Scripts, Up: Top
|
||
|
||
5 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 PACKAGE have to be defined using the variable
|
||
‘PACKAGE-github-token-scopes’, and you have to tell ‘ghub-request’ on
|
||
behalf of what package a request is being made by passing the symbol
|
||
PACKAGE as the value of its AUTH argument.
|
||
|
||
(ghub-request "GET" "/user" nil :auth 'PACKAGE)
|
||
|
||
-- Variable: PACKAGE-github-token-scopes
|
||
|
||
This variable defines the token scopes requested by the package
|
||
named PACKAGE. The doc-string should explain what the various
|
||
scopes are needed for to prevent users from giving PACKAGE fewer
|
||
permissions than it absolutely needs and also to give them greater
|
||
confidence that PACKAGE is only requesting the permissions that it
|
||
actually need.
|
||
|
||
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’s scopes later on.
|
||
|
||
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’s password
|
||
instead of a token.
|
||
|
||
-- Command: ghub-token-scopes
|
||
|
||
Because we cannot be certain that the user hasn’t messed up the
|
||
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 ‘M-x ghub-token-scopes’ and to provide the
|
||
correct values for the HOST, USERNAME and PACKAGE when prompted,
|
||
and to then post the output.
|
||
|
||
It is to be expected that users will occasionally mess that up so
|
||
this command does not only output the scopes but also the user
|
||
input so that you can have greater confidence in the validity of
|
||
the user’s answer.
|
||
|
||
Scopes for USERNAME^PACKAGE@HOST: (SCOPE...)
|
||
|
||
|
||
File: ghub.info, Node: API, Prev: Using Ghub in a Package, Up: Top
|
||
|
||
6 API
|
||
*****
|
||
|
||
This section describes the Ghub API. In other words it describes the
|
||
public functions and variables provided by the Ghub library and not the
|
||
Github API that can be accessed by using those functions. The latter is
|
||
documented at <https://developer.github.com/v3>.
|
||
|
||
* Menu:
|
||
|
||
* Making Requests::
|
||
* Authentication::
|
||
* Configuration Variables::
|
||
|
||
|
||
File: ghub.info, Node: Making Requests, Next: Authentication, Up: API
|
||
|
||
6.1 Making Requests
|
||
===================
|
||
|
||
-- Function: ghub-request method resource &optional params &key query
|
||
payload headers unpaginate noerror reader username auth host
|
||
|
||
This function make a request for RESOURCE using METHOD. PARAMS,
|
||
QUERY, PAYLOAD and/or HEADERS are alists holding additional request
|
||
data. The response body is returned and the response header in
|
||
stored in the variable ‘ghub-response-headers’.
|
||
|
||
• METHOD is the http method, given as a string.
|
||
|
||
• RESOURCE is the resource to access, given as a string
|
||
beginning with a slash.
|
||
|
||
• PARAMS, QUERY, PAYLOAD and HEADERS are alists and are 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 are stored in the ‘cdr’ (not
|
||
the ‘cadr’) and can be strings, integers and lists of strings
|
||
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 METHOD is
|
||
"HEAD" or "GET", then they have to be transmitted as a query,
|
||
otherwise as a payload.
|
||
|
||
• Use PARAMS to automatically transmit like QUERY or
|
||
PAYLOAD would depending on METHOD.
|
||
|
||
• Use QUERY to explicitly transmit data as a query.
|
||
|
||
• Use PAYLOAD to explicitly transmit data as a payload.
|
||
|
||
• Use HEADERS for those rare resources that require that
|
||
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 UNPAGINATE is non-nil, then this function makes multiple
|
||
requests if necessary to get all items at RESOURCE.
|
||
|
||
• If NOERROR is non-nil, then no error is raised if the request
|
||
fails and ‘nil’ is returned instead.
|
||
|
||
• If READER is non-nil, then it is used to read and return from
|
||
the response buffer. The default is
|
||
‘ghub--read-json-response’. For the very few resources that
|
||
do not return json, you might want to use
|
||
‘ghub--read-raw-response’.
|
||
|
||
• If USERNAME is non-nil, then the request is made on behalf of
|
||
that user. It is better to specify the user using the Git
|
||
variable ‘github.user’ for "api.github.com", or
|
||
‘github.HOST.user’ if connecting to a Github Enterprise
|
||
instance.
|
||
|
||
• Each package that uses Ghub should use its own token. If AUTH
|
||
is nil, then the generic ‘ghub’ token 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 also.
|
||
|
||
Some symbols have a special meaning. ‘none’ means to make an
|
||
unauthorized request. ‘basic’ means to make a password based
|
||
request. If the value is a string, then it is assumed to be a
|
||
valid token. ‘basic’ and an explicit token string are only
|
||
intended for internal and debugging uses.
|
||
|
||
If AUTH is a package symbol, then the scopes are specified
|
||
using the variable ‘AUTH-github-token-scopes’. It is an error
|
||
if that is not specified. See ‘ghub-github-token-scopes’ for
|
||
an example.
|
||
|
||
• If HOST is non-nil, then connect to that Github instance.
|
||
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 ‘github.host’ instead
|
||
of using this argument.
|
||
|
||
-- 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 ‘ghub-request’ always returns
|
||
the response body.
|
||
|
||
To access the response header use this variable after
|
||
‘ghub-request’ has returned.
|
||
|
||
-- Variable: ghub-override-system-name
|
||
|
||
If non-nil, the value of this variable is used to override the
|
||
value returned by ‘system-name’ for the purpose of identifying the
|
||
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 define the token scopes requested by the respective
|
||
package PACKAGE given by the first word in the variable name.
|
||
‘ghub’ itself is treated like any other package. Also see *note
|
||
Using Ghub in a Package::.
|
||
|
||
-- Function: ghub-head resource &optional params &key query payload
|
||
headers unpaginate noerror reader username auth host
|
||
-- Function: ghub-get resource &optional params &key query payload
|
||
headers unpaginate noerror reader username auth host
|
||
|
||
These functions are simple wrappers around ‘ghub-request’. Their
|
||
signature is identical to that of the latter, except that they do
|
||
not have an argument named METHOD. The http method is instead given
|
||
by the second word in the function name.
|
||
|
||
As described in the documentation for ‘ghub-request’, it depends on
|
||
the used method whether the value of the PARAMS argument is used 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
|
||
-- Function: ghub-post resource &optional params &key query payload
|
||
headers unpaginate noerror reader username auth host
|
||
-- Function: ghub-patch resource &optional params &key query payload
|
||
headers unpaginate noerror reader username auth host
|
||
-- Function: ghub-delete resource &optional params &key query payload
|
||
headers unpaginate noerror reader username auth host
|
||
|
||
These functions are simple wrappers around ‘ghub-request’. Their
|
||
signature is identical to that of the latter, except that they do
|
||
not have an argument named METHOD. The http method is instead given
|
||
by the second word in the function name.
|
||
|
||
As described in the documentation for ‘ghub-request’, it depends on
|
||
the used method whether the value of the PARAMS argument is used 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 username auth host duration
|
||
|
||
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’t cause the repository to immediately become available.
|
||
The Github API documentation usually mention this when describing
|
||
an affected resource.
|
||
|
||
If you want to do something with some resource right after creating
|
||
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 ‘ghub-error’.
|
||
|
||
RESOURCE specifies the resource that this function waits for.
|
||
|
||
DURATION specifies for how many seconds to wait at most, defaulting
|
||
to 64 seconds. Emacs will block during that time, but the user can
|
||
abort using ‘C-g’.
|
||
|
||
The first attempt is made immediately and often that will actually
|
||
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 ‘ghub-request’’s documentation above for information about the
|
||
other arguments.
|
||
|
||
|
||
File: ghub.info, Node: Authentication, Next: Configuration Variables, Prev: Making Requests, Up: API
|
||
|
||
6.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 variable ‘auth-sources’. It
|
||
can also be called non-interactively, but you shouldn’t do that
|
||
yourself.
|
||
|
||
This is useful if you want fully setup things before attempting to
|
||
make the initial request, if you want to provide fewer than the
|
||
requested scopes or customize ‘auth-sources’ first, or if something
|
||
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 that order, the HOST (Github instance), the
|
||
USERNAME, the PACKAGE and the SCOPES in the minibuffer, providing
|
||
reasonable default choices. SCOPES defaults to the scopes that
|
||
PACKAGE requests using the variable ‘PACKAGE-github-token-scopes’.
|
||
|
||
-- 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
|
||
|
||
6.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.user’ but for the
|
||
Github Enterprise instance identified by HOST.
|
||
|
||
The reason why separate variables are used is that this makes it
|
||
possible to set the 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 (define in
|
||
the constant ‘ghub-default-host-host’, which you should never
|
||
attempt to change.)
|
||
|
||
-- Variable: ghub-override-system-name
|
||
|
||
Ghub uses a different token for each quadruple ‘(USERNAME PACKAGE
|
||
HOST LOCAL-MACHINE)‘. Theoretically it could reuse tokens to some
|
||
extend 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 ‘(PACKAGE .
|
||
LOCAL-MACHINE)‘, or more precisely the string "Emacs package
|
||
PACKAGE @ LOCAL-MACHINE". USERNAME and HOST do not have to be
|
||
encoded because the token is stored for USERNAME on HOST and cannot
|
||
be used by another user and/or on another instance.
|
||
|
||
There is one potential problem though; for any given ‘(PACKAGE .
|
||
LOCAL-MACHINE)‘ there can only be one token identified by "Emacs
|
||
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 thing 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 ‘system-name’.
|
||
|
||
|
||
|
||
Tag Table:
|
||
Node: Top757
|
||
Node: Introduction2781
|
||
Node: Limitations5317
|
||
Node: Getting Started7458
|
||
Node: Setting the Username7960
|
||
Node: Interactively Creating and Storing a Token9385
|
||
Node: Manually Creating and Storing a Token15340
|
||
Node: How Ghub uses Auth-Source16428
|
||
Node: Using Ghub in Personal Scripts18071
|
||
Node: Using Ghub in a Package19520
|
||
Node: API22085
|
||
Node: Making Requests22512
|
||
Node: Authentication31069
|
||
Node: Configuration Variables32868
|
||
|
||
End Tag Table
|
||
|
||
|
||
Local Variables:
|
||
coding: utf-8
|
||
End:
|