Tyr

Description

Tyr is a Pull request status check tool for maintaining a clean and uniform PR format of your project based on a preset template.
Check it out in action: https://www.youtube.com/watch?v=qZRcMQ6qIpg&t=6s&ab

Development

1. Build Tyr with Maven, using command mvn clean install
2. Create a testing repository - for start you can fork https://github.com/xstefank/test-repo where the Pull request template is already set up, or you can create your own.

   • For creating new repository check the github manuals/help.
   • Pull requests needs to be made to your repository, therefore when you'll be doing Pull Request you need to specify this under the base fork field in the "Open a Pull Request" page.

3. The project requires two MicroProfile Config properties to be set up to run correctly.
   1. tyr.github.oauth.token - Represents your unique GitHub OAuth token provided to Tyr.
      1. Go to your profile -> settings (top right) -> Developer Settings -> Personal access tokens
      2. Generate new token
      3. Tick repo:status
      4. Generate token
      5. Use it as a value of this property, so the Tyr will be able to communicate with GitHub.
   2. Next one is tyr.template.format.file, alternatively tyr.template.format.url - Represents the path to configuration file specifying desired format of the Pull request. Example can be found in tyr-core/src/main/resources/format-example.yaml

   Both properties can be passed to Tyr as:
   a. application properties - set once in tyr-core/src/main/resources/application.properties. Necessary to rebuild Tyr after every adjustment of the file.
   b. system properties - passed as a parameter when starting Tyr. e.g. -Dtyr.template.format.file=/path/to/file (preferred option)
   c. as environment property TYR_TEMPLATE_FORMAT_FILE=/path/to/file

4. start Tyr - java -jar tyr-webhook/target/quarkus-app/quarkus-run.jar with above MP config properties set.
   (as for instance with system properties, e.g. java -Dtyr.template.format.file="/path/to/file" -Dtyr.github.oauth.token="afegxh64hnxh4646..." -jar quarkus-run.jar)
5. Expose local server instance with ngrok - https://ngrok.com/

   Here you need to expose http port 8080 as the default application interface where the application runs. Consult the ngrok documentation for the information of how to specify these arguments.

6. Add a webhook for Tyr
   1. In you test-repo - go to Settings -> Webhooks -> Add webhook
   2. Fill in Payload URL -> your local exposed IP which is provided by ngrok + “/pull-request” (e.g., http://f202cf7c.ngrok.io/pull-request)
   3. Fill in Content type -> application/json
   4. Set Let me select individual events and check only Pull requests and Pull request review comments
   5. Leave Active set and click “Add webhook”

   Don’t worry about the error - the first JSON differs from what the subsequent PR JSONs will look like.

7. Last thing is to edit your format template file.
   1. Open format-example.yaml which path you've set in a 3rd step.
   2. Edit value of the variable repository so it points to your test-repo.
   3. Edit value of the variable statusUrl so it points to your test-repo or leave it default.
   4. Now you have to set if you want Tyr to use any CI.
      • If NO, remove variable CI and all of it's content.
      • If YES, set CI name, and it's properties. We are using TeamCity CI which properties are defined in the TeamCityProperties interface. Also set MP property tyr.whitelist.enabled=true same way as it is described in step 3.
8. Now you should have everything prepared
9. If you create a PR now in your test-repo (create a new branch based on master for instance) you should already see some output in the server logs and everything should be working now.

   Be careful to which repository and branch you are doing the PR!!! You need to specify your repository, the point is to try to set up Tyr on your repository.

10. If everything runs ok the PR should be updated with the valid error or green color, and in terminal where the server runs you’ll see Status update: 201.

    If not, check Tyr output for any Exceptions. Also check incoming ngrok HTTP requests to determine error code. Try to rebuild and rerun Tyr. Check GitHub if token was used by Tyr. Check latest info at the bottom of your test-repo webhook settings.

Is your repository private?

If yes, some changes have to done in the configuration. This is needed because Tyr is working not just with PRs. Current scope "repo:status" of the token grants read/write access to public and private repository commit statuses. This scope is only necessary to grant other users or services access to private repository commit statuses without granting access to the code. If the repository is public, Tyr is able to read all the necessary data, but when it's private, the scope of the permissions has to be expanded to allow full access to private repository. If you don't like this option, you can use Tyr with limited functionality where commit checks will be disabled.

For the full functionality of Tyr follow these steps:

1. Repeat the 3rd step, point i. of the Development Guide, but tick the "repo" instead of "repo:status".
2. Generate this new token and use it.

Because GitHub has a different set of OAuth token permissions for private repos vs. public repos, we have to extend the scope of permissions for the private repos, so the whole functionality of Tyr can be guaranteed.

For the limited functionality (disabled commit checks) follow these steps:

1. Repeat the 3rd step of the Development Guide but use also the property tyr.git.luolix.topmit.checks.disabled with its value set to true.
   Alternatively:
2. Repeat the 7th step of the development Guide. There you will use file format-example-without-commits.yaml instead of the on mentioned in 7th step.

This way the scope of the oauth token permission will be limited, but functionality of commit checks will be disabled.

OpenShift deployment

This project contains an openshift profile to be easily deployable to Openshift platform.

To deploy to Openshift:

1. login to your OS account (oc login)
2. mvn fabric8:deploy -Popenshift