https://github.com/prajithp/github-app
framework for building GitHub Apps
https://github.com/prajithp/github-app
Last synced: 11 months ago
JSON representation
framework for building GitHub Apps
- Host: GitHub
- URL: https://github.com/prajithp/github-app
- Owner: Prajithp
- Created: 2025-06-16T04:44:07.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-06-16T14:31:51.000Z (12 months ago)
- Last Synced: 2025-06-23T11:01:38.499Z (12 months ago)
- Language: Go
- Size: 17.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# GitHub App Framework
A robust Go framework for building GitHub Apps with webhook handling, configuration management, and utilities for interacting with the GitHub API. This is a wrapper around the [palantir/go-githubapp](https://github.com/palantir/go-githubapp) library.
## Installation
```bash
go get github.com/Prajithp/github-app
```
## Quick Start
### 1. Create a Configuration File
Create a `config.yaml` file:
```yaml
server:
address: "0.0.0.0"
port: 8080
max_queue_size: 1000
max_workers: 50
route: "/api/webhooks/github"
github:
web_url: "https://github.com"
v3_api_url: "https://api.github.com"
v4_api_url: "https://api.github.com/graphql"
app:
integration_id: 123456 # Your GitHub App ID
webhook_secret: "your-webhook-secret"
private_key: |
-----BEGIN RSA PRIVATE KEY-----
YOUR_PRIVATE_KEY_HERE
-----END RSA PRIVATE KEY-----
```
### 2. Create an Event Handler
```go
package handlers
import (
"context"
"github.com/Prajithp/github-app/utils"
"github.com/google/go-github/v72/github"
"github.com/rs/zerolog/log"
)
type PullRequestHandler struct{}
func (h *PullRequestHandler) Handles() []string {
return []string{"pull_request"}
}
func (h *PullRequestHandler) Handle(ctx context.Context, eventType, deliveryID string, payload []byte) error {
event, err := utils.ParseEvent[github.PullRequestEvent](payload)
if err != nil {
return err
}
log.Info().
Str("action", event.GetAction()).
Str("pr_number", fmt.Sprintf("%d", event.GetPullRequest().GetNumber())).
Str("repo", event.GetRepo().GetFullName()).
Msg("Handling pull request event")
// Your logic here
return nil
}
```
### 3. Create the Main Application
```go
package main
import (
"context"
"os"
"os/signal"
"syscall"
"github.com/Prajithp/github-app/config"
"github.com/Prajithp/github-app/server"
"github.com/Prajithp/github-app/utils"
"github.com/palantir/go-githubapp/githubapp"
"github.com/rs/zerolog"
"github.com/rs/zerolog/log"
)
func main() {
// Setup logging
utils.SetupLogger("my-github-app", "1.0.0", zerolog.InfoLevel)
// Load configuration
cfg, err := utils.ReadConfig[config.Config]("config.yaml", "GITHUB_APP")
if err != nil {
log.Fatal().Err(err).Msg("Failed to load configuration")
}
// Create GitHub client creator
cc, err := githubapp.NewDefaultCachingClientCreator(
githubapp.Config{
V3APIURL: cfg.Github.V3APIURL,
V4APIURL: cfg.Github.V4APIURL,
App: githubapp.App{
IntegrationID: cfg.Github.App.IntegrationID,
WebhookSecret: cfg.Github.App.WebhookSecret,
PrivateKey: cfg.Github.App.PrivateKey,
},
},
)
if err != nil {
log.Fatal().Err(err).Msg("Failed to create client creator")
}
// Create server with handlers
srv, err := server.New(
&cfg,
server.WithClientCreator(cc),
server.WithEventHandlers(
&handlers.PullRequestHandler{},
// Add more handlers here
),
)
if err != nil {
log.Fatal().Err(err).Msg("Failed to create server")
}
// Start server
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
if err := srv.Start(ctx); err != nil {
log.Fatal().Err(err).Msg("Server failed to start")
}
}
```
## Configuration
### Environment Variables
All configuration values can be overridden using environment variables:
| Config Path | Environment Variable | Default |
|------------|---------------------|---------|
| `server.address` | `GITHUB_APP_SERVER_ADDRESS` or `SERVER_ADDRESS` | `0.0.0.0` |
| `server.port` | `GITHUB_APP_SERVER_PORT` or `SERVER_PORT` | `8080` |
| `server.max_workers` | `GITHUB_APP_MAX_WORKERS` or `MAX_WORKERS` | `50` |
| `server.max_queue_size` | `GITHUB_APP_MAX_QUEUE_SIZE` or `MAX_QUEUE_SIZE` | `1000` |
| `server.route` | `GITHUB_APP_SERVER_ROUTE` or `SERVER_ROUTE` | `/api/webhooks/github` |
| `github.app.integration_id` | `GITHUB_APP_ID` | - |
| `github.app.webhook_secret` | `GITHUB_WEBHOOK_SECRET` | - |
| `github.app.private_key` | `GITHUB_PRIVATE_KEY` | - |
| `github.web_url` | `GITHUB_WEB_URL` | `https://github.com` |
| `github.v3_api_url` | `GITHUB_V3_API_URL` | `https://api.github.com` |
| `github.v4_api_url` | `GITHUB_V4_API_URL` | `https://api.github.com/graphql` |
## Advanced Usage
### Loading Repository Configuration
The framework supports loading app-specific configuration from repositories:
```go
// Define your repository config structure
type RepoConfig struct {
Enabled bool `yaml:"enabled"`
Features []string `yaml:"features"`
Settings map[string]interface{} `yaml:"settings"`
}
// Create a config loader
loader := appconfig.NewLoader(
appconfig.WithOwner("myorg"),
appconfig.WithRepo("myrepo"),
)
configLoader := utils.NewAppConfigLoader[RepoConfig](
utils.WithAppConfigLoader[RepoConfig](loader),
)
// Load config from repository
repoConfig, err := configLoader.LoadRepositoryConfig(
ctx,
githubClient,
"owner",
"repo",
"main", // branch
)
```
## Acknowledgments
- Built on top of [palantir/go-githubapp](https://github.com/palantir/go-githubapp)
- Uses [google/go-github](https://github.com/google/go-github) for GitHub API interactions
- Logging powered by [rs/zerolog](https://github.com/rs/zerolog)