### Start Local Emulation with serverless-offline Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/AWS-README.md After installing the serverless-offline plugin, use this command to start local emulation of API Gateway and Lambda. ```bash serverless offline ``` -------------------------------- ### Create and Update .env File Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Copy the example .env file and update it with your specific deployment environment variables, including APP_ID, WEBHOOK_SECRET, and either PRIVATE_KEY or PRIVATE_KEY_PATH. Configure GH_ORG if installing in an organization. ```bash cp .env.example .env ``` -------------------------------- ### Environment Definition Example Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/6. deployment-environments.md An example of how to define a deployment environment within a repository's settings file. ```APIDOC ## Environment API Spec

name string ${ ext{\color{orange}Required}}$

This is the name of the environment, and will be what is referenced in a workflow with environment: <name>

 Example: ```yaml environments: - name: dms-prod-example ... ```

wait_timer integer 

The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).

 Example: ```yaml environments: - name: dms-prod-example wait_timer: 30 ... ```

prevent_self_review boolean 

Whether or not a user who created the job is prevented from approving their own job.

 Example: ```yaml environments: - name: dms-prod-example prevent_self_review: true ... ```

reviewers array of objects or null ${ ext{\color{orange}Required}}$ ${ ext{\color{orange}if}}$ ${ ext{\color{orange}prevent\_self\_review}}$ ${ ext{\color{orange}is}}$ ${ ext{\color{orange}true}}$

The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must be given explicit access to the repository as either a team or collaborator. Only one of the required reviewers needs to approve the job for it to proceed.

Properties of reviewers

 type string 

  The type of reviewer.
  Can be one of: User, Team.

 id integer 

  The id of the user or team who can review the deployment

  Can be obtained by:
   Team: gh api /orgs/<org>/teams/<team-slug> | jq .id
   User: gh api /users/<username> | jq .id

 ```yaml environments: - name: production prevent_self_review: true reviewers: - type: Team id: 1234647 - type: User id: 139262123 ... ```

deployment_branch_policy object or null 

The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.

``` -------------------------------- ### Example GHA Workflow for Safe Settings Sync Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-action.md This workflow uses the GHA 'cron' feature to run a full-sync every 4 hours. It checks out the admin repository, then the safe-settings repository, installs Node.js, installs dependencies, and runs the full-sync command. Ensure environment variables for authentication and configuration paths are correctly set. ```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.17 # 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: ${{ env.SAFE_SETTINGS_VERSION }} path: ${{ env.SAFE_SETTINGS_CODE_DIR }} - uses: actions/setup-node@v4 - run: npm install working-directory: ${{ env.SAFE_SETTINGS_CODE_DIR }} - run: npm run full-sync working-directory: ${{ env.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 ``` -------------------------------- ### Install Dependencies Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Install project dependencies using npm. This step is required after cloning the repository. ```bash npm install ``` -------------------------------- ### Example Repository Definition Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/1. repository-settings.md Defines a comprehensive set of repository settings including initialization, templates, description, visibility, topics, and security analysis features. This is a complete example of a repository configuration. ```yaml # These settings are synced to GitHub by https://github.com/github/safe-settings repository: auto_init: true gitignore_template: node license_template: mit description: This is my repository description homepage: https://www.example.com private: true visibility: internal topics: [github, probot, new-topic, another-topic, topic-12] security_and_analysis: advanced_security: status: enabled secret_scanning: status: enabled secret_scanning_push_protection: status: enabled has_issues: true has_projects: false has_wiki: false is_template: false default_branch: main allow_squash_merge: true allow_merge_commit: true allow_rebase_merge: true allow_auto_merge: true delete_branch_on_merge: true allow_update_branch: true squash_merge_commit_title: PR_TITLE squash_merge_commit_message: COMMIT_MESSAGES merge_commit_title: PR_TITLE merge_commit_message: PR_TITLE archived: false allow_forking: false web_commit_signoff_required: false security: enableVulnerabilityAlerts: true enableAutomatedSecurityFixes: true ``` -------------------------------- ### Example Repository Variable Definition Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/2. repository-variables.md An example demonstrating the definition of a repository variable with a specific value. This format is used for syncing variables to GitHub. ```yaml variables: - name: MY_AWESOME_VAR value: super duper value ... ``` -------------------------------- ### Cron Schedule Example Source: https://github.com/github/safe-settings/blob/main-enterprise/README.md Example of setting a cron schedule for running safe-settings using node-cron syntax. The example shows how to run the task every minute. ```dotenv # ┌────────────── second (optional) # │ ┌──────────── minute # │ │ ┌────────── hour # │ │ │ ┌──────── day of month # │ │ │ │ ┌────── month # │ │ │ │ │ ┌──── day of week # │ │ │ │ │ │ # │ │ │ │ │ │ # * * * * * * CRON=* * * * * # Run every minute ``` -------------------------------- ### Install serverless-offline Plugin Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/AWS-README.md Install the serverless-offline plugin to emulate API Gateway and Lambda locally. This command adds the plugin to your project's devDependencies and serverless.yml. ```bash serverless plugin install -n serverless-offline ``` -------------------------------- ### Install Helm Chart with Custom Values Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Install the Safe Settings Helm chart using a custom values file. This is the recommended approach for managing configurations. ```bash helm install safe-settings oci://ghcr.io/github/helm-charts/safe-settings --values myvalues.yaml ``` -------------------------------- ### Example Repository Homepage Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/1. repository-settings.md Provides a URL for additional information about the repository. This is useful for linking to project websites or documentation. ```yaml repository: - homepage: https://awesomeness.super-repo.com ... ``` -------------------------------- ### Example Repository Description Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/1. repository-settings.md Sets a short description for the repository. This helps in quickly understanding the purpose of the repository. ```yaml repository: - description: This repo is so awesome, we named it super-repo ... ``` -------------------------------- ### Example Autolink Definition Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/7. autolinks.md This is an example of how autolink settings might be defined in a YAML configuration file. It shows variable definitions that could be used in conjunction with autolink configurations. ```yaml # These settings are synced to GitHub by https://github.com/FICO-1ES/1es-safe-settings variables: - name: MY_AWESOME_VAR value: '845705' - name: my_lowercase_var value: I have spaces ``` -------------------------------- ### Environment Wait Timer Example Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/6. deployment-environments.md Configures the wait timer for a deployment environment, specifying a delay in minutes between 0 and 43,200. ```yaml environments: - name: dms-prod-example wait_timer: 30 ... ``` -------------------------------- ### Add Repository Collaborator Example Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/3. collaborators.md Example snippet demonstrating how to define a collaborator with a 'maintain' permission. This is used when adding a user to a repository. ```yaml collaborators: - username: AquaMan permission: maintain ... ``` -------------------------------- ### Start Docker Container with Docker Compose Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Use docker-compose to start the Docker container in detached mode, utilizing the environment variables specified in the .env file. ```bash cd safe-settings/; docker-compose --env-file .env up -d ``` -------------------------------- ### Config Path Configuration Source: https://github.com/github/safe-settings/blob/main-enterprise/README.md Example of setting the path to the configuration directory for safe-settings. The default is '.github'. ```dotenv CONFIG_PATH=.github ``` -------------------------------- ### Example Environment Definition Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/6. deployment-environments.md Defines a deployment environment named 'production' with specific configurations for wait timers, self-review prevention, reviewers, deployment branch policies, and variables. ```yaml ... teams: # This team must be given explicit permission # before we can add them as a reviewer below - name: super-friends permission: write collaborators: # This user must be given explicit permission # before we can add them as a reviewer below - username: KalEl permission: write environments: - name: production wait_timer: 0 prevent_self_review: true reviewers: - type: Team id: 1234647 - type: User id: 139262123 deployment_branch_policy: protected_branches: false custom_branch_policies: - names: ['main','dev'] type: branch - names: ['v*.*.*'] type: tag deployment_protection_rules: - app_id: 25112 variables: - name: MY_AWESOME_VAR value: '845705' - name: my_lowercase_var value: I have spaces ``` -------------------------------- ### Admin Repository Configuration Source: https://github.com/github/safe-settings/blob/main-enterprise/README.md Example of configuring the source repository for safe-settings. The default is 'admin'. ```dotenv ADMIN_REPO=safe-settings-config ``` -------------------------------- ### Install Helm Chart with Set Values Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Install the Safe Settings Helm chart and override specific values directly using the --set flag. Useful for quick adjustments or scripting. ```bash helm install safe-settings oci://ghcr.io/github/helm-charts/safe-settings --set appEnv.APP_ID=""0000"" --set appEnv.PRIVATE_KEY="TFM...==" --set appEnv.WEBHOOK_SECRET="ZjZlYTFjN...==" ``` -------------------------------- ### Deployment Settings File Configuration Source: https://github.com/github/safe-settings/blob/main-enterprise/README.md Example of specifying the path to the deployment settings file for safe-settings. The default is 'deployment-settings.yml'. ```dotenv DEPLOYMENT_CONFIG_FILE=deployment-settings.yml ``` -------------------------------- ### Environment Name Example Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/6. deployment-environments.md Specifies the name of a deployment environment, which is referenced in workflows using the `environment:` key. ```yaml environments: - name: dms-prod-example ... ``` -------------------------------- ### Logging Level Configuration Source: https://github.com/github/safe-settings/blob/main-enterprise/README.md Example of setting the logging level for the safe-settings application. Supported levels include 'trace'. ```dotenv LOG_LEVEL=trace ``` -------------------------------- ### Example Repository Name Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/1. repository-settings.md Specifies the name of the repository. This is a fundamental property for identifying a repository. ```yaml repository: - name: super-repo ... ``` -------------------------------- ### Set Collaborator Permission Example Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/3. collaborators.md Example snippet showing how to set a collaborator's permission to 'maintain'. This applies to organization-owned repositories and accepts predefined permissions or custom role names. ```yaml collaborators: - username: WonderWoman permission: maintain ``` -------------------------------- ### Rulesets: No Custom Checks Example 2 Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/status-checks.md Demonstrates the status checks configuration when no custom checks are defined at the repository level, while organization and sub-organization levels have checks defined. Shows the expected outcome for newly deployed rules and UI updates. ```text Org checks: Org Check Sub-org checks: Sub-org Check Repo checks for Repo2: _NONE_ ``` ```text Status checks: - Newly deployed rules: - Org: Org Check - Repo1: Sub-org Check - Repo2: _NONE_ - Updating status checks via GitHub UI: - Org: Status checks reverted back to safe settings - Repo1: Status checks reverted back to safe settings - Repo2: Custom status checks are retained ``` -------------------------------- ### Settings File Path Configuration Source: https://github.com/github/safe-settings/blob/main-enterprise/README.md Example of specifying the path to the main settings file for safe-settings. The default is 'settings.yml'. ```dotenv SETTINGS_FILE_PATH=settings.yml ``` -------------------------------- ### Example Label Definition Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/8. labels.md Defines a 'bug' label with a specific color and description. This configuration is synced to GitHub. ```yaml labels: - name: bug color: CC0000 description: An issue with the system ``` -------------------------------- ### Example Collaborator Definition Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/3. collaborators.md Defines a list of collaborators with their respective permissions. This configuration is synced to GitHub by the safe-settings tool. ```yaml collaborators: - username: Batman permission: maintain - username: Superman permission: admin ``` -------------------------------- ### Clone the Repository Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Clone the source code to your local environment to prepare for building the Docker container. Ensure Node.js is installed if running locally without Docker. ```bash git clone https://github.com/github/safe-settings.git ``` ```bash cd safe-settings/ ``` -------------------------------- ### Example Repository Visibility and Private Setting Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/1. repository-settings.md Sets the repository's visibility to 'internal' and also marks it as private. It's recommended to default to 'internal' for InnerSource initiatives. ```yaml repository: - private: true visibility: internal ... ``` -------------------------------- ### Example Repository Private Setting Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/1. repository-settings.md Configures the repository's privacy. Setting this to true makes the repository private. Be aware of potential 422 errors if your organization restricts visibility changes. ```yaml repository: - private: true ... ``` -------------------------------- ### Branch Protection: No Custom Checks Example Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/status-checks.md Depicts the status checks configuration for branch protection rules when no custom checks are defined at any level (org, sub-org, repo). Shows the inherited checks for newly deployed rules and UI updates. ```text Org checks: Org Check Sub-org checks: Sub-org Check Repo checks for Repo2: Repo Check ``` ```text Status checks: - Newly deployed rules: - Repo1: Org Check, Sub-org Check - Repo2: Org Check, Sub-org Check, Repo Check - Updating status checks via GitHub UI: - Repo1: Status checks reverted back to safe settings - Repo2: Status checks reverted back to safe settings ``` -------------------------------- ### Running Tests with npm Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/awslambda.md These bash commands cover the essential npm scripts for managing dependencies and running tests within the project. This includes installing, running all tests, generating coverage reports, and running tests in watch mode for development. ```bash # Install dependencies npm install # Run all tests npm test # Run tests with coverage npm run test:coverage # Run tests in watch mode for development npm run test:watch # Run specific test file npx jest tests/keyUtils.test.js ``` -------------------------------- ### Start Docker Container in Foreground (Debug) Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Run the Docker container in interactive mode to view logs directly in the terminal for debugging connectivity and functionality issues. ```bash docker run -it -p 3000:3000 safe-settings ``` -------------------------------- ### Get Application URL with Ingress Source: https://github.com/github/safe-settings/blob/main-enterprise/helm/safe-settings/templates/NOTES.txt If Ingress is enabled, this snippet iterates through configured hosts and paths to construct the application URL. ```go-template {{- if .Values.ingress.enabled }} {{- range $host := .Values.ingress.hosts }} {{- range .paths }} http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host.host }}{{ .path }} {{- end }} {{- end }} {{- end }} ``` -------------------------------- ### Start Docker Container Detached Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Run the Docker container in detached mode, mapping port 3000 for webhook communication. Use 'docker ps' to verify it is running. ```bash docker run -d -p 3000:3000 safe-settings ``` ```bash docker ps ``` -------------------------------- ### Add or Update Team Repository Permissions Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/4. teams.md This example shows how to specify a team name and its permission level for a repository. The 'name' field is required and refers to the team's slug. ```yaml teams: - name: JusticeLeague permission: maintain ... ``` -------------------------------- ### Configure Required Status Checks Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/5. branch-protection.md Example of setting up required status checks for a branch. This includes specifying if branches must be up to date and listing the required check contexts. ```yaml branches: - name: default protection: required_status_checks: strict: true checks: - stark-industries/barndoor-protocol - stark-industries/sokovia-accords ... ``` -------------------------------- ### Environment Reviewers Example Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/6. deployment-environments.md Defines the reviewers (teams or users) required to approve deployments for an environment when `prevent_self_review` is enabled. Reviewers must have explicit repository access. ```yaml environments: - name: production prevent_self_review: true reviewers: - type: Team id: 1234647 - type: User id: 139262123 ... ``` -------------------------------- ### Get Application URL with NodePort Source: https://github.com/github/safe-settings/blob/main-enterprise/helm/safe-settings/templates/NOTES.txt When the service type is NodePort, these commands retrieve the NodePort and Node IP to construct the application URL. ```bash export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "safe-settings.fullname" . }}) export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}") echo http://$NODE_IP:$NODE_PORT ``` -------------------------------- ### Rulesets: No Custom Checks Example 1 Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/status-checks.md Illustrates the status checks configuration when no custom checks are defined at the organization, sub-organization, or repository level. Highlights a conflict when status checks are defined at both sub-org and repo levels. ```text Org checks: Org Check Sub-org checks: Sub-org Check Repo checks for Repo2: Repo Check ``` ```text Status checks: - Newly deployed rules: - Org: Org Check - Repo1: Sub-org Check - Repo2: _Failed to deploy as required_status_checks can't be defined twice in both sub-org and repo level_ - Updating status checks via GitHub UI: - Org: Status checks reverted back to safe settings - Repo1: Status checks reverted back to safe settings - Repo2: NA ``` -------------------------------- ### Example Branch Protection Definition Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/5. branch-protection.md Defines comprehensive branch protection rules for a repository, including pull request review requirements, status checks, admin enforcement, and user/team restrictions. This configuration is synced to GitHub by the safe-settings tool. ```yaml branches: - name: default protection: required_pull_request_reviews: required_approving_review_count: 2 dismiss_stale_reviews: true require_code_owner_reviews: true require_last_push_approval: true required_signatures: true require_linear_history: false bypass_pull_request_allowances: apps: - Jarvis - Edith users: - TonyStank teams: - Avengers dismissal_restrictions: users: - Hulk teams: - Revengers required_status_checks: strict: true checks: - stark-industries/barndoor-protocol - stark-industries/sokovia-accords enforce_admins: true restrictions: users: - starlord teams: - guardians ``` -------------------------------- ### Sample Teams Configuration with Include/Exclude Source: https://github.com/github/safe-settings/blob/main-enterprise/README.md Demonstrates how to configure teams with specific permissions and control their application to repositories using 'include' and 'exclude' glob patterns. 'Exclude' takes precedence over 'include'. ```yaml teams: - name: Myteam-admins permission: admin - name: Myteam-developers permission: push - name: Other-team permission: push include: - '*-config' ``` -------------------------------- ### Package Serverless Application Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/AWS-README.md Use this command to package your Serverless application before deployment. ```bash serverless package ``` -------------------------------- ### Create Heroku App and Set Config Vars Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Use the Heroku CLI to create a new app and set essential configuration variables. The PRIVATE_KEY is read from a local file. ```bash $ heroku create Creating arcane-lowlands-8408... done, stack is cedar http://arcane-lowlands-8408.herokuapp.com/ | git@heroku.com:arcane-lowlands-8408.git Git remote heroku added ``` ```bash $ heroku config:set APP_ID=aaa \ WEBHOOK_SECRET=bbb \ PRIVATE_KEY="$(cat ~/Downloads/*.private-key.pem)" ``` -------------------------------- ### Deploy Serverless Application Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/AWS-README.md Execute this command to deploy your packaged Serverless application to AWS. ```bash serverless deploy ``` -------------------------------- ### Build the Docker Container Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Build the Docker image for the safe-settings application. This command tags the image as 'safe-settings'. ```bash docker build -t safe-settings . ``` -------------------------------- ### Environment Prevent Self-Review Example Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/6. deployment-environments.md Sets the `prevent_self_review` flag to true for an environment, ensuring that users who create a job cannot approve their own. ```yaml environments: - name: dms-prod-example prevent_self_review: true ... ``` -------------------------------- ### Run Local Docker Container Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/docker-debugging.md Runs the local Docker image in the foreground with explicit environment variables and port mapping. Inspect logs if startup fails. ```bash docker run --name safe-settings-local \ --env-file ./.env \ --env NODE_ENV=development \ --env HOST=0.0.0.0 \ -p 3000:3000 \ -it safe-settings:local ``` ```bash docker logs safe-settings-local ``` ```bash docker exec -it safe-settings-local /bin/sh ``` ```bash docker rm -f safe-settings-local ``` -------------------------------- ### Enable Pull Request Comment Configuration Source: https://github.com/github/safe-settings/blob/main-enterprise/README.md Example of enabling or disabling pull request comments for safe-settings. The default is 'true'. ```dotenv ENABLE_PR_COMMENT=true ``` -------------------------------- ### Repository Variable Definition Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/2. repository-variables.md An example of how to define repository variables in a YAML configuration file. These variables can be used in GitHub Actions workflows. ```APIDOC ## Repository Variable Definition This section defines repository variables that can be referenced in a GitHub Actions workflow. ### Properties - **name** (string) - Required - The name of the variable. - **value** (string) - Required - The value of the variable. ### Example ```yaml variables: - name: MY_AWESOME_VAR value: '845705' - name: my_lowercase_var value: I have spaces ``` ``` -------------------------------- ### Build Local Docker Image Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/docker-debugging.md Builds the Docker image from local source code. Use this to test changes before publishing. ```bash docker build -t safe-settings:local . ``` -------------------------------- ### Configure GitHub Repository Variables Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/awslambda.md Set up repository variables in GitHub to store AWS and application-specific configurations required for the deployment pipeline. ```bash AWS_REGION=your-aws-region AWS_ACCOUNT_ID=your-aws-account-id ECR_REPOSITORY=safe-settings-lambda LAMBDA_FUNCTION_NAME=safe-settings-lambda SCHEDULER_FUNCTION_NAME=safe-settings-scheduler GH_ORG=your-organization APP_ID=your-github-app-id WEBHOOK_SECRET=your-webhook-secret SAFE_SETTINGS_GITHUB_CLIENT_ID=your-client-id ``` -------------------------------- ### Block Repository Rename by Human Configuration Source: https://github.com/github/safe-settings/blob/main-enterprise/README.md Example of configuring whether to block manual repository renaming by humans. The default is 'false'. ```dotenv BLOCK_REPO_RENAME_BY_HUMAN=true ``` -------------------------------- ### Create ECR Repository and Lambda Functions Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/awslambda.md Use AWS CLI commands to set up the ECR repository and create two Lambda functions. One function handles webhooks, and the other handles scheduled tasks, both utilizing the same Docker image but with different entry points. ```bash aws ecr create-repository --repository-name safe-settings-lambda --region YOUR_AWS_REGION ``` ```bash aws lambda create-function \ --function-name safe-settings-lambda \ --code ImageUri=YOUR_ACCOUNT.dkr.ecr.YOUR_AWS_REGION.amazonaws.com/safe-settings-lambda:latest \ --role arn:aws:iam::YOUR_ACCOUNT:role/lambda-execution-role \ --package-type Image \ --timeout 30 \ --memory-size 512 \ --image-config '{"Command":["safe-settings-handler.webhooks"]}' ``` ```bash aws lambda create-function \ --function-name safe-settings-scheduler \ --code ImageUri=YOUR_ACCOUNT.dkr.ecr.YOUR_AWS_REGION.amazonaws.com/safe-settings-lambda:latest \ --role arn:aws:iam::YOUR_ACCOUNT:role/lambda-execution-role \ --package-type Image \ --timeout 60 \ --memory-size 512 \ --image-config '{"Command":["safe-settings-handler.scheduler"]}' ``` ```bash aws lambda create-function-url-config \ --function-name safe-settings-lambda \ --auth-type NONE \ --cors '{"AllowOrigins":["*"],"AllowMethods":["POST"]}' ``` -------------------------------- ### Configure Repository as Template Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/1. repository-settings.md Set the 'is_template' property to true to make the repository available as a template. ```yaml repository: - is_template: false ... ``` -------------------------------- ### Minimal Known-Good Local Command Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/docker-debugging.md A concise command to build and run the local Docker image with essential configurations. Includes cleanup. ```bash docker build -t safe-settings:local . && \ docker run --rm --name safe-settings-local \ --env-file ./.env \ --env NODE_ENV=development \ --env HOST=0.0.0.0 \ -p 3000:3000 \ -it safe-settings:local ``` -------------------------------- ### Show Helm Chart Information Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md View the available configuration options and metadata for the Safe Settings Helm chart. This command fetches information from the specified OCI registry. ```bash helm show chart oci://ghcr.io/github/helm-charts/safe-settings ``` -------------------------------- ### Create Admin Repository with GitHub CLI Source: https://github.com/github/safe-settings/blob/main-enterprise/README.md Use the GitHub CLI to create a private repository named 'admin' within your organization. This repository will store all configuration files for Safe-Settings. ```bash gh repo create your-org/admin --private ``` -------------------------------- ### Restrict Push Access to Branch Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/5. branch-protection.md Define specific users, teams, or apps that are allowed to push to a protected branch. This example restricts push access to 'superman' and the 'justice-league' team. ```yaml branches: - name: default protection: ... restrictions: users: - superman teams: - justice-league ... ``` -------------------------------- ### Label Name Configuration Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/8. labels.md Shows how to define the name for a label, including support for emoji. ```yaml labels: - name: bug ... ``` -------------------------------- ### Trigger Deployment Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/awslambda.md Push your changes to the 'master' branch to initiate the automated deployment process via GitHub Actions. ```bash git push origin master ``` -------------------------------- ### Enforce Admin Restrictions for Status Checks Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/github-settings/5. branch-protection.md Example showing how to enforce required status checks for repository administrators. This setting ensures that even admins must pass all configured checks. ```yaml branches: - name: default protection: required_status_checks: strict: true checks: - stark-industries/barndoor-protocol - stark-industries/sokovia-accords enforce_admins: true ``` -------------------------------- ### Custom Override Validator for Branch Protection Source: https://github.com/github/safe-settings/blob/main-enterprise/README.md Use `overridevalidators` to define rules for when a setting is overridden. This example ensures that the `required_approving_review_count` for branch protection is not decreased. Both `baseconfig` and `overrideconfig` are available in the script. ```yaml overridevalidators: - plugin: branches error: | `Branch protection required_approving_review_count cannot be overidden to a lower value` script: | console.log(`baseConfig ${JSON.stringify(baseconfig)}`) console.log(`overrideConfig ${JSON.stringify(overrideconfig)}`) if (baseconfig.protection.required_pull_request_reviews.required_approving_review_count && overrideconfig.protection.required_pull_request_reviews.required_approving_review_count ) { return overrideconfig.protection.required_pull_request_reviews.required_approving_review_count >= baseconfig.protection.required_pull_request_reviews.required_approving_review_count } return true ``` -------------------------------- ### Get Application URL with LoadBalancer Source: https://github.com/github/safe-settings/blob/main-enterprise/helm/safe-settings/templates/NOTES.txt For LoadBalancer service types, this snippet retrieves the LoadBalancer IP and constructs the application URL. Note that it may take time for the IP to become available. ```bash NOTE: It may take a few minutes for the LoadBalancer IP to be available. You can watch the status of by running 'kubectl get --namespace {{ .Release.Namespace }} svc -w {{ include "safe-settings.fullname" . }}' export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "safe-settings.fullname" . }} --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}}) echo http://$SERVICE_IP:{{ .Values.service.port }} ``` -------------------------------- ### Combine Probot Apps in package.json Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Use this configuration to deploy multiple Probot apps within a single instance. List dependencies in `package.json` and specify them in the `probot.apps` field. ```json { "name": "my-probot-app", "private": true, "dependencies": { "probot-autoresponder": "probot/autoresponder", "probot-settings": "probot/settings" }, "scripts": { "start": "probot run" }, "probot": { "apps": ["probot-autoresponder", "probot-settings"] } } ``` -------------------------------- ### Show Helm Chart Values Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Display the default configuration values for the Safe Settings Helm chart. Use this to understand customizable parameters before creating a values file. ```bash helm show values oci://ghcr.io/github/helm-charts/safe-settings ``` -------------------------------- ### Generate Kubernetes YAMLs from Helm Chart Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Generate raw Kubernetes YAML manifests from the Safe Settings Helm chart without installing it. This is useful for inspecting the generated resources or for manual application. ```bash helm template safe-settings oci://ghcr.io/github/helm-charts/safe-settings --values myvalues.yaml ``` -------------------------------- ### Custom Config Validator for Collaborator Permissions Source: https://github.com/github/safe-settings/blob/main-enterprise/README.md Implement custom validation rules using `configvalidators` to enforce specific settings. This example prevents assigning 'admin' permissions to collaborators. The `script` should return `true` for success and `false` for failure. ```yaml configvalidators: - plugin: collaborators error: | `Admin role cannot be assigned to collaborators` script: | console.log(`baseConfig ${JSON.stringify(baseconfig)}`) return baseconfig.permission != 'admin' ``` -------------------------------- ### Deploy to Heroku Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Push your application code to the Heroku remote to deploy the application. ```bash $ git push heroku master ... -----> Node.js app detected ... -----> Launching... done http://arcane-lowlands-8408.herokuapp.com deployed to Heroku ``` -------------------------------- ### Access Application with ClusterIP and Port Forwarding Source: https://github.com/github/safe-settings/blob/main-enterprise/helm/safe-settings/templates/NOTES.txt If the service type is ClusterIP, this command sets up port forwarding to access the application locally via http://127.0.0.1:8080. ```bash export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "safe-settings.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}") export CONTAINER_PORT=$(kubectl get pod --namespace {{ .Release.Namespace }} $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}") echo "Visit http://127.0.0.1:8080 to use your application" kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:$CONTAINER_PORT ``` -------------------------------- ### Compare GitHub Branch Settings Source: https://github.com/github/safe-settings/blob/main-enterprise/README.md Compares local branch settings against GitHub's to identify additions, modifications, and deletions. Useful for detecting configuration drift. ```json { "branches": [ { "name": "master", "protection": { "required_pull_request_reviews": { "required_approving_review_count": 2, "dismiss_stale_reviews": false, "require_code_owner_reviews": true, "dismissal_restrictions": {} }, "required_status_checks": { "strict": true, "contexts": [] }, "enforce_admins": false } } ] } ``` ```json { "branches": [ { "name": "master", "protection": { "url": "https://api.github.com/repos/decyjphr-org/test/branches/develop/protection", "required_status_checks": { "url": "https://api.github.com/repos/decyjphr-org/test/branches/develop/protection/required_status_checks", "strict": true, "contexts": [], "contexts_url": "https://api.github.com/repos/decyjphr-org/test/branches/develop/protection/required_status_checks/contexts", "checks": [] }, "restrictions": { "url": "https://api.github.com/repos/decyjphr-org/test/branches/develop/protection/restrictions", "users_url": "https://api.github.com/repos/decyjphr-org/test/branches/develop/protection/restrictions/users", "teams_url": "https://api.github.com/repos/decyjphr-org/test/branches/develop/protection/restrictions/teams", "apps_url": "https://api.github.com/repos/decyjphr-org/test/branches/develop/protection/restrictions/apps", "users": [], "teams": [], "apps": [] }, "required_pull_request_reviews": { "url": "https://api.github.com/repos/decyjphr-org/test/branches/develop/protection/required_pull_request_reviews", "dismiss_stale_reviews": true, "require_code_owner_reviews": true, "required_approving_review_count": 2, "dismissal_restrictions": { "url": "https://api.github.com/repos/decyjphr-org/test/branches/develop/protection/dismissal_restrictions", "users_url": "https://api.github.com/repos/decyjphr-org/test/branches/develop/protection/dismissal_restrictions/users", "teams_url": "https://api.github.com/repos/decyjphr-org/test/branches/develop/protection/dismissal_restrictions/teams", "users": [], "teams": [] } }, "required_signatures": false, "enforce_admins": false, "required_linear_history": false, "allow_force_pushes": { "enabled": false }, "allow_deletions": false, "required_conversation_resolution": false } } ] } ``` ```json { "additions": {}, "modifications": { "branches": [ { "protection": { "required_pull_request_reviews": { "dismiss_stale_reviews": false } }, "name": "master" } ] }, "deletions": {}, "hasChanges": true } ``` -------------------------------- ### Expose Application with Kubernetes Service Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Apply the Safe Settings service configuration to expose the application within your Kubernetes cluster. Ensure 'svc-safe-settings.yaml' is present. ```bash kubectl apply -f svc-safe-settings.yaml ``` -------------------------------- ### Apply Kubernetes Deployment Manifest Source: https://github.com/github/safe-settings/blob/main-enterprise/docs/deploy.md Apply the Safe Settings deployment configuration to your Kubernetes cluster. Ensure 'safe-settings.yaml' is present in your current directory. ```bash kubectl apply -f safe-settings.yaml ```