clarify instructions for groups

README.md

@@ -9,33 +9,49 @@ Roles:
 
 * New User: new key to be added; can be a new employee being added for first time, existing employee getting access to a new repo, key rotation, etc
 * Existing User: user who already has access to the appropriate project
-  * E.g. look up in the [groups](/groups/) dir
-  * E.g. look up in in [verify/.sops.yaml](verify/.sops.yaml)
+  * Definition: List of all users: [verify/.sops.yaml](verify/.sops.yaml)
 
 ## 1a. Onboarding: [New User]: create and add a gpg key
-- create a branch titled `add_pubkey_<firstname>-<lastname>`
-  - e.g. `git branch add_pubkey_test-user`
+1. Clone this repository
+1. Create a branch titled `add_pubkey_[firstname]-[lastname]`. <!-- NOTE: Validation Hack: User will not be able to mistakenly create this literal branch, as the unpermitted chars '[' will prevent the branch from being created: "Branch name cannot contain '['" as per https://git-scm.com/docs/git-check-ref-format. I.e. it's a dirty hack to get some server-side(?) validation ;-) --> <!--  - Web: e.g. The following link can be used to create a branch: [https://git.dev-at.de/smardigo-hetzner/communication-keys/-/branches/new?branch_name=add_pubkey_[firstname]-[lastname]](https://git.dev-at.de/smardigo-hetzner/communication-keys/-/branches/new?branch_name=add_pubkey_[firstname]-[lastname]) -->
+    - CLI: e.g. `git branch add_pubkey_Max-Musterman`
     - Note: no strict naming convention for the branch, it's strictly a Human-in-the-Loop process
-- please follow steps 1-13 at the following link: https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key
+1. Follow steps 1-13 at the following link: https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key
     - CAVEAT: step 14 is not necessary, as it is specific to a GitHub account
-- add ONLY the _PUBLIC_ part of your gpg key!!! to this repo
+1. add ONLY the _PUBLIC_ part of your gpg key!!! to your branch
     - file format: `<email>@netgo.de.gpg.pub`
-- git: commit the new file, push
-- open a MergeRequest/PullRequest
-- hand-off to an Existing User of the repo. 
+1. git: commit the new file, push
+1. open a MergeRequest
+1. Hand-Off: Assign the MR to an Existing User in your Team to have your key added.
+    - Hint: Look up all Existing Users in the comments at: [verify/.sops.yaml](verify/.sops.yaml)
 
 ## 1b. Onboarding: [Existing User|New User]: Add new user to groups
 
+Determine the groups to which access is needed, e.g. a specific repository.
+
+If uncertain, ask a Team Member for help!
+
+Technical Instructions - please forgive the complexity
+
 Access for each repo is tracked using the `./groups/` directory; each sub-directory represents a "group" (Note: some "groups" are also "roles", e.g. `admin`)
 
 Most of the groups correspond directly to git repository names, aka "project name"
 
-```bash
+Create a symlink from the group-directory back to the keyfile
+```shell
 cd groups/<project_name>
 ln -s ../../<path_to_key.gpg.pub>
 ```
 
-Note: this step can be performed by anyone (either new user or existing user), but it makes the most sense for an existing user to configure the groups since this is domain-specific knowledge (i.e. new users won't typically know the grups)
+Example:
+
+Add "Max Musterman" to the group for `devnso-adp-argocd`:
+```shell
+# navigate to group-directory for devnos
+cd groups/devnso-adp-argocd
+# symlink to pubkey for New User
+ln -s ../../max.musterman@netgo.de.gpg.pub
+```
 
 ## 3. Onboarding: [Existing User]: Configure sops config