Proper readme.

README.md

@@ -1,8 +1,62 @@
 # kitops - generic GitOps agent
 
-kitops monitors one or more Git repositories and performs arbitrary actions when those repositories are updated.
+kitops monitors one or more Git repositories and performs arbitrary actions when those repositories are updated. It can be used by devops:y people to implement a wide variety of Continuous Delivery and Deployment scenarios and by systems and infra teams to provide GitOps-style workflows to the developers they support.
 
-kitops is under development and not yet ready to be used.
+**kitops is under development and not yet ready to be used.**
+
+## What is GitOps?
+
+[gitops.tech](https://www.gitops.tech/):
+
+> GitOps is a way of implementing Continuous Deployment for cloud native applications. It focuses on a developer-centric experience when operating infrastructure, by using tools developers are already familiar with, including Git and Continuous Deployment tools. The core idea of GitOps is having a Git repository that always contains declarative descriptions of the infrastructure currently desired in the production environment and an automated process to make the production environment match the described state in the repository. If you want to deploy a new application or update an existing one, you only need to update the repository[.]
+
+It turns out that this model can easily be applied to any configuration management task, by leveraging the fact that Git can be used to version any kind of text.
+
+## Why would you want to use kitops?
+
+The traditional model is to have your pipelines (or actions or workflows) push deployments onto target environments.
+
+<picture>
+
+This model has several potential weaknesses:
+
+1. the pipeline has to know where the result should be delivered and deployed
+1. when the number of target environments grow numerous, some may fail while others pass, making it hard to get a passing deploy
+1. it requires the pipeline (typically executing outside the target environment) to have extensive permissions
+1. assumes developers are responsible for the environment in its entirety
+
+kitops enables the environment to "pull" deployments from a git repository.
+
+<picture>
+
+This model:
+
+- is scalable - only repository rate limiting caps the number of target environments
+- adheres to the Principle of Least Privilege - the pipeline has no access to the environment and the environment only needs read access to the repository. This is particularly relevant in Azure, where granting permissions to a pipeline requires extensive AAD permissions, but creating a service principal for kitops can be delegated to developers via the `Application Developer` role.
+- allows a third party to take responsibility for the target environment
+
+## How does kitops work?
+
+kitops has several forms of packaging, see below. The simplest way to run kitops is to test the Docker image:
+
+```shell
+docker run bittrance/kitops --url https://github.com/bittrance/kitops --action 'echo "kitops was updated"'
+```
+
+kitops is a statically compiled binary. It uses only pure Rust libraries and it therefore depends only on libc (and an ssh binary where you want git+ssh support). It supports a wide variety of platforms and can be deployed in many different ways:
+
+- as a long-running process on a VM
+- as a periodic job
+- as a long-running container
+- as a CLI tool to perform a single run
+
+kitops runs each task on a schedule.
+
+<picture>
+
+Each time kitops successfully applies all the actions of a task, it updates its state file. The state file acts as memory between executions so if kitops is run as a periodic job, you should point --state-file to persistent file storage.
+
+kitops will clone repositories that are not found in --repo-dir so you can use ephemeral storage for this, but if your repositories are large, you may want to keep repositories on persistent storage too. This allows fetching only new changes, dramatically reducing network traffic.
 
 ## Roadmap
 
@@ -18,8 +72,9 @@ The plan forward, roughly in falling priority:
 - [x] new git sha and branch name in action env vars
 - [x] changed task config should override state loaded from disk
 - [x] docker packaging
-- [ ] readme with design and deployment options
+- [x] readme with design and deployment options
 - [ ] branch patterns allows a task to react to changes on many branches
+- [ ] Support GitHub runner long polling interface
 - [ ] intelligent gitconfig handling
 - [ ] allow git commands in workdir (but note that this means two tasks can no longer point to the same repo without additional changeas)
 - [ ] useful logging (log level, json)