Next: , Previous: , Up: Getting Started   [Contents][Index]

2.3 Creating and Storing a Token

2.3.1 Creating a Token

To create a token, use the web interface of the host you want to connect to. Here is a list of pages to do this for certain popular hosts:

For other forges we cannot provide a functioning URL because they contain unknown values such as your name. Just go to the general settings page of the respective host and then go from there.

Except on gitea and gogs each token can be limited to certain "scopes", i.e., it is possible to limit for which purposes any given token can be used.

Before you create a token to be used for a certain package, you should consult the documentation of that package, which in turn should tell you which scopes are needed and why. The Forge package for example does so in (forge)Token Creation.

2.3.2 Storing a Token

Please also see (auth)Top for all the gory details about Auth-Source.

The variable auth-sources controls how and where Auth-Source keeps its secrets. The default value is a list of three files: ("~/.authinfo" "~/.authinfo.gpg" "~/.netrc"), but to avoid confusion you should make sure that only one of these files exists, and then you should also adjust the value of the variable to only ever use that file, for example: 

(setq auth-sources '("~/.authinfo"))

In ~/.authinfo secrets are stored in plain text. If you don’t want that, then you should use the encrypted ~/.authinfo.gpg instead: 

(setq auth-sources '("~/.authinfo.gpg"))

Auth-Source also supports storing secrets in various external key-chains. See (auth)Top for more information.

The default 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 Github username is "ziggy", the package is named "forge", and you want to access Github.com with the token "012345abcdef…", an entry in one of the three mentioned files would then look like this: 

machine api.github.com login ziggy^forge password 012345abcdef...

Assuming your Gitlab username is "ziggy", the package is named "forge", and you want to access Gitlab.com with the token "012345abcdef…", an entry in one of the three mentioned files would then look like this: 

machine gitlab.com/api/v4 login ziggy^forge password 012345abcdef...

Next: Github Configuration Variables, Previous: Setting the Username, Up: Getting Started   [Contents][Index]