Skip to main content

Using Sapling with GitHub

When using Sapling with GitHub, we strongly recommend the following:

  • Install the GitHub CLI (gh), as some of our current GitHub integrations rely on it.
  • Using the GitHub CLI, authenticate with GitHub via gh auth login --git-protocol https.

In order for Sapling to work with GitHub pull requests on your behalf, you must provide it with a Personal Access Token (PAT). While the GitHub CLI is not the only way to obtain a PAT, it is certainly one of the most convenient.

While we ultimately plan to remove the requirement of installing the GitHub CLI to use Sapling with GitHub (though the PAT will still be necessary), you will still need some mechanism to cache your GitHub credentials in Git to enjoy the best experience with Sapling. For example, a graphical interface like Interactive Smartlog would be unpleasant to use if it prompted your for a password every time it needed to talk to GitHub. To avoid this, GitHub recommends two solutions for caching your GitHub credentials, the GitHub CLI being the primary choice.

While GitHub gives you the option of cloning a repo with either HTTPS or SSH URLs, HTTPS is generally considered easier to use because HTTPS default port 443 is far less likely to be blocked by a firewall than SSH default port 22.

Cloning a repo​

Once you have authenticated via gh auth login --git-protocol https, you should be able to clone any GitHub repository via its HTTPS URL that you have access to using Sapling:

sl clone https://github.com/facebook/sapling

With the GitHub CLI caching your credentials, you will be able to run commands like sl ssl to see the status of any linked pull requests in your Smartlog, as it uses your PAT behind the scenes to query their current state.

Pull requests​

When it comes to working with pull requests from Sapling, you have two options: sl pr and sl push. Each has its tradeoffs, so you may opt to use a different solution, depending on the scenario:

sl pr (aka "Sapling stack")​

See the dedicated Sapling Stack page for more information.

Pros:

  • Works with any GitHub repo.

Cons:

  • Creates "overlapping" pull requests that may be confusing to reviewers using the GitHub pull request UI. Reviewers are strongly encouraged to use ReviewStack for code review instead of GitHub.
tip

You can use the pr revset to automatically pull and checkout GitHub pull request. For example, sl goto pr123. See sl help revsets for more info.

sl push​

The GitHub website provides a way to turn a Git branch into a pull request. You can use sl push to create branches, then use the GitHub website to create pull requests.

If you have write access to the repo, you can push to a new branch:

sl push --to remote/my-new-feature

If you don't have write access to the repo, you can fork the repo from the GitHub website, add your fork as a remote, then push to your fork:

sl paths --add my-fork ssh://git@github.com/my-username/sapling.git
sl push --to my-fork/my-new-feature

After push, open the repo webpage. You will see GitHub detected the push:

my-new-feature   had recent pushes less than a minute ago

Compare & pull request

Click the "Compare & pull request" button to create a pull request.

You can also manually specify a Git branch and create a pull request. Read Creating a pull request from a fork for instructions.

To update an existing pull request, use sl push -f to force push to the same branch.

Pros:

  • Take control of commits (one or more) the pull request contains more explicitly.
  • Use GitHub website to edit the pull request summary. It is easy to preview and auto-complete.

Cons:

  • Need a few more clicks on the GitHub webpage.
  • Only create a single pull request per branch.

Troubleshooting​

could not read Username error when trying to git push​

If you see an error like the following:

stderr: fatal: could not read Username for 'https://github.com': No such device or address

Then you likely need to run gh auth setup-git [--hostname HOST] to configure gh as a Git credential helper. This will add the following to your .gitconfig (though the host will be different if you used --hostname to specify your GitHub Enterprise hostname):

[credential "https://github.com"]
    helper =
    helper = !/usr/bin/gh auth git-credential
[credential "https://gist.github.com"]
    helper =
    helper = !/usr/bin/gh auth git-credential

See gh issue #3796 for details