diff --git a/README.md b/README.md
index 74f7dee424082bd523a235b77f8fc6ee4850bfec..10c53e2998d626775cfd09e8b30577c304b31e95 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,60 @@ integration of project changes into the manifest. It is meant to be included int
 relevant Yocto repositories as a [git submodule][1].
 
 
-### Providing `GITBOT_TOKEN`
+## Deploy changes into all projects using 'gitlab-ci' as submodule
+
+The gitlab-ci repo is integrated into the other related projects as submodule and as
+reference in their .gitlab-ci.yml file. Both references need to be updated when a
+change in the repo should be deployed to the projects using it.
+
+To achieve the the CI pipeline is setup to update all these projects in one run.
+The submodule *must not* be updated manually, but the CI needs some manual steps
+to do the deployment.
+As this repo contains all the CI code some extra care is needed not to break the
+whole thing. To allow testing the CI, before everything is merged into the yocto
+pipeline a special set of test projects is available in the ci-test group.
+
+### The workflow to deploy a change 
+
+* Commit and push change to the gitlab-ci repo, create a Merge Request
+* The pipeline checks syntax and so on in the Analyze stage
+* The Integrate stage allows testing the change in the complete setup
+  There are two possible integrate steps, one to deploy the change into Merge Request in 
+  the ci-test group, the other is for the productive yocto setup.
+* When the integrate stage has run, a build is started in the related manifest projects
+
+* In all projects there are now integration branches created, named
+  'integrate/gitlab-ci/<gitlab-ci branch name>'
+  These could be used to add additional changes if needed. But the should only happen
+  in very special cases.
+
+* If everything is OK until here, (build OK, CI works as expected ...)
+  the change can be merged into the main branch of gitlab-ci.
+  *This only adds the patch to the gitlab-ci repo's main branch, the reference
+    in the projects using this are not yet updated*
+
+* After the merge a new pipeline is created. In this pipeline there are two 
+  manual jobs: 'merge-ci-test' and 'merge-yocto'
+  These jobs update the reference in the project groups 'ci-test' and 'yocto'.
+  This is split up to allow more testing in cases where the CI changes can only
+  be tested when working on the master branch.
+
+* When the behaviour of the CI on the master branch may be effected of the change
+  only 'merge-ci-test' should be executed. 
+  After this some tests may be done on the ci-test projects.
+  Probably you want to create a commit in minimal-foo, create a merge-request,
+  check the running pipeline, and merge it.
+  After that, check if the merge is succesfull and the manifest is updated as 
+  needed.
+
+* When everything is working the 'merge-yocto' pipeline can be executed, to 
+  deploy the change to the productive projects.
+* When the tests on 'ci-test' have failed, just create a new patch fixing the
+  issue in the gitlab-ci repo and do the testing again.
+
+
+
+## Providing `GITBOT_TOKEN`
 
 The scripts need a [personal GitLab access token][2] of a user with access to all
 relevant repositories (manifest and all contained projects) in order to work correctly.
@@ -22,7 +75,8 @@ via the CI environment variable `GITBOT_TOKEN` (set under project's settings ->
 defined.
 
 
-### Workflow to add a repository to SRCREV.conv for reproducible bitbake builds
+## Workflow to add a repository to SRCREV.conv for reproducible bitbake builds
+
 Some bitbake recipes are set to `SRCREV = "${AUTOREV}"`. To enable reproducible
 builds, the current revision is written to the SRCREV.conf file. This file is
 part of the manifest repo, which is used for release tags. This workflow adds