5.2.11. Github¶
5.2.11.1. Pull Requests¶
This API endpoint is for creating attachments in a bug that are redirect links to a specific Github pull request. This allows a bug viewer to click on the Github link and be automatically redirected to the pull request.
Github Setup Instructions
Create or identify a Bugzilla bot account to own this webhook.
A BMO admin must add that bot account to the
github-webhook-botgroup via the Users admin UI (/editusers.cgi). Membership in this group is a privileged grant: it lets any of the account’s (non-sticky) API keys drive this endpoint, so only add bots whose owners are trusted.The attachment and its comment are written as the shared
github-automation@bmo.tldaccount, but this endpoint only acts on publicly visible bugs. The target bug is checked against the (unauthenticated) request user before the automation account is adopted, so a pull request title naming a confidential bug is rejected withgithub_pr_bug_not_foundno matter which bot key signed it.The one exception is the cleanup pass that obsoletes the same pull request attachment on other bugs. That pass is scoped to the bugs the signing bot account can see, so a bot with security group memberships can obsolete an attachment on (and add the accompanying comment to) a confidential bug it has access to.
Log in as the bot account and go to Preferences > API Keys.
Create a new API key with a descriptive label (e.g.
github-webhook-mozilla-bteam-bmo). Copy the key value — it will only be shown once.
Warning
This API key also grants full access to the Bugzilla REST API as the bot account. Treat it as a credential: store it only in the GitHub webhook secret field and never share it.
From the repository main page, click on the Settings tab.
Click on Webhooks from the left side menu.
Click on the Add Webhook button near the top right.
For the payload url, enter
https://bugzilla.mozilla.org/rest/github/pull_request.Choose
application/jsonfor the content type.Enter the Bugzilla API key you created above as the webhook secret.
Make sure Enable SSL is turned on.
Select “Let me select individual events” and only enable changes for “Pull Requests”.
Make sure at the bottom that “Active” is checked on.
Save the webhook.
Warning
The bug id, title, and repository all come from the (signed) request body, so a leaked key is a general attachment-creation credential, not one scoped to a single repository: it can attach a pull request link to, and comment on, any publicly visible bug. Its reach into confidential bugs is limited to obsoleting an existing pull request attachment on a bug the signing bot account can see. Keep webhook bots out of security groups they do not need, and treat every such key as a credential.
Note
If a webhook secret is ever compromised, revoke the affected API key from the bot account’s Preferences > API Keys page. Revoking one key does not affect any other bot’s webhook. Every authenticated webhook action is logged with, and the resulting bug comment attributes, the bot account whose key signed the request, so misuse of a leaked key is traceable.
Note
Past pull requests will not automatically get a link created in the bug. New pull requests should get the link automatically when the pull request is first created.
Note
The API endpoint looks at the pull request title for the bug id so
make sure the title is formatted correctly to allow the bug id to be determined.
Examples are: Bug 1234:, Bug - 1234, bug 1234, or Bug 1234 -.
Request
The endpoint will error for any requests that do not have X-GitHub-Event header with
either the value pull_request or ping. Ping events can happen when a webhook is
first created. In that case, Bugzilla will return success if the signature checks out.
POST /rest/github/pull_request
{
"pull_request": {
"html_url": "https://github.com/mozilla-bteam/bmo/pull/1943",
"number": 1943,
"title": "Bug 1234567 - Some really bad bug which should be fixed"
}
}
The above example is only a small amount of the full data that is sent.
Some params must be set, or an error will be thrown. The required params are marked in bold.
name |
type |
description |
|---|---|---|
pull_request |
Object |
Object containing data about the current pull request. |
pull_request.html_url |
string |
A fully qualified link to the pull request. |
pull_request.number |
int |
The pull request ID unique to the repository. |
pull_request.title |
string |
The full title of the current pull request containing the bug report ID. |
Response
Operation was completed successfully.
{
"error": 0
"id": 22
}
name |
type |
description |
|---|---|---|
error |
boolean |
Whether the operation was successful or not. |
id |
int |
ID of the pre-existing or newly-created attachment. |
An error condition occurred.
{
"error": 1
"message": "The pull request title did not contain a valid bug ID."
}
name |
type |
description |
|---|---|---|
error |
boolean |
Whether the operation was successful or not. |
message |
string |
A message detailing what the error condition was. |
5.2.11.2. Push Comments¶
This API endpoint is for adding comments to a bug when a push is made to a linked
Github repository. The comment will be short and specially formatted using pieces
of information from the full JSON sent to Bugzilla by the push event. If the bug
does not have the keyword leave-open set, the bug will be resolved as FIXED.
Also, the qe-verify flag will be set to + for the bug unless the
?no-qe-verify=1 query parameter is passed in the URL. For some specific
repositories, a Firefox status flag may be set to FIXED.
Github Setup Instructions
Create or identify a Bugzilla bot account to own this webhook.
A BMO admin must add that bot account to the
github-webhook-botgroup via the Users admin UI (/editusers.cgi). Membership in this group is a privileged grant: it lets any of the account’s (non-sticky) API keys drive this endpoint, so only add bots whose owners are trusted.The bug changes themselves are made as the shared
github-automation@bmo.tldaccount, but only for bugs the signing bot account can see. A bug referenced in a commit message that the bot cannot see is silently skipped. So the bot account’s own visibility decides which bugs its webhook can touch: a bot that must comment on bugs in a given security group has to be a member of that group.Note that group membership is not the only thing that grants visibility. A confidential bug is also visible to its assignee, its QA contact, and (when the product allows it) its reporter or a user on its CC list. A bot with no group memberships is therefore not strictly limited to public bugs, so avoid leaving webhook bot accounts as the assignee, QA contact, or a CC of confidential bugs.
Log in as the bot account and go to Preferences > API Keys.
Create a new API key with a descriptive label (e.g.
github-webhook-mozilla-bteam-bmo-push). Copy the key value — it will only be shown once.
Warning
This API key also grants full access to the Bugzilla REST API as the bot account. Treat it as a credential: store it only in the GitHub webhook secret field and never share it.
From the repository main page, click on the Settings tab.
Click on Webhooks from the left side menu.
Click on the Add Webhook button near the top right.
For the payload url, enter
https://bugzilla.mozilla.org/rest/github/push_comment.Add
?no-qe-verify=1to the URL if you do not want theqe-verifyflag set.Choose
application/jsonfor the content type.Enter the Bugzilla API key you created above as the webhook secret.
Make sure Enable SSL is turned on.
Select “Let me select individual events” and only enable changes for “Pushes”.
Make sure at the bottom that “Active” is checked on.
Save the webhook.
Warning
The bug ids and repository name come from the (signed) request body, and the commit messages that supply those bug ids can be written by anyone able to land on a monitored branch. A leaked key is therefore a general bug-modification credential, not one scoped to a single repository — but its reach is bounded by what the signing bot account can see. Keep webhook bots out of security groups they do not need.
Note
If a webhook secret is ever compromised, revoke the affected API key from the bot account’s Preferences > API Keys page. Revoking one key does not affect any other bot’s webhook. Every authenticated webhook action is logged with, and the resulting bug comment attributes, the bot account whose key signed the request, so misuse of a leaked key is traceable.
Note
The legacy global github_pr_signature_secret parameter identifies no bot
account, so requests signed with it are limited to public bugs. Deployments
that need this endpoint to comment on confidential bugs must migrate to
per-bot API keys and clear that parameter.
Note
The API endpoint looks at the commit messages for the bug ID so
make sure the message is formatted correctly to allow the bug ID to be determined.
Examples are: Bug 1234:, Bug - 1234, bug 1234, or Bug 1234 -.
Request
The endpoint will error for any events that do not have X-GitHub-Event header with
either the value push or ping. Ping events can happen when a webhook is first
created. In that case, Bugzilla will return success if the signature checks out.
POST /rest/github/push_comment
{
"ref": "refs/heads/master",
"repository": {
"full_name": "mozilla-bteam/bmo",
"html_url": "https://github.com/mozilla-bteam/bmo",
"description": "bugzilla.mozilla.org source - report issues here: https://bugzilla.mozilla.org/enter_bug.cgi?product=bugzilla.mozilla.org",
},
"commits": [
{
"message": "Bug 1803939 - Webhook URL field is too short",
"url": "https://github.com/mozilla-bteam/bmo/commit/b4edfe9343e1474e0a6959531d2362078ea6ee84",
"author": {
"name": "dklawren",
"username": "dklawren"
},
"added": [],
"removed": [],
"modified": [
"extensions/Webhooks/Extension.pm",
"extensions/Webhooks/template/en/default/account/prefs/webhooks.html.tmpl"
]
}
]
}
The above example is only a small amount of the full data that is sent.
Note
Only the first line of the commit message will be used on the bug comment.
Some params must be set, or an error will be thrown. The required params are marked in bold.
name |
type |
description |
|---|---|---|
ref |
string |
The branch (ref) that the commit was pushed to (ex: refs/heads/master). |
repository.full_name |
string |
The name of the Github repository. |
commits |
array |
An array of commit objects that were pushed. |
commits.<index>.message |
string |
The full commit message containing the bug report ID. |
commits.<index>.url |
string |
The full URL to the commit on Github. |
commits.<index>.author.username |
string |
The user name of the commit author. |
Response
Operation was completed successfully.
{
"bugs": {
1803939: [
{
"text": "Authored by https:\/\/github.com\/dklawren\nhttps:\/\/github.com\/mozilla-bteam\/bmo\/commit\/4ef4caed5bc22a734bd9ec15aaac87c19ef6e80e\nBug 1803939 - Webhook URL field is too short"
}
]
},
"error": 0
}
name |
type |
description |
|---|---|---|
error |
boolean |
Whether the operation was successful or not. |
bugs |
object |
Object containing bug IDs as object keys. |
bugs.<id> |
array |
List of comment objects that were added to the bug <id>. |
bugs.<id>.<index>.text |
string |
The comment text that was added to the bug <id>. |
An error condition occurred.
{
"error": 1
"message": "The push commit message did not contain a valid bug ID."
}
name |
type |
description |
|---|---|---|
error |
boolean |
Whether the operation was successful or not. |
message |
string |
A message detailing what the error condition was. |
This documentation undoubtedly has bugs; if you find some, please file them here.