update hookshot private key installation method

docs/configuring-playbook-bridge-hookshot.md

@@ -11,13 +11,34 @@ Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot
 
 1. For each of the services (GitHub, GitLab, Jira, Figma, generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](roles/matrix-bridge-hookshot/defaults/main.yml) as required.
 2. Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab, Generic), while you must first add the required configuration and enable the others (GitHub, Jira, Figma).
-3. If you're setting up the GitHub bridge, you'll need to generate and download a private key file after you created your GitHub app. Before running the playbook, you need to copy that file to `roles/matrix-bridge-hookshot/files/private-key.pem` so the playbook can install it for you.
+3. If you're setting up the GitHub bridge, you'll need to generate and download a private key file after you created your GitHub app. Copy the contents of that file to the variable `matrix_hookshot_github_private_key` so the playbook can install it for you, or use one of the [other methods](#manage-github-private-key-with-matrix-aux-role) explained below. 
 4. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready. Hookshot can be set up individually using the tag `setup-hookshot`.
 5. Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start using the bridge.
 
+Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in [main.yml](roles/matrix-bridge-hookshot/defaults/main.yml) for how to use them.
+
+### Manage GitHub Private Key with matrix-aux role
+
+The GitHub bridge requires you to install a private key file. This can be done in multiple ways:
+- copy the *contents* of the downloaded file and set the variable `matrix_hookshot_github_private_key` to the contents (see example in [main.yml](roles/matrix-bridge-hookshot/defaults/main.yml)).
+- somehow copy the file to the path `{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}` (default: `/matrix/hookshot/private-key.pem`) on the server manually.
+- use the `matrix-aux` role to copy the file from an arbitrary path on your ansible client to the correct path on the server.
+
+To use `matrix-aux`, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add to `matrix-aux` configuration like this:
+```yaml
+matrix_aux_file_definitions:
+  - dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}"
+    content: "{{ lookup('file', '/path/to/your-github-private-key.pem') }}"
+    mode: '0400'
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+```
+For more info see the documentation in the [matrix-aux base configuration file](/roles/matrix-aux/defaults/main.yml).
+
+### Provisioning API
 
 The provisioning API will be enabled automatically if you set `matrix_dimension_enabled: true` and provided a `matrix_hookshot_provisioning_secret`, unless you override it either way. To use hookshot with dimension, you will need to enter as "Provisioning URL": `http://matrix-hookshot:9002`, which is made up of the variables `matrix_hookshot_container_url` and `matrix_hookshot_provisioning_port`.
 
-If metrics are enabled, they will be automatically available in the builtin Prometheus and Grafana, but you need to set up your own Dashboard for now. If additionally metrics proxying for use with external Prometheus is enabled (`matrix_nginx_proxy_proxy_synapse_metrics`), hookshot metrics will also be available (at `matrix_hookshot_metrics_endpoint`, default `/hookshot/metrics`, on the stats subdomain) and with the same password. See also [the Prometheus and Grafana docs](../configuring-playbook-prometheus-grafana.md).
+### Metrics
 
-Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in `/roles/matrix-bridge-hookshot/defaults/main.yml` for how to use them.
+If metrics are enabled, they will be automatically available in the builtin Prometheus and Grafana, but you need to set up your own Dashboard for now. If additionally metrics proxying for use with external Prometheus is enabled (`matrix_nginx_proxy_proxy_synapse_metrics`), hookshot metrics will also be available (at `matrix_hookshot_metrics_endpoint`, default `/hookshot/metrics`, on the stats subdomain) and with the same password. See also [the Prometheus and Grafana docs](../configuring-playbook-prometheus-grafana.md).

roles/matrix-bridge-hookshot/defaults/main.yml

@@ -35,8 +35,14 @@ matrix_hookshot_webhook_endpoint: "{{ matrix_hookshot_public_endpoint }}/webhook
 # https://half-shot.github.io/matrix-hookshot/setup/github.html
 matrix_hookshot_github_enabled: false
 matrix_hookshot_github_appid: ''
-# manually copy the generated and downloaded GitHub private key to roles/matrix-bridge-hookshot/files/private-key.pem
+# set this variable to the contents of the generated and downloaded GitHub private key:
-matrix_hookshot_github_private_key: 'private-key.pem'
+# matrix_hookshot_github_private_key: |
+#   -----BEGIN RSA PRIVATE KEY-----
+#   0123456789ABCDEF...
+#   -----END RSA PRIVATE KEY-----
+# alternatively, leave it empty and do it manually or use matrix-aux instead, see docs/matrix-bridge-hookshot.md for info.
+matrix_hookshot_github_private_key: ''
+matrix_hookshot_github_private_key_file: 'private-key.pem'
 matrix_hookshot_github_secret: '' # "Webhook secret" on the GitHub App page
 matrix_hookshot_github_oauth_enabled: false
 # you need to configure oauth settings only when you have enabled oauth (optional)

roles/matrix-bridge-hookshot/tasks/setup_install.yml

@@ -64,12 +64,12 @@
 
 - name: Ensure hookshot github private key file installed if github is enabled
   copy:
-    src: private-key.pem
+    content: "{{ matrix_hookshot_github_private_key }}"
-    dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key }}"
+    dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}"
-    mode: 0600
+    mode: 0400
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
-  when: "matrix_hookshot_github_enabled|bool"
+  when: "{{ matrix_hookshot_github_enabled|bool and matrix_hookshot_github_private_key|length }}"
 
 - name: Ensure matrix-hookshot.service installed
   template: