Pull Requests for GitHub repository settings
This GitHub App syncs repository settings defined in
.github/settings.ymlto GitHub, enabling Pull Requests for repository settings.
.github/settings.ymlfile in your repository. Changes to this file on the default branch will be synced to GitHub.
All top-level settings are optional. Some plugins do have required fields.
# These settings are synced to GitHub by https://probot.github.io/apps/settings/repository:
See https://developer.github.com/v3/repos/#edit for all available settings.
The name of the repository. Changing this will rename the repository
name: repo-name
A short description of the repository that will show up on GitHub
description: description of repo
A URL with more information about the repository
homepage: https://example.github.io/
A comma-separated list of topics to set on the repository
topics: github, probot
Either
true
to make the repository private, orfalse
to make it public.private: false
Either
true
to enable issues for this repository,false
to disable them.has_issues: true
Either
true
to enable projects for this repository, orfalse
to disable them.If projects are disabled for the organization, passing
true
will cause an API error.has_projects: true
Either
true
to enable the wiki for this repository,false
to disable it.has_wiki: true
Either
true
to enable downloads for this repository,false
to disable them.has_downloads: true
Updates the default branch for this repository.
default_branch: master
Either
true
to allow squash-merging pull requests, orfalse
to preventsquash-merging.
allow_squash_merge: true
Either
true
to allow merging pull requests with a merge commit, orfalse
to prevent merging pull requests with merge commits.
allow_merge_commit: true
Either
true
to allow rebase-merging pull requests, orfalse
to preventrebase-merging.
allow_rebase_merge: true
Either
true
to enable automated security fixes, orfalse
to disableautomated security fixes.
enable_automated_security_fixes: true
Either
true
to enable vulnerability alerts, orfalse
to disablevulnerability alerts.
enable_vulnerability_alerts: true
Labels: define labels for Issues and Pull Requests
labels:
name: bug color: CC0000 description: An issue with the system 🐛.
name: feature
#
, make sure to wrap it with quotes!color: '#336699' description: New functionality.
name: first-timers-only
oldname: Help Wanted
milestones:
open
or closed
collaborators:
username: bkeepers
pull
- can pull, but not push to or administer this repository.push
- can pull and push, but not administer this repository.admin
- can pull, push and administer this repository.maintain
- Recommended for project managers who need to manage the repository without access to sensitive or destructive actions.triage
- Recommended for contributors who need to proactively manage issues and pull requests without write access.permission: push
username: hubot permission: pull
teams:
pull
- can pull, but not push to or administer this repository.push
- can pull and push, but not administer this repository.admin
- can pull, push and administer this repository.maintain
- Recommended for project managers who need to manage the repository without access to sensitive or destructive actions.triage
- Recommended for contributors who need to proactively manage issues and pull requests without write access.branches:
# The number of approvals required. (1-6)
required_approving_review_count: 1
# Dismiss approved reviews automatically when a new commit is pushed.
dismiss_stale_reviews: true
# Blocks merge until code owners have reviewed.
require_code_owner_reviews: true
# 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.
dismissal_restrictions:
users: []
teams: []
# Required. Require branches to be up to date before merging.
strict: true
# Required. The list of status checks to require in order to merge into this branch
contexts: []
apps: []
users: []
teams: []
#, e.g.
color: '#F341B2'. Make sure to wrap it with quotes!
required_pull_request_reviews,
required_status_checks,
enforce_adminsand
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.
This app uses probot-config. This means you can inherit settings from another repo, and only override what you want to change.
Individual settings in the arrays listed under
labels,
teams(once it is supported) and
brancheswill be merged with the base repo if the
nameof an element in the array matches the
nameof 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.
To further clarify: Inheritance within the Protected Branches plugin allows you to override specific settings per branch. For example, your
.githubrepo may set default protection on the
masterbranch. You can then include
masterin your
branchesarray, and only override the
required_approving_review_count. Alternatively, you might only have a branch like
developin your
branchesarray, and would still get
masterprotection from your base repo.
WARNING: Note that this app inherently escalates anyone with
pushpermissions to the _admin__ role, since they can push config settings to the
masterbranch, 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.
Until restrictions are added in this app, one way to preserve admin/push permissions is to utilize the GitHub CodeOwners feature to set one or more administrative users as the code owner of the
.github/settings.ymlfile, 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.
See docs/deploy.md if you would like to run your own instance of this plugin.