feat: Documentation for push --git mode, as advanced topic
@@ -8,10 +8,51 @@ Opinionated platform that runs on Kubernetes, that takes you from App to URL in
## Contents
+- [Git Pushing](#git-pushing)
- [Traefik](#traefik)
- [Linkerd](#linkerd)
- [Traefik and Linkerd](#traefik-and-linkerd)
+## Git Pushing
+
+The quick way of pushing an application, as explained at
+[README: Push an application](../README.md#push-an-application), uses a local
+directory containing a checkout of the application's sources.
+
+Internally this is actually quite complex. It involves the creation and upload
+of a tarball from these sources by the client to the Epinio server, storage into
+Epinio's Gitea component, and then checkout from that git repository by the
+tekton pipeline for staging, i.e. compilation and creation of the docker image
+to be used by the underlying kubernetes cluster.
+
+This process can be shortend however by using the Epinio client's "git mode". In
+this mode `epinio push` does not take a local directory of sources, but the
+location of a git repository holding the sources, and the id of the revision to
+use. The client then simply arranges for the tekton pipeline to pull directly
+from that git repository instead of from the internal gitea. No tarball, no
+upload, no saving to gitea.
+
+The syntax is
+
+```
+epinio push NAME GIT-REPOSITORY-URL --git REVISION
+```
+
+For comparison all the relevant syntax:
+
+```
+epinio push NAME
+epinio push NAME DIRECTORY
+epinio push NAME GIT-REPOSITORY-URL --git REVISION
+```
+
+__Attention__: While it is possible to use a branch name for the `REVISION` id,
+this is not recommened at this point. We recommend to use an exact git hash
+instead. While a second push of an application with the same branch will
+apparently pick up and deploy any commits done on that branch since the previous
+push this may be a (fortunate) accident of the current implementation and we are
+not guaranteeing this yet.
+
## Traefik
When you installed Epinio, it looked at your cluster to see if you had
