Document how this should all work

README.md

@@ -2,4 +2,63 @@
 
 ## Overview
 
-This repo builds containers for a bunch of repos that don't have their own builds but *do* have Dockerfiles.
+This repo builds containers for a bunch of other peoples' repos that don't have their own builds but *do* have Dockerfiles.
+
+## Usage
+
+See **Setup** for details on setting up the system. In short:
+
+```bash
+python3 -m venv venv
+. venv/bin/activate
+pip3 install -r requirements.txt
+export [all that crap in Setup]
+./bulkbuild.py repos.yml
+```
+
+## Behavior
+
+Given a registry user `$USER`, every run of this script will do the following for each repo `$REPO` defined in `repos.yml`:
+
+* Clone the head of the specified branch of the repository
+* `cd` into it
+* For the head of the specified branch (and the ref in the latest tag `$TAG` if `repo_build_tags` is true):
+  * Check out that ref `$COMMIT_SHA`
+  * For each container `$CONTAINER` to build from this repository:
+    * `cd` into the relative path
+    * Build the container using the specified Dockerfile
+    * Push the image as `$USER/$REPO:$COMMIT_SHA`
+    * Push the image as `$USER/$REPO:bleeding`
+    * If the ref is a tag
+      * Push the image as `$USER/$REPO:$TAG`
+      * Push the image as `$USER/$REPO:latest`
+
+Pretty straightforward, pretty intuitive. Every build updates `:bleeding`, tags update `:latest`.
+
+## Setup
+
+Repos are defined in `repos.yml` and read in via stdin
+
+```yaml
+---
+repository_name:                                # A friendly name for the repository, pick your poison
+  repo_url: "https://foo.bar/repo"              # The path to the repository to git clone from
+  repo_branch: main                             # The branch to clone
+  repo_build_tags: true                         # Optional - If specified and true, build and push the latest tag from this repo
+  containers:                                   # A dict of containers you want built
+    container1:                                 # Name of the first container
+      path: "container1"                        # The relative path in the repo where the Dockerfile for this lives
+      dockerfile: "Dockerfile-foo"              # Optional - The name of the Dockerfile to use. Defaults to "Dockerfile"
+    container2:                                 # Multiple containers can be built from one repo
+      path: "container2"
+      dockerfile: "Dockerfile-bar"
+```
+
+You will also need to set these envvars:
+
+| envvar | description |
+| ------ | ----------- |
+| `$CI_HUB_NAME` | The domain name (NOT the URL) of the container registry service you plan to use. Defaults to Docker Hub if not specified |
+| `$CI_HUB_USERNAME` | Your username on the container registry service. Not to be confused with your login credentials |
+| `$CI_HUB_LOGIN_NAME` | The username to use for logging into the registry |
+| `$CI_HUB_LOGIN_PASSWORD` | The password to use for logging into the registry |

repos.yml

@@ -3,6 +3,8 @@
 ---
 5dd:
   repo_url: "https://github.com/Oliveriver/5d-diplomacy-with-multiverse-time-travel"
+  repo_branch: "main"
+  repo_build_tags: true
   containers:
     5dd_client:
       path: "client"