Add instructions for configuring SANDPAPER_WORKFLOW post-transition

learners/migrating-from-styles.md

@@ -14,7 +14,7 @@
 **_We strongly recommend that you create a backup of your lesson repository before you follow this workflow._**
 :::
 
 :::::::: prereqs 
 
 ## Prerequisites
 
@@ -32,11 +32,11 @@
 
 ## Transition Workflow
 
 1. [Set up the transition tools](#workflow-setup)
 2. [Create an Rscript for your lesson](#Rscript)
 3. [Run the transition tool](#transition)
 4. [Set up your GitHub repository to receive the transitioned lesson](#github)
 5. [Post-transition steps](#post-transition)
 
 ::: callout
 Note: these steps assume your lesson exists in The Carpentries Incubator i.e. under the `carpentries-incubator` organisation on GitHub. If it does not, you will need to replace all of the folder names etc below accordingly.
@@ -88,7 +88,7 @@
 bash add-lesson.sh carpentries-incubator/YOUR-LESSON-NAME
 ```
 
 But you may wish to populate this script with some function calls to clean up various common artifacts produced by the transition, or to preserve any [custom workflows](#custom-workflows) you have added to your lesson repository. Look at the `.R` scripts in the [`carpentries-incubator/`](https://github.com/carpentries/lesson-transition/tree/main/carpentries-incubator), [`datacarpentry`](https://github.com/carpentries/lesson-transition/tree/main/datacarpentry), [`librarycarpentry`](https://github.com/carpentries/lesson-transition/tree/main/librarycarpentry), and [`swcarpentry`](https://github.com/carpentries/lesson-transition/tree/main/swcarpentry) directories of the `lesson-transition` repository for inspiration.
 
 ### 3. Run the transition tool{#transition}
 
@@ -150,7 +150,7 @@
 To check how things are looking, [install the Workbench tools for your system](index.html#installation), then open R in this directory and run `sandpaper::serve()`.
 
 #### Optional: update your lesson's R script to produce a smoother transition
 While previewing this transitioned lesson site, you might see some problems in the content of your lesson site that appeared during the migration. Liquid comments (delineated by `{% comment %}` and `{% endcomment %}` tags) are one commonly-encountered artifact. Another is broken links to the lesson setup instructions, which are found at `index.html#setup` in a Workbench site. These can be fixed by editing the lesson after transition, but for a cleaner commit history on your lesson you might wish to delete the transitioned lesson directory (inside the `release` folder), modify the R script for your lesson to handle those issues, and re-run the transition tool. (See [_Create an Rscript for your lesson_](#Rscript) above.)
 
 #### If something goes wrong
 To go back to the start and try again, delete the directory for your lesson within the `release/` directory, i.e. `rm -rf release/carpentries-incubator/YOUR-LESSON-NAME`.
@@ -215,7 +215,19 @@
 
 1. **Delete and re-create any forks and local clones** of your lesson project, to minimise the likelihood that you will accidentally push the old project history back to the GitHub repository. If you have any collaborators and fellow lesson developers/maintainers, ask them to do the same.
 2. If your lesson is in The Carpentries Incubator, [**tell the Curriculum Team**](mailto:[email protected]) that you have completed the transition so that we can activate the automated creation of pull requests to update the Workbench infrastructure when new versions of the packages are released.
-3. (Optional, but highly recommended) Open a pull request to https://github.com/carpentries/reactables/ to **add the invalid commit hash** (in the `invalid.hash` file created for your lesson during the transition (step 3 above)) to [the `workbench/invalid-hashes.json` file](https://github.com/carpentries/reactables/blob/main/workbench/invalid-hashes.json). This will include the hash in the data feed used by our infrastructure to support the GitHub Actions workflow that will automatically close any pull requests opened to your repository from a branch containing the old project history. To do this:
+3. If your lesson is _not_ in the Incubator, **enable automated pull requests to keep your infrastructure updated** by adding a SANDPAPER_WORKFLOW token to your repository:
+    * Navigate to <https://github.com/settings/tokens/new> and give your new token a name (e.g. "Sandpaper Token (YOUR-ORG-OR-USER-NAME/YOUR-LESSON-NAME)").
+    * Check the box next to _workflow_.
+    * Set an expiry date for the token.
+    * Select _Generate token_.
+    * Copy the token displayed on the screen.
+    * On your GitHub repository:
+        * Navigate to Settings->Secrets and variables->Actions->New repository secret
+        * Set _Name_ to SANDPAPER_WORKFLOW, and paste your new token into the _Secret_ box.
+        * Select Add secret
+
+  The maintenance workflows that use this token are scheduled to run weekly. When The Carpentries releases new versions of the workflow files used to build and maintain lessons, a pull request will be opened automatically on any repository with the SANDPAPER_WORKFLOW token set to incorporate the relevant updates. If your lesson uses R Markdown source files, the same token will be used to keep the package dependencies for your lesson updated.
+5. (Optional, but highly recommended) Open a pull request to https://github.com/carpentries/reactables/ to **add the invalid commit hash** (in the `invalid.hash` file created for your lesson during the transition (step 3 above)) to [the `workbench/invalid-hashes.json` file](https://github.com/carpentries/reactables/blob/main/workbench/invalid-hashes.json). This will include the hash in the data feed used by our infrastructure to support the GitHub Actions workflow that will automatically close any pull requests opened to your repository from a branch containing the old project history. To do this:
     * Make a fork of [the `carpentries/reactables` GitHub repository](https://github.com/carpentries/reactables/)
     * On a new branch of that fork, edit the `workbench/invalid-hashes.json` file, adding a new line before the final `}` line matching the format of the other lines containing hashes, i.e. 
       `"carpentries-incubator/YOUR-LESSON-NAME": "HASHASHASHASHASHASHASH"`