Tips and Tricks

Please add your tips and tricks here. If you prefer, you can instead create a show & tell "discussion".

Also see the list of show & tell "discussions".

---

Using SSH identities

Given an SSH identity such as

$ cat ~/.ssh/config
Host gh
     HostName github.com
     User git

git knows how to deal with the gh host alias, for example:

$ git clone gh:magit/forge

Teaching Forge about SSH identities

Important

Starting with Forge v0.4.0, this isn't necessary anymore. If you added such an entry in the past, you should remove it.

Forge needs a little bit of help though. You need to add a new entry to forge-alist.

The entry for github.com looks like this:

("github.com"
 "api.github.com"
 "github.com"
 forge-github-repository)

You need to add another entry for gh, which is very similar to the github.com entry, should come after that, and looks like this:

("gh"
 "api.github.com"
 "github.com"
 forge-github-repository)

Using Git URL rewriting instead

Given the above SSH identity you might want to consider using Git's URL rewriting functionality instead. To do so remove the respective configuration from ~/.ssh/config, and then add something like this to ~/.config/git/config:

[url "git@github.com:"]
	insteadOf = gh:

If you use this approach, then you do not have to (and should not) add an entry for gh to forge-alist.

Accessing private repositories or organization

Please ensure your access token has the necessary permissions. The API would likely return a 404 to not disclose private repositories. Example for Github these scopes are required:

• repo grants full read/write access to private and public repositories.
• user grants access to profile information.
• read:org grants read-only access to organization membership.

It's also worth validating that (if applicable) you enable SSO for the token in question (image below redacted).

Accessing unsecured forges

Initially only secured forges (those using tls) were supported (because I assumed that nobody would forgo securing their gitlab and github instances, or even that doing so would be impossible.)

Nowadays (forge v0.4.0) it isn't much more complicated to use unsecured instances than those that are properly configured. In addition to the usual setup, you only have to add the APIHOST and WEBHOST of the respective entry of forge-alist to ghub-insecure-hosts.

For example, for an entry

("example.com" "example.com/api/v4" "www.example.com" forge-gitlab-repository)

use

(add-to-list 'ghub-insecure-hosts "example.com/api/v4")
(add-to-list 'ghub-insecure-hosts "www.example.com")

(An earlier kludge for unsecured forges made it necessary that you defined a new forge-repository-derived class. If you have done that in the past and want to move to the simpler setup described above, then you must first remove all repositories that already use that class from the database, and adjust all the entries of forge-alist that reference that class.)

Accessing private forge through zero trust proxy

To access a private forge through a zero-trust proxy, an additional access token must be attached to requests. Let tmp-access-token be a function that returns access token in a string. We can advise function ghub--headers to inject the access token:

(advice-add 'ghub--headers :around
            (lambda (original-fun headers host &rest r)
              (if (string-match-p (regexp-quote "zero-trust.forge") host)
                  (push (cons "access-token" (tmp-access-token)) headers)
                nil)
              (apply original-fun headers host r)))