Handle secrets in branches
There were two problems with secrets related to branches. First,
a secret defined in one branch could not be used in another. This
is because the isSameProject method was a bit overzealous and also
ensured the secrets were on the same branch. Relaxing that allows
secrets to be used by jobs defined in multiple branches of the same
project.
Second, because secrets are required to be globally unique, the
expected workflow of branching a project would immediately produce
a configuration error since the secret would already be defined.
To handle this case, allow multiple definitions of a secret, but
only if they are in multiple branches of the same project, and only
if they have the same data. This should facilitate this workflow,
as well as the ability to age-out secrets on old branches.
We do not support different values for the same secret name on
different branches.
Story: 2001443
Task: 6154
Story: 2001442
Task: 6153
Change-Id: Ia9d5b77d1ce46e6461b370e951301ede4045bbb9
diff --git a/doc/source/user/config.rst b/doc/source/user/config.rst
index 525cb38..0f610a3 100644
--- a/doc/source/user/config.rst
+++ b/doc/source/user/config.rst
@@ -1137,8 +1137,12 @@
encrypted, however, data which are not sensitive may be provided
unencrypted as well for convenience.
-A Secret may only be used by jobs defined within the same project. To
-use a secret, a :ref:`job` must specify the secret in
+A Secret may only be used by jobs defined within the same project.
+Note that they can be used by any branch of that project, so if a
+project's branches have different access controls, consider whether
+all branches of that project are equally trusted before using secrets.
+
+To use a secret, a :ref:`job` must specify the secret in
:attr:`job.secrets`. Secrets are bound to the playbooks associated
with the specific job definition where they were declared. Additional
pre or post playbooks which appear in child jobs will not have access
@@ -1175,6 +1179,12 @@
`allowed-projects` job attribute can be used to restrict the projects
which can invoke that job.
+Secrets, like most configuration items, are globally unique, though a
+secret may be defined on multiple branches of the same project as long
+as the contents are the same. This is to aid in branch maintenance,
+so that creating a new branch based on an existing branch will not
+immediately produce a configuration error.
+
.. attr:: secret
The following attributes must appear on a secret: