Add README.

1 files changed, 49 insertions, 0 deletions

diff --git a/utils/new-publish/README b/utils/new-publish/README
new file mode 100644
index 0000000..b5940f5
--- /dev/null
+++ b/utils/new-publish/README
@@ -0,0 +1,49 @@
+Prototype of new Publishing API for Linaro CI
+=============================================
+
+Background
+---------------------
+Builds of various products and components must finish with publishing
+their artifacts to a central server, hereafter called "snapshots".
+Builds also must be queued for testing in LAVA. All publishing
+should happen in secure manner, prohibiting direct system break-ins
+and minimizing types of other attacks, like denial of service.
+
+This prototype tries to establish consistent external interface reusable
+for wild variety of Linaro builds, and initial implementation which
+works with existing infrastructure and setup in place.
+
+Generalize publishing process:
+
+Builder -> Snapshots
+
+
+External Interface
+------------------
+Build jobs use publishing API using the shell command calls. There're
+2 scripts to perform publishing action:
+
+* publish-start
+* publish-finish
+
+They compliment each other and should be used in pair.
+
+Script parameters:
+
+publish-start --token <token> <build_id> <glob_pattern>...
+
+publish-finish --token <token> <build_id>
+
+
+Internal Implementation
+-----------------------
+There's currently no token-based authentication for publishing services,
+and instead SSH auth used. Consequenetly, for security reasons, the accounts
+used for publishing should be as restricted as possible, in practice we
+use few accounts for each step of the process, each fortified to disallow
+opportunity of direct shell access. SFTP is used as a transport (due to
+historical reasons).
+
+Current publisher process goes as:
+
+Builder -> Master -> Snapshots