https://github.com/phrase/zendesk-integration
https://github.com/phrase/zendesk-integration
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/phrase/zendesk-integration
- Owner: phrase
- License: mit
- Created: 2021-09-30T12:58:09.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2022-07-06T08:39:59.000Z (almost 4 years ago)
- Last Synced: 2025-02-06T07:13:13.684Z (over 1 year ago)
- Size: 76.2 KB
- Stars: 1
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: license.md
Awesome Lists containing this project
README
# zendesk-integration
The zendesk github integration consist of 6 github actions.
- [issue_created.yml](blob/main/.github/workflows/issue_created.yml)
- [issue_commented.yml](blob/main/.github/workflows/issue_commented.yml)
- [zendesk_comment.yml](blob/main/.github/workflows/zendesk_comment.yml)
- [zendesk_commented.yml](blob/main/.github/workflows/zendesk_commented.yml)
- [zendesk_solve.yml](blob/main/.github/workflows/zendesk_solve.yml)
- [zendesk_solved.yml](blob/main/.github/workflows/zendesk_solved.yml)
In addition, within zendesk there needs to be a [Webhook](https://developer.zendesk.com/api-reference/event-connectors/webhooks/webhooks/#create-or-clone-webhook) and two [Triggers](https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#create-trigger) configured.
## Github actions
### Issue created
Once an issue is created it send the issue to zendesk,
creating (or using) the user `` with email `@users.noreply.github.com`.
This mail adress format is also used by github when a user sets the privacy option that the mail should be hidden.
Once the ticket got created a comment to the issue will be added to inform the user about the tech support contact.
### Issue commented
Every comment on an issue gets send to zendesk. It will look up the connected ticket and author and attaches the
comment to the ticket, There is no additional comment added on the issue to avoid noise.
### Zendesk commented
Once a comment on zendesk was added to a ticket from github it will send a webhook to github which triggers a
github action to sync the zendesk comment back to the issue.
## Zendesk setup
### Webhook
To be able to receive comments from zendesk and sync them back to the github issue a webhook needs to be created within zendesk.
This can either be done through their interface or through the api. The following data is required:
```json
{
"webhook": {
"name": "Github Issue Integration",
"subscriptions": ["conditional_ticket_events"],
"endpoint": "https://api.github.com/repos///dispatches",
"http_method": "POST",
"request_format": "json",
"authentication": {
"type": "bearer_token",
"add_position": "header",
"data":{
"token":""
}
}
}
}
```
``, `` and `` needs to be replaced with real data.
### Triggers
The webhook itself does not get triggered automatically in zendesk. For this, a `Trigger` needs to be defined.
#### Trigger for comments
```json
{
"trigger": {
"title": "Zendesk comments to Github",
"actions": [
{
"field": "notification_webhook",
"value": [
"",
"{\"event_type\": \"zendesk-comment\", \"client_payload\": { \"ticket\": {\"id\": \"{{ticket.id}}\",\"external_id\": \"{{ticket.external_id}}\"},\"comment\": {\"body\": \"{{ticket.latest_comment.value}}\",\"author\": \"{{ticket.latest_comment.author.name}}\"}}}"
]
}
],
"conditions": {
"all": [
{
"field": "comment_is_public",
"operator": "is",
"value": true
},
{
"field": "subject_includes_word",
"operator": "includes",
"value": "Github_Issue"
},
{
"field": "comment_includes_word",
"operator": "not_includes",
"value": "GITHUB_ISSUE_COMMENT"
}
],
"any": []
},
"description": "#zendesk-github-comments",
}
}
```
#### Trigger for solving issue
```json
{
"trigger": {
"title": "Zendesk closing Github issues",
"actions": [
{
"field": "notification_webhook",
"value": [
"",
"{\"event_type\": \"zendesk-solved\", \"client_payload\": { \"ticket\": {\"id\": \"{{ticket.id}}\",\"external_id\": \"{{ticket.external_id}}\"}}}}"
]
}
],
"conditions": {
"all": [
{
"field": "status",
"operator": "is",
"value": "solved"
},
{
"field": "subject_includes_word",
"operator": "includes",
"value": "Github_Issue"
}
],
"any": []
},
"description": "#zendesk-github-issue-solving",
}
}
```
`` needs to be replaced with the real ID of the new generated webhook.
Additional conditions can be set to e.g. limit tickets to specific organizations or categories.
:warning: Only public comments should be syned to github. If `comment_is_public` is left out (or set to `"not_relevant"`)
private comments would also be synced to github and made public.
:warning: The conditions `subject_includes_word` and `comment_includes_word` matches words added by the github actions.
They should not be removed but can be changed to anything - just make sure to also adjust the github actions accordingly.
## Integration
One important notice: This setup requires only one *global* `zendesk_commented` and one *global* `zendesk_solved` github action (only once) while the
`zendesk_comment`, `zendesk_solve`, `issue_commented` and `issue_created` github actions needs to be added to every repository where the issues should
get synced to zendesk.
The workflow can also be reused via [Calling a reusable workflow](https://docs.github.com/en/actions/learn-github-actions/reusing-workflows#calling-a-reusable-workflow)
to only have one place for the integration code.
```
on:
repository_dispatch:
types:
- zendesk
jobs:
zendesk_comment:
uses: phrase/zendesk-integration/.github/workflows/zendesk_comment.yml@main
```
```
on:
repository_dispatch:
types:
- zendesk-solving-issue
jobs:
zendesk_comment:
uses: phrase/zendesk-integration/.github/workflows/zendesk_solve.yml@main
```
```
on:
issues:
types: [opened]
jobs:
issue_created:
uses: phrase/zendesk-integration/.github/workflows/issue_created.yml@main
secrets:
ZENDESK_BASIC_AUTH: ${{ secrets.ZENDESK_BASIC_AUTH }}
```
```
on:
issue_comment:
types: [created]
jobs:
issue_created:
uses: phrase/zendesk-integration/.github/workflows/issue_commented.yml@main
secrets:
ZENDESK_BASIC_AUTH: ${{ secrets.ZENDESK_BASIC_AUTH }}
```