- > This could be done by setting an `env` variable called `ADMIN_REPO`. + > [!Note] + > It is possible to override this behavior and specify a custom repo instead of the `admin` repo.
+ > This could be done by setting an `env` variable called `ADMIN_REPO`. -1. The **settings** in the **default** branch is applied. If the settings are changed in a non-default branch and a PR is created to merge the changes, it would be run in a `dry-run` mode to evaluate and validate the settings, and checks would pass or fail based on that. +2. The **settings** in the **default** branch is applied. If the settings are changed in a non-default branch and a PR is created to merge the changes, it would be run in a `dry-run` mode to evaluate and validate the settings, and checks would pass or fail based on that. 2. In `safe-settings` the settings can have 2 types of targets: 1. `org` - These settings are applied to the `org`. `Org`-targeted settings are defined in `.github/settings.yml` . Currently, only `rulesets` are supported as `org`-targeted settings. 2. `repo` - These settings are applied to `repos` 3. For The `repo`-targeted settings there can be at 3 levels at which the settings could be managed: 1. Org-level settings are defined in `.github/settings.yml` - > [!Note] - > It is possible to override this behavior and specify a different filename for the `settings` yml repo.
- > This could be done by setting an `env` variable called `SETTINGS_FILE_PATH`.
- > Similarly, the `.github` directory can be overridden with an `env` variable called `CONFIG_PATH`. +> [!Note] +> It is possible to override this behavior and specify a different filename for the `settings` yml repo.
+> This could be done by setting an `env` variable called `SETTINGS_FILE_PATH`.
+> Similarly, the `.github` directory can be overridden with an `env` variable called `CONFIG_PATH`. 2. `Suborg` level settings. A `suborg` is an arbitrary collection of repos belonging to projects, business units, or teams. The `suborg` settings reside in a yaml file for each `suborg` in the `.github/suborgs` folder. - > [!Note] - > In `safe-settings`, sub orgs could be groups of repos based on `repo names`, or `teams` which the repos have collaborators from, or `custom property values` set for the repos +> [!Note] +> In `safe-settings`, sub orgs could be groups of repos based on `repo names`, or `teams` which the repos have collaborators from, or `custom property values` set for the repos 3. `Repo` level settings. They reside in a repo specific yaml in `.github/repos` folder 4. It is recommended to break the settings into org-level, suborg-level, and repo-level units. This will allow different teams to define and manage policies for their specific projects or business units. With `CODEOWNERS`, this will allow different people to be responsible for approving changes in different projects. > [!Note] > `Suborg` and `Repo` level settings directory structure cannot be customized. - -> [!Note] +> > The settings file must have a `.yml` extension only. `.yaml` extension is ignored, for now. ## How it works @@ -46,14 +45,23 @@ The App listens to the following webhook events: - **branch_protection_rule**: If a branch protection rule is modified or deleted, `safe-settings` will `sync` the settings to prevent any unauthorized changes. -- **repository.edited**: If the default branch is renamed, `safe-settings` will `sync` the settings, returning the default branch to the configured value for the repo. +- **repository.edited**: For e.g. If the default branch is renamed, or if topics change, `safe-settings` will `sync` the settings, to prevent any unauthorized changes. + +- **repository.renamed**: If a repository is renamed, the default behavior is safe-settings will ignore this (for backward-compatibility). If `BLOCK_REPO_RENAME_BY_HUMAN` env variable is set to true, `safe-settings` will revert the repo to the previous name unless it is renamed using a `bot`. If it is renamed using a `bot`, it will try to copy the existing `
|
+
This is the name of the repository + | +Example: + +```yaml +repository: + - name: super-repo +... +``` + + |
|
+
A short description of this repository + | +Example: + +```yaml +repository: + - description: This repo is so awesome, we named it super-repo +... +``` + + |
|
+
A URL with more information about the repository. + | +Example: + +```yaml +repository: + - homepage: https://awesomeness.super-repo.com +... +``` + + |
|
+
Either true to make the repository private or false to make it public. Default: Default: | +Example: + +```yaml +repository: + - private: true +... +``` + + |
|
+
The visibility of the repository. It is recommended to set your defaults to Can be one of: | +Example: + +```yaml +repository: + - private: true + visibility: internal +... +``` + + |
|
+
Specify which security and analysis features to enable or disable for the repository. +To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization." + +Properties of
+
+ | + +```yaml +repository: + security_and_analysis: + advanced_security: + status: enabled + secret_scanning: + status: enabled + secret_scanning_push_protection: + status: enabled +... +``` + + |
|
+
Either true to enable issues for this repository or Default: | + +```yaml +repository: + - has_issues: false +... +``` + + |
|
+
Either Default: | + +```yaml +repository: + - has_projects: false +... +``` + + |
|
+
Either Default: | + +```yaml +repository: + - has_wiki: false +... +``` + + |
|
+
Either Default: | + +```yaml +repository: + - is_template: false +... +``` + + |
|
+
Updates the default branch for this repository. + | + +```yaml +repository: + - default_branch: main +... +``` + + |
|
+
Either Default: | + +```yaml +repository: + - allow_squash_merge: false +... +``` + + |
|
+
Either Default: | + +```yaml +repository: + - allow_merge_commit: false +... +``` + + |
|
+
Either Default: | + +```yaml +repository: + - allow_rebase_merge: false +... +``` + + |
|
+
Either Default: | + +```yaml +repository: + - allow_auto_merge: true +... +``` + + |
|
+
Either Default: | + +```yaml +repository: + - delete_branch_on_merge: true +... +``` + + |
|
+
Either Default: | + +```yaml +repository: + - allow_update_branch: true +... +``` + + |
|
+
The default value for a squash merge commit title: + • Can be one of: | + +```yaml +repository: + - squash_merge_commit_title: PR_TITLE +... +``` + + |
|
+
The default value for a squash merge commit title: +• Can be one of: | + +```yaml +repository: + - squash_merge_commit_message: PR_BODY +... +``` + + |
|
+
The default value for a squash merge commit title: + • Can be one of: | + +```yaml +repository: + - merge_commit_title: PR_TITLE +... +``` + + |
|
+
The default value for a squash merge commit title: + • Can be one of: | + +```yaml +repository: + - merge_commit_message: PR_BODY +... +``` + + |
|
+
Whether to archive this repository. Default: | + +```yaml +repository: + - archived: true +... +``` + + |
|
+
Either Default: | + +```yaml +repository: + - allow_forking: false +... +``` + + |
|
+
Either Default: | + +```yaml +repository: + - web_commit_signoff_required: false +... +``` + + |
|
+
Repository variables that can be referenced in a GitHub Actions workflow + +Properties of
+
+ | +Example: + +```yaml +variables: + - name: MY_AWESOME_VAR + value: super duper value +... +``` + + |
|
+ The handle for the GitHub user account. + | + +```yaml +collaborators: + - username: AquaMan + permission: maintain +... +``` + + |
|
+ The permission to grant the collaborator. Only valid on organization-owned repositories. We accept the following permissions to be set: Default: | + +```yaml +collaborators: + - username: WonderWoman + permission: maintain +``` + + |
|
+ The slug of the team name. + | + +```yaml +teams: + - name: JusticeLeague + permission: maintain +... +``` + + |
|
+ The permission to grant the team on this repository. We accept the following permissions to be set: Default: | + +```yaml +teams: + - name: SuperFriends + permission: maintain +``` + + |
|
+
Require status checks to pass before merging. Set to Properties of
+
+ | +Example: + +```yaml +branches: + - name: default + protection: + required_status_checks: + strict: true + checks: + - stark-industries/barndoor-protocol + - stark-industries/sokovia-accords +... +``` + + |
|
+ Enforce all configured restrictions for administrators. Set to true to enforce required status checks for repository administrators. Set to | + +```yaml +branches: + - name: default + protection: + required_status_checks: + strict: true + checks: + - stark-industries/barndoor-protocol + - stark-industries/sokovia-accords + enforce_admins: true +``` + + |
|
+
Require at least one approving review on a pull request, before merging. Set to Properties of
+
+ | + +```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 + bypass_pull_request_allowances: + apps: + - Jarvis + - Edith + users: + - TonyStank + teams: + - Avengers + dismissal_restrictions: + users: + - Hulk + teams: + - Revengers +... +``` + + |
|
+
Restrict who can push to the protected branch. User, app, and team restrictions are only available for organization-owned repositories. Set to Properties of
+ | +Example: + +```yaml +branches: + - name: default + protection: + ... + restrictions: + users: + - superman + teams: + - justice-league +... +``` + + |
|
+ Enforces a linear commit Git history, which prevents anyone from pushing merge commits to a branch. Set to Default: | + +```yaml +branches: + - name: default + protection: + require_linear_history: false +... +``` + + |
|
+ Permits force pushes to the protected branch by anyone with write access to the repository. Set to true to allow force pushes. Set to false or null to block force pushes. Default: false. For more information, see "Enabling force pushes to a protected branch" in the GitHub Help documentation. + | + +```yaml +branches: + - name: default + protection: + allow_force_pushes: false +... +``` + + |
|
+ Allows deletion of the protected branch by anyone with write access to the repository. Set to Default: | + +```yaml +branches: + - name: default + protection: + allow_deletions: false +... +``` + + |
|
+ If set to Default: | + +```yaml +branches: + - name: default + protection: + block_creations: false +... +``` + + |
|
+ Requires all conversations on code to be resolved before a pull request can be merged into a branch that matches this rule. Set to Default: | + +```yaml +branches: + - name: default + protection: + required_conversation_resolution: false +... +``` + + |
|
+ Whether to set the branch as read-only. If this is Default: | + +```yaml +branches: + - name: default + protection: + lock_branch: false +... +``` + + |
|
+ Whether users can pull changes from upstream when the branch is locked. Set to true to allow fork syncing. Set to Default: | + +```yaml +branches: + - name: default + protection: + allow_fork_syncing: false +... +``` + + |
|
+ Whether users are required to configure SSH or GPG signatures for all commits pushed to this branch. +Default: | + +```yaml +branches: + - name: default + protection: + required_signatures: true +... +``` + + |
|
+
This is the name of the environment, and will be what is referenced in a workflow with | +Example: + +```yaml +environments: + - name: dms-prod-example +... +``` + + |
|
+
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 +... +``` + + |
|
+
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 +... +``` + + |
|
+
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
+
+ | + +```yaml +environments: + - name: production + prevent_self_review: true + reviewers: + - type: Team + id: 1234647 + - type: User + id: 139262123 +... +``` + + |
|
+
The type of deployment branch policy for this environment. To allow all branches to deploy, set to Properties of
+ | +Example: + +```yaml +environments: + - name: production + ... + deployment_branch_policy: + protected_branches: true + custom_branch_policies: false +... +``` + + |
|
+
Environment variables that can be referenced in a GitHub Actions workflow + +Properties of
+
+ | +Example: + +```yaml +environments: + - name: production + variables: + - name: MY_AWESOME_VAR + value: super duper value +... +``` + + |
|
+ Either true to enable issues for this repository or Default: |
+
+```yaml
+autolinks:
+ - key_prefix: JIRA-
+ url_template: https://jira.example.com/browse/JIRA- |
|
+ Either true to enable issues for this repository or Default: |
+
+```yaml
+autolinks:
+ - key_prefix: JIRA-
+ url_template: https://jira.example.com/browse/JIRA- |
|
+ Whether this autolink reference matches alphanumeric characters. If Default: |
+
+```yaml
+autolinks:
+ - key_prefix: JIRA-
+ url_template: https://jira.examole.com/browse/JIRA- |
|
+ The name of the label. Emoji can be added to label names, using either native emoji or colon-style markup. For example, typing | + +```yaml +labels: + - name: bug +... +``` + + |
|
+ The hexadecimal color code for the label, without the leading | + +```yaml +labels: + - name: bug + color: CC0000 +... +``` + + |
|
+ A short description of the label. Must be 100 characters or fewer. + | + +```yaml +labels: + - name: bug + description: Something isn't working +... +``` + + |
- > This could be done by setting an `env` variable called `ADMIN_REPO`. - -2. The **settings** in the **default** branch is applied. If the settings are changed in a non-default branch and a PR is created to merge the changes, it would be run in a `dry-run` mode to evaluate and validate the settings, and checks would pass or fail based on that. -2. In `safe-settings` the settings can have 2 types of targets: - 1. `org` - These settings are applied to the `org`. `Org`-targeted settings are defined in `.github/settings.yml` . Currently, only `rulesets` are supported as `org`-targeted settings. - 2. `repo` - These settings are applied to `repos` - -3. For The `repo`-targeted settings there can be at 3 levels at which the settings could be managed: - 1. Org-level settings are defined in `.github/settings.yml` -> [!Note] -> It is possible to override this behavior and specify a different filename for the `settings` yml repo.
-> This could be done by setting an `env` variable called `SETTINGS_FILE_PATH`.
-> Similarly, the `.github` directory can be overridden with an `env` variable called `CONFIG_PATH`. - - 2. `Suborg` level settings. A `suborg` is an arbitrary collection of repos belonging to projects, business units, or teams. The `suborg` settings reside in a yaml file for each `suborg` in the `.github/suborgs` folder. - -> [!Note] -> In `safe-settings`, sub orgs could be groups of repos based on `repo names`, or `teams` which the repos have collaborators from, or `custom property values` set for the repos - - 3. `Repo` level settings. They reside in a repo specific yaml in `.github/repos` folder -4. It is recommended to break the settings into org-level, suborg-level, and repo-level units. This will allow different teams to define and manage policies for their specific projects or business units. With `CODEOWNERS`, this will allow different people to be responsible for approving changes in different projects. - -> [!Note] -> `Suborg` and `Repo` level settings directory structure cannot be customized. +`Safe-settings` – an app to manage policy-as-code and apply repository settings across an organization. + +1. In `safe-settings`, all the settings are stored centrally in an `admin` repo within the organization. Unlike the [GitHub Repository Settings App](https://github.com/repository-settings/app), the settings files cannot be in individual repositories. + + > It is possible specify a custom repo instead of the `admin` repo with `ADMIN_REPO`. See [Environment variables](#environment-variables) for more details. + +1. The **settings** in the **default** branch are applied. If the settings are changed on a non-default branch and a PR is created to merge the changes, the app runs in a `dry-run` mode to evaluate and validate the changes. Checks pass or fail based on the `dry-run` results. + +1. In `safe-settings` the settings can have 2 types of targets: + 1. `org` - These settings are applied to the organization. `Org`-targeted settings are defined in `.github/settings.yml`. Currently, only `rulesets` are supported as `org`-targeted settings. + 1. `repo` - These settings are applied to repositories. + +1. For the `repo`-targeted settings, there can be 3 levels at which the settings are managed: + 1. `Org`-level settings are defined in `.github/settings.yml` + + > It is possible to override this behavior and specify a different filename for the `settings.yml` file with `SETTINGS_FILE_PATH`. Similarly, the `.github` directory can be overridden with `CONFIG_PATH`. See [Environment variables](#environment-variables) for more details. + + 1. `Suborg` level settings. A `suborg` is an arbitrary collection of repos belonging to projects, business units, or teams. The `suborg` settings reside in a yaml file for each `suborg` in the `.github/suborgs` folder. + + > In `safe-settings`, `suborgs` could be groups of repos based on `repo names`, or `teams` which the repos have collaborators from, or `custom property values` set for the repos + + 1. `Repo` level settings. They reside in a repo specific yaml in `.github/repos` folder + +1. It is recommended to break the settings into `org`-level, `suborg`-level, and `repo`-level units. This will allow different teams to define and manage policies for their specific projects or business units. With `CODEOWNERS`, this will allow different people to be responsible for approving changes in different projects. + +> [!NOTE] +> The `suborg` and `repo` level settings directory structure cannot be customized. > -> The settings file must have a `.yml` extension only. `.yaml` extension is ignored, for now. +> Settings files must have a `.yml` extension only. For now, the `.yaml` extension is ignored. ## How it works ### Events The App listens to the following webhook events: -- **push**: If the settings are created or modified, that is, if push happens in the `default` branch of the `admin` repo and the file added or changed is `.github/settings.yml` or `.github/repos/*.yml`or `.github/suborgs/*.yml`, then the settings would be applied either globally to all the repos, or specific repos. For each repo, the settings that are actually applied depend on the default settings for the org, overlayed with settings for the suborg that the repo belongs to, overlayed with the settings for that specific repo. - -- **repository.created**: If a repository is created in the org, the settings for the repo - the default settings for the org, overlayed with settings for the suborg that the repo belongs to, overlayed with the settings for that specific repo - is applied. +- **push**: If the settings are created or modified, that is, if push happens in the `default` branch of the `admin` repo and the file added or changed is `.github/settings.yml` or `.github/repos/*.yml`or `.github/suborgs/*.yml`, then the settings would be applied either globally to all the repos, or specific repos. For each repo, the settings that are actually applied depend on the default settings for the org, overlaid with settings for the suborg that the repo belongs to, overlaid with the settings for that specific repo. + +- **repository.created**: If a repository is created in the org, the settings for the repo - the default settings for the org, overlaid with settings for the suborg that the repo belongs to, overlaid with the settings for that specific repo - is applied. - **branch_protection_rule**: If a branch protection rule is modified or deleted, `safe-settings` will `sync` the settings to prevent any unauthorized changes. @@ -49,7 +47,7 @@ The App listens to the following webhook events: - **repository.renamed**: If a repository is renamed, the default behavior is safe-settings will ignore this (for backward-compatibility). If `BLOCK_REPO_RENAME_BY_HUMAN` env variable is set to true, `safe-settings` will revert the repo to the previous name unless it is renamed using a `bot`. If it is renamed using a `bot`, it will try to copy the existing `
@@ -258,7 +254,7 @@ Here is a screenshot of what the users will see in the `checkrun` page:
### Error handling -The app creates a `Check` at the end of its processing to indicate if there were any errors. The `Check` is called `safe-settings` and corrosponds to the latest commit on the `default` branch of the `admin` repo. +The app creates a `Check` at the end of its processing to indicate if there were any errors. The `Check` is called `safe-settings` and corresponds to the latest commit on the `default` branch of the `admin` repo. Here is an example of a `checkrun` result:
@@ -270,292 +266,88 @@ And the `checkrun` page will look like this: