sauron

README

sauron

Watch for changes to a file in a public GitHub repository, get notifications.

Design

Sauron is designed to be run on a schedule, whether that's a CRON job, a CloudWatch shedule or something else. Each invocation provides details about which repository to watch (and optionally which branch / path within that repository). Sauron fetches the current state and compares it against the stored state. If there is a difference, a notification is published (except on the first run).

Sauron is designed to allow for easy extension of the storage notification backends. Details below.

Storage

Sauron currently supports the following methods for storing state:

• S3 bucket
• PostgresSQL database
• File

Notifications

Sauron currently supports the following methods for notifying about changes:

• SNS topic
• File

Deploy

You have a few options when it comes to deploy Sauron. Currently supported are a standlone CLI with a CRON job and an AWS deployment using Lambda, S3 for storage and SNS for notifications.

Standalone

Sauron comes with a standalone CLI. If you have a go toolchain, you can simply run:

go install github.com/Bowbaq/sauron/cmd/sauron

Otherwise the releases page will have the latest binaries for your platform.

Usage

Usage:
  sauron [OPTIONS]

notifier.sns:
      --notifier.sns.topic-arn= ARN of the SNS topic [$SNS_TOPIC_ARN]

notifier.file:
      --notifier.file.path=     path of the state file [$NOTIFY_FILE_PATH]

store.s3:
      --store.s3.bucket=        name of the bucket [$S3_BUCKET]
      --store.s3.key=           path to the key (default: state.json) [$S3_KEY]

store.postgres:
      --store.pg.datasource=    postgresql datasource (see database/sql) [$PG_DATASOURCE]

store.file:
      --store.file.path=        path of the state file (default: .sauron) [$STORE_FILE_PATH]

github:
      --github.owner=           owner of the repository [$GITHUB_OWNER]
      --github.repository=      name of the repository [$GITHUB_REPOSITORY]
      --github.branch=          branch to watch in the repository [$GITHUB_BRANCH]
      --github.path=            path to watch in the repository [$GITHUB_PATH]

Help Options:
  -h, --help                    Show this help message

Example CRON job:

0 * * * * sauron --github.owner Bowbaq --github.repository sauron --notifier.file.path sauron.changelog

AWS

Dependencies

The AWS deployment script needs the following tools to be installed:

• apex - package the Go lambda into a format AWS can run
• terraform - manage the infrastructure
• aws-cli - apply infrastructure tweaks that terraform cannot support

Configuration

1. Clone this repository in a convenient location.

   git clone https://github.com/Bowbaq/sauron.git
   

2. Create the configuration file from the template, then customize

   cp infrastructure/terraform.tfvars.template infrastructure/terraform.tfvars
   

   • Update the account_id (you can find it here)
   • Add your own watches to the list (by default sauron watches this file)

Deployment

1. Run the deployment script

   AWS_PROFILE=<profile> AWS_DEFAULT_REGION=<region> ./scripts/deploy-aws
   

   This will:
   • Package the lambda function
   • Create the needed infrastructure.

     Note: This may not be free, but it should be cheap (and I'm not responsible for any cost you might incur)

Congratulations, Sauron is now publishing change events to an SNS topic. You can get the ARN by running:

(cd infrastructure; terraform output sns_topic)

You can get email notification by subscribing to the topic:

aws sns subscribe                                                \
  --topic-arn "$(cd infrastructure; terraform output sns_topic)" \
  --protocol email                                               \
  --notification-endpoint john.doe@example.com

Documentation

Index

• type Options
• type Sauron
  • func New(opts Options) *Sauron
  • func (s *Sauron) SetNotifier(n notifier.Notifier)
  • func (s *Sauron) SetStore(db store.Store)
  • func (s *Sauron) SetWatcher(w watcher.Watcher)
  • func (s *Sauron) Watch(opts model.WatchOptions) error

Types

type Options

type Options struct {
	WatcherOptions  watcher.Options  `group:"watcher" namespace:"watcher"`
	NotifierOptions notifier.Options `group:"notifier" namespace:"notifier"`
	StoreOptions    store.Options    `group:"store" namespace:"store"`
}

Options contains the parameters necessary to configure Sauron

type Sauron

type Sauron struct {
	// contains filtered or unexported fields
}

Sauron watches for changes in GitHub repositories

func New

func New(opts Options) *Sauron

New creates a new instance of Sauron. If no options are provided, the sate is stored in a file (.sauron) and notifications are written to standard error

func (*Sauron) SetNotifier

func (s *Sauron) SetNotifier(n notifier.Notifier)

SetNotifier overrides the notifier

func (*Sauron) SetStore

func (s *Sauron) SetStore(db store.Store)

SetStore sets the store

func (*Sauron) SetWatcher

func (s *Sauron) SetWatcher(w watcher.Watcher)

SetWatcher overrides the watcher

func (*Sauron) Watch

func (s *Sauron) Watch(opts model.WatchOptions) error

Watch checks for updates in the target repository