gogs/gogs

APIs for pull requests

yurivict opened this issue · 23 comments

yurivict commented

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 commented

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 commented

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!

  • 👍1
kmadel commented

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

  • 👍1
lstahlman commented

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

unknwon commented

@lstahlman OK, go ahead.

lstahlman commented

Thanks!

hhenkel commented

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

  • 👍2
lstahlman commented

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 commented

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 commented

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 commented

@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 commented

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 commented

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

lstahlman commented

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 commented

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 commented

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

guyzmo commented

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!

  • 👍3
hhenkel commented

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

  • ❤️2
guyzmo commented

@hhenkel Brilliant!

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

guyzmo commented

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 commented

@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 commented

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

the nice to have

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

ricardobranco777 commented

Any news?

  • 👍1