Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[#143] Update README instructions with the latest project changes #152

Merged
merged 1 commit into from
Feb 24, 2021
Merged

[#143] Update README instructions with the latest project changes #152

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 54 additions & 54 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,66 +1,66 @@
# Tyr
# Tyr

![Powered by OpenShift Online](https://www.openshift.com/images/logos/powered_by_openshift.png)

Pull request template status check
## 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 with Maven - mvn clean install
1. Create a testing repository - for start you can fork my
https://github.com/xstefank/test-repo where the PR template is set up or
you can create your own :)
- For creating new repository check the github manuals/help
- PRs needs to be created to YOUR repository, you need to specify it
under the base fork field in the Open a Pull Request page
1. The project requires two properties to be set up to run correctly
- GitHub OAuth token - can be passed as a
[MicroProfile Config](https://github.com/eclipse/microprofile-config)
property `tyr.github.oauth.token`
- Configuration file specifying the format of the PR - the example can
be found in `tyr-runner/src/main/resources/format-example.yaml`, the supported
MicroProfile Config properties are `tyr.template.format.file` or
`tyr.template.format.url`
1. start Tyr - `java -jar tyr-runner.jar` with above MP config properties set
(as for instance system properties, e.g. `-Dtyr.template.format.file=/path/to/file`)
1. Build Tyr with Maven, using command `mvn clean install`
1. 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.
1. The project requires two [MicroProfile Config](https://github.com/eclipse/microprofile-config/blob/master/spec/src/main/asciidoc/microprofile-config-spec.asciidoc) 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
1. Generate new token
1. Tick repo:status
1. Generate token
1. 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.\
xstefank marked this conversation as resolved.
Show resolved Hide resolved
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
1. start Tyr - `java -jar tyr-webhook-runner.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 tyr-webhook-runner.jar`)
1. 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
1. Now you should have everything prepared locally, next step is to let
GitHub know where your Tyr instance runs
> 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.
1. Add a webhook for Tyr
- In you test-repo - go to Settings -> Webhooks -> Add webhook
- Fill in Payload URL -> *your local exposed IP which is provided by
ngrok + “/pull-request”* (e. g., http://f202cf7c.ngrok.io/pull-request)
- Fill in Content type -> application/json
- Set *Let me select individual events* and check only *Pull requests*
1. In you test-repo - go to Settings -> Webhooks -> Add webhook
1. Fill in Payload URL -> *your local exposed IP which is provided by
ngrok + **“/pull-request”*** (e.g., http://f202cf7c.ngrok.io/pull-request)
1. Fill in Content type -> application/json
1. Set *Let me select individual events* and check only *Pull requests*
and *Pull request review comments*
- 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
1. If you create a PR now (create a new branch based on master for instance)
you should already see some output in the server logs
- 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.
1. However, you will still probably see problems with the custom PR check
which the app is trying to send to GitHub as there is a requirement to
provide an oauth token to the GitHub API
1. Go to your profile -> settings (top right) -> Developer Settings ->
Personal access tokens
1. Generate new token
1. Tick repo:status
1. Generate token
1. The last step is to let Tyr know what is the token value
- add the token to **config.properties** file (the example is provided in
the `tyr-runner/src/main/resources` folder) and copy this file to the same directory
where Tyr is running
1. Restart Tyr
1. Rerun (update existing or create new PR) - everything should be working now
1. Leave Active set and click “Add webhook”
1 Don’t worry about the error - the first JSON differs from what the
subsequent PR JSONs will look like.
1. Last thing is to edit your format template file.
1. Open `format-template.yaml` which path you've set in a 3rd step.
1. Edit value of the variable `repository` so it points to __your__ test-repo.
1. Edit value of the variable `statusUrl` so it points to __your__ test-repo or leave it default.
1. Now you have to set if you want Tyr to use any CI.
xstefank marked this conversation as resolved.
Show resolved Hide resolved
* If NO, remove variable `CI` and all of it's content.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Command regexes could be removed also..

Copy link
Contributor Author

@xvanick1 xvanick1 Feb 24, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Currently readme file describes only required steps to successfully set up Tyr for first run and having those command regexes in there does not affect the first successful set up and run. I think that what you are suggesting would be better to have described in format-template.yaml file as a set of comments to let user know what does he have available in Tyr and how to set or disable individual options because it is up to user to specify what he wants to have available - how he configures the file. I admit that having the "statusUrl" on default does not affect the first successful run, but it is required to remove whole CI section from the file or set it correctly.

* 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.
1. Now you should have everything prepared
1. 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.
1. 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**
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.

## OpenShift deployment

Expand Down