maintainerbot

README

maintainerbot

Maintainerbot is designed to make it easy to create custom bots for interacting with Github repositories. The core of Maintainerbot is maintner, a Go program that creates an in-memory representation of your Github repository. Removing the Github API (and the need to handle rate limits, and paging) is a great way to make creating bots easy.

(maintner and gopherbot are written by the Go Authors, and available from the golang.org/x/build package.)

Usage

Here's a bot that can check whether users have signed the CLA, against a list of usernames stored in a spreadsheet.

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond)
defer cancel()

token := os.Getenv("GITHUB_TOKEN")
ghc := maintainerbot.NewGitHubClient(token, 0)
bot := maintainerbot.New("rails", "rails", token)
spreadsheetURL := "https://docs.google.com/spreadsheets/d/<key>/export?format=csv&sheet=0"
cla := tasks.NewCLAChecker(ghc, "http://example.com/sign-cla", tasks.NewSpreadsheetFetcher(spreadsheetURL))
cla.StartFetch(ctx)
bot.RegisterTask(cla)
bot.Run(ctx)

Other task types are available in the tasks package.

Installation

go get -u github.com/sourcegraph/maintainerbot

More Docs/Examples

Check out the godoc for more comprehensive documentation. A running example (the one used by Sourcegraph, as of October 2018) can be found in the examples directory.

Documentation

Overview

Package maintainerbot contains tools for running automated tasks on a Github repo.

Call maintainerbot.New() to create a new bot, then register tasks on it with bot.RegisterTask(). Finally, bot.Run() will run the tasks in a loop, calling each Task periodically. The Task can do whatever it needs to do to update the repository as it sees fit.

Example

package main

import (
	"context"
	"os"
	"time"

	"github.com/sourcegraph/maintainerbot"
	"github.com/sourcegraph/maintainerbot/tasks"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond)
	defer cancel()

	token := os.Getenv("GITHUB_TOKEN")
	ghc := maintainerbot.NewGitHubClient(token, 0)
	bot := maintainerbot.New("golang", "go", token)
	spreadsheetURL := "https://docs.google.com/spreadsheets/d/<key>/export?format=csv&sheet=0"
	cla := tasks.NewCLAChecker(ghc, "http://example.com/sign-cla", tasks.NewSpreadsheetFetcher(spreadsheetURL))
	cla.StartFetch(ctx)
	congrats := tasks.NewCongratulator(ghc, "Congrats, @{{ .Username }}!")
	bot.RegisterTask(cla)
	bot.RegisterTask(congrats)
	bot.Run(ctx)
}

Index

• func NewGitHubClient(token string, rateLimit time.Duration) *github.Client
• type Bot
  • func New(owner, repo, token string) *Bot
  • func (b *Bot) RegisterTask(t Task)
  • func (b *Bot) Run(ctx context.Context)
• type Task

Examples

• Package
• Task

Functions

func NewGitHubClient

func NewGitHubClient(token string, rateLimit time.Duration) *github.Client

NewGitHubClient creates a new GitHub client for the given token. rateLimit is the duration between requests; a rate limit of 0 defaults to 5000 requests per hour.

Types

type Bot

type Bot struct {
	// Directory for caching local data about issues and pull requests.
	// Defaults to $HOME/var/maintainerbot.
	DataDir string
	// Interval between queries to send to GitHub. Defaults to 720ms, which
	// works out to 5000 queries per hour.
	GitHubRateLimit time.Duration
	// contains filtered or unexported fields
}

func New

func New(owner, repo, token string) *Bot

New creates a new Bot.

func (*Bot) RegisterTask

func (b *Bot) RegisterTask(t Task)

RegisterTask registers t with the bot. When the Bot is running, t will be called periodically with the latest repo contents.

func (*Bot) Run

func (b *Bot) Run(ctx context.Context)

Run calls each registered task in turn with the updated contents of the GitHub repository, until the context is canceled. If a task returns a non-zero error, it is logged to the console.

type Task

type Task interface {
	Do(ctx context.Context, repo *maintner.GitHubRepo) error
}

Task is any periodic task that you would like to run on the repository.

Example

package main

import (
	"context"
	"os"
	"strings"

	maintainerbot "github.com/sourcegraph/maintainerbot"
	"golang.org/x/build/maintner"
)

type docTask struct{}

// Do labels each GitHub issue containing the word "doc" in the title with the
// "Documentation" label.
func (d *docTask) Do(ctx context.Context, repo *maintner.GitHubRepo) error {
	return repo.ForeachIssue(func(gi *maintner.GitHubIssue) error {
		if gi.Closed || gi.PullRequest || !strings.Contains(gi.Title, "doc") || gi.HasLabel("Documentation") {
			return nil
		}
		// Issue needs a "documentation" label, add it here.
		return nil
	})
}

func main() {
	d := &docTask{}
	bot := maintainerbot.New("rails", "rails", os.Getenv("GITHUB_TOKEN"))
	bot.RegisterTask(d)
	bot.Run(context.TODO())
}