flipt-io / cup

Git Contribution Automation

cup An Instant API for Git

Warning

This is an active experiment into the benefits of managing an API over Git, so expect it to change quite frequently.

Cup helps you build APIs and automation ontop of your Git repositories.

A configurable and extensible server for managing and exposing API resources directly from a target Git repository. It exposes a Kubernetes-like declarative API, which organizes resources into typed (group + version + kind) sets. Resources can be listed, read, updated, and deleted. When changes to the state of a resource are made, the resulting calculated difference is automatically proposed as a pull or merge request on a target Git SCM. How resources map to and from API request payloads to files in your repository is handled by Controllers. Controllers are configurable and broadly extensible through the power of WASM via the Wazero runtime.

📣 Feedback

We really want to learn how you do configuration management. If you have a second, we would greatly appreciate your input on this feedback form.

cup.mp4

Table of Contents

• Features
• Roadmap
• Use cases
• Dependencies
• Server
• CLI

Features

• 🔋 Materialize API resources directly from Git
• 🏭 Manage change through a declarative API
• 🔩 Extend using the power of WASM

Roadmap

• 📦 Package and distribute controllers as OCI images
• 🛰️ Track open proposals directly through the cupd API
• 🔒 Secure access via authorization policies

Use cases

Cup is a foundation on which to build tooling around configuration repositories. We imagine folks may find all sorts of weird and wonderful applications for Cup (and we want to hear about them).

Some ideas we're brewing:

• A central CLI for exploring and editing the state of your configuration repositories
• A dashboard for exploring and editing how your services are configured
• Access controlled management for infrastructure change requests
• New project or service templating (project structure, build, test and deploy pipelines)
• Expose configuration controls (e.g. feature flags, resource requests) to non-Git users

Dependencies

• Go (>= 1.20)
• An SCM (Currently supported: GitHub, Gitea)

Server

The server component of the Cup project is known as cupd. It is a configurable API server, which exposes and manages the state of a target repository.

Building

For now, to play with cupd you will need to clone this project and build from source.

From the root of this project, run:

mkdir -p bin

go build -o bin/cupd ./cmd/cupd/...

This will produce a binary cupd in the local folder bin.

Usage

➜  cupd serve -h
DESCRIPTION
  Run the cupd server

USAGE
  cupd serve [flags]

FLAGS
  -api-address :8181          server listen address
  -api-git-repo string        target git repository URL
  -api-git-scm github         SCM type (one of [github, gitea])
  -api-local-path .           path to local source directory
  -api-resources .            path to server configuration directory (controllers, definitions and bindings)
  -api-source local           source type (one of [local, git])
  -tailscale-auth-key string  Tailscale auth key (optional)
  -tailscale-ephemeral=false  join the network as an ephemeral node (optional)
  -tailscale-hostname string  hostname to expose on Tailscale

CLI

cup is a CLI that is heavily influenced by kubectl. It can be used locally to interact and introspect a running cupd.

Installation

MacOS

brew tap flipt-io/brew

brew install cup

Building

mkdir -p bin

go build -o bin/cup ./cmd/cup/...

This will produce a binary cup in the local folder bin.

Usage

NAME:
   cup - Manage remote cupd instances

USAGE:
   cup [global options] command [command options] [arguments...]

COMMANDS:
   config, c  Access the local configuration for the cup CLI.
   help, h    Shows a list of commands or help for one command
   discovery:
     definitions, defs  List the available resource definitions
   resource:
     get     Get one or more resources
     apply   Put a resource from file on stdin
     edit    Edit a resource
     delete  Delete a resource

GLOBAL OPTIONS:
   --config value, -c value     (default: "/Users/georgemac/Library/Application Support/cup/config.json")
   --output value, -o value     (default: "table")
   --address value, -a value
   --namespace value, -n value
   --level value, -l value      set the logging level (default: "info")
   --help, -h                   show help

Appreciation

cup is built on the shoulders of giants and inspired by many awesome projects that came before.

Built on:

• The Go programming language
• The Wazero Go WASM runtime
• The wonderful SCMs (Gitea, GitHub, etc.)

Inspired by:

• Kubernetes
• Our own wonderful Flipt