document issue 29663 in puppet

howto/puppet.md

@@ -673,6 +673,31 @@ more information:
 
     ssh NODE puppet agent -t
 
+### Problems pushing to the Puppet server
+
+Normally, when you push new commits to the Puppet server, a hook runs
+and updates the working copy. But sometimes this fails with an error
+like:
+
+    remote: error: unable to unlink old 'modules/ipsec/misc/config.yaml': Permission denied.
+
+The problem, in such cases, is that the files in the `/etc/puppet/`
+checkout are not writable by your user. It could also happen that the
+repository itself (in `/srv/puppet.torproject.org/git/tor-puppet`)
+could have permission issues.
+
+This problem is described in [issue 29663](https://gitlab.torproject.org/tpo/tpa/team/-/issues/29663) and is due to someone
+not pushing properly before you. To fix the permissions, try:
+
+    sudo chown -R root:adm /etc/puppet
+    sudo chown :puppet /etc/puppet/secret
+    sudo chmod -R g+rw /etc/puppet
+    sudo chmod g-w /etc/puppet/secret
+
+A similar recipe could be applied to the git repository, as
+needed. Hopefully this will be resolved when we start deploying with a
+role account instead.
+
 ## Disaster recovery
 
 <!-- what to do if all goes to hell. e.g. restore from backups? -->