README.md

⚠️ Go Sync is under active development and subject to breaking changes.

Go Sync (all the things)

You have people*. You have places you want them to be. Go Sync makes it happen.

* Doesn't have to be people.

Installation

go get github.com/ovotech/go-sync@latest

# Then get the adapters you need.
go get github.com/ovotech/go-sync/adapters/slack@latest

You're ready to Go Sync! 🎉

Usage

Read the documentation on pkg.go.dev.

Go Sync consists of two fundamental parts:

1. Sync
2. Adapters

As long as your adapters are compatible, you can synchronise anything.

// Create an adapter using the recommended method.
client := service.New("some-token")
source := myAdapter.New(client, "some-value")

// Initialise an adapter using an Init function.
destination, err := myAdapter.Init(map[gosync.ConfigKey]string{
	myAdapter.Token:     "some-token",
	myAdapter.Something: "some-value",
})
if err != nil {
	log.Fatal(err)
}

sync := gosync.New(source)

err := sync.SyncWith(context.Background(), destination)
if err != nil {
	log.Fatal(err)
}

Init

While we recommend using New to create an adapter in most cases, some plugins may provide an Init function for instantiating them too. Init functions are intended for programmatically creating adapters either via environment variables or some other dynamic configuration.

Sync 🔄

Sync is the logic that powers the automation. It accepts a source adapter, and synchronises it with destination adapters.

Sync is only uni-directional by design. You know where your things are, and where you want them to be. It works by:

1. Get a list of things in your source service.
   1. Cache it, so you're not calling your source service more than you have to.
2. Get a list of things in your destination service.
3. Add the things that are missing.
4. Remove the things that shouldn't be there.
5. Repeat from 2 for further adapters.

Adapters 🔌

Adapters provide a common interface to services. Adapters must implement our Adapter interface and functionally perform 3 things:

1. Get the things.
2. Add some things.
3. Remove some things.

These things can be anything, but we recommend email addresses. There's no point trying to sync a Slack User ID with a GitHub user! 🙅

Can't find an adapter you're looking for? Why not write your own! ✨

Made with 💚 by OVO Energy's DevEx team