Add pause-buildset-registry role

This is a simple utility that provides the zuul_return functionality
for repos that need it encapsulating the existence of zuul_return.

For instance, system-config wanted to start doing this in a playbook
but linting the playbooks became super hard because of the new need
to have zuul installed for the zuul_return library. Just keep it here
in the family.

Change-Id: I6035009455f6434c2d6cfd976c7c6f414bdc2ae7

doc/source/container-roles.rst

@@ -9,6 +9,7 @@ Container Roles
 .. zuul:autorole:: install-kubernetes
 .. zuul:autorole:: install-openshift
 .. zuul:autorole:: install-podman
+.. zuul:autorole:: pause-buildset-registry
 .. zuul:autorole:: promote-docker-image
 .. zuul:autorole:: pull-from-intermediate-registry
 .. zuul:autorole:: push-to-intermediate-registry

roles/pause-buildset-registry/README.rst

@@ -0,0 +1,10 @@
+Pause a buildset registry
+
+Utility role to pause a job providing a buildset registry.
+
+**Role Variables**
+
+.. zuul:rolevar:: buildset_registry
+
+   Location of external buildset registry. If this is defined,
+   the job will not pause.

roles/pause-buildset-registry/tasks/main.yaml

@@ -0,0 +1,10 @@
+# If buildset_registry is defined, that means a parent job is running it;
+# only if it is not defined does it mean that we are running it.  If we
+# are running it, pause the job so that child jobs will automatically
+# use it.
+- name: Pause the job
+  when: buildset_registry is not defined
+  zuul_return:
+    data:
+      zuul:
+        pause: true