YouTrack - GitHub Integration

This Flask app exposes a single endpoint /pull-request/ to be used as a GitHub webhook for pull request events and pull request review events

YouTrack tickets and pull requests are associated by git branch name. Branch names must exactly match YouTrack ticket ids.

Actions taken by the webhook:

1. If the event payload action field is review_requested:
   1. sets the ticket state to "Submitted"
   2. assigns the ticket to the first listed reviewer on the PR
   3. comments on the ticket with the url of the PR
2. If the event payload action field is closed and pull_request[merged] is true:
   1. sets the ticket state to "Ready to deploy"
   2. unassigns the ticket
3. If the event payload action field is submitted and review[state] is not "approved":
   1. sets the ticket state to "Reopened"
   2. assigns the ticket back to the PR owner

Configuration

See the config.json file. The config requires 4 things:

1. the YouTrack instance name
2. a permanent YouTrack API access token
3. a secret token used by GitHub to secure the webhook: see https://developer.github.com/webhooks/securing/
4. a dictionary from GitHub logins to YouTrack usernames

If a config value is provided in the format "VAULT:path:key" in will be resolved by looking up the secret from vault.

Deployment

The app runs inside a docker container and is mapped to port 4567 on the host machine. We currently have this deployed on support.montagu.dide.ic.ac.uk (see montagu-machine). To deploy:

1. if already running, remove the container: docker rm -f youtrack-integration
2. pip3 install -r requirements.txt
3. ./run --use-vault to first resolve secrets before running the app

Tests

To run tests :

1. pip3 install -r requirements-dev.txt --user
2. pytest

CI

On Buildkite:

1. ./buildkite/test.sh runs tests in a docker container
2. ./buildkite/build.sh builds and pushes the docker image

Adding the webhook

The webhook can be added to a whole organisation or to a repository. For the mrc-ide org it will be most appropriate to only activate individual repositories.

1. Go to https://github.com/:org/:repo/settings/hooks or https://github.com/organizations/:org/settings/hooks
2. Click Add Webhook
3. Payload URL is https://montagu.vaccineimpact.org/pull-request/
4. Content type is application/json
5. Secret from the vault as vault read secret/youtrack-integration/github
6. Select "Let me select individual events" and select "Pull requests" and "Pull request reviews"
7. Click the big green "Add webhook" button