Add API to update a branch #14910

New Issue

GiteaMirror · 2025-11-02T11:25:39-06:00

GiteaMirror commented

2025-11-02 11:25:39 -06:00

Originally created by @hramrach on GitHub (Aug 27, 2025).

Feature Description

The docs show:

get List a repository's branches
post Create a branch
get Retrieve a specific branch from a repository, including its effective branch protection
del Delete a specific branch from a repository
patch Update a branch

but update documentation shows:

Update a branch

Authorizations:

BasicAuthTokenAccessTokenAuthorizationHeaderTokenSudoParamSudoHeaderTOTPHeader

path Parameters

owner required | string owner of the repo

repo required | string name of the repo

branch required | string name of the branch

Request Body schema: application/json

name required | string unique New branch name

Is this meant to be "Rename a branch"?

There does not seem to be any way to update the branch. The more general feature https://github.com/go-gitea/gitea/issues/11835 seems stalled.

Screenshots

No response

Originally created by @hramrach on GitHub (Aug 27, 2025). ### Feature Description The docs show: get List a repository's branches post Create a branch get Retrieve a specific branch from a repository, including its effective branch protection del Delete a specific branch from a repository patch Update a branch but update documentation shows: <h2 class="sc-jMsorb cXfBCP">Update a branch </h2><div class="sc-jHatCz rIptA"><div class="sc-igQrDQ fEyRno"><h5 class="sc-cUiCeM sc-icgweO cTXMHO dWlQBn">Authorizations:</h5><svg class="sc-dcKlJK jnfsqh" version="1.1" viewBox="0 0 24 24" x="0" xmlns="http://www.w3.org/2000/svg" y="0" aria-hidden="true"></svg></div></div><div class="sc-jHatCz rIptA"><div class="sc-jLKpbB cuZkaP"><span class="sc-jBqEzj jdjyEV"><span class="sc-hWwHby TSqO"><i>BasicAuth</i></span></span><span class="sc-jBqEzj jdjyEV"><span class="sc-hWwHby TSqO"><i>Token</i></span></span><span class="sc-jBqEzj jdjyEV"><span class="sc-hWwHby TSqO"><i>AccessToken</i></span></span><span class="sc-jBqEzj jdjyEV"><span class="sc-hWwHby TSqO"><i>AuthorizationHeaderToken</i></span></span><span class="sc-jBqEzj jdjyEV"><span class="sc-hWwHby TSqO"><i>SudoParam</i></span></span><span class="sc-jBqEzj jdjyEV"><span class="sc-hWwHby TSqO"><i>SudoHeader</i></span></span><span class="sc-jBqEzj jdjyEV"><span class="sc-hWwHby TSqO"><i>TOTPHeader</i></span></span></div></div><div><h5 class="sc-cUiCeM cTXMHO">path Parameters</h5> owner required | string owner of the repo repo required | string name of the repo branch required | string name of the branch <h5 class="sc-cUiCeM cTXMHO">Request Body schema: <span class="sc-dCVDEO iKSlPA">application/json</span></h5><div html="" class="sc-dTUlgT sc-fhPBcz fJWtJg gNpMqQ"></div> name required | string unique New branch name - Is this meant to be "Rename a branch"? There does not seem to be any way to update the branch. The more general feature https://github.com/go-gitea/gitea/issues/11835 seems stalled. ### Screenshots _No response_

GiteaMirror added the topic/api type/proposal labels 2025-11-02 11:25:39 -06:00

GiteaMirror commented

2025-11-02 11:25:39 -06:00

@kemzeb commented on GitHub (Aug 28, 2025):

Is this meant to be "Rename a branch"?

The original implementation did have it as /rename. The PR original closely followed GitHub's design for the same endpoint, but after some feedback it was agreed that the endpoint was strangely designed and we resorted to calling it /update. GitHub doesn't have an update branch API so this was fine. At the time, I only saw branch renaming as a way to update a branch so it was included.

What type of branch update functionality are you looking for in the API? Maybe it can be performed by this endpoint rather than the potential lower-level git ref API PR you linked. Then again, maybe GitHub's lacks more branch API endpoints because the functionality could be done with their git ref API.

@kemzeb commented on GitHub (Aug 28, 2025): > Is this meant to be "Rename a branch"? The [original](https://github.com/go-gitea/gitea/pull/32433) implementation did have it as `/rename`. The PR original closely followed GitHub's design for the same endpoint, but after some feedback it was agreed that the endpoint was strangely designed and we resorted to calling it `/update`. GitHub doesn't have an update branch API so this was fine. At the time, I only saw branch renaming as a way to update a branch so it was included. What type of branch update functionality are you looking for in the API? Maybe it can be performed by this endpoint rather than the potential lower-level git ref API PR you linked. Then again, maybe GitHub's lacks more branch API endpoints because the functionality could be done with their [ git ref API](https://docs.github.com/en/rest/git/refs?apiVersion=2022-11-28).

GiteaMirror commented

2025-11-02 11:25:39 -06:00

@hramrach commented on GitHub (Aug 28, 2025):

Basically the create branch API for existing branches.

There is a similar API for files that specifies the existing file SHA for update and no SHA for new file so I suppose the create API could be extended in this way.

@hramrach commented on GitHub (Aug 28, 2025): Basically the create branch API for existing branches. There is a similar API for files that specifies the existing file SHA for update and no SHA for new file so I suppose the create API could be extended in this way.

GiteaMirror commented

2025-11-02 11:25:39 -06:00

@hramrach commented on GitHub (Aug 28, 2025):

I also have to say it's strange to call a rename endpoint update.

@hramrach commented on GitHub (Aug 28, 2025): I also have to say it's strange to call a rename endpoint update.

GiteaMirror commented

2025-11-02 11:25:40 -06:00

@hramrach commented on GitHub (Aug 28, 2025):

get Gets the metadata and contents (if a file) of an entry in a repository, or a list of entries if a dir
put Update a file in a repository
post Create a file in a repository
del Delete a file in a repository

as put is not used for branches this could be extended to be consistent with the file API.

@hramrach commented on GitHub (Aug 28, 2025): get Gets the metadata and contents (if a file) of an entry in a repository, or a list of entries if a dir put Update a file in a repository post Create a file in a repository del Delete a file in a repository as put is not used for branches this could be extended to be consistent with the file API.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#14910