Skip to content

Latest commit

 

History

History

github-service

README.md

GitHub API Wrapper Service

This service's responsibility is to manage GitHub API calls and to provide authentication tokens every 5 minutes to make valid calls to the App API. It exposes three REST functions to interact with the GitHub API. The table below lists the provided endpoints:

Function Endpoint Description
Add Labels POST /repo/{user}/{repository}/pr/{id}/labels Adds a list of labels to the given Pull Request
Add Reviewers POST /repo/{user}/{repository}/pr/{id}/reviewers Adds a list of reviewers the the given Pull Request
Get changed files GET /repo/{user}/{repository}/pr/{id}/files Fetches for the changed files in a given Pull Request

Configuring your GitHub App

For this service to work, you will need to create a new GitHub App and install it in one or more repositories to be able to make changes to its PRs or Issues.

By creating a GitHub App, it will provide a private key which can be used by this service to interact with the GitHub API.

Creating a new GitHub App

Follow the GitHub documentation to create a new GitHub App and a private key.

When asked to set permissions, choose "Access: Read & Write" for Issues and Pull Requests. Then, in "Subscribe to Events" section set "Pull request". This way you will be able to make changes in the repositories' PRs where you've installed the GitHub App.

After creating the private key, download it locally in somewhere safe.

Converting the generated private key

Convert the downloaded private key from PEM to DER format with the following command:

openssl pkcs8 -topk8 -inform PEM -outform DER -in ~/github-api-app.private-key.pem -out ~/github-api-app.private-key.der -nocrypt

Replace the file ~/github-api-app.private-key.pem with your local path.

This will generate a private key in DER format which we will use to generate the GitHub API tokens on demand.

Installing the App in one or more repositories

It's recommended to install the GitHub App in a test repository to not mess with your account or organizations.

Create a new repository, then go to your Developer Settings, click on "Edit" button next to your GitHub App, then click on "Install App", choose your account and install it in the test repository you just created.

Trying the service locally

Now you have the GitHub App, a test repository and a private key. It's time to try the application locally.

Clone this repo if you haven't yet, edit the file src/main/resources/application.properties and add the following data:

org.kogito.examples.sw.github.service.key=<LOCAL PATH TO YOUR DER FILE>
org.kogito.examples.sw.github.service.installation_id=<APP INSTALLATION ID>
org.kogito.examples.sw.github.service.app_id=<APP ID>

Replace <LOCAL PATH TO YOUR DER FILE> with the absolute path of the converted private key file (DER format).

<APP INSTALLATION ID> can be grabbed in the Installations Dashboard. Just click in "Configure" button next to the app name, and you will be redirected to the Installation page. The installation id is in the end of the URL, e.g.: https://github.com/settings/installations/12345.

The <APP_ID> is the number displayed in the App Dashboard. Click in the "App settings" link to be redirected to the dashboard.

Having everything in place, start the Quarkus application with the following command:

mvn clean quarkus:dev

Then access the Swagger UI to play around with the API: http://localhost:8080/swagger-ui

⚠️ Important:

  1. Open a test PR to have some data to play with
  2. Invite a friend to be a contributor to your repo, so you can make the service request for their review in the PRs 😗

Deploying on Kubernetes

IMPORTANT! ⚠️ we assume you have read the prerequisites section in the main README file. Please follow those instructions before continuing.

Heads up! This service will be deployed as a Knative Service instead of a regular Kubernetes Deployment.

To make things easier there is a script in this directory to generate the template files, build the application and the image, and then deploy it to your Kubernetes cluster.

IMPORTANT! You must be authenticated to the target Kubernetes cluster as a cluster administrator for this script to work.

You can run the script once and all the required files will be generated in the kubernetes directory, and the image will be published to your Quay.io account.

Fill the value for the variables as shown below and run the script:

# the script accepts positional arguments as following:
QUAY_NAMESPACE=
APP_ID=
INSTALLATION_ID=
DER_FILE=

./deploy-kubernetes.sh $QUAY_NAMESPACE $APP_ID $INSTALLATION_ID $DER_FILE

You should see a similar output like this:

Build logs ``` // build logs surpressed ---> Building and pushing image using tag quay.io/ricardozanini/github-service:latest STEP 1: FROM adoptopenjdk:11-jre-hotspot STEP 2: RUN mkdir -p /opt/app/lib --> Using cache 26183c5ad8a51a030030a250db0c99e649fdd9668ef4766d0b66782d0dad7573 STEP 3: COPY target/github-service-2.0.0-SNAPSHOT-runner.jar /opt/app --> 31bc2627d32 STEP 4: COPY target/lib/*.jar /opt/app/lib --> 62eae5cdde7 STEP 5: CMD ["java", "-jar", "/opt/app/github-service-2.0.0-SNAPSHOT-runner.jar"] STEP 6: COMMIT quay.io/ricardozanini/github-service:latest --> 7c555a3060c 7c555a3060c666582824552d8824f2787b59b67b506fb933b171764bde894730 Getting image source signatures Copying config 7c555a3060 [--------------------------------------] 0.0b / 6.2KiB Writing manifest to image destination Writing manifest to image destination Storing signatures ---> Applying objects to the cluster in the namespace kogito-github. configmap/github-service-properties unchanged secret/github-app-ids unchanged secret/github-app-key unchanged service.serving.knative.dev/github-service configured ```

To verify if the service have been correctly deployed run:

$ kubectl get ksvc github-service  -n kogito-github

NAME             URL                                               LATESTCREATED          LATESTREADY            READY   REASON
github-service   http://github-service.kogito-github.example.com   github-service-7frvw   github-service-7frvw   True

The READY column should be true.

Exposing the service on Minikube

If you're running on another cluster than Minikube, the service's route exposed by Knative Serving probably is accessible to you. On Minikube there are some additional steps to be made.

Run a new terminal window:

minikube tunnel

Leave the process executing and then execute:

./expose-on-minikube.sh

This script will fetch the Minikube IP exposed by the tunnel command and add the route to your local /etc/hosts file.

You can then access the service via the service URL:

$  kubectl get ksvc github-service  -n kogito-github --output jsonpath="{.status.url}"

http://github-service.kogito-github.example.com

As we did when running through the jar file, we can access the Swagger UI and play around with the API:

http://github-service.kogito-github.example.com/swagger-ui

The first query may take a little time to return since Knative will start the service's pod on demand. After some time the pod will just terminate.

Congratulations! The GitHub functions is now available in the cluster ready to be consumed by the Kogito Workflow.

Cleaning up!

See the project root's README documentation.