Merge branch 'main' into 73-dfeshiny-reactable-wrapper

.github/workflows/dashboard_deploy_template.yaml

@@ -0,0 +1,65 @@
+name: Dashboard Deploy
+
+on:
+  workflow_call:
+    inputs:
+      parameter_file:
+        description: "Path to the parameters file"
+        required: true
+        type: string
+    secrets:
+      SHINYAPPS_SECRET:
+        required: true
+      SHINYAPPS_TOKEN:
+        required: true
+
+jobs:
+  deployShiny:
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/dfe-analytical-services/dfe-r-base:latest
+      options: --user root
+      credentials:
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - name: Read parameters
+        run: |
+          DASHBOARD_NAME=$(yq -r '.dashboard_name' ${{ inputs.parameter_file }})
+          DEPLOY_TARGET=$(yq -r '.deploy_target' ${{ inputs.parameter_file }})
+
+          echo "DASHBOARD_NAME=$DASHBOARD_NAME" >> $GITHUB_ENV
+          echo "DEPLOY_TARGET=$DEPLOY_TARGET" >> $GITHUB_ENV
+
+      - name: Set environment variables based on branch
+        run: |
+          if [[ "${{ github.ref_name }}" == "main" ]]; then
+            echo "SHINYAPP_NAME=$DASHBOARD_NAME" >> $GITHUB_ENV
+          else
+            echo "SHINYAPP_NAME=dev-$DASHBOARD_NAME" >> $GITHUB_ENV
+          fi
+
+      - name: Restore renv snapshot
+        shell: Rscript {0}
+        run: |
+          if (!requireNamespace("renv", quietly = TRUE)) install.packages("renv")
+          renv::restore()
+
+      - name: Install rsconnect
+        shell: Rscript {0}
+        run: |
+          if (!requireNamespace("rsconnect", quietly = TRUE)) install.packages("rsconnect")
+
+      - name: Deploy to ShinyApps.io
+        if: github.event_name != 'pull_request'
+        run: >
+          Rscript
+          -e "rsconnect::setAccountInfo(name = 'department-for-education', token = '${{secrets.SHINYAPPS_TOKEN}}', secret = '${{secrets.SHINYAPPS_SECRET}}')"
+          -e "rsconnect::deployApp(appName='${{env.SHINYAPP_NAME}}', forceUpdate = TRUE)"

vignettes/using-the-dfeshiny-deploy-template.Rmd

@@ -0,0 +1,150 @@
+---
+title: "Using the dfeshiny Deploy Template"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Using the dfeshiny Deploy Template}
+  %\VignetteEncoding{UTF-8}
+  %\VignetteEngine{knitr::rmarkdown}
+editor_options: 
+  markdown: 
+    wrap: 72
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+When developing DFE Shiny dashboards, it’s common to want a consistent,
+simple, and secure way to deploy applications to platforms such as
+ShinyApps.io or the new DfE hosting platform. This article shows how to
+use the dfeshiny reusable workflow template for GitHub Actions, with
+parameters defined in a separate YAML file to minimize duplication and
+speed up development.
+
+## Overview
+
+1.  **Have a `deploy_parameters.yaml`**:  Store all your deployment parameters, 
+    including the app name and deployment target.
+
+2.  **Minimal Local Workflow**: Reference the *remote* reusable workflow
+    (stored in another repository) from your local
+    `.github/workflows/deploy.yaml`.
+
+3.  **Secrets Management**: Ensure your repository has the required
+    secrets (e.g., `SHINYAPPS_TOKEN` and `SHINYAPPS_SECRET`) set up
+    under *Settings \> Secrets and variables*.
+
+## 1. Create a `deploy_parameters.yaml`
+
+At the root of your project, add a file called
+`deploy_parameters.yaml`.\
+Below is an example with optional parameters:
+
+```{yaml}
+dashboard_name: "my-cool-dashboard"
+deploy_target: "shinyapps"
+```
+
+-   `dashboard_name`: Your application’s name on ShinyApps (or other
+    hosting platform).
+
+-   `deploy_target`: Where you want to deploy (e.g., `"shinyapps"`).
+
+## 2. Set Up Your Local Workflow
+
+In your local `.github/workflows/` folder, create or edit a
+file—commonly named `deploy.yaml`. This file defines **only** the
+trigger conditions (which branches to watch) and then calls the remote
+reusable workflow.
+
+Here is a minimal example:
+
+```{yaml}
+name: Deploy Dashboard
+
+on:
+  push:
+    branches:
+      - main
+      - development
+
+jobs:
+  deploy:
+    uses: dfe-analytical-services/dfeshiny/.github/workflows/deploy-dashboard-template.yaml@main
+    with:
+      parameter_file: deploy_parameters.yaml
+```
+
+-   `on: push`… ensures this workflow runs whenever code is pushed to
+    `main` or `development`.
+
+-   `uses: dfe-analytical-services/dfeshiny-deploy-templates…` points to
+    the remote repo and file containing the actual deployment steps.
+
+-   `with: parameter_file: deploy_parameters.yaml` tells the remote
+    workflow which file to parse for parameters.
+
+## 3. Secrets and Permissions
+
+Before your deployment can succeed, you need to set the relevant secrets
+in your local repository. These secrets are **not** shared automatically
+across repos, so you must create them in your project’s *Settings \>
+Secrets and variables \> Actions*:
+
+-   **SHINYAPPS_TOKEN**
+
+-   **SHINYAPPS_SECRET**
+
+## 4. How the Template Works
+
+Once you commit your `deploy.yaml` and `deploy_parameters.yaml`, the
+GitHub Actions runner will:
+
+1.  **Check Out the Code** – Pulls your repository code and the
+    `deploy_parameters.yaml`.
+
+2.  **Parse Parameters** – Uses a tool like `yq` to read
+    `deploy_parameters.yaml`:
+
+    -   `dashboard_name`
+
+    -   `deploy_target`
+
+3.  **Restore R Dependencies** – If your project uses `renv`, it runs
+    `renv::restore()` to ensure your local library is consistent.
+
+4.  **Deploy** – Calls the appropriate deployment method based on
+    `deploy_target`.
+
+    -   For ShinyApps.io, it uses `rsconnect::deployApp()`.
+
+## Summary
+
+Using a reusable GitHub Actions workflow template:
+
+-   **Reduces complexity** of dashboards deployments - you only maintain
+    a minimal local config .
+
+-   **Ensures** **consistent deployment** practices across your
+    dashboards.
+
+-   Makes it easy to **update** deployments across your dashboards with
+    minimal changes in each repository.
+
+If you have questions about credentials or advanced usage, contact the
+Explore Education Statistics Platforms team at
+[explore.statistics\@education.gov.uk](mailto:[email protected]).
+
+> Whilst following the instructions in this article will help you set up
+> the deployment of your dashboard, you will still need to seek approval
+> to publish from the Explore Education Statistics team and ask for them
+> to set up the secrets management on GitHub for your deployment to go
+> through.
+
+With these steps, you can quickly set up your dashboards to deploy on
+push—whether that’s ShinyApps.io or a future DfE platform—while
+keeping all your deployment logic in a single, centralized workflow
+template.