Package github

import "github.com/matrix-org/go-neb/services/github"

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.


const ServiceType = "github"

ServiceType of the Github service

const WebhookServiceType = "github-webhook"

WebhookServiceType of the Github Webhook service.

type Service

type Service struct {
    // 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

func (s *Service) Commands(cli *matrix.Client) []types.Command

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.

func (*Service) Expansions

func (s *Service) Expansions(cli *matrix.Client) []types.Expansion

Expansions expands strings of the form:


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:


using the default repository.

func (*Service) Register

func (s *Service) Register(oldService types.Service, client *matrix.Client) error

Register makes sure that the given realm ID maps to a github realm.

type WebhookService

type WebhookService struct {

    // 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/closed.
            //    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.
            // Full list: 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"]

func (*WebhookService) OnReceiveWebhook

func (s *WebhookService) OnReceiveWebhook(w http.ResponseWriter, req *http.Request, cli *matrix.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

func (s *WebhookService) Register(oldService types.Service, client *matrix.Client) error

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.


Name Synopsis