EVENT_REFERENCE.md

Event Reference

This section exists primarily for reference purposes and documents all GitHub webhooks which can be handled by this gateway and their corresponding Brigade events that may be emitted into the Brigade event bus.

The transformation of a webhook into an event is relatively straightforward and subject to a few very simple rules:

1. In most cases, the event's type field will directly match the the webhook's type as determined by the value of the X-GitHub-Event HTTP header.

   For the relatively few webhooks whose JSON payload contains an action field, the corresponding event will have a type of the form <webhook type>:<action>. For instance, for a webhook of type pull_request with the value opened in the action field, the corresponding event would be of type pull_request:opened. This approach is used because this gateway's creators have observed that when a webhook is qualified by an action field, the processing a script author might wish to perform for one value of the action field typically varies significantly from the processing they might wish to perform for some other value of the action field. By way of example, the logic required for handling a newly opened pull request might be quite different from the logic required for handling a pull request that's been closed. With this being the case, this gateway's creators considered it prudent to map each webhook type + action combination to its own distinct Brigade event type.

2. With every webhook handled by this gateway being indicative of activity involving some specific repository, the name of the affected repository is copied from the webhook's JSON payload and promoted to the repo qualifier on the corresponding event. This permits projects to subscribe to events relating only to specific repositories. Read more about qualifiers here.

3. For any webhook that is indicative of activity involving not only a specific repository, but also some specific ref (branch or tag) or commit (identified by SHA), this gateway copies those details from the webhook's JSON payload and promotes them to the corresponding event's git.ref and/or git.commit fields. By doing so, Brigade is enabled to locate specific code referenced by the webhook/event. The importance of this cannot be understated, as it is what permits Brigade to be used for implementing CI/CD pipelines.

4. If this gateway is able to infer that a webhook pertains only to a specific Brigade project, this information will be included in the corresponding event's projectID field and will effectively limit delivery of the event to the applicable Brigade project.

5. If this gateway is able to infer a human-friendly title for any webhook, the corresponding event will be augmented with values in its shortTitle and longTitle fields.

6. For all webhooks, without exception, the entire JSON payload, without any modification, becomes the corresponding event's payload. The event payload field is a string field, however, so script authors wishing to access the payload will need to parse the payload themselves with a JSON.parse() call or similar.

7. For the relatively few webhooks that are of particular importance when utilizing Brigade to implement CI/CD pipelines, all previous rules apply, but additional events may also be emitted into Brigade's event bus. See the CI/CD documentation for more details.

The following table summarizes all GitHub webhooks that can be handled by this gateway and the corresponding event(s) that are emitted into Brigade's event bus.

⭐️  symbols in the table call attention to the few events that are most relevant to the most common use case: CI/CD.

Webhook	Scope	Possible Action Values	Event Type(s) Emitted
check_run	specific commit	created completed rerequested rerequested_action	check_run:created check_run:completed check_run:rerequested + ⭐️  ci:job_requested check_run:rerequested_action
check_suite	specific commit	completed requested rerequested	check_suite:completed check_suite:requested + ci:pipeline_requested check_suite:rerequested + ⭐️  ci:pipeline_requested
create	specific branch or tag		create
deleted	specific branch or tag		deleted
fork	specific repository		fork
gollum	specific repository		gollum
installation	multiple specific repositories; the gateway will split this into multiple repository-specific events	created deleted suspend unsuspend new_permissions_accepted	installation:created installation:deleted installation:suspend installation:unsuspend installation:new_permissions_accepted
installation_repositories	multiple specific repositories; the gateway will split this into multiple repository-specific events	added removed	installation_repositories:added installation_repositories:removed
issue_comment	specific repository	created edited deleted	issue_comment:created issue_comment:edited issue_comment:deleted
issues	specific repository	opened edited deleted pinned unpinned closed reopened assigned labeled unlabeled locked unlocked transferred milestoned demilestoned	issues:opened issues:edited issues:deleted issues:pinned issues:unpinned issues:closed issues:reopened issues:assigned issues:labeled issues:unlabeled issues:locked issues:unlocked issues:transferred issues:milestoned issues:demilestoned
label	specific repository	created edited deleted	label:created label:edited label:deleted
member	specific repository	added removed edited	member:added member:removed member:edited
milestone	specific repository	created closed opened edited deleted	milestone:created milestone:closed milestone:opened milestone:edited milestone:deleted
page_build	specific repository		page_build
project_card	specific repository	created edited moved converted deleted	project_card:created project_card:edited project_card:moved project_card:converted project_card:deleted
project_column	specific repository	created edited moved deleted	project_column:created project_column:edited project_column:moved project_column:deleted
project	specific repository	created edited closed reopened deleted	project:created project:edited project:closed project:reopened project:deleted
public	specific repository		public
pull_request	specific commit	opened edited closed assigned unassigned review_requested review_request_removed ready_for_review converted_to_draft labeled unlabeled synchronize auto_merge_enabled auto_merge_disabled locked unlocked reopened	pull_request:opened pull_request:edited pull_request:closed pull_request:assigned pull_request:unassigned pull_request:review_requested pull_request:review_request_removed pull_request:ready_for_review pull_request:converted_to_draft pull_request:labeled pull_request:unlabeled pull_request:synchronize pull_request:auto_merge_enabled pull_request:auto_merge_disabled pull_request:locked pull_request:unlocked pull_request:reopened
pull_request_review	specific commit	submitted edited dismissed	pull_request_review:submitted pull_request_review:edited pull_request_review:dismissed
pull_request_review_comment	specific commit	created edited deleted	pull_request_review_comment:created pull_request_review_comment:edited pull_request_review_comment:deleted
push	specific commit		push
release	specific repository	published unpublished created edited deleted prereleased released	release:published + ⭐️  cd:pipeline_requested release:unpublished release:created release:edited release:deleted release:prereleased release:released
repository	specific repository	created deleted archived unarchived anonymous_access_enabled edited renamed transferred publicized privatized	repository:created repository:deleted repository:archived repository:unarchived repository:anonymous_access_enabled repository:edited repository:renamed repository:transferred repository:publicized repository:privatized
status	specific commit		status
team_add	specific repository		team_add
watch	specific repository	started	watch:started