Adding external runner for doing a one-time full-sync (#604)

* Adding external runner for doing a one-time full-sync

* Updating docs to describe GHA setup process

Author: dolan-a

README.md

@@ -32,8 +32,12 @@
 >
 > Settings files must have a `.yml` extension only. For now, the `.yaml` extension is ignored.
 
+
 ## How it works
 
+`Safe-settings` is designed to run as a service listening for webhook events or as a scheduled job running on some regular cadence. It can also be triggered through GitHub Actions. (See the [How to use](#how-to-use) section for details on deploying and configuring.)
+
+
 ### Events
 The App listens to the following webhook events:
 
@@ -364,11 +368,13 @@ You can pass environment variables; the easiest way to do it is via a `.env` fil
 
 ## How to use
 
-1. __[Deploy and install the app](docs/deploy.md)__.
+1. Create an `admin` repo (or an alternative of your choosing) within your organization. Remember to set `CONFIG_REPO` if you choose something other than `admin`. See [Environment variables](#environment-variables) for more details.
+
+2. Add the settings for the `org`, `suborgs`, and `repos`. Sample files can be found [here](docs/sample-settings).
+
+3. __[Deploy and install the app](docs/deploy.md)__.  Alternatively, the __[GitHub Actions Guide](docs/github-action.md)__ describes how to run `safe-settings` with GitHub Actions.
 
-2. Create an `admin` repo (or an alternative of your choosing) within your organization. Remember to set `CONFIG_REPO` if you choose something other than `admin`. See [Environment variables](#environment-variables) for more details.
 
-3. Add the settings for the `org`, `suborgs`, and `repos`. Sample files can be found [here](docs/sample-settings).
 
 
 ## License

docs/github-action.md

@@ -0,0 +1,57 @@
+# Running Safe-settings with GitHub Actions (GHA)
+
+This guide describes how to schedule a full safe-settings sync using GitHub Actions. This assumes that an `admin` repository has been configured with your `safe-settings` configuration. Refer to the [How to Use](../README.md#how-to-use) docs for more details on that process.
+
+
+## GitHub App Creation
+Follow the [Create the GitHub App](deploy.md#create-the-github-app) guide to create an App in your GitHub account. This will allow `safe-settings` to access and modify your repos.
+
+
+## Defining the GitHub Action Workflow
+Running a full-sync with `safe-settings` can be done via `npm run full-sync`. This requires installing Node, such as with [actions/setup-node](https://github.com/actions/setup-node) (see example below). When doing so, the appropriate environment variables must be set (see the [Environment variables](#environment-variables) document for more details).
+
+
+### Example GHA Workflow
+The below example uses the GHA "cron" feature to run a full-sync every 4 hours. While not required, this example uses the `.github` repo as the `admin` repo (set via `ADMIN_REPO` env var) and the safe-settings configurations are stored in the `safe-settings/` directory (set via `CONFIG_PATH` and `DEPLOYMENT_CONFIG_FILE`).
+
+```yaml
+name: Safe Settings Sync
+on:
+  schedule:
+    - cron: "0 */4 * * *"
+  workflow_dispatch: {}
+
+jobs:
+  safeSettingsSync:
+    runs-on: ubuntu-latest
+    env:
+      # Version/tag of github/safe-settings repo to use:
+      SAFE_SETTINGS_VERSION: 2.1.13
+
+      # Path on GHA runner box where safe-settings code downloaded to:
+      SAFE_SETTINGS_CODE_DIR: ${{ github.workspace }}/.safe-settings-code
+    steps:
+      # Self-checkout of 'admin' repo for access to safe-settings config:
+      - uses: actions/checkout@v4
+
+      # Checkout of safe-settings repo for running full sync:
+      - uses: actions/checkout@v4
+        with:
+          repository: github/safe-settings
+          ref: $SAFE_SETTINGS_VERSION
+          path: $SAFE_SETTINGS_CODE_DIR
+      - uses: actions/setup-node@v4
+      - run: npm install
+        working-directory: $SAFE_SETTINGS_CODE_DIR
+      - run: npm run full-sync
+        working-directory: $SAFE_SETTINGS_CODE_DIR
+        env:
+          GH_ORG: ${{ vars.SAFE_SETTINGS_GH_ORG }}
+          APP_ID: ${{ vars.SAFE_SETTINGS_APP_ID }}
+          PRIVATE_KEY: ${{ secrets.SAFE_SETTINGS_PRIVATE_KEY }}
+          GITHUB_CLIENT_ID: ${{ vars.SAFE_SETTINGS_GITHUB_CLIENT_ID }}
+          GITHUB_CLIENT_SECRET: ${{ secrets.SAFE_SETTINGS_GITHUB_CLIENT_SECRET }}
+          ADMIN_REPO: .github
+          CONFIG_PATH: safe-settings
+          DEPLOYMENT_CONFIG_FILE: ${{ github.workspace }}/safe-settings/deployment-settings.yml
+```

full-sync.js

@@ -0,0 +1,19 @@
+const { createProbot } = require('probot')
+const appFn = require('./')
+
+const probot = createProbot()
+probot.log.info('Starting full sync.')
+const app = appFn(probot, {})
+app.syncInstallation()
+  .then(settings => {
+    if (settings.errors.length > 0) {
+      probot.log.error('Errors occurred during full sync.')
+      process.exit(1)
+    } else {
+      probot.log.info('Done with full sync.')
+    }
+  })
+  .catch(error => {
+    process.stdout.write(`Unexpected error during full sync: ${error}\n`)
+    process.exit(1)
+  })

lib/settings.js

@@ -22,6 +22,7 @@ class Settings {
       settings.logError(error.message)
       await settings.handleResults()
     }
+    return settings
   }
 
   static async syncSubOrgs (nop, context, suborg, repo, config, ref) {

package.json

@@ -7,6 +7,7 @@
   "scripts": {
     "dev": "nodemon --inspect",
     "start": "probot run ./index.js",
+    "full-sync": "node ./full-sync.js",
     "test": "npm-run-all --print-label --parallel lint:* --parallel test:*",
     "lint:es": "eslint .",
     "lint:js": "standard",