Configure GitHub integration

To set up GitHub integration you will need to add a webhook for Tickd to your GitHub repository and set up a GitHub integration in Tickd.

To add a webhook to your GitHub repository:
  1. Go to the home page for your GitHub repository on the GitHub website.
  2. Click on the Settings tab at the top of the page
  3. Click the Webhooks link shown in the Options menu at the left of the page.
  4. Click the Add Webhook button at the top of the page.
  5. Set the Payload Url value for Tickd. This will be https://<tickd_domain>/rpc/postnote/index.cfm where <tickd_domain> is the domain for your Tickd instance, for example: https://kiltkraft.tickd.it/rpc/postnote/index.cfm
  6. Set the Content type to application/json
  7. Optionally, set a value in the Secret field
  8. SSL Verification should be enabled
  9. Under Which events would you like to trigger this webhook? select “Just the push event”
  10. Make sure that the Active checkbox is ticked
  11. Click the Add Webhook button to create the Webhook. A link for the webhook will be shown on the Webhooks page.

Note that the webhook attempts to connect when it is created. We expect this to fail if the GitHub integration has not already been set up in Tickd.

To set up GitHub integration in Tickd:
  1. Open the Admin page by clicking the Admin Menu item in the top menu of Tickd and click the Integrations menu item in the Admin Menu at the left of the page. The integration page will be opened, with the possible integration types shown.
  2. Click on “GitHub” to add a new GitHub integration.
  3. Enter the name of your GitHub repository.
  4. Enter the Repository URL. This is the URL of your repository home page on the GitHub site.
  5. If you have set a Secret value for your webhook, enter the value on the Secret field.
  6. Click the Save button.
  7. If the email address that you use for accessing your GitHub repository is different from the email address that you use for logging on to Tickd, add your GitHub email address to the list of alternative emails in your user settings.

To view the integrations that have been set up, click the Integrations List  icon at the top right of the integrations page. The integrations are listed by name, with an icon showing the integration type. You can filter the list of integrations shown by entering all or part of the integration name in the Filter field at the top left of the page.

Troubleshooting
  1. Go to the integrations page for your repository on the GitHub site (Repository home page – Settings – Webhooks) The webhooks that have been set up for the repository are listed on the page.
  2. Click the Edit button for the Tickd webhook to open the webhook page.
  3. Check that the URL and Secret Token (if set) are correct and that “Just the push event” is selected.
  4. Recent deliveries are listed at the bottom of the page. Click on a recent delivery to view the details.
  5. The response code for a delivery should be 200. Any response code other than 200 indicates a problem, but some failed deliveries will have a response code of 200, so check the response body which is shown on the Response tab. A response of +OK indicates success. If an error message is shown it should give some indication of the issue (See below).
Some common issues are:
  • Response code: 404, Response body: -FAIL: Repository not found  – Check that the URLs set for your Tickd integration and your webhook in GitHub are correct.
  • Response code: 401, Response body: -FAIL: Invalid secret – Verify that the Secret value set in the webhook and Tickd integration are identical.
  • Response code: 401, Response body: -FAIL: Disabled repository – Check that the Tickd integration is enabled.
  • Response code: 200, Response body: -FAIL: No ticket found – Check that the ticket it used in your commit message is correct.
  • Response code: 401, Response body: -FAIL: Tickd user not found – Verify that the email associated with your GitHub account is the same associated with your Tickd user account, or listed as alternative emails for your Tickd user account

 

Required Permissions: Administrator only

Useful links: