GraphQL: no way to link an existing branch to an issue's Development section

[ronin9110]

🏷️ Discussion Type

Product Feedback

💬 Feature/Topic Area

API

Body

What I want
Link a branch that already exists to an issue's Development section from the API, the same way the issue sidebar's gear allows in the web UI.

What happens

• createLinkedBranch(input: {issueId, repositoryId, name, oid}) with the name and head oid of an existing branch returns {"data":{"createLinkedBranch":{"linkedBranch":null}}} with HTTP 200 and no errors. Nothing is linked. Passing refs/heads/<name> gives the same result.
• gh issue develop <n> --name <existing-branch> (gh 2.92.0) fails with failed to create linked branch: API returned empty branch name.
• The web UI links the same branch to the same issue without trouble.

Why it matters
Branches are often created before their issue, or by tooling and agents that work through the API. Without an API to link them, the Development section stays empty, and automation falls back to comments.

Asks

1. Let createLinkedBranch link an existing branch when name matches an existing ref (and oid matches its head), or add a linkBranchToIssue mutation.
2. Until then, return an error instead of linkedBranch: null with no errors.

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐

[100rootrain]

+1 on getting an error instead of linkedBranch: null. Silently returning success is the worst part of this.

Until there's a proper API, here are two workarounds that may help:

1. Link a PR instead of the branch

Open a PR (a draft is fine) from the existing branch and include a closing keyword in the body, e.g. Closes #123. The PR then appears in the issue's Development section, and you can do this through the API (createPullRequest / gh pr create --draft --body "Closes #123"). The catch is that closing keywords only link when the PR targets the default branch.

2. Delete the branch, then recreate it with createLinkedBranch

createLinkedBranch takes an oid to base the new branch on, so you can:

1. Note the branch's current head SHA.
2. Delete the remote branch.
3. Call createLinkedBranch with the same name and that SHA as oid.

That should recreate the branch at the same commit, this time linked to the issue. I haven't tested this myself, so please try it on a throwaway branch first. Also be careful: deleting a branch closes any open PRs from it, and branch rulesets may block the deletion.

[ronin9110]

Thanks for the ideas. Neither fits our workflow, which I think is common:

1. Draft PR with Closes #N: closing keywords only link when the PR targets the default branch. Our default branch is production, and work reaches it through an integration branch, so a PR from a work branch into the default
   branch is exactly what we must not open, draft or not.
2. Delete and recreate with createLinkedBranch: deleting a shared work branch is risky (open PRs close, rulesets may block it), and it still links only one issue. When two issues share a branch, the second call hits the same
   silent linkedBranch: null.

The web UI already links an existing branch through the Development gear, so the server side can do it. The ask stays the same: expose that link in the API (accept an existing name/oid in createLinkedBranch, or add a
linkBranchToIssue mutation), and return an error instead of null until then.

[100rootrain]

Fair points, both of them. I hadn't considered a shared branch linked to multiple issues, and you're right that delete-and-recreate can't cover that. It also shows this isn't an edge case: the web UI supports a many-to-one link that the API has no way to create at all. So I agree the real fix has to be on the API side.

One small thing you could do in parallel: the gh issue develop failure is probably worth reporting separately in cli/cli. Even before the API changes, gh could check whether the branch already exists and say so, instead of API returned empty branch name. That repo is maintained by GitHub and triaged in the open, so a small, concrete report like that tends to get a response sooner than a Community feature request.

[ronin9110]

Good call, thanks. Filed it: cli/cli#14946

Testing it also settled #13805 (closed, "error with slash in branch name"): the slash isn't the cause. In a test repo, an existing branch failed with or without a slash (example and feat/example), while a new feat/new-example was created and linked. So the gh error and the silent linkedBranch: null here have the same root: createLinkedBranch can't link a branch that already exists.