You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This GitHub App syncs repository settings defined in `.github/settings.yml` to GitHub, enabling Pull Requests for repository settings.
4
4
5
-
[![Powered by Vercel][vercel-badge]][vercel-link]
5
+
<!--status-badges start -->
6
6
7
7
[![Node CI Workflow Status][github-actions-ci-badge]][github-actions-ci-link]
8
8
[![Renovate][renovate-badge]][renovate-link]
9
9
10
10
<!--status-badges end -->
11
11
12
-
This GitHub App syncs repository settings defined in `.github/settings.yml` to GitHub, enabling Pull Requests for repository settings.
13
-
14
12
## Usage
15
13
16
-
1.__[Install the app](https://github.com/apps/settings)__.
17
-
1. Create a `.github/settings.yml` file in your repository. Changes to this file on the default branch will be synced to GitHub.
14
+
### Install
18
15
19
-
All top-level settings are optional. Some plugins do have required fields.
16
+
To gain the benefits of the Repository Settings app, it will need to installed
17
+
as a GitHub App on your repositories.
18
+
First, choose which approach to using the Repository Settings App is most appropriate for you:
20
19
21
-
```yaml
22
-
# These settings are synced to GitHub by https://probot.github.io/apps/settings/
20
+
### Hosted GitHub.com App
23
21
24
-
repository:
25
-
# See https://docs.github.com/en/rest/reference/repos#update-a-repository for all available settings.
26
-
27
-
# The name of the repository. Changing this will rename the repository
28
-
name: repo-name
29
-
30
-
# A short description of the repository that will show up on GitHub
31
-
description: description of repo
32
-
33
-
# A URL with more information about the repository
34
-
homepage: https://example.github.io/
35
-
36
-
# A comma-separated list of topics to set on the repository
37
-
topics: github, probot
38
-
39
-
# Either `true` to make the repository private, or `false` to make it public.
40
-
private: false
41
-
42
-
# Either `true` to enable issues for this repository, `false` to disable them.
43
-
has_issues: true
44
-
45
-
# Either `true` to enable projects for this repository, or `false` to disable them.
46
-
# If projects are disabled for the organization, passing `true` will cause an API error.
47
-
has_projects: true
48
-
49
-
# Either `true` to enable the wiki for this repository, `false` to disable it.
50
-
has_wiki: true
51
-
52
-
# Either `true` to enable downloads for this repository, `false` to disable them.
53
-
has_downloads: true
54
-
55
-
# Updates the default branch for this repository.
56
-
default_branch: master
57
-
58
-
# Either `true` to allow squash-merging pull requests, or `false` to prevent
59
-
# squash-merging.
60
-
allow_squash_merge: true
61
-
62
-
# Either `true` to allow merging pull requests with a merge commit, or `false`
63
-
# to prevent merging pull requests with merge commits.
64
-
allow_merge_commit: true
65
-
66
-
# Either `true` to allow rebase-merging pull requests, or `false` to prevent
67
-
# rebase-merging.
68
-
allow_rebase_merge: true
69
-
70
-
# Either `true` to enable automatic deletion of branches on merge, or `false` to disable
71
-
delete_branch_on_merge: true
72
-
73
-
# Either `true` to enable automated security fixes, or `false` to disable
74
-
# automated security fixes.
75
-
enable_automated_security_fixes: true
76
-
77
-
# Either `true` to enable vulnerability alerts, or `false` to disable
78
-
# vulnerability alerts.
79
-
enable_vulnerability_alerts: true
80
-
81
-
# Labels: define labels for Issues and Pull Requests
82
-
labels:
83
-
- name: bug
84
-
color: CC0000
85
-
description: An issue with the system 🐛.
86
-
87
-
- name: feature
88
-
# If including a `#`, make sure to wrap it with quotes!
89
-
color: '#336699'
90
-
description: New functionality.
91
-
92
-
- name: Help Wanted
93
-
# Provide a new name to rename an existing label
94
-
new_name: first-timers-only
95
-
96
-
# Milestones: define milestones for Issues and Pull Requests
97
-
milestones:
98
-
- title: milestone-title
99
-
description: milestone-description
100
-
# The state of the milestone. Either `open` or `closed`
101
-
state: open
102
-
103
-
# Collaborators: give specific users access to this repository.
104
-
# See https://docs.github.com/en/rest/reference/repos#add-a-repository-collaborator for available options
105
-
collaborators:
106
-
# - username: bkeepers
107
-
# permission: push
108
-
# - username: hubot
109
-
# permission: pull
110
-
111
-
# Note: `permission` is only valid on organization-owned repositories.
112
-
# The permission to grant the collaborator. Can be one of:
113
-
# * `pull` - can pull, but not push to or administer this repository.
114
-
# * `push` - can pull and push, but not administer this repository.
115
-
# * `admin` - can pull, push and administer this repository.
116
-
# * `maintain` - Recommended for project managers who need to manage the repository without access to sensitive or destructive actions.
117
-
# * `triage` - Recommended for contributors who need to proactively manage issues and pull requests without write access.
118
-
119
-
# See https://docs.github.com/en/rest/deployments/environments#create-or-update-an-environment for available options
120
-
# Note: deployment_branch_policy differs from the API for ease of use. Either protected_branches (boolean) OR custom_branches (array of strings) can be provided; this will manage the API requirements under the hood. See https://docs.github.com/en/rest/deployments/branch-policies for documentation of custom_branches. If both are provided in an unexpected manner, protected_branches will be used.
121
-
# Either removing or simply not setting deployment_branch_policy will restore the default 'All branches' setting.
122
-
environments:
123
-
- name: production
124
-
wait_timer: 5
125
-
reviewers:
126
-
- id: 1
127
-
type: 'Team'
128
-
- id: 2
129
-
type: 'User'
130
-
deployment_branch_policy:
131
-
protected_branches: true
132
-
- name: development
133
-
deployment_branch_policy:
134
-
custom_branches:
135
-
- main
136
-
- dev/*
137
-
138
-
# See https://docs.github.com/en/rest/reference/teams#add-or-update-team-repository-permissions for available options
139
-
teams:
140
-
- name: core
141
-
# The permission to grant the team. Can be one of:
142
-
# * `pull` - can pull, but not push to or administer this repository.
143
-
# * `push` - can pull and push, but not administer this repository.
144
-
# * `admin` - can pull, push and administer this repository.
145
-
# * `maintain` - Recommended for project managers who need to manage the repository without access to sensitive or destructive actions.
146
-
# * `triage` - Recommended for contributors who need to proactively manage issues and pull requests without write access.
# Branch Protection settings. Set to null to disable
155
-
protection:
156
-
# Required. Require at least one approving review on a pull request, before merging. Set to null to disable.
157
-
required_pull_request_reviews:
158
-
# The number of approvals required. (1-6)
159
-
required_approving_review_count: 1
160
-
# Dismiss approved reviews automatically when a new commit is pushed.
161
-
dismiss_stale_reviews: true
162
-
# Blocks merge until code owners have reviewed.
163
-
require_code_owner_reviews: true
164
-
# Specify which users and teams can dismiss pull request reviews. Pass an empty dismissal_restrictions object to disable. User and team dismissal_restrictions are only available for organization-owned repositories. Omit this parameter for personal repositories.
165
-
dismissal_restrictions:
166
-
users: []
167
-
teams: []
168
-
# Required. Require status checks to pass before merging. Set to null to disable
169
-
required_status_checks:
170
-
# Required. Require branches to be up to date before merging.
171
-
strict: true
172
-
# Required. The list of status checks to require in order to merge into this branch
173
-
contexts: []
174
-
# Required. Enforce all configured restrictions for administrators. Set to true to enforce required status checks for repository administrators. Set to null to disable.
175
-
enforce_admins: true
176
-
# Prevent merge commits from being pushed to matching branches
177
-
required_linear_history: true
178
-
# Required. Restrict who can push to this branch. Team and user restrictions are only available for organization-owned repositories. Set to null to disable.
179
-
restrictions:
180
-
apps: []
181
-
users: []
182
-
teams: []
183
-
```
184
-
185
-
### Notes
186
-
187
-
1. Label color can also start with `#`, e.g. `color: '#F341B2'`. Make sure to wrap it with quotes!
188
-
1. Each top-level element under branch protection must be filled (eg: `required_pull_request_reviews`, `required_status_checks`, `enforce_admins` and `restrictions`). If you don't want to use one of them you must set it to `null` (see comments in the example above). Otherwise, none of the settings will be applied.
189
-
190
-
### Inheritance
191
-
192
-
This app is built with [probot](https://github.com/probot/probot), and thus uses the [octokit-plugin-config](https://github.com/probot/octokit-plugin-config). This means you can inherit settings from another repo, and only override what you want to change.
193
-
194
-
Individual settings in the arrays listed under `labels`, `teams` (once it is supported) and `branches` will be merged with the base repo if the `name` of an element in the array matches the `name` of an element in the corresponding array in the base repo. A possible future enhancement would be to make that work for the other settings arrays based on `username`, or `title`. This is not currently supported.
195
-
196
-
To further clarify: Inheritance within the Protected Branches plugin allows you to override specific settings per branch. For example, your `.github` repo may set default protection on the `master` branch. You can then include `master` in your `branches` array, and only override the `required_approving_review_count`.
197
-
Alternatively, you might only have a branch like `develop` in your `branches` array, and would still get `master` protection from your base repo.
22
+
A hosted version is provided for use with GitHub.com.
198
23
199
-
## Security Implications
24
+
__[Install the app](https://github.com/apps/settings)__ on your repositories or
25
+
entire organization.
200
26
201
-
__WARNING:__ Note that this app inherently _escalates anyone with `push` permissions to the __admin__ role_, since they can push config settings to the `master` branch, which will be synced. In a future, we may add restrictions to allow changes to the config file to be merged only by specific people/teams, or those with __admin__ access _(via a combination of protected branches, required statuses, and branch restrictions)_. Until then, use caution when merging PRs and adding collaborators.
27
+
[![Powered by Vercel][vercel-badge]][vercel-link]
202
28
203
-
Until restrictions are added in this app, one way to preserve admin/push permissions is to utilize the [GitHub CodeOwners feature](https://help.github.com/articles/about-codeowners/) to set one or more administrative users as the code owner of the `.github/settings.yml` file, and turn on "require code owner review" for the master branch. This does have the side effect of requiring code owner review for the entire branch, but helps preserve permission levels.
29
+
### Self-Hosted App
204
30
205
-
## Deployment
31
+
If you would prefer to self-host your own instance, see the documentation about
32
+
[self-hosting](docs/self-host.md) if you would like to run your own instance of this app.
206
33
207
-
<!--consumer-badges start -->
34
+
### Configuration
208
35
209
-
![node][node-badge]
36
+
Now that you have the repository settings app installed for your repositories,
37
+
see the documentation about [configuration](docs/configuration.md) for details
38
+
about updating your repository settings through pull-requests.
210
39
211
-
<!--consumer-badges end -->
40
+
## Security Implications
212
41
213
-
See [docs/deploy.md](docs/deploy.md) if you would like to run your own instance of this plugin.
42
+
> [!Caution]
43
+
> Note that this app inherently _escalates anyone with `push`
44
+
permissions to the __admin__ role_, since they can push config settings to the
45
+
default branch, which will be synced.
46
+
Until then, use caution when merging PRs and adding collaborators.
47
+
48
+
One way to preserve admin/push permissions is to utilize the
0 commit comments