{"id":1961,"date":"2025-04-25T16:14:32","date_gmt":"2025-04-25T16:14:32","guid":{"rendered":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2025\/04\/25\/how-the-github-cli-can-now-enable-triangular-workflows\/"},"modified":"2025-04-25T16:14:32","modified_gmt":"2025-04-25T16:14:32","slug":"how-the-github-cli-can-now-enable-triangular-workflows","status":"publish","type":"post","link":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2025\/04\/25\/how-the-github-cli-can-now-enable-triangular-workflows\/","title":{"rendered":"How the GitHub CLI can now enable triangular workflows"},"content":{"rendered":"

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\u2019s 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\u2019ll still want to push local changes to your own branch. This is where triangular workflows come in.<\/p>\n

It\u2019s 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\u2019re working in a triangular workflow. While this can work seamlessly on github.com, the process hasn\u2019t always been seamless with the GitHub CLI<\/a>.<\/p>\n

The GitHub CLI team has recently made improvements (released in v2.71.0<\/a>) to better support these triangular workflows, ensuring that the gh pr commands work smoothly with your Git configurations. So, whether you\u2019re 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\u2019re already familiar with how Git handles triangular workflows, feel free to skip ahead to learn about how to use gh pr commands with triangular workflows. Otherwise, let\u2019s 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<\/a><\/h2>\n

To provide a framework for what we set out to do, it\u2019s 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

<\/a>Figure 1: A typical git branch setup<\/p>\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<\/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<\/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 2: Disambiguating headRef and baseRef for push\/pull operations<\/p>\n

When dealing with a branch, we\u2019ll 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\u2019s because, in these instances, the working branch is the pull\u2019s baseRef and the push\u2019s headRef, so they\u2019re already disambiguated.<\/p>\n

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

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

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

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

Pull Requests<\/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 \u201cpause\u201d 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 3: Demonstrating how GitHub Pull Requests correspond to pushing and pulling<\/p>\n

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

Now that you understand the basics, let\u2019s 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\u2019s default branch into your local feature branch, eliminating the need to run commands like git rebase <default> or git merge <default> on your feature branch to ensure the branch you\u2019re 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

<\/a>Figure 4: juxtaposing centralized workflows from triangular workflows.<\/p>\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 5: a triangular workflow<\/p>\n

We can go one step further and set up triangular workflows using different<\/em> remotes as well. This most commonly occurs when you\u2019re developing on a fork. In this situation, you usually give the fork and source remotes different names. I\u2019ll 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

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

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

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

[remote \u201corigin\u201d]
\n url = https:\/\/github.com\/OWNER\/REPO.git
\n fetch = +refs\/heads\/*:refs\/remotes\/origin\/*
\n[branch \u201cdefault\u201d]
\n remote = origin
\n merge = refs\/heads\/default
\n[branch \u201cbranch\u201d]
\n remote = origin
\n merge = refs\/heads\/branch<\/p>\n

Figure 7: A typical Git configuration setup found in .git\/config<\/em><\/p>\n

The [remote \u201corigin\u201d] part is naming the Git repository located at github.com\/OWNER\/REPO.git to origin,<\/em> so we can reference it elsewhere by that name. We can see that reference being used in the specific [branch] configurations for both the default<\/em> and branch<\/em> branches in their remote keys. This key, in conjunction with the branch name, typically makes up the branch\u2019s pushRef<\/strong>: in this example, it is origin\/branch<\/em>.<\/p>\n

The remote and merge keys are combined to make up the branch\u2019s pullRef<\/strong>: in this example, it is origin\/branch<\/em>.<\/p>\n

Setting up a triangular branch workflow<\/a><\/h3>\n

The simplest way to assemble a triangular workflow is to set the branch\u2019s merge key to a different branch name, like so:<\/p>\n

[branch \u201cbranch\u201d]
\n remote = origin
\n merge = refs\/heads\/default<\/p>\n

Figure 8: a triangular branch\u2019s 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

<\/a>Figure 9: A triangular branch workflow<\/p>\n

Setting up a triangular fork workflow<\/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 \u201cupstream\u201d]
\n url = https:\/\/github.com\/ORIGINALOWNER\/REPO.git
\n fetch = +refs\/heads\/*:refs\/remotes\/upstream\/*
\n[remote \u201corigin\u201d]
\n url = https:\/\/github.com\/FORKOWNER\/REPO.git
\n fetch = +refs\/heads\/*:refs\/remotes\/origin\/*<\/p>\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\u2019ve used them here, but they can be named anything you want1<\/a>.<\/p>\n

However, toggling a branch\u2019s remote key between upstream<\/em> and origin<\/em> won\u2019t actually set up a triangular fork workflow\u2014it 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\u2019s pushremote<\/a><\/h4>\n

A branch\u2019s configuration has a key called pushremote that does exactly what the name suggests: configures the remote that the branch will push to. A triangular fork workflow config using pushremote may look like this:<\/p>\n

[branch \u201cbranch\u201d]
\n remote = upstream
\n merge = refs\/heads\/default
\n pushremote = origin<\/p>\n

Figure 11: a triangular fork\u2019s 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 and merge keys, while the pushRef<\/strong> is origin\/branch<\/em>, as determined by combining the pushremote key and the branch name.<\/p>\n

<\/a>Figure 12: A triangular fork workflow<\/p>\n

Setting a repo\u2019s remote.pushDefault<\/a><\/h4>\n

To configure all branches in a repository to have the same behavior as what you\u2019re seeing in Figure 12, you can instead set the repository\u2019s pushDefault. The config for this is below:<\/p>\n

[remote]
\n pushDefault = origin
\n[branch \u201cbranch\u201d]
\n remote = upstream
\n merge = refs\/heads\/default<\/p>\n

Figure 13: a triangular fork\u2019s 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 key and the branch name, resulting in origin\/branch<\/em>.<\/p>\n

When using the branch\u2019s pushremote and the repo\u2019s remote.pushDefault keys together, Git will preferentially resolve the branch\u2019s configuration over the repo\u2019s, so the remote set on pushremote supersedes the remote set on remote.pushDefault.<\/p>\n

Updating the gh pr command set to reflect Git<\/a><\/h2>\n

Previously, the gh pr 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\u2014a big enough topic for a whole article in itself\u2014I\u2019m going to focus here on what you can now do<\/em> with the updated gh pr command set.<\/p>\n

If you set up triangular Git workflows in the manner described above, we will automatically resolve gh pr 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} resolves to first, if it resolves at all. Then it will fall back to respect a branch\u2019s pushremote, and if that isn\u2019t set, finally look for a repo\u2019s remote.pushDefault config settings.<\/p>\n

What this means is that the CLI is assuming your branch\u2019s pullRef<\/strong> is the pull request\u2019s baseRef<\/strong> and the branch\u2019s pushRef<\/strong> is the pull requests headRef<\/strong>. In other words, if you\u2019ve configured git pull and git push to work, then gh pr commands should just work.2<\/a> The diagram below, a general version of Figure 5, demonstrates this nicely:<\/p>\n

Figure 14: the triangular workflow supported by the GitHub CLI with respect to a branch\u2019s pullRef and pushRef. This is the generalized version of Figure 5<\/p>\n

Conclusion<\/a><\/h2>\n

We\u2019re constantly working to improve the GitHub CLI, and we\u2019d like the behavior of the GitHub CLI to reasonably reflect the behavior of Git. This was a team effort\u2014everyone contributed to understanding, reviewing, and testing the code to enable this enhanced gh pr command set functionality.<\/p>\n

It also couldn\u2019t have happened without the support of our contributors, so we extend our thanks to them:<\/p>\n

@Frederick888 for opening the original pull request<\/a>
\n@benknoble for his support with pull request review and feedback
\n@phil-blain for highlighting the configurations<\/a> we\u2019ve talked about here on the original issue<\/a>
\n@neutrinoceros and @rd-yan-farba for reporting a couple of bugs<\/a> that the team fixed in v2.66.1<\/a><\/p>\n

CLI native support for triangular workflows was 4.5 years in the making, and we\u2019re proud to have been able to provide this update for the community.<\/p>\n

The GitHub CLI Team
\n@andyfeller, @babakks, @bagtoad, @jtmcg, @mxie, @RyanHecht, and @williammartin<\/p>\n

\n

Some commands in gh are opinionated about remote names and will resolve remotes in this order: upstream, github, origin, <other remotes unstably sorted>. There is a convenience command you can run to supersede this:* gh repo set-default [<repository>] to override the default behavior above and preferentially resolve<\/em> <repository> as the default remote repo.<\/em>\u00a0\u21a9<\/a><\/p>\n

If you find a git configuration that doesn\u2019t work, please open an issue in the OSS repo so we can fix it.\u00a0\u21a9<\/a><\/p>\n<\/div>\n

The post How the GitHub CLI can now enable triangular workflows<\/a> appeared first on The GitHub Blog<\/a>.<\/p>","protected":false},"excerpt":{"rendered":"

Most developers are familiar with the standard Git workflow. You create a branch, make changes, and push those changes back […]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"default","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","ast-disable-related-posts":"","theme-transparent-header-meta":"","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"default","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"footnotes":""},"categories":[8],"tags":[],"class_list":["post-1961","post","type-post","status-publish","format-standard","hentry","category-github-engineering"],"_links":{"self":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts\/1961","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/comments?post=1961"}],"version-history":[{"count":0,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts\/1961\/revisions"}],"wp:attachment":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/media?parent=1961"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/categories?post=1961"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/tags?post=1961"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}