robertventurini/GiteaAPI

GiteaAPI

A ruby gem that makes scripting with Gitea PRs easier.

Prerequisites

This gem requires json and net/html modules to work and was tested against Ruby 2.6.3 on macOS Catalina. You will need access to a running Gitea instance and have generated an 'Application Access Token' on that instance before you can use this gem.

This has been tested against GiteaAPI v1.1.1

Getting Started

Download the latest gem from releases and install it gem install GiteaAPI-x.x.x.gem, or clone the repository and build and install the gem yourself

gem build GiteaAPI.gemspec
gem install GiteaAPI-x.x.x.gem # where x.x.x is the version you're installing

Once the gem is installed you need to require GiteaAPI and establish an authentication object for your interactions

require 'GiteaAPI'

## Argument 1 is the base url to a Gitea instance, where <owner> is replaced with the owner of the repository instance
 # Argument 2 is the repo you'll be interacting with
 # Argument 3 is a 40 character hexidecimal Application Access Token that was generated by the Gitea instance you'll be accessing
authentication = GiteaAPI::Authentication.new("https://try.gitea.io/api/v1/repos/<owner>", "<repo name>", "<application token>")

Now that you have an authentication object, you can fetch pull requests using the 'fetch' method on the pull request class GiteaAPI::PullRequest.fetch(auth, pullRequestState=nil, pullRequestSort=nil, limit=0)

pullRequests = GiteaAPI::PullRequest.fetch(authentication)

Optional parameters for PR State and/or sort order can be included in your request by using keyed values in the hashmaps GiteaAPI::PullRequestState and GiteaAPI::PullRequestSort respectively. When omitted the fetch command assumes open and recently updated by default.

pullRequests = GiteaAPI::PullRequest.fetch(authentication, GiteaAPI::PullRequestState["open"], GiteaAPI::PullRequestSort["recentupdate"])

Once you've retrieved a set of pull requests from your server, you can review them in your script by using the review method. Lets suppose for example that your build system just finished building PR 513 and you want to issue a CI approval for that PR...

require 'GiteaAPI'

authentication = GiteaAPI::Authentication.new(baseUrl, repo, token)

# Fetch open prs sorted by recently updated
pullRequests = GiteaAPI::PullRequest.fetch(authentication)

for pr in pullRequests
	if pr.prnum == 513
		# Found the PR matching CI build, approve it
		pr.review(auth, message, true)
		break
	end
end

If your build system failed to build the PR in question, you would use the same review command, but instead of passing in true for the 3rd (approval) argument, pass in false.

pr.review(auth, message, false) ## Reject the PR

Debugging and Testing

Giteas GUI doesn't offer a way to delete reviews directly but fortunately their API does. To enable testing of CI scripts GiteaAPI::PullRequestReview defines a delete method which will allow you to clean up noise or erroneous approval / rejections that could be generated by a calling scripted sequence. Lets again look at hypothetical PR 513

require 'GiteaAPI'

authentication = GiteaAPI::Authentication.new(baseUrl, repo, token)
pullRequests = GiteaAPI::PullRequest.fetch(authentication)

prToReview = nil
for pr in pullRequests
	if pr.prnum == 513
		prToReview = pr
		break
	end
end

## Capture the PullRequestReview instance on return
review = prToReview.review(auth, message, true)

## Now that we a review object that we generated, we can call delete on it
review.delete(auth, prToReview)

## The review object in memory now refers to stale data, further 
 # interaction with Gitea regarding this data is undefined. 
 # For saftey we'll set this to nil
review = nil

If the running instance of your script didn't generate the review object you wish to remove, you can fetch reviews direct using GiteaAPI::PullRequestReview.fetch(auth, pullRequest) and then iterate the set until you find the one you want to delete.

Whats left?

Well... Tons! This only touches on a very small part of the available Gitea API with a specific focus around PR approval and rejections for better CI integration. This serves the immediate need for the time, but I hope to continue expanding API coverage here when I can.