Notice: The contents of this repository are meant for reference example only and should not directly be used in a production environment without additional testing and validation.
The purpose of this repository is to serve as a reference example for setting up automated validation and enforcement of GitHub Repository settings within a target Organization.
This example repository uses Node.js to communicate with the GitHub REST API using the GitHub REST API client for JavaScript from Octokit.
- watcher.js: Contains functional logic and module exports which are consumed by other application files to apply configuration settings across Repositories and associated Branches within an Organization.
- github-action.js: Node.js app file meant to use for batch processing to scan multiple repositories within an organization to verify baseline configurations are in place. The format of this file is meant to be used as a Workflow within a GitHub Action with associated Environment variables provided from the Workflow.
- Node.js: Tested with
v16.14.2
of Node.js with npm version8.6.0
. Refer to the Node.js Docs Site for installation details. - GitHub Organization: A GitHub Organization is required to use examples within this repository. It is strongly encouraged to use a dedicated testing organization first so that changes are not accidentally introduced into primary organizations and associated repositories.
- Github Access: Requires Organization Administrative rights for setting up an organization webhook.
- GitHub Organization Webhook: A Webhook will be used with the GitHub organization to communicate trigger events to the Web App included with this repository.
- GitHub App: Communications with the GitHub REST API require authenticated access for components used with this example. See GitHub App Docs for setup.
- GitHub App should have permissions:
Repository
->Administration
: read/writeRepository
->Contents
: read/writeRepository
->Metadata
: readOrganization
->Administration
: read
- GitHub App should have permissions:
This example repository can be triggered with a Workflow Dispatch event to directly trigger a workflow run with parameters.
- package.json: Node.js app definition and source of dependencies.
- github-action.js: Entry point for the application called by
workflow_dispatch
. - watcher.js: Contains functions and module exports which are called from github-action.js entry point.
- Environment Variables used:
GHWATCHER_BASEURL
: Used by watcher.js, GitHub Base URL for API calls. Defaults tohttps://api.github.com
. For a GitHub Enterprise Server(GHES) installation this would behttps://FQDN-of-GHES/api/v3
.GHWATCHER_APP_ID
: required, Used by watcher.js, GitHub App ID for interacting with the GitHub REST API with Octokit.GHWATCHER_APP_PEM
: required, Used by watcher.js, GitHub App Private Key content for interacting with the GitHub REST API with Octokit.GHWATCHER_APP_INSTALLATION_ID
: required, Used by watcher.js, will be used to generate a short-lived token for interacting with the GitHub REST API with Octokit.GHWATCHER_ALLOWED_ORG_LIST
: required, Used by github-action.js to determine if therepository.owner.login
sent in the webhook request is matched to a valid listing of Organization names which this application is allowed to target. Limits interactions from this application to only scan specified target Organizations which are explicitly allowed. Supports a String value either space or comma delimited.GHWATCHER_ENABLE_DEPENDABOT
: Used by github-action.js to determine if Dependabot scanning should be enabled on repositories when applying branch protection rules, enabling by setting a String value oftrue
. Default value isnull
.GHWATCHER_ENFORCE_PRIVATE
: Used by watcher.js to determine if checks/enforcement should happen for private repositories, setting to value oftrue
to include private repositories. Default value isfalse
.GHWATCHER_REPO_SKIP_LIST
: Used by watcher.js to determine if named repositories should be skipped from checks/enforcement. Supports a String value either space or comma delimited.
The following shows relevant configuration options which are similar to the watcher.yml workflow located in this repository.
on:
# Allow for manual execution
workflow_dispatch:
# Execute on schedule
schedule:
- cron: '30 5,17 * * *'
jobs:
watcher_exec:
runs-on: ubuntu-latest
strategy:
matrix:
org:
- example-org-name-1
- example-org-name-2
include:
# Specify secrets for authentication to example-org-name-1
- org: example-org-name-1
GHWATCHER_APP_ID: GHWATCHER_APP_ID_1
GHWATCHER_APP_PEM: GHWATCHER_APP_PEM_1
GHWATCHER_APP_INSTALLATION_ID: GHWATCHER_APP_INSTALLATION_ID_1
# Specify secrets for authentication to example-org-name-2
- org: example-org-name-2
GHWATCHER_APP_ID: GHWATCHER_APP_ID_2
GHWATCHER_APP_PEM: GHWATCHER_APP_PEM_2
GHWATCHER_APP_INSTALLATION_ID: GHWATCHER_APP_INSTALLATION_ID_2
# Populate shared environment variables used by all orgs
env:
# Org-specific configurations can be passed as matrix-include items
GHWATCHER_APP_ID: ${{ secrets[matrix.GHWATCHER_APP_ID] }}
GHWATCHER_APP_PEM: ${{ secrets[matrix.GHWATCHER_APP_PEM] }}
GHWATCHER_APP_INSTALLATION_ID: ${{ secrets[matrix.GHWATCHER_APP_INSTALLATION_ID] }}
GHWATCHER_CHECK_ORG: ${{ matrix.org }}
GHWATCHER_ENFORCE_PRIVATE: false
GHWATCHER_REPO_SKIP_LIST: github-watcher-admin
GHWATCHER_ALLOWED_ORG_LIST: ${{ matrix.org }}
GHWATCHER_ENABLE_DEPENDABOT: true
GHWATCHER_BASEURL: https://api.github.com
steps:
- uses: actions/checkout@v2
- name: Use Node.js 16.x
uses: actions/setup-node@v1
with:
node-version: 16.x
- name: npm setup
run: npm install
- name: ${{ matrix.org }} - exec watcher
run: npx node github-action.js
- name: Summary
run: cat ${{ matrix.org }}.md >> $GITHUB_STEP_SUMMARY
- Uses the GitHub REST API client for JavaScript from Octokit.
- Octokit OpenAPI interactive reference page [https://octokit.github.io/rest.js/v18]
The MIT License
Copyright (c) 2022-present github.com/collinmcneese
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.