Getting started

Learn how to set up PullApprove for your organization.

Pull request organization dashboard

Step 1) Install the app

PullApprove 4 is an API-driven integration that gives you new tools to manage pull requests and code reviews across your organization.

When you install the app, it will run in a read-only mode. This way you can see what PullApprove would do without affecting everyone's workflow. If you decide not to use it, you can simply uninstall the app.

Install the GitHub App Bitbucket Install the Bitbucket App

Step 2) Pull request workflows

Within your organization, you'll have pull request workflows.

A pull request will use a workflow when it matches the given conditions.

Pull request workflows

By default, you will start with one workflow that matches all pull requests and has these steps:

  1. Pre-review - "draft" pull requests will be held here until they're ready for review
  2. In review - by default, all pull requests will require a basic human code review
  3. Ready to merge - the final phase, where pull requests are ready to merge and the GitHub status is "success"

In the PullApprove UI, you'll be able to visualize where pull requests fall and create new workflows to "bucket" them into different processes.

Pull request workflow

Step 3) Review teams

You'll notice that the "In review" phase has a requirement that says teams.all_approved. This is where the "human review" requirement gets tied in.

Pull request organization dashboard

Review teams are a first-class concept in PullApprove. Each team has conditions for which PRs they're assigned to, and approval requirements.

Because each team can have their own requirements, you can set up a more fine-grained review process than simply "require X approvals".

To start, you'll be given a generic "Code review" team with yourself as the only member.

As you add more teams to your process, you can be more specific about requesting their review in parallel or in sequence depending on how you use them in workflows.

Step 4) Enable the full GitHub integration

When you're ready to see PullApprove as a GitHub commit status, you can exit read-only mode via your organization settings.

PullApprove will start sending commit statuses, review requests, and comments back to GitHub. The status will be "pending" until a PR makes it to the final "Ready to merge" phase of a workflow.

PullApprove code review GitHub commit status

You will most likely want to make pullapprove4 a required commit status in your GitHub protected branch settings.

PullApprove required commit status in GitHub protected branch settings

Want help?

If you have any questions or want suggestions on how to get started, feel free to reach out.

We regularly help organizations get set up and get a feel for how things can work. Like any flexible system, there are multiple solutions to most problems -- we can help you find the best one for your team.