Hamster

KO | EN

gitlite — search

#python #react #machine-learning #java #javascript #api #deep-learning #python3 #tensorflow #php #nodejs #swift

★ 43 Open GitHub ↗

🐀 A Bot toolkit for github that supports OAuth, Events, API, Custom Commands and Check Runs.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
    <img alt="Hamster Logo" src="https://raw.githubusercontent.com/Clivern/Hamster/master/assets/img/logo.png" height="80" />
    <h3 align="center">Hamster</h3>
    <p align="center">A Bot Toolkit for Github!</p>
</p>

## Documentation

### Config & Run The Application

Hamster uses [Go Modules](https://github.com/golang/go/wiki/Modules) to manage dependencies. First Create a dist config file.

```bash
$ cp config.json config.dist.json
```

Then add your `app_mode`, `app_port`, `app_log_level`, `github_token`, `github_webhook_secret`, `repository_author` and `repository_name`

```json
{
    "app_mode": "prod",
    "app_port": "8080",
    "app_log_level": "info",
    "github_token": "...",
    "github_webhook_secret": "...",
    "repository_author": "Clivern",
    "repository_name": "Hamster",

"app_domain": "example.com",
    "github_app_client_id": "..",
    "github_app_redirect_uri": "..",
    "github_app_allow_signup": "true",
    "github_app_scope": "..",
    "github_app_client_secret": ".."
}
```

You can config `app_domain` and the rest of github app configs `github_app_*` in case you need a github app not a personal bot.

Add a new webhook from `Settings > Webhooks`, Set the `Payload URL` to be `https://hamster.com/listen`, `Content type` as `JSON` and Add Your Webhook Secret.

And then run the application

```bash
$ go build hamster.go
$ ./hamster

// OR

$ go run hamster.go
```

Also running hamster with docker still an option. Just don't forget to update `GithubToken`, `GithubWebhookSecret`, `RepositoryAuthor` and `RepositoryName` inside `docker-compose.yml` file. Then run the following stuff

```bash
$ docker-compose build
$ docker-compose up -d
```

### Customize the Default Event Listeners

Anytime github call hamster listen endpoint, there will be a callback that get called with incoming data. For example when you get a status change call from github, the `StatusListener(status event.Status)` will get called. So do whatever you need inside this callback.

**any event:** any time listen endpoint get a call, the following callback get called.

```go
// plugin/base.go

// Any Action
func RawListener(raw event.Raw) (bool, error) {
    logger.Info("Raw event listener fired!")
    return true, nil
}
```

**[status event:](https://developer.github.com/v3/activity/events/types/#statusevent)** any time a Repository has a status update from the API, The following callback get called.
```go
// plugin/base.go

// Status Action
func StatusListener(status event.Status) (bool, error) {
    logger.Info("Status event listener fired!")
    return true, nil
}
```

**[watch event:](https://developer.github.com/v3/activity/events/types/#watchevent)** any time a User stars a Repository.
```go
// plugin/base.go

// Watch Action
func WatchListener(watch event.Watch) (bool, error) {
    logger.Info("Watch event listener fired!")
    return true, nil
}
```

**[issues event:](https://developer.github.com/v3/activity/events/types/#issuesevent)** any time an Issue is assigned, unassigned, labeled, unlabeled, opened, edited, milestoned, demilestoned, closed, or reopened.
```go
// plugin/base.go

// Issue Action
func IssuesListener(issues event.Issues) (bool, error) {
    logger.Info("Issues event listener fired!")
    return true, nil
}
```

**[issue_comment event:](https://developer.github.com/v3/activity/events/types/#issuecommentevent)** any time a comment on an issue is created, edited, or deleted.
```go
// plugin/base.go

// Issue Comment Action
func IssueCommentListener(issueComment event.IssueComment) (bool, error) {
    logger.Info("IssueComment event listener fired!")
    return true, nil
}
```

**[push event:](https://developer.github.com/v3/activity/events/types/#pushevent)** Any Git push to a Repository, including editing tags or branches. Commits via API actions that update references are also counted. This is the default event.
```go
// plugin/base.go

// Push Action
func PushListener(push event.Push) (bool, error) {
    logger.Info("Push event listener fired!")
    return true, nil
}
```

**[create event:](https://developer.github.com/v3/activity/events/types/#createevent)** Any time a Branch or Tag is created.

```go
// plugin/base.go

// Create Action
func CreateListener(create event.Create) (bool, error) {
    logger.Info("Create event listener fired!")
    return true, nil
}
```

**[label event:](https://developer.github.com/v3/activity/events/types/#labelevent)** Any time a Label is created, edited, or deleted.

```go
// plugin/base.go

// Label Action
func LabelListener(label event.Label) (bool, error) {
    logger.Info("Label event listener fired!")
    return true, nil
}
```

**[delete event:](https://developer.github.com/v3/activity/events/types/#deleteevent)** Any time a branch or tag is deleted.

```go
// plugin/base.go

// Delete Action
func DeleteListener(delete event.Delete) (bool, error) {
    logger.Info("Delete event listener fired!")
    return true, nil
}
```

**[milestone event:](https://developer.github.com/v3/activity/events/types/#milestoneevent)** Any time a Milestone is created, closed, opened, edited, or deleted.

```go
// plugin/base.go

// Milestone Action
func MilestoneListener(milestone event.Milestone) (bool, error) {
    logger.Info("Milestone event listener fired!")
    return true, nil
}
```

**[pull_request event:](https://developer.github.com/v3/activity/events/types/#pullrequestevent)** Any time a pull request is assigned, unassigned, labeled, unlabeled, opened, edited, closed, reopened, or synchronized (updated due to a new push in the branch that the pull request is tracking). Also any time a pull request review is requested, or a review request is removed.

```go
// plugin/base.go

// Pull Request Action
func PullRequestListener(pullRequest event.PullRequest) (bool, error) {
    logger.Info("PullRequest event listener fired!")
    return true, nil
}
```

**[pull_request_review event:](https://developer.github.com/v3/activity/events/types/#pullrequestreviewevent)** Any time a pull request review is submitted, edited, or dismissed.

```go
// plugin/base.go

// Pull Request Review Action
func PullRequestReviewListener(pullRequestReview event.PullRequestReview) (bool, error) {
    logger.Info("PullRequestReview event listener fired!")
    return true, nil
}
```

**[pull_request_review_comment event:](https://developer.github.com/v3/activity/events/types/#pullrequestreviewcommentevent)** Any time a comment on a pull request's unified diff is created, edited, or deleted (in the Files Changed tab).

```go
// plugin/base.go

// Pull Request Review Comment Action
func PullRequestReviewCommentListener(pullRequestReviewComment event.PullRequestReviewComment) (bool, error) {
    logger.Info("PullRequestReviewComment event listener fired!")
    return true, nil
}
```

All current supported events and the future events will be available on `plugin/base.go`. Also it is handy to add aditional callbacks so each event can have any number of callbacks.

Also please check [the latest github webhooks guide](https://developer.github.com/webhooks/).

### Build Custom Commands

In order to build an interactive bot, you will need to listen to a pre-defined commands that once your repo users type on an issue or a comment, your application get notified. Github don't support this by default but it is still possible to achieve this manually.

First you need to define you command and the callback on `internal/app/controller/listener.go`, exactly like the `test` command:

```go
// The default test command for issue comments
commands.RegisterIssueCommentAction("test", plugin.IssueCommentTestCommandListener)

//The new run command for issue comments
commands.RegisterIssueCommentAction("run", plugin.IssueCommentRunCommandListener)
```

```go
// The default test command for issues
commands.RegisterIssuesAction("test", plugin.IssuesTestCommandListener)

//The new run command for issues
commands.RegisterIssuesAction("run", plugin.IssuesRunCommandListener)
```

Then define the callbacks on `plugin/base.go` same as `test` commands callbacks:

```go
// Test Command Callbacks
// Test Command Listener for Issues
func IssuesTestCommandListener(command event.Command, issues event.Issues) (bool, error) {
    logger.Info("IssuesTestCommandListener event listener fired!")
    return true, nil
}

// Test Command Listener for Issues Comments
func IssueCommentTestCommandListener(command event.Command, issue_comment event.IssueComment) (bool, error) {
    logger.Info("IssueCommentTestCommandListener event listener fired!")
    return true, nil
}

// Run Command Callbacks
// Run Command Listener for Issues
func IssuesRunCommandListener(command event.Command, issues event.Issues) (bool, error) {
    logger.Info("IssuesTestCommandListener event listener fired!")
    return true, nil
}

// Run Command Listener for Issues Comments
func IssueCommentRunCommandListener(command event.Command, issue_comment event.IssueComment) (bool, error) {
    logger.Info("IssueCommentTestCommandListener event listener fired!")
    return true, nil
}
```

Now if you create a new issue or issue comment, the related callbacks will get notified with command object:

```go
/test
/test{option1}
/test{option1,option2}
/test{option1,option2,option3}

/run
/run{option1}
/run{option1,option2}
/run{option1,option2,option3}

The command object will be

event.Command{Name=test, Parameters=[]}
event.Command{Name=test, Parameters=[option1]}
event.Command{Name=test, Parameters=[option1 option2]}
event.Command{Name=test, Parameters=[option1 option2 option3]}

event.Command{Name=run, Parameters=[]}
event.Command{Name=run, Parameters=[option1]}
event.Command{Name=run, Parameters=[option1 option2]}
event.Command{Name=run, Parameters=[option1 option2 option3]}
```

### Create a Github Comment

```go
// for more info https://developer.github.com/v3/issues/comments/#create-a-comment

import (
    "github.com/clivern/hamster/internal/app/pkg/github"
    "os"
)