Document dependency requirements and secret opt-in behaviour

Record the raised octokit lower bound and the new rbnacl/libsodium
runtime requirement in the changelog and README, document the per-secret
Dependabot opt-in, and note that destroying an environment is
irreversible.

Author: phelma

CHANGELOG.md

@@ -12,8 +12,9 @@ and this project adheres to
 
 * New `secrets` task group, defined via `RakeGithub.define_secrets_tasks`, for
   managing GitHub repository secrets. It exposes `provision`, `destroy` and
-  `ensure` tasks. Each secret is written to both the Actions and Dependabot
-  secret stores so that Dependabot-triggered workflow runs can read them.
+  `ensure` tasks. Each secret is written to the Actions secret store, and
+  additionally to the Dependabot secret store when it sets `dependabot: true`,
+  so that Dependabot-triggered workflow runs can read the secrets they need.
 
   Secrets are supplied as an array of hashes, e.g.
   `[{ name: 'SOME_SECRET', value: 'plaintext' }]`, and are encrypted
@@ -39,6 +40,14 @@ and this project adheres to
 
 * The `pull_requests:merge` task no longer requires setting the branch name and
   commit message provide via arguments as parameters within the task definition.
+* The `octokit` dependency lower bound has been raised from `>= 4.16` to
+  `>= 7.0`, as the Dependabot secret methods used by the `secrets` task group
+  were introduced in octokit 7.0. Consumers pinning octokit below 7.0 will need
+  to relax that constraint.
+* Added a new runtime dependency on `rbnacl` (`~> 7.1`), used to encrypt
+  secrets client-side. `rbnacl` requires the native libsodium library to be
+  installed on the host (see the Installation section of the README); this is
+  only needed when using the `secrets` task group.
 
 ## [0.9.0] 2022-01-28
 

README.md

@@ -18,6 +18,21 @@ Or install it yourself as:
 
     $ gem install rake_github
 
+### System dependencies
+
+The `secrets` task group encrypts secrets client-side using `rbnacl`, which
+requires the native [libsodium](https://libsodium.org) library to be present on
+the host. Install it before running any `secrets` task:
+
+    # macOS
+    $ brew install libsodium
+
+    # Debian/Ubuntu
+    $ apt-get install libsodium23
+
+libsodium is only required when using the `secrets` tasks; the other task groups
+have no additional system dependencies.
+
 ## Usage
 
 ### define_deploy_keys_tasks
@@ -52,7 +67,7 @@ end
 | deploy_keys_destroy_task_name   | symbol | N        | Option to change the destroy task name                     | :obliterate                                            | :destroy                             |
 | deploy_keys_provision_task_name | symbol | N        | Option to change the provision task name                   | :add                                                   | :provision                           |
 | deploy_keys_ensure_task_name    | symbol | N        | Option to change the ensure task name                      | :destroy_and_provision                                 | :ensure                              |
-| secrets                         | array  | N        | Secrets to provision on the repository                     | { name: string, value: string }                       | [ ]                                  |
+| secrets                         | array  | N        | Secrets to provision on the repository                     | { name: string, value: string, dependabot: bool }     | [ ]                                  |
 | secrets_namespace               | symbol | N        | Namespace to contain secrets tasks                         | :repository_secrets                                    | :secrets                             |
 | secrets_destroy_task_name       | symbol | N        | Option to change the secrets destroy task name             | :obliterate                                            | :destroy                             |
 | secrets_provision_task_name     | symbol | N        | Option to change the secrets provision task name           | :add                                                   | :provision                           |
@@ -103,9 +118,13 @@ the `%s` placeholder, e.g. `pull_requests:merge[new_feature,"%s [skip ci]"]`.
 ### define_secrets_tasks
 
 Sets up rake tasks for managing repository secrets. Each secret is written to
-both the Actions and Dependabot secret stores, so that Dependabot-triggered
-workflow runs can read them. Secrets are encrypted client-side before being
-sent to GitHub.
+the Actions secret store by default. A secret can additionally be written to the
+Dependabot secret store by setting `dependabot: true`, so that
+Dependabot-triggered workflow runs can read the secrets they need. Secrets are
+encrypted client-side before being sent to GitHub.
+
+These tasks require the native libsodium library to be installed on the host —
+see [System dependencies](#system-dependencies) above.
 
 ```ruby
 require 'rake_github'
@@ -119,6 +138,11 @@ RakeGithub.define_secrets_tasks(
     {
       name: 'SOME_SECRET',
       value: 'some-plaintext-value'
+    },
+    {
+      name: 'SHARED_SECRET',
+      value: 'another-plaintext-value',
+      dependabot: true # also write to the Dependabot store
     }
   ]
 end
@@ -128,7 +152,7 @@ end
 |----------------------|--------|----------|------------------------------------------------------------|---------------------------------------------|------------|
 | repository           | string | Y        | Repository to perform tasks upon                           | 'organisation/repository_name'              | N/A        |
 | access_token         | string | Y        | Github token for authorisation                             | 'ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' | N/A        |
-| secrets              | array  | N        | Secrets to provision on the repository                     | { name: string, value: string }            | [ ]        |
+| secrets              | array  | N        | Secrets to provision on the repository                     | { name: string, value: string, dependabot: bool } | [ ]        |
 | destroy_task_name    | symbol | N        | Option to change the destroy task name                     | :obliterate                                 | :destroy   |
 | provision_task_name  | symbol | N        | Option to change the provision task name                   | :add                                        | :provision |
 | ensure_task_name     | symbol | N        | Option to change the ensure task name                      | :destroy_and_provision                      | :ensure    |
@@ -146,8 +170,9 @@ rake secrets:provision
 
 #### secrets:provision
 
-Provisions the specified secrets to the repository, writing each one to both
-the Actions and Dependabot secret stores.
+Provisions the specified secrets to the repository, writing each one to the
+Actions secret store and, for secrets marked `dependabot: true`, also to the
+Dependabot secret store.
 
 #### secrets:destroy
 
@@ -220,7 +245,10 @@ and user reviewers to their numeric ids.
 
 #### environments:destroy
 
-Destroys the specified environments from the repository.
+Destroys the specified environments from the repository. This is irreversible
+and also discards each environment's protection rules, environment secrets and
+deployment history. `environments:ensure` therefore fully recreates each
+environment rather than patching it in place.
 
 #### environments:ensure