# Introduction

Welcome to MergeDeps! MergeDeps allows you to block accidental merges while waiting on other tasks **by explicitly blocking the merge until the dependency is merged**. MergeDeps does this without requiring, or even requesting, access to your source code.

This can be useful in the following situations:

* You have created branches off a feature branch, and don't want to merge the feature branch until all other branches have been resolved
* You have new features that are dependent on another teams work, and want to avoid merging until the other service is ready.

### Usage:

MergeDeps watches for dependency lines in the description of a Pull Request.

It will respond to lines which begin with `Depends on` (case insensitive), followed by a list of Pull Request references. References can be in the following format:

| Reference                     | Location                                                           |
| ----------------------------- | ------------------------------------------------------------------ |
| `#<id>`                       | A Pull Request within the same project                             |
| `<project>#<id>`              | A Pull Request in a different project within the same organization |
| `<organization>/<project>#id` | A Pull Request in a projected within a different organization      |

> Note that dependencies on private repositories in other organizations require MergeDeps installed in both organizations, with access to both repositories, and access confirmation by the owner of the depended-on repository.

For example,&#x20;

```
# Create a dependency on #85 in your local project, 
# and #40000 in the rails/rails project

Depends on #85, rails/rails#40000
```

#### Time-based Blocks

MergeDeps supports blocking a Pull Request until a given time. For this, you can use `Blocked until`, followed by any recognized time format.

For example, `Blocked until 12/25/2020`.

![](https://4245976741-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MKv8rVJTVKOCZmrQo9L%2F-MOK3rT2w-1HD3rCM8pm%2F-MOK8EmNOyCSU4AvXetN%2Fimage.png?alt=media\&token=fdaf4fb6-5ac9-460e-80c1-f3d22526c88b)

#### Updating:

The dependencies of a Pull Request can be updated at any time by editting the description of the Pull Request. **The current body of the Pull Request is the source of truth for specifying dependencies**.&#x20;

If you would like to remove a dependency, but still keep a record of it in the description, you can format the dependency with a strikethrough (~~strikethrough~~) and it will be ignored. This can work for entire lines (~~Depends on #3, #4~~), or specific dependencies (Depends on ~~#3~~ #4).


# Installation

MergeDeps is easily installed by installing the Github Application into your organization. You can install the MergeDeps app, or configure an existing installation, [here](https://github.com/apps/mergedeps/installations/new).

When installing MergeDeps, you will see a Github authorization screen:

![](https://4245976741-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MKv8rVJTVKOCZmrQo9L%2F-MKvSWwDDkCnLVaOElOq%2F-MKvXWntUM5DdQhxyr9S%2Fimage.png?alt=media\&token=4ad6b9dd-c9dd-4c46-a65c-d96f5c83051f)

By default, Github will prompt you to install MergeDeps on all repositories. **This is not necessary for MergeDeps to function**. We recommend that you only grant access to repositories which you plan to use MergeDeps on. This includes repositories which depend on, or are depended on by, other repositories.

For example, lets say you have a Pulll Request in your repository `frontend`, which depends on a Pull Request in your repository `backend`. MergeDeps must be granted access to both repositories.

### Required Check

We **highly recommend** making the `mergedeps` check a required check on your repository. This is what causes Github to enforce the check before merge. This is done by creating a **Branch protection rule.**

**You can do this in your repository by going into "Settings" > "Branches" and creating a rule for your main branch.**

![](https://4245976741-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MKv8rVJTVKOCZmrQo9L%2F-MKvSWwDDkCnLVaOElOq%2F-MKveUxLyZ1-WU0D26zF%2Fimage.png?alt=media\&token=ef8779aa-d44f-4204-a436-57f1b69f5dea)

![](https://4245976741-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MKv8rVJTVKOCZmrQo9L%2F-MKvSWwDDkCnLVaOElOq%2F-MKvern5CZagZfXCFI5X%2Fimage.png?alt=media\&token=50986a0e-66a5-4bf6-bd13-b681447e4c84)


# Reconfigure Installation

You may have to reconfigure MergeDeps access to your repositories, for instance if you need to grant access to a new repositories.

This can be done by going [here](https://github.com/apps/mergedeps/installations/new). If you have multiple organizations, you will have to select the organization you wish to configure.

At this point, you should see a screen as follows. You can modify Repository access here.

![](https://4245976741-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MKv8rVJTVKOCZmrQo9L%2F-MKvSWwDDkCnLVaOElOq%2F-MKvYYRu9kUU3CF_opsX%2Fimage.png?alt=media\&token=57d173fe-54c5-409c-9077-662706e09ea8)


# Debugging


# Upgrading

When MergeDeps is first installated, a subscription to our Free plan is automatically created for the organization.

Your plan can be fully managed at our [Customer Portal](https://manage.mergedeps.com) by signing in with your Github account.

> Note that current all members in your organization have access to modify your subscription. Limiting access here is on our roadmap.