diff --git a/docs/configuration.md b/docs/configuration.md index ac245696fe..91187afbba 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,186 +2,31 @@ Create a `.github/settings.yml` file 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. +## Sections -```yaml -# These settings are synced to GitHub by https://probot.github.io/apps/settings/ +All sections are optional. Some do have required fields. -repository: - # See https://docs.github.com/en/rest/reference/repos#update-a-repository for all available settings. +Find details about each available section in their own page: - # 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, or `false` 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, or `false` 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, or `false` to prevent - # squash-merging. - allow_squash_merge: true - - # Either `true` to allow merging pull requests with a merge commit, or `false` - # to prevent merging pull requests with merge commits. - allow_merge_commit: true - - # Either `true` to allow rebase-merging pull requests, or `false` to prevent - # rebase-merging. - allow_rebase_merge: true - - # Either `true` to enable automatic deletion of branches on merge, or `false` to disable - delete_branch_on_merge: true - - # Either `true` to enable automated security fixes, or `false` to disable - # automated security fixes. - enable_automated_security_fixes: true - - # Either `true` to enable vulnerability alerts, or `false` to disable - # vulnerability 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 - # If including a `#`, make sure to wrap it with quotes! - color: '#336699' - description: New functionality. - - - name: Help Wanted - # Provide a new name to rename an existing label - new_name: first-timers-only - -# Milestones: define milestones for Issues and Pull Requests -milestones: - - title: milestone-title - description: milestone-description - # The state of the milestone. Either `open` or `closed` - state: open - -# Collaborators: give specific users access to this repository. -# See https://docs.github.com/en/rest/reference/repos#add-a-repository-collaborator for available options -collaborators: - # - username: bkeepers - # permission: push - # - username: hubot - # permission: pull - - # Note: `permission` is only valid on organization-owned repositories. - # The permission to grant the collaborator. Can be one of: - # * `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. - -# See https://docs.github.com/en/rest/deployments/environments#create-or-update-an-environment for available options -# 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. -# Either removing or simply not setting deployment_branch_policy will restore the default 'All branches' setting. -environments: - - name: production - wait_timer: 5 - reviewers: - - id: 1 - type: 'Team' - - id: 2 - type: 'User' - deployment_branch_policy: - protected_branches: true - - name: development - deployment_branch_policy: - custom_branches: - - main - - dev/* - -# See https://docs.github.com/en/rest/reference/teams#add-or-update-team-repository-permissions for available options -teams: - - name: core - # The permission to grant the team. Can be one of: - # * `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: admin - - name: docs - permission: push - -branches: - - name: master - # https://docs.github.com/en/rest/reference/repos#update-branch-protection - # Branch Protection settings. Set to null to disable - protection: - # Required. Require at least one approving review on a pull request, before merging. Set to null to disable. - required_pull_request_reviews: - # 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 status checks to pass before merging. Set to null to disable - required_status_checks: - # 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: [] - # Required. Enforce all configured restrictions for administrators. Set to true to enforce required status checks for repository administrators. Set to null to disable. - enforce_admins: true - # Prevent merge commits from being pushed to matching branches - required_linear_history: true - # Required. Restrict who can push to this branch. Team and user restrictions are only available for organization-owned repositories. Set to null to disable. - restrictions: - apps: [] - users: [] - teams: [] -``` - -### Notes - -1. Label color can also start with `#`, e.g. `color: '#F341B2'`. Make sure to wrap it with quotes! -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. +* [Repository](./plugins/repository.md) +* [Teams](./plugins/teams.md) +* [Collaborators](./plugins/collaborators.md) +* [Branches](./plugins/branches.md) +* [Environments](./plugins/environments.md) +* [Labels](./plugins/labels.md) +* [Milestones](./plugins/milestones.md) ### Inheritance -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. +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. -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. +Individual settings in the arrays listed under `labels`, `teams`, 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. -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`. +#### 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`. Alternatively, you might only have a branch like `develop` in your `branches` array, and would still get `master` protection from your base repo. diff --git a/docs/plugins/branches.md b/docs/plugins/branches.md new file mode 100644 index 0000000000..8783e8fb67 --- /dev/null +++ b/docs/plugins/branches.md @@ -0,0 +1,45 @@ +# Branches + +https://docs.github.com/en/rest/reference/repos#update-branch-protection + +> [!IMPORTANT] +> 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. + +```yaml +branches: + - name: master + # Branch Protection settings. Set to null to disable + protection: + # Required. Require at least one approving review on a pull request, before merging. Set to null to disable. + required_pull_request_reviews: + # 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 status checks to pass before merging. Set to null to disable + required_status_checks: + # 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: [] + # Required. Enforce all configured restrictions for administrators. Set to true to enforce required status checks for repository administrators. Set to null to disable. + enforce_admins: true + # Prevent merge commits from being pushed to matching branches + required_linear_history: true + # Required. Restrict who can push to this branch. Team and user restrictions are only available for organization-owned repositories. Set to null to disable. + restrictions: + apps: [] + users: [] + teams: [] +``` diff --git a/docs/plugins/collaborators.md b/docs/plugins/collaborators.md new file mode 100644 index 0000000000..55200c9e22 --- /dev/null +++ b/docs/plugins/collaborators.md @@ -0,0 +1,19 @@ +# Collaborators + +https://docs.github.com/en/rest/collaborators/collaborators + +```yaml +collaborators: + - username: bkeepers + permission: push + - username: hubot + permission: pull + + # Note: `permission` is only valid on organization-owned repositories. + # The permission to grant the collaborator. Can be one of: + # * `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. +``` diff --git a/docs/plugins/environments.md b/docs/plugins/environments.md new file mode 100644 index 0000000000..5df58955fc --- /dev/null +++ b/docs/plugins/environments.md @@ -0,0 +1,32 @@ +# Environments + + +See https://docs.github.com/en/rest/deployments/environments#create-or-update-an-environment for available options. + +> [!IMPORTANT] +> `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. +> +> Either removing or simply not setting `deployment_branch_policy` will restore the default 'All branches' setting. + +```markdown +environments: + - name: production + wait_timer: 5 + reviewers: + - id: 1 + type: 'Team' + - id: 2 + type: 'User' + deployment_branch_policy: + protected_branches: true + - name: development + deployment_branch_policy: + custom_branches: + - main + - dev/* +``` diff --git a/docs/plugins/labels.md b/docs/plugins/labels.md new file mode 100644 index 0000000000..b8fca689c3 --- /dev/null +++ b/docs/plugins/labels.md @@ -0,0 +1,23 @@ +# Labels + +> [!NOTE] +> Label color can start with `#`, e.g. `color: '#F341B2'`. + +> [!IMPORTANT] +> If including the `#`, make sure to wrap it with quotes since it would otherwise be treated as a yaml comment! + +```yaml +labels: + - name: bug + color: CC0000 + description: An issue with the system 🐛. + + - name: feature + # If including a `#`, make sure to wrap it with quotes! + color: '#336699' + description: New functionality. + + - name: Help Wanted + # Provide a new name to rename an existing label + new_name: first-timers-only +``` diff --git a/docs/plugins/milestones.md b/docs/plugins/milestones.md new file mode 100644 index 0000000000..ac54ad5475 --- /dev/null +++ b/docs/plugins/milestones.md @@ -0,0 +1,11 @@ +# Milestones + +https://docs.github.com/en/rest/issues/milestones#update-a-milestone + +```yaml +milestones: + - title: milestone-title + description: milestone-description + # The state of the milestone. Either `open` or `closed` + state: open +``` diff --git a/docs/plugins/repository.md b/docs/plugins/repository.md new file mode 100644 index 0000000000..9fe3cd4a51 --- /dev/null +++ b/docs/plugins/repository.md @@ -0,0 +1,63 @@ +# Repository + +See https://docs.github.com/en/rest/reference/repos#update-a-repository for all +available repository properties and descriptions of each. + + +```yaml +repository: + + # 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, or `false` 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, or `false` 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, or `false` to prevent + # squash-merging. + allow_squash_merge: true + + # Either `true` to allow merging pull requests with a merge commit, or `false` + # to prevent merging pull requests with merge commits. + allow_merge_commit: true + + # Either `true` to allow rebase-merging pull requests, or `false` to prevent + # rebase-merging. + allow_rebase_merge: true + + # Either `true` to enable automatic deletion of branches on merge, or `false` to disable + delete_branch_on_merge: true + + # Either `true` to enable automated security fixes, or `false` to disable + # automated security fixes. + enable_automated_security_fixes: true + + # Either `true` to enable vulnerability alerts, or `false` to disable + # vulnerability alerts. + enable_vulnerability_alerts: true +``` diff --git a/docs/plugins/teams.md b/docs/plugins/teams.md new file mode 100644 index 0000000000..77275f79b0 --- /dev/null +++ b/docs/plugins/teams.md @@ -0,0 +1,17 @@ +# Teams + +See https://docs.github.com/en/rest/teams/teams#add-or-update-team-repository-permissions for available options + +```yaml +teams: + - name: core + # The permission to grant the team. Can be one of: + # * `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: admin + - name: docs + permission: push +```