Tips and Tricks

Please add your tips and tricks here.

---

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

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 "[email protected]:"]
	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.

Accessing private GitLab instances via HTTP

Only secure instances are supported by default (see issue #9 for details).

However, private GitLab instances via HTTP can easily be configured using the following workaround:

(defclass forge-gitlab-http-repository (forge-gitlab-repository)
  ((issues-url-format         :initform "http://%h/%o/%n/issues")
   (issue-url-format          :initform "http://%h/%o/%n/issues/%i")
   (issue-post-url-format     :initform "http://%h/%o/%n/issues/%i#note_%I")
   (pullreqs-url-format       :initform "http://%h/%o/%n/merge_requests")
   (pullreq-url-format        :initform "http://%h/%o/%n/merge_requests/%i")
   (pullreq-post-url-format   :initform "http://%h/%o/%n/merge_requests/%i#note_%I")
   (commit-url-format         :initform "http://%h/%o/%n/commit/%r")
   (branch-url-format         :initform "http://%h/%o/%n/commits/%r")
   (remote-url-format         :initform "http://%h/%o/%n")
   (create-issue-url-format   :initform "http://%h/%o/%n/issues/new")
   (create-pullreq-url-format :initform "http://%h/%o/%n/merge_requests/new")
   (pullreq-refspec :initform "+refs/merge-requests/*/head:refs/pullreqs/*")))

(add-to-list 'ghub-insecure-hosts "git.private.network.repo/api/v4")

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)))