APIs for pull requests

[yurivict]

Particularly these commands are desired:

• /api/v1/{user}/{repo}/pulls?status={open/closed}&id={id} - retrieves the list of pull requests (or one pull request)
• /api/v1/{user}/{repo}/pull/{num}/files - retrieves the list of affected files for the pull request
• /api/v1/{user}/{repo}/pull/{num}/diff - retrieves the diff file for the pull request
• /api/v1/{user}/{repo}/pull/{num}/comments - retrieves the list of comments
• /api/v1/{user}/{repo}/pull/{num}/comment-submit - PUT submits a new comment

[romanresh]

Besides enumerated commands, we use the following PR API in GitLab:

1. Accept pull request via API
2. Reassign pull request
3. Create comment in pull request

We'd like to migrate to Gogs from Gitlab, but these api commands are required in our infrastructure (PR are accepted via an external utility).

[kmadel]

I just wanted to mention that I have written a Gogs Plugin for Jenkins to support Pipeline Multibranch and Org Scanning (auto creates project folders for repos and Pipeline projects for branches that have a Jenkinsfile in them). Initial release is available here: https://github.com/kmadel/gogs-branch-source-plugin/releases/tag/v0.1-alpha

The biggest missing features is support for Pull Requests. Even without a webhook or a Rest API to interact with them - is there anyway to interact with PRs via plain vanialla Git?

Thanks for the awesome work!

[kmadel]

By the way, I would like to mention that I believe Pull Requests should be able to be retrieved the same way that repo branches are (and the way GitHub does it):

GET /repos/:owner/:repo/pulls

And with at least the 'state' parameter to filter:
state string Either open, closed, or all to filter by state. Default: open

[lstahlman]

@unknown are you already working on this in conjunction with #2246? If not, I would like to help out.

[unknwon]

@lstahlman OK, go ahead.

[lstahlman]

Thanks!

[hhenkel]

One implementing the API should probably orientate himself at this github api?

[lstahlman]

That makes sense. I think most of the features requested here fit with that api, though some are dependent on related features that are still in progress (e.g., comments API).

[kmadel]

I also wanted to mention (and please correct me if I am wrong), but I don't believe it is even currently possible to get a list of Pull Request issues.

GET /repos/:owner/:repo/issues does not allow passing in the Issue option to include pull requests per https://github.com/gogits/gogs/blob/master/routers/api/v1/repo/issue.go#L19

[lstahlman]

I am including the ability to pass options through /repos/:owner/:repo/pulls and I think there should be the same sort of support for issues. I was actually considering submitting a PR for that once I'm done with the initial work for the PR API.

[kmadel]

@lstahlman How far along are you on the PR API - and did you see this PR: #3547

Not quite as robust as what GitHub includes for PRs, but a simple start - I suppose you may already have something better.

[lstahlman]

Yeah I saw that and am somewhat dependent on that PR getting accepted. I had my own version in dev, but it very closely matches what you submitted.

I'm pretty far along on the basics (list, get, create, update). I was starting to add support for PR commit/file details, but I think I will split that into a separate contribution.

[bkcsoft]

@lstahlman Are you still working on this one? if so can you send a PR for what you have? 😃

[lstahlman]

I paused while waiting for #3547 & gogs/go-gogs-client#47 to be accepted, but I'll go ahead and post a WIP PR shortly so the code is out there.

[lstahlman]

The WIP PRs I just posted implement the basic list, get, create, edit & merge features. I'm open to feedback and can add in extra bits where needed. I still need to finish the documentation markdown but should be able to post that in the next day or so.

@kmadel this is going to conflict with your PR #3547 as I changed the API format of the PR struct to more closely match the Github API (there seems to be a bit of a push for this).

[lstahlman]

FYI I updated the PR to include the documentation. It's lengthy so I won't cross-post it here.

[guyzmo]

Along with the support of pull requests — if it's not already implemented — please, really please make it possible to git fetch the pull-requests as git refs.

git fetch github pull/42/head # how it's implemented on github

Both github and gitlab support this and it's one of the great features they share, and bitbucket lack of it is the most frustrating side of the tool. Don't be like bitbucket, be like the others!

[hhenkel]

@guyzmo what you're requesting is already there? #1655

[guyzmo]

@hhenkel Brilliant!

Just need the PR listing/creation/close/comment API and it's going to be 👌

[guyzmo]

BTW, if I may comment on the API structure, it's better to use a more RESTful structure:

• /api/v1/{user}/{repo}/pullrequest

• GET: (with ?status={open/closed}&id={id} params) retrieves (and filters) the list of pull requests
• POST: creates a new PR

• /api/v1/{user}/{repo}/pullrequest/{num}

• GET: retrieves all details about a given PR
• UPDATE: modifies mutable values of the PR
• DELETE: ø (to close a PR update its status value)

• /api/v1/{user}/{repo}/pullrequest/{num}/comment
  • GET: retrieves the list of comments
  • POST: creates a new comment
  • UPDATE/PUT: updates an existing comment
  • DELETE: deletes a comment

---

• /api/v1/{user}/{repo}/pull/{num}/diff
  • would that one be really necessary? I mean, a simple property with link of the existing diff web page and patch raw file should be enough.

• Though if that info cannot be reached using API's auth on the web content pages, then the API endpoint needs to be there

• /api/v1/{user}/{repo}/pullrequest/{num}/files - retrieves the list of affected files for the pull request

• idem: would it be necessary? The list of affected files can be easily extracted from a patch file.

my €0.02

[bkcsoft]

@guyzmo Gogs is following the GitHub API as close as possible, so deviating from it by choice (for little reason) would not be merged.

[guyzmo]

This is a good idea, as from my experience implementing git services APIs, I have to admit github API is a very good one (whether you name it pull, pulls or pullrequest is just a minor technical detail). And what I suggested is following that API, cf Github documentation. I'm just suggesting to take baby steps in implementing it 😉

the really necessary

• List pull requests: GET /repos/:owner/:repo/pulls
• Get a single pull request: GET /repos/:owner/:repo/pulls/:number
• Create a pull request: POST /repos/:owner/:repo/pulls
• Update a pull request: PATCH /repos/:owner/:repo/pulls/:number

the nice to have

you can also get commit list (which is not really useful if you implement the commit list endpoint):

• List commits on a pull request:
  GET /repos/:owner/:repo/pulls/:number/commits
• List pull requests files:
  GET /repos/:owner/:repo/pulls/:number/files
• Get if a pull request has been merged:
  GET /repos/:owner/:repo/pulls/:number/merge
• Merge a pull request:
  PUT /repos/:owner/:repo/pulls/:number/merge

[ricardobranco777]

Any news?