diff --git a/doc/source/conf.py b/doc/source/conf.py
index 349b11e6..9a6a6a18 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -28,7 +28,8 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
-    'openstackdocstheme'
+    'sphinxcontrib.mermaid',
+    'openstackdocstheme',
 ]
 
 
diff --git a/doc/source/contributor/promotions.mmd b/doc/source/contributor/promotions.mmd
new file mode 100644
index 00000000..a9a83abe
--- /dev/null
+++ b/doc/source/contributor/promotions.mmd
@@ -0,0 +1,5 @@
+graph TD
+    master --> |build-packages|current-consistent
+    current-consistent --> |<a href='http://cistatus.tripleo.org/promotion/'>tripleo-ci promotion</a>|current-tripleo
+    current-tripleo --> |<a href='http://cistatus.tripleo.org/phase1/'>rdo phase1 promotion</a>|current-tripleo-rdo
+    current-tripleo-rdo --> |<a href='http://cistatus.tripleo.org/phase2/'>rdo phase2 promotion</a>|current-tripleo-rdo-internal
diff --git a/doc/source/contributor/stages-overview.rst b/doc/source/contributor/stages-overview.rst
index e59362fe..282c0198 100644
--- a/doc/source/contributor/stages-overview.rst
+++ b/doc/source/contributor/stages-overview.rst
@@ -9,6 +9,10 @@ Each stage shows the inputs taken and the artifacts produced.
           Links for stable branches would include the stable release name,
           for example, `Pike stable release <https://trunk.rdoproject.org/centos7-pike/tripleo-ci-testing/>`_.
 
+.. mermaid:: promotions.mmd
+
+*Overview of the tags used during the tripleo promotions stages*
+
 1. **Upstream TripleO**
 
     `CI DLRN Master consistent
diff --git a/test-requirements.txt b/test-requirements.txt
index 38234e83..f4e825b1 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -4,6 +4,7 @@
 # Doc requirements
 sphinx>=1.6.2 # BSD
 sphinx_rtd_theme==0.1.7
+sphinxcontrib-mermaid
 
 hacking<1.2.0,>=1.1.0