firstbirdtech / emergence

A bot that automatically merges your pull requests on configurable conditions.

Version Matrix

eMERGEnce

Maven Central Github Actions CI Workflow codecov Docker Pulls License Scala Steward badge

eMERGEnce is a bot that helps you to get rid of all your emerged pull requests automatically on configurable conditions.

Getting Started

The current supported Version Control System are:

We appreciate contributions for other VCS implementations as well, just show us your PR!

Running eMERGEnce

You can run eMERGEnce with Docker.

To get a list of available options run: docker run firstbird/emergence:latest --help and you should get the following output:

eMERGEnce 0.1.0
Usage: emergence [options]
  --usage  <bool>
        Print usage and exit
  --help | -h  <bool>
        Print help message and exit
  --config  <path>
        The path to the eMERGEnce run config file.
  --vcs-type  <BitbucketCloud>
        The type of VCS you want to run eMERGEnce.
  --vcs-api-host  <uri>
        The base URI for VCS api calls. e.g. https://api.bitbucket.org/2.0
  --vcs-login  <string>
        The username for authenticating VCS API calls.
  --git-ask-pass  <path>
        The path to the executable script file that returns your VCS secret for authenticating VCS API calls.
  --repo-config-name  <string>
        The name/path of the eMERGEnce config file inside the repository. Default: .emergence.yml

An example docker run command might look like this (depending on the selected VCS type):

docker run -v $HOST_DIR:/opt/emergence -it firstbird/emergence:latest \
    --config "/opt/emergence/run-config.yml" \
    --vcs-type "bitbucket-cloud" \
    --vcs-api-host "https://api.bitbucket.org/2.0" \
    --vcs-login ${BITBUCKET_USERNAME} \ 
    --git-ask-pass "opt/emergence/git-ask-pass.sh"

Please check Configuring eMERGEnce for the format of the file passed via the --config option.

The --git-ask-pass option must be the path to an executable that returns to stdout. For example:

#!/bin/sh
echo "my-git-secret"

Configuring eMERGEnce

Configuration for eMERGEence can be configured using the --config option as well as with a repository local configuration file.

Operators

Operator Name Description
== Exact equals.
^$ A valid Java regex.

Conditions

Condition Name Operators Description
build-success-all All build results for the pull requests must be successful.
author == OR ^$ The name of the author that created the pull request.
source-branch == OR ^$ The name of the source branch.
target-branch == OR ^$ The name of the target branch.
build-success == OR ^$ The name of a specific build result

Merge Settings

Name Required Default Description
merge.strategy false squash The merge strategy to use for merging the PR. Allowed: merge-commit, squash or fast-forward
merge.close_source_branch false true Whether to close/delete the source branch or not.

Config Resolver

The conditions and merge settings are resolved with a given priority using this strategy (from lowest to highest):

  1. defaults object from the run config specified via the --config option
  2. repositories.[i] config per array element from the run config specified via the --config option
  3. The configuration provided in the repository directly, specified via the --repo-config-name option

For example if your run config looks like this (--config option):

repositories:
  - name: firstbirdtech/my-repo
    conditions:
      - "build-success-all"
    merge:
      strategy: fast-forward
      close_source_branch: true

defaults:
  merge:
    strategy: merge-commit
    close_source_branch: false
  conditions:
    - "author == emergence"

and in the repository firstbirdtech/my-repo you have the file .emergence.yml:

conditions:
  - "source-branch ^$ ^update\/.+$"
  - "target-branch == master"
merge:
  strategy: squash
  close_source_branch: false

then eMERGEnce will use the follwing settings:

  • Conditions:
    • "build-success-all"
    • "author == emergence"
    • "target-branch == master"
  • Merge
    • Strategy: squash
    • Close Source Branch: false

Please note that conditions are combined instead of overwritten!

Credits

The code of this project is heavily inspired and based on fthomas's awesome scala-steward project. Go check it out!

Contributors

License

This code is licensed under the Apache 2.0 License.