Change default to playground instead of experimental

⚠️ Sunset Notice ⚠️

TODO(@tianhaoz95): add future plans and migration guide.

What are not going to change:

The project can still be self-hosted (Heroku or as a GitHub action, see https://probot.github.io/docs/deployment for details).
I will still maintain the project health including getting dependencies up-to-date and merging code contributions.

What are changing:

There will not be hosted services.
There won't be new features planned.

Repository status

ApproveMan is a GitHub app that helps approve pull requests with safe changes.

Motivation

To maintain the health of repositories, it's important to set up review policies to make sure every pull request is good.

GitHub provides "protected branches" as a way to enforce code review policies on incoming pull requests.

However, not all pull requests require human attention.

For example, it's reasonable for a repository to set up a location with a user's GitHub ID like [project_root]/playground/${username} to allow developers add quick experiments that they want to keep a record and share with the team.

In this case, if I want to add some notes in [project_root]/playground/${username}/my-note.md, there is no reason to ask another developer to review the change.

Usage

For GitHub

The app can be installed from the GitHub Marketplace.

You can configure the behavior by adding rules into .github/approveman.yml.

Here is an example that, given that my GitHub ID is tianhaoz95, approves all my changes that go into playground/tianhaoz95 and docs/personal/tianhaoz95:

ownership_rules:
  directory_matching_rules:
    - name: personal projects in experimental
      path: playground/{{username}}/**/*
    - name: personal documentation
      path: docs/personal/{{username}}/**/*

Note:

The default config contains playground/{{username}}/**/* if no config file is provided in the repository.
All pull requests that modify files within .github the directory is denied regardless of the rules in the configuration for safety.
The globstar matches only the directories. More specifically, if you want all Markdown files in a directory, please use playground/{{username}}/**/*.md instead of playground/{{username}}/**.md which might work with some of the matching package variances.

Here is an example of how it works:

For GitHub Enterprise

Run with container

After setting GHE_HOST, APP_ID, WEBHOOK_PROXY_URL, WEBHOOK_SECRET, use the following command to start the server:

sudo docker run \
    --env GHE_HOST \
    --env APP_ID \
    --env WEBHOOK_PROXY_URL \
    --env WEBHOOK_SECRET \
    ghcr.io/tianhaoz95/approveman-server:v1.1.2

For more details, see GitHub Container Registry.

Run locally

To run a server for GitHub Enterprise, please also set GHE_HOST and APP_ACTOR_NAME_OVERRIDE before running the server:

# This will be the custom domain for your GitHub Enterprise
export GHE_HOST="github.example.com"

# The following is just an example, you will need to set it to
# the app's actor name that you assign it with in GitHub Enterprise
# integration.
export APP_ACTOR_NAME_OVERRIDE="project-name__approveman[bot]"

npm run build # Build the TypeScript source
npm start # Start the server

After the server is up and running, the rest should be the same as the GitHub setup.

Available config

The following is a full configuration with default values:

ownership_rules:
  # If files inside .github directory should be allowed.
  # When it is set of true, rules like .github/workflows/playground__{{username}}-*.yml
  # can be enable with certain rules.
  # When it is set of false (default value), a pull request will not be approved
  # reguardless of rules if any files inside the .github folder is touched.
  allow_dot_github: false
  # A list of usernames that should not get their pull requests approved even
  # validated by rules. This can be used when some users are spotted to abuse
  # the auto approval and checks in unwanted content that violates the code of
  # conduct or other policies set by the owner.
  global_blacklisted_users: []
  # An optional list of usernames that should get their pull requests approved if
  # validated by rules. This can be used when only some users are trusted "commit
  # directly to the default branch", but you still want repository checks to be run for
  # their changes.  If not specified or empty, all users are considered to be "allowed".
  # This is also useful for automation usecases, automatically approving PRs created by
  # specific machine users.
  # N.B. Where a user is both "allowed" and "blacklisted", blacklisting takes precedence.
  global_allowed_users: []
  # The rules for matching directory ownership. A pull request is determined to be safe
  # when all the files modified satisfy at least one of the rules.
  directory_matching_rules:
      # The name of the rules that is used mainly for logging.
    - name: "Default playground rule for prototyping."
      # The directory that certain user with {{username}} owns.
      path: "playground/{{username}}/**/*"