diff --git a/README.md b/README.md index 4acf9f7a..3d667d1e 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ Some examples of what you can do: - Ensure pull requests follow conventions and [prevent merging][comment-if-guidelines-not-met] when it is not followed. - [Notify author of failed guidelines][comment] when opening an issue. - Schedule [detection for obsolete (stale) issues and pull requests][staleness] and notify author and collaborators. +- [Auto-merge][automerge] pull requests once all checks pass. - And [more][configuration] --- @@ -45,7 +46,7 @@ We need your help: - Have an **💡idea** for a **new feature**? Please [create a new issue](https://github.com/mergeability/mergeable/issues) and tell us! - **Fix a bug**, implement a new **validator** or **action** and [open a pull request](CONTRIBUTING.md)! -> ☝️ **NOTE:** For development and testing. You'll want to [read about how to run it locally](deploy.md#running-locally). +> ☝️ **NOTE:** For development and testing. You'll want to [read about how to run it locally][run-locally]. # Authors @@ -58,4 +59,6 @@ AGPL, Copyright (c) 2019 [Justin Law](https://github.com/jusx) & [Shine Lee](htt [comment-if-guidelines-not-met]: https://mergeable.readthedocs.io/en/latest/recipes.html#comment-if-guidelines-not-met [comment]: https://mergeable.readthedocs.io/en/latest/actions/comment.html [staleness]: https://mergeable.readthedocs.io/en/latest/recipes.html#check-stale-pr-and-issues +[automerge]: https://mergeable.readthedocs.io/en/latest/recipes.html#auto-merge-pull-requests-once-all-checks-pass [configuration]: https://mergeable.readthedocs.io/en/latest/configuration.html +[run-locally]: https://mergeable.readthedocs.io/en/latest/deployment.html#running-locally diff --git a/deploy.md b/deploy.md deleted file mode 100644 index c282bc01..00000000 --- a/deploy.md +++ /dev/null @@ -1,58 +0,0 @@ -## Deploying - -If you would like to run your own instance of this plugin, you can do so by forking this repo and deploying it to your own servers or run it locally. - -The [Probot deployment guide](https://probot.github.io/docs/deployment/) describes this as well. - -[Create a GitHub App](https://github.com/settings/apps/new) and configure the permissions & events with the following: - -**Settings:** -- GitHub app name - **Your app name** -- Webhook URL - **Your webhook url for listening to events** (for local deployments you can use [smee.io](https://smee.io/)) -- Webhook secret - **Your generated webhook seceret** (GitHub app page has instructions on how to create this) - -**Permissions:** -- Checks - **Read & Write** -- Issues - **Read & Write** -- Repository metadata - **Read Only** -- Pull requests - **Read Only** -- Commit Statuses - **Read & Write** -- Single File - **Read-only** - - Path: `.github/mergeable.yml` -- Repository Contents - **Read-Only** -- Repository projects - **Read-Only** - -**And subscription to the following events:** -- [x] Pull request -- [x] Pull request review comment -- [x] Pull request review -- [x] Issues - -Make sure to create a private key for the app after it's been registered. - -## Running Locally -1. Clone the forked repository on to your machine -2. Globally install smee-client from with npm ```npm install -g smee-client``` -3. Go to [smee.io](https://smee.io) and create a new webhook OR use the cli by - running the `smee` command. -4. Copy `.env.template` to a new file called `.env`, and fill it out. -5. Run `npm run dev` in your local repository -6. Add a repository for your Github app by going to [application settings](https://github.com/settings/installations) -7. Do a test pull request to check if everything is working - -Note: if you wish to use a different config file name beside `mergeable.yml`, use `CONFIG_PATH` environment variable. Config files uses `.github` as base path, see [here](https://github.com/probot/probot/blob/1a19bdd/src/context.ts#L190) - -### Possible issues - -#### `400 bad request` / `Error: No X-Hub-Signature found on request` - -This happens when you haven't configured the webhook secret correctly in your -locally running instance. Make sure to set the `SECRET_TOKEN` environment variable -in `.env` before running `npm run dev`. - -#### `ERROR probot: Integration not found` - -This may occur when running Mergeable using a GitHub Enterpise instance. - -To fix, try making sure you've set the `GHE_HOST` variable in `.env` to the -hostname of your Enterprise instance. E.g. `GHE_HOST=github.your_company.com`. diff --git a/docs/annotations.rst b/docs/annotations.rst index 07fc191b..3e65c2e5 100644 --- a/docs/annotations.rst +++ b/docs/annotations.rst @@ -1,22 +1,23 @@ +.. _annotations-page: Annotations ===================================== Annotations allows the use of dynamic values in your recipes. -To bypass the annotation, use `\` prefix. (i.e `\@author` will be replaced with literal `@author`) +To bypass the annotation, use ``\`` prefix. (i.e ``\@author`` will be replaced with literal `@author`) :: + @author : replace with the login of creator of issues/PR -Actions supported -- assign -- comment -- checks +Actions supported: +:: + 'assign', 'comment', 'checks' -.. note:: - Don't see any annotation that fits your needs? let us know by creating an `issue `_ +.. hint:: + Don't see any annotation that fits your needs? Let us know by creating an `issue `_ on github. diff --git a/docs/configuration.rst b/docs/configuration.rst index fb847fdc..5cf9fd3b 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -7,8 +7,8 @@ Configuration First, you'll need to start by creating a ``.github/mergeable.yml`` file in your repository. -.. hint:: - Check out our :ref:`recipes-page` page for examples and most commonly used settings +.. note:: + Check out our :ref:`recipes-page` page for examples and most commonly used settings. Next, we'll go into how the configuration is structured. @@ -34,7 +34,7 @@ error: Each recipe appears as a separate check in the pull request. -Here is a full example of how a recipe looks - +Here is a full example of how a recipe looks: .. code-block:: yml @@ -79,7 +79,7 @@ Here is a full example of how a recipe looks - - do: {{action}} .. note:: - There are some default actions that'll be automatically applied based on the events specified + There are some default actions that'll be automatically applied based on the events specified. Filters ------------ @@ -90,7 +90,7 @@ Filters are checks that mergeable will process in order to determine if validato Each filter have certain events that it can support, so keep an eye out for them. .. hint:: - Don't see an filter that should be on here? Let us know by creating an `issue `_ on github + Don't see an filter that should be on here? Let us know by creating an `issue `_ on github. Filter List @@ -108,7 +108,7 @@ Validators are checks that mergeable will process in order to determine whether Each validator have certain events that it can support, so keep an eye out for them. .. hint:: - Don't see an validator that should be on here? Let us know by creating an `issue `_ on github + Don't see an validator that should be on here? Let us know by creating an `issue `_ on github. Validator List @@ -125,6 +125,7 @@ Validator List validators/description.rst validators/headRef.rst validators/label.rst + validators/lastComment.rst validators/milestone.rst validators/project.rst validators/size.rst @@ -153,7 +154,7 @@ Options List Operators ------------ -These operators can help create more complex logic of validations +These operators can help create more complex logic of validations. Operator List @@ -169,7 +170,7 @@ Actions Actions that mergeable is currently able to perform. .. hint:: - Don't see an action that should be on here? Let us know by creating an `issue `_ on github + Don't see an action that should be on here? Let us know by creating an `issue `_ on github. .. toctree:: actions/assign.rst @@ -185,9 +186,10 @@ Actions that mergeable is currently able to perform. Reusable Configuration -------------------------- -YML has a feature called `Anchor`_ that allows you to create reusable parts in the config +YML has a feature called `Anchor `_ that allows you to create reusable parts in the config: .. code-block:: yml + on_fail_comment: &default_fail_comment - do: comment payload: diff --git a/docs/deployment.rst b/docs/deployment.rst index 1fb9e7cb..7d222403 100644 --- a/docs/deployment.rst +++ b/docs/deployment.rst @@ -4,50 +4,56 @@ Deploying --------------------- If you would like to run your own instance of this plugin, you can do so by forking this repo and deploying it to your own servers or run it locally -The `Probot deployment guide `_ describes this as well +The `Probot deployment guide `_ describes this as well. `Create a GitHub App `_ and configure the permissions & events with the following: **Settings:** * GitHub app name - **Your app name** -* Webhook URL - **Your webhook url for listening to events** (for local deployments you can use `smee.io `_)) +* Webhook URL - **Your webhook url for listening to events** (for local deployments you can use `smee.io `_) * Webhook secret - **Your generated webhook seceret** (GitHub app page has instructions on how to create this) -**Permissions:** +**Repository Permissions:** * Checks - **Read & Write** * Issues - **Read & Write** -* Repository metadata - **Read Only** -* Pull requests - **Read Only** -* Commit Statuses - **Read & Write** -* Single File - **Read-only** +* Metadata - **Read Only** +* Pull requests - **Read & Write** +* Commit statuses - **Read & Write** +* Single file - **Read-only** * Path: ``.github/mergeable.yml`` -* Repository Contents - **Read-Only** -* Repository projects - **Read-Only** +* Contents - **Read-Only** +* Projects - **Read-Only** + +**Organization Permissions:** + +* Members - **Read Only** **And subscription to the following events:** +* [x] Issue comment +* [x] Issues * [x] Pull request -* [x] Pull request review comment * [x] Pull request review -* [x] Issues +* [x] Status Make sure to create a private key for the app after it's been registered. Running Locally ------------------ -1. Clone the forked repository on to your machine +1. Clone the forked repository on to your machine. 2. Globally install smee-client from with npm ``npm install -g smee-client`` 3. Go to `smee.io `_ and create a new webhook OR use the cli by running the ``smee`` command. 4. Copy ``.env.template`` to a new file called ``.env``, and fill it out. -5. Run ``npm run dev`` in your local repository +5. Run ``npm run dev`` in your local repository. 6. Add a repository for your Github app by going to `application settings `_ -7. Do a test pull request to check if everything is working +7. Do a test pull request to check if everything is working. -Note: if you wish to use a different config file name besides ``mergeable.yml``, use the ``CONFIG_PATH`` environment variable. Config files use ``.github`` as base path, see `here `_. +.. note:: + If you wish to use a different config file name besides ``mergeable.yml``, use the ``CONFIG_PATH`` environment variable. Config files use ``.github`` as base path, see `here `_. Possible Issues @@ -59,6 +65,13 @@ This happens when you haven't configured the webhook secret correctly in your locally running instance. Make sure to set the ``SECRET_TOKEN`` environment variable in ``.env`` before running ``npm run dev``. +``ERROR probot: Integration not found`` + +This may occur when running Mergeable using a GitHub Enterpise instance. + +To fix, try making sure you've set the `GHE_HOST` variable in `.env` to the +hostname of your Enterprise instance. E.g. `GHE_HOST=github.your_company.com`. + .. note:: For a list of possible configurable variables within mergeable, check :ref:`configurable-variables-page` diff --git a/docs/filters/payload.rst b/docs/filters/payload.rst index 07ffe832..baa7d18d 100644 --- a/docs/filters/payload.rst +++ b/docs/filters/payload.rst @@ -1,9 +1,9 @@ Payload ^^^^^^^^^^^^^^ -Check against any available fields within the payload, each event can have different field, please refer to `github API documentation`_ for available fields. +Check against any available fields within the payload, each event can have different field, please refer to `github API documentation `_ for available fields. -An example to check if a pull_request_review event has `state` of `changes_requested` +An example to check if a `pull_request_review` event has ``state`` of `changes_requested` :: @@ -23,7 +23,7 @@ To check if a `pull_request` event is not a `draft` boolean: match: false -An example to check if a pull_request event has a `label` named `foo` +An example to check if a `pull_request` event has a ``label`` named `foo` :: @@ -54,4 +54,4 @@ Each field must be checked using one of the following options Supported Events: :: - 'pull_request.*', 'pull_request_review.*', 'issues.*' + 'pull_request.*', 'pull_request_review.*', 'issues.*', 'issue_comment.*' diff --git a/docs/index.rst b/docs/index.rst index 58aa662e..e7bede16 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,7 @@ Mergeable helps automate your team's GitHub workflow without a single line of co usage.rst configuration.rst recipes.rst + deployment.rst contributing.rst support.rst changelog.rst diff --git a/docs/options/must_exclude.rst b/docs/options/must_exclude.rst index 30ec6d84..a55d169e 100644 --- a/docs/options/must_exclude.rst +++ b/docs/options/must_exclude.rst @@ -45,7 +45,7 @@ You can also use an array of regex matchers. If any of them match, the validatio - No - i -Supported Validators:- +Supported Validators: :: - 'baseRef', 'headRef', 'changeset', 'content', 'description', 'label', 'milestone', 'title' + 'author', 'baseRef', 'headRef', 'changeset', 'content', 'description', 'label', 'lastComment', 'milestone', 'title' diff --git a/docs/options/must_include.rst b/docs/options/must_include.rst index 610abdb5..c820a1f5 100644 --- a/docs/options/must_include.rst +++ b/docs/options/must_include.rst @@ -45,7 +45,7 @@ You can also use an array of regex matchers. If any of them match, the validatio - No - i -Supported Validators:- +Supported Validators: :: - 'baseRef', 'headRef', 'changeset', 'commit', 'content', 'description', 'label', 'milestone', 'project', 'title' + 'author', 'baseRef', 'headRef', 'changeset', 'commit', 'content', 'description', 'label', 'lastComment', 'milestone', 'project', 'title' diff --git a/docs/recipes.rst b/docs/recipes.rst index c6765bc1..89686b7a 100644 --- a/docs/recipes.rst +++ b/docs/recipes.rst @@ -3,9 +3,12 @@ Recipes -------------------------- +.. note:: + Check out our :ref:`annotations-page` page for possible placeholders in values. + Work In Progress """"""""""""""""" -Prevent accidental merging of Pull Requests that are work in progress by labeling it WIP or prefixing the title with the abbreviation. +Prevent accidental merging of Pull Requests that are work in progress by labeling it `WIP` or prefixing the title with the abbreviation. :: @@ -18,7 +21,7 @@ Prevent accidental merging of Pull Requests that are work in progress by labelin regex: ^\[WIP\] - do: label must_exclude: - regex: 'wip' + regex: 'wip|work in progress' No Empty Description """"""""""""""""" diff --git a/docs/validators/last comment.rst b/docs/validators/lastComment.rst similarity index 100% rename from docs/validators/last comment.rst rename to docs/validators/lastComment.rst diff --git a/docs/validators/size.rst b/docs/validators/size.rst index d4ef8730..8d192b08 100644 --- a/docs/validators/size.rst +++ b/docs/validators/size.rst @@ -14,7 +14,7 @@ Validates that the files specified are all part of a pull request (added or modi count: 250 message: Change is very large. Should be under 250 lines of additions deletions: - count: 500 + count: 250 message: Change is very large. Should be under 250 lines of deletions. ignore_comments: false #if true, comments will not be counted toward the lines count diff --git a/recipes/pr-wip.md b/recipes/pr-wip.md deleted file mode 100644 index 70e71663..00000000 --- a/recipes/pr-wip.md +++ /dev/null @@ -1,33 +0,0 @@ -## Work In Progress - -Prevent accidental merging of Pull Requests that are work in progress by labeling it `WIP` or prefixing the title with the abbreviation. - -### Recipe -```yml -version: 2 -mergeable: - - when: pull_request.* - validate: - - do: title - must_exclude: - regex: 'wip|work in progress' - - do: label - must_exclude: - regex: 'wip|work in progress' - pass: - - do: checks - status: success - payload: - title: Success!! - summary: '{{#results}}- {{message.pass}} {{/results}}' - fail: - - do: checks - status: failure - payload: - title: Fail!! - summary: > - The following errors have occured {{#results}}- {{message.fail}} {{/results}} -``` - -### Why -With this recipe, mergeable will fail the pull request when the terms `wip` or `work in progress` is found in the title or label.