diff --git a/README.md b/README.md index 20a29bfe..b3137a37 100644 --- a/README.md +++ b/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 diff --git a/docs/github-action.md b/docs/github-action.md new file mode 100644 index 00000000..699ae9a9 --- /dev/null +++ b/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 +``` diff --git a/full-sync.js b/full-sync.js new file mode 100644 index 00000000..a39f8b46 --- /dev/null +++ b/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) + }) diff --git a/lib/settings.js b/lib/settings.js index 961aa4c6..05ddcbe4 100644 --- a/lib/settings.js +++ b/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) { diff --git a/package.json b/package.json index dbad5350..a923feb2 100644 --- a/package.json +++ b/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",