Documentation
¶
Overview ¶
Package github implements a command service and a webhook service for interacting with Github.
The command service is a service which adds !commands and issue expansions for Github. The webhook service adds Github webhook support.
Index ¶
Constants ¶
const ServiceType = "github"
ServiceType of the Github service
const WebhookServiceType = "github-webhook"
WebhookServiceType of the Github Webhook service.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Service ¶
type Service struct {
types.DefaultService
// The ID of an existing "github" realm. This realm will be used to obtain
// credentials of users when they create issues on Github.
RealmID string
}
Service contains the Config fields for the Github service.
Before you can set up a Github Service, you need to set up a Github Realm.
You can set a "default repository" for a Matrix room by sending a `m.room.bot.options` state event which has the following `content`:
{
"github": {
"default_repo": "owner/repo"
}
}
This will allow the "owner/repo" to be omitted when creating/expanding issues.
Example request:
{
"RealmID": "github-realm-id"
}
func (*Service) Commands ¶
Commands supported:
!github create owner/repo "issue title" "optional issue description"
Responds with the outcome of the issue creation request. This command requires a Github account to be linked to the Matrix user ID issuing the command. If there is no link, it will return a Starter Link instead.
!github comment [owner/repo]#issue "comment"
Responds with the outcome of the issue comment creation request. This command requires a Github account to be linked to the Matrix user ID issuing the command. If there is no link, it will return a Starter Link instead.
func (*Service) Expansions ¶
Expansions expands strings of the form:
owner/repo#12
Where #12 is an issue number or pull request. If there is a default repository set on the room, it will also expand strings of the form:
#12
using the default repository.
type WebhookService ¶
type WebhookService struct {
types.DefaultService
// The user ID to create/delete webhooks as.
ClientUserID string
// The ID of an existing "github" realm. This realm will be used to obtain
// the Github credentials of the ClientUserID.
RealmID string
// A map from Matrix room ID to Github "owner/repo"-style repositories.
Rooms map[string]struct {
// A map of "owner/repo"-style repositories to the events to listen for.
Repos map[string]struct {
// The webhook events to listen for. Currently supported:
// push : When users push to this repository.
// pull_request : When a pull request is made to this repository.
// issues : When an issue is opened/edited/closed/reopened.
// issue_comment : When an issue or pull request is commented on.
// pull_request_review_comment : When a line comment is made on a pull request.
// labels : When any issue or pull request is labeled/unlabeled. Unique to Go-NEB.
// milestones : When any issue or pull request is milestoned/demilestoned. Unique to Go-NEB.
// assignments : When any issue or pull request is assigned/unassigned. Unique to Go-NEB.
// Most of these events are directly from: https://developer.github.com/webhooks/#events
Events []string
}
}
// Optional. The secret token to supply when creating the webhook. If supplied,
// Go-NEB will perform security checks on incoming webhook requests using this token.
SecretToken string
// contains filtered or unexported fields
}
WebhookService contains the Config fields for the Github Webhook Service.
Before you can set up a Github Service, you need to set up a Github Realm. This service does not require a syncing client.
This service will send notices into a Matrix room when Github sends webhook events to it. It requires a public domain which Github can reach. Notices will be sent as the service user ID, not the ClientUserID.
Example request:
{
ClientUserID: "@alice:localhost",
RealmID: "github-realm-id",
Rooms: {
"!qmElAGdFYCHoCJuaNt:localhost": {
Repos: {
"matrix-org/go-neb": {
Events: ["push", "issues", "pull_request", "labels"]
}
}
}
}
}
func (*WebhookService) OnReceiveWebhook ¶
func (s *WebhookService) OnReceiveWebhook(w http.ResponseWriter, req *http.Request, cli *gomatrix.Client)
OnReceiveWebhook receives requests from Github and possibly sends requests to Matrix as a result.
If the "owner/repo" string in the webhook request case-insensitively matches a repo in this Service config AND the event type matches an event type registered for that repo, then a message will be sent into Matrix.
If the "owner/repo" string doesn't exist in this Service config, then the webhook will be deleted from Github.
func (*WebhookService) PostRegister ¶
func (s *WebhookService) PostRegister(oldService types.Service)
PostRegister cleans up removed repositories from the old service by working out the delta between the old and new hooks.
func (*WebhookService) Register ¶
Register will create webhooks for the repos specified in Rooms
The hooks made are a delta between the old service and the current configuration. If all webhooks are made, Register() succeeds. If any webhook fails to be created, Register() fails. A delta is used to allow clients to incrementally build up the service config without recreating the hooks every time a change is made.
Hooks are deleted when this service receives a webhook event from Github for a repo which has no user configurations.
Hooks can get out of sync if a user manually deletes a hook in the Github UI. In this case, toggling the repo configuration will force NEB to recreate the hook.
Source Files
Directories