github

README

go-webhookd-github

Go package to implement the whosonfirst/go-webhookd interfaces for receiving and transforming webhooks originating from GitHub.

Documentation

go-webhookd

Before you begin please read the go-webhookd documentation for an overview of concepts and principles.

Usage

import (
	_ "github.com/go-webhookd-github"
)

Receivers

GitHub

The GitHub receiver handles Webhooks sent from GitHub. It validates that the message sent is actually from GitHub (by way of the X-Hub-Signature header) but performs no other processing. It is defined as a URI string in the form of:

github://?secret={SECRET}&ref={REF}

Properties

Name	Value	Description	Required
secret	string	The secret used to generate the HMAC hex digest of the message payload.	yes
ref	string	An optional Git ref to filter by. If present and a WebHook is sent with a different ref then the daemon will return a 666 error response.	no

Transformations

GitHubCommits

The GitHubCommits transformation will extract all the commits (added, modified, removed) from a push event and return a CSV encoded list of rows consisting of: commit hash, repository name, path. For example:

e3a18d4de60a5e50ca78ca1733238735ddfaef4c,sfomuseum-data-flights-2020-05,data/171/316/450/9/1713164509.geojson
e3a18d4de60a5e50ca78ca1733238735ddfaef4c,sfomuseum-data-flights-2020-05,data/171/316/451/9/1713164519.geojson
e3a18d4de60a5e50ca78ca1733238735ddfaef4c,sfomuseum-data-flights-2020-05,data/171/316/483/5/1713164835.geojson

It is defined as a URI string in the form of:

githubcommits://?exclude_additions={EXCLUDE_ADDITIONS}&exclude_modification={EXCLUDE_MODIFICATIONS}&exclude_deletions={EXCLUDE_DELETIONS}

Properties

Name	Value	Description	Required
exclude_additions	boolean	A flag to indicate that new additions in a commit should be ignored.	no
exclude_modifications	boolean	A flag to indicate that modifications in a commit should be ignored.	no
exclude_deletions	boolean	A flag to indicate that deletions in a commit should be ignored.	no

GitHubRepo

The GitHubRepo transformation will extract the reporsitory name for all the commits matching (added, modified, removed) criteria. It is defined as a URI string in the form of:

githubrepo://?exclude_additions={EXCLUDE_ADDITIONS}&exclude_modification={EXCLUDE_MODIFICATIONS}&exclude_deletions={EXCLUDE_DELETIONS}

Properties

Name	Value	Description	Required
exclude_additions	boolean	A flag to indicate that new additions in a commit should be ignored.	no
exclude_modifications	boolean	A flag to indicate that modifications in a commit should be ignored.	no
exclude_deletions	boolean	A flag to indicate that deletions in a commit should be ignored.	no

See also

• https://github.com/whosonfirst/go-webhookd

Documentation

Overview

package github implements the `whosonfirst/go-webhookd` interfaces for receiving and transforming webhooks originating from GitHub.

Index

• func GenerateSignature(body string, secret string) (string, error)
• func NewGitHubCommitsTransformation(ctx context.Context, uri string) (webhookd.WebhookTransformation, error)
• func NewGitHubReceiver(ctx context.Context, uri string) (webhookd.WebhookReceiver, error)
• func NewGitHubRepoTransformation(ctx context.Context, uri string) (webhookd.WebhookTransformation, error)
• func UnmarshalEvent(event_type string, body []byte) (interface{}, error)
• type GitHubCommitsTransformation
  • func (p *GitHubCommitsTransformation) Transform(ctx context.Context, body []byte) ([]byte, *webhookd.WebhookError)
• type GitHubReceiver
  • func (wh GitHubReceiver) Receive(ctx context.Context, req *http.Request) ([]byte, *webhookd.WebhookError)
• type GitHubRepoTransformation
  • func (p *GitHubRepoTransformation) Transform(ctx context.Context, body []byte) ([]byte, *webhookd.WebhookError)

Functions

func GenerateSignature

func GenerateSignature(body string, secret string) (string, error)

GenerateSignature() generates a GitHub-compatiable signature derived from 'body' and 'secret'.

func NewGitHubCommitsTransformation

func NewGitHubCommitsTransformation(ctx context.Context, uri string) (webhookd.WebhookTransformation, error)

NewGitHubCommitsTransformation() creates a new `GitHubCommitsTransformation` instance, configured by 'uri' which is expected to take the form of:

githubcommits://?{PARAMETERS}

Where {PARAMTERS} is: * `?exclude_additions` An optional boolean value to exclude newly added files from the final output. * `?exclude_modifications` An optional boolean value to exclude update (modified) files from the final output. * `?exclude_deletions` An optional boolean value to exclude deleted files from the final output.

func NewGitHubReceiver

func NewGitHubReceiver(ctx context.Context, uri string) (webhookd.WebhookReceiver, error)

NewGitHubReceiver instantiates a new `GitHubReceiver` for receiving webhook messages from GitHub, configured by 'uri' which is expected to take the form of:

github://?secret={SECRET}&ref={BRANCH}

Where {SECRET} is the shared secret used to generate signatures to validate messages and {BRANCH} is the optional branch (reference) name to limit message processing to.

func NewGitHubRepoTransformation

func NewGitHubRepoTransformation(ctx context.Context, uri string) (webhookd.WebhookTransformation, error)

NewGitHubRepoTransformation() creates a new `GitHubRepoTransformation` instance, configured by 'uri' which is expected to take the form of:

githubrepo://?{PARAMETERS}

Where {PARAMTERS} is: * `?exclude_additions` An optional boolean value to exclude newly added files from consideration. * `?exclude_modifications` An optional boolean value to exclude update (modified) files from consideration. * `?exclude_deletions` An optional boolean value to exclude deleted files from consideration.

func UnmarshalEvent

func UnmarshalEvent(event_type string, body []byte) (interface{}, error)

UnmarshalEvent unmarshals a GitHub event message derived from 'body' in to an interface of type 'event_type'.

Types

type GitHubCommitsTransformation

type GitHubCommitsTransformation struct {
	webhookd.WebhookTransformation
	// ExcludeAdditions is a boolean flag to exclude newly added files from the final output.
	ExcludeAdditions bool
	// ExcludeModifications is a boolean flag to exclude updated (modified) files from the final output.
	ExcludeModifications bool
	// ExcludeDeletions is a boolean flag to exclude deleted files from the final output.
	ExcludeDeletions bool
}

GitHubCommitsTransformation implements the `webhookd.WebhookTransformation` interface for transforming GitHub commit webhook messages in to CSV data containing: the commit hash, the name of the repository and the path to the file commited.

func (*GitHubCommitsTransformation) Transform

func (p *GitHubCommitsTransformation) Transform(ctx context.Context, body []byte) ([]byte, *webhookd.WebhookError)

Transform() transforms 'body' (which is assumed to be a GitHub commit webhook message) in to CSV data containing: the commit hash, the name of the repository and the path to the file commited.

type GitHubReceiver

type GitHubReceiver struct {
	webhookd.WebhookReceiver
	// contains filtered or unexported fields
}

GitHubReceiver implements the `webhookd.WebhookReceiver` interface for receiving webhook messages from GitHub.

func (GitHubReceiver) Receive

func (wh GitHubReceiver) Receive(ctx context.Context, req *http.Request) ([]byte, *webhookd.WebhookError)

Receive() returns the body of the message in 'req'. It ensures that messages are sent as HTTP `POST` requests, that both `X-GitHub-Event` and `X-Hub-Signature` headers are present, that message body produces a valid signature using the secret used to create 'wh' and, if necessary, that the message is associated with the branch used to create 'wh'.

type GitHubRepoTransformation

type GitHubRepoTransformation struct {
	webhookd.WebhookTransformation
	// ExcludeAdditions is a boolean flag to exclude newly added files from consideration.
	ExcludeAdditions bool
	// ExcludeModifications is a boolean flag to exclude updated (modified) files from consideration.
	ExcludeModifications bool
	// ExcludeDeletions is a boolean flag to exclude updated (modified) files from consideration.
	ExcludeDeletions bool
}

GitHubRepoTransformation implements the `webhookd.WebhookTransformation` interface for transforming GitHub commit webhook messages in to the name of the repository where the commit occurred.

func (*GitHubRepoTransformation) Transform

func (p *GitHubRepoTransformation) Transform(ctx context.Context, body []byte) ([]byte, *webhookd.WebhookError)

Transform() transforms 'body' (which is assumed to be a GitHub commit webhook message) in to name of the repository where the commit occurred.