{"id":85920,"date":"2025-04-25T09:00:37","date_gmt":"2025-04-25T16:00:37","guid":{"rendered":"https:\/\/github.blog\/?p=85920"},"modified":"2025-04-25T09:43:30","modified_gmt":"2025-04-25T16:43:30","slug":"how-the-github-cli-can-now-enable-triangular-workflows","status":"publish","type":"post","link":"https:\/\/github.blog\/open-source\/git\/how-the-github-cli-can-now-enable-triangular-workflows\/","title":{"rendered":"How the GitHub CLI can now enable triangular workflows"},"content":{"rendered":"\n

Most developers are familiar with the standard Git workflow. You create a branch, make changes, and push those changes back to the same branch on the main repository. Git calls this a centralized workflow. It’s straightforward and works well for many projects.<\/p>\n

However, sometimes you might want to pull changes from a different branch directly into your feature branch to help you keep your branch updated without constantly needing to merge or rebase. However, you’ll still want to push local changes to your own branch. This is where triangular workflows come in.<\/p>\n

It’s possible that some of you have already used triangular workflows, even without knowing it. When you fork a repo, contribute to your fork, then open a pull request back to the original repo, you’re working in a triangular workflow. While this can work seamlessly on github.com, the process hasn’t always been seamless with the GitHub CLI<\/a>.<\/p>\n

The GitHub CLI team has recently made improvements (released in v2.71.2<\/a>) to better support these triangular workflows, ensuring that the gh pr<\/code> commands work smoothly with your Git configurations. So, whether you’re working on a centralized workflow or a more complex triangular one, the GitHub CLI will be better equipped to handle your needs.<\/p>\n

If you’re already familiar with how Git handles triangular workflows, feel free to skip ahead to learn about how to use gh pr<\/code> commands with triangular workflows. Otherwise, let’s get into the details of how Git and the GitHub CLI have historically differed, and how four-and-a-half years after it was first requested, we have finally unlocked managing pull requests using triangular workflows in the GitHub CLI.<\/p>\n

First, a lesson in Git fundamentals<\/span><\/a><\/h2>\n

To provide a framework for what we set out to do, it’s important to first understand some Git basics. Git, at its core, is a way to store and catalog changes on a repository and communicate those changes between copies of that repository. This workflow typically looks like the diagram below:<\/p>\n

\"Figure<\/a>
Figure 1: A typical git branch setup<\/figcaption><\/figure>\n

The building blocks of this diagram illustrate two important Git concepts you likely use every day, a ref<\/strong> and push\/pull<\/strong>.<\/p>\n

Refs<\/span><\/a><\/h3>\n

A ref<\/strong> is a reference to a repository and branch. It has two parts: the remote<\/strong>, usually a name like origin<\/em> or upstream<\/em>, and the branch<\/strong>. If the remote is the local repository, it is blank. So, in the example above, origin\/branch<\/em> in the purple box is a remote ref<\/strong>, referring to a branch named branch<\/em> on the repository name origin<\/em>, while branch<\/em> in the green box is a local ref<\/strong>, referring to a branch named branch<\/em> on the local machine.<\/p>\n

While working with GitHub, the remote ref is usually the repository you are hosting on GitHub. In the diagram above, you can consider the purple box GitHub and the green box your local machine.<\/p>\n

Pushing and pulling<\/span><\/a><\/h3>\n

A push<\/strong> and a pull<\/strong> refer to the same action, but from two different perspectives. Whether you are pushing or pulling is determined by whether you are sending or receiving the changes. I can push a commit to your repo, or you can pull that commit from my repo, and the references to that action would be the same.<\/p>\n

To disambiguate this, we will refer to different refs as the headRef<\/strong> or baseRef<\/strong>, where the headRef<\/strong> is sending the changes (pushing<\/em> them) and the baseRef<\/strong> is receiving the changes (pulling<\/em> them).<\/p>\n

\"Figure
Figure 2: Disambiguating headRef and baseRef for push\/pull operations<\/figcaption><\/figure>\n

When dealing with a branch, we’ll often refer to the headRef of its pull operations as its pullRef<\/strong> and the baseRef of its push operations as its pushRef<\/strong>. That’s because, in these instances, the working branch is the pull’s baseRef and the push’s headRef, so they’re already disambiguated.<\/p>\n

The @{push}<\/code> revision syntax<\/span><\/a><\/h4>\n

Turns out, Git has a handy built-in tool for referring to the pushRef for a branch: the @{push}<\/code> revision syntax. You can usually determine a branch’s pushRef by running the following command:<\/p>\n

git rev-parse --abbrev-ref @{push}<\/code><\/p>\n

This will result in a human-readable ref, like origin\/branch<\/strong>, if one can be determined.<\/p>\n

Pull Requests<\/span><\/a><\/h4>\n

On GitHub, a pull request<\/strong> is a proposal to integrate changes from one ref to another. In particular, they act as a simple “pause” before performing the actual integration operation, often called a merge<\/strong>, when changes are being pushed from ref to another. This pause allows for humans (code reviews) and robots (GitHub Copilot reviews and GitHub Actions workflows) to check the code before the changes are integrated. The name pull request<\/em> came from this language specifically: You are requesting that a ref pulls your changes into itself.<\/p>\n

\"Figure
Figure 3: Demonstrating how GitHub Pull Requests correspond to pushing and pulling<\/figcaption><\/figure>\n

Common Git workflows<\/span><\/a><\/h2>\n

Now that you understand the basics, let’s talk about the workflows we typically use with Git every day.<\/p>\n

A centralized workflow<\/strong> is how most folks interact with Git and GitHub. In this configuration, any given branch is pushing and pulling from a remote ref with the same branch name. For most of us, this type of configuration is set up by default when we clone a repo and push a branch. It is the situation shown in Figure 1.<\/p>\n

In contrast, a triangular workflow<\/strong> pushes to and pulls from different<\/em> refs. A common use case for this configuration is to pull directly from a remote repository’s default branch into your local feature branch, eliminating the need to run commands like git rebase <default><\/code> or git merge <default><\/code> on your feature branch to ensure the branch you’re working on is always up to date with the default branch. However, when pushing changes, this configuration will typically push to a remote ref with the same branch name as the feature branch.<\/p>\n

\"Figure<\/a>
Figure 4: juxtaposing centralized workflows from triangular workflows.<\/figcaption><\/figure>\n

We complete the triangle when considering pull requests: the headRef<\/strong> is the pushRef<\/strong> for the local ref and the baseRef<\/strong> is the pullRef<\/strong> for the local branch:<\/p>\n

\"Figure
Figure 5: a triangular workflow<\/figcaption><\/figure>\n

We can go one step further and set up triangular workflows using different<\/em> remotes as well. This most commonly occurs when you’re developing on a fork. In this situation, you usually give the fork and source remotes different names. I’ll use origin<\/em> for the fork and upstream<\/em> for the source, as these are common names used in these setups. This functions exactly the same as the triangular workflows above, but the remotes<\/strong> and branches<\/strong> on the pushRef<\/strong> and pullRef<\/strong> are different:<\/p>\n

\"Figure<\/a>
Figure 6: juxtaposing triangular workflows and centralized workflows with different remotes such as with forks<\/figcaption><\/figure>\n

Using a Git configuration file for triangular workflows<\/span><\/a><\/h3>\n

There are two primary ways that you can set up a triangular workflow using the Git configuration – typically defined in a `.git\/config` or `.gitconfig` file<\/a>. Before explaining these, let’s take a look at what the relevant bits of a typical configuration look like in a repo’s `.git\/config` file for a centralized workflow:<\/p>\n

[remote “origin”] \n    url = https:\/\/github.com\/OWNER\/REPO.git \n    fetch = +refs\/heads\/*:refs\/remotes\/origin\/*  \n[branch “default”]\n    remote = origin  \n    merge = refs\/heads\/default  \n[branch “branch”]\n    remote = origin \n    merge = refs\/heads\/branch\n<\/code><\/pre>\n
Figure 7: A typical Git configuration setup found in .git\/config<\/em><\/p>\n
The [remote “origin”]<\/code> part is naming the Git repository located at github.com\/OWNER\/REPO.git<\/code> to origin,<\/em> so we can reference it elsewhere by that name. We can see that reference being used in the specific [branch]<\/code> configurations for both the default<\/em> and branch<\/em> branches in their remote<\/code> keys. This key, in conjunction with the branch name, typically makes up the branch’s pushRef<\/strong>: in this example, it is origin\/branch<\/em>.<\/p>\n
The remote<\/code> and merge<\/code> keys are combined to make up the branch’s pullRef<\/strong>: in this example, it is origin\/branch<\/em>.<\/p>\n
Setting up a triangular branch workflow<\/span><\/a><\/h3>\n
The simplest way to assemble a triangular workflow is to set the branch’s merge<\/code> key to a different branch name, like so:<\/p>\n
[branch “branch”]\n    remote = origin\n    merge = refs\/heads\/default\n<\/code><\/pre>\n
Figure 8: a triangular branch’s Git configuration found in .git\/config<\/em><\/p>\n
This will result in the branch pullRef<\/strong> as origin\/default<\/em>, but pushRef<\/strong> as origin\/branch<\/em>, as shown in Figure 9.<\/p>\n
\"Figure<\/a>
Figure 9: A triangular branch workflow<\/figcaption><\/figure>\n
Setting up a triangular fork workflow<\/span><\/a><\/h3>\n
Working with triangular forks requires a bit more customization than triangular branches because we are dealing with multiple remotes. Thus, our remotes in the Git config will look  different than the one shown previously in Figure 7:<\/p>\n
[remote “upstream”]\n    url = https:\/\/github.com\/ORIGINALOWNER\/REPO.git \n    fetch = +refs\/heads\/*:refs\/remotes\/upstream\/* \n[remote “origin”]\n    url = https:\/\/github.com\/FORKOWNER\/REPO.git  \n    fetch = +refs\/heads\/*:refs\/remotes\/origin\/*\n<\/code><\/pre>\n
Figure 10: a Git configuration for a multi-remote Git setup found in .git\/config<\/em><\/p>\n
Upstream<\/em> and origin<\/em> are the most common names used in this construction, so I’ve used them here, but they can be named anything you want1<\/a><\/sup>.<\/p>\n
However, toggling a branch’s remote<\/code> key between upstream<\/em> and origin<\/em> won’t actually set up a triangular fork workflow—it will just set up a centralized workflow with either of those remotes, like the centralized workflow shown in Figure 6. Luckily, there are two common Git configuration options to change this behavior.<\/p>\n
Setting a branch’s pushremote<\/code><\/span><\/a><\/h4>\n
A branch’s configuration has a key called pushremote<\/code> that does exactly what the name suggests: configures the remote that the branch will push to. A triangular fork workflow config using pushremote<\/code> may look like this:<\/p>\n
[branch “branch”]\n    remote = upstream  \n    merge = refs\/heads\/default  \n    pushremote = origin\n<\/code><\/pre>\n
Figure 11: a triangular fork’s Git config using pushremote found in .git\/config<\/em><\/p>\n
This assembles the triangular fork repo we see in Figure 12. The pullRef<\/strong> is upstream\/default<\/em>, as determined by combining the remote<\/code> and merge<\/code> keys, while the pushRef<\/strong> is origin\/branch<\/em>, as determined by combining the pushremote<\/code> key and the branch name.<\/p>\n
\"Figure<\/a>
Figure 12: A triangular fork workflow<\/figcaption><\/figure>\n
Setting a repo’s remote.pushDefault<\/code><\/span><\/a><\/h4>\n
To configure all branches in a repository to have the same behavior as what you’re seeing in Figure 12, you can instead set the repository’s pushDefault<\/code>. The config for this is below:<\/p>\n
[remote] \n    pushDefault = origin \n[branch “branch”]\n    remote = upstream \n    merge = refs\/heads\/default\n<\/code><\/pre>\n
Figure 13: a triangular fork’s Git config using remote.pushDefault found in .git\/config<\/em><\/p>\n
This assembles the same triangular fork repo as shown in Figure 12 above, however this time the pushRef<\/strong> is determined by combining the remote.pushDefault<\/code> key and the branch name, resulting in origin\/branch<\/em>.<\/p>\n
When using the branch’s pushremote<\/code> and the repo’s remote.pushDefault<\/code> keys together, Git will preferentially resolve the branch’s configuration over the repo’s, so the remote set on pushremote<\/code> supersedes the remote set on remote.pushDefault<\/code>.<\/p>\n
Updating the gh pr<\/code> command set to reflect Git<\/span><\/a><\/h2>\n
Previously, the gh pr<\/code> command set did not resolve pushRefs<\/strong> and pullRefs<\/strong> in the same way that Git does. This was due to technical design decisions that made this change both difficult and complex. Instead of discussing that complexity—a big enough topic for a whole article in itself—I’m going to focus here on what you can now do<\/em> with the updated gh pr<\/code> command set.<\/p>\n
If you set up triangular Git workflows in the manner described above, we will automatically resolve gh pr<\/code> commands in accordance with your Git configuration.<\/strong><\/p>\n
To be slightly more specific, when trying to resolve a pull request for a branch, the GitHub CLI will respect whatever @{push}<\/code> resolves to first, if it resolves at all. Then it will fall back to respect a branch’s pushremote,<\/code> and if that isn’t set,  finally look for a repo’s remote.pushDefault<\/code> config settings.<\/p>\n
What this means is that the CLI is assuming your branch’s pullRef<\/strong> is the pull request’s baseRef<\/strong> and the branch’s pushRef<\/strong> is the pull requests headRef<\/strong>. In other words, if you’ve configured git pull<\/code> and git push<\/code> to work, then gh pr<\/code> commands should just work.2<\/a><\/sup> The diagram below, a general version of Figure 5, demonstrates this nicely:<\/p>\n
\"Figure
Figure 14: the triangular workflow supported by the GitHub CLI with respect to a branch’s pullRef and pushRef. This is the generalized version of Figure 5<\/figcaption><\/figure>\n
Conclusion<\/span><\/a><\/h2>\n
We’re constantly working to improve the GitHub CLI, and we’d like the behavior of the GitHub CLI to reasonably reflect the behavior of Git. This was a team effort—everyone contributed to understanding, reviewing, and testing the code to enable this enhanced gh pr<\/code> command set functionality.<\/p>\n
It also couldn’t have happened without the support of our contributors, so we extend our thanks to them:<\/p>\n