Log in to v4

Getting started

Learn how to set up PullApprove for your organization.

Pull request organization dashboard

Step 1) Install the app

PullApprove v4 is a GitHub App that interacts with the GitHub API, giving you new tools to manage pull requests and code reviews across your organization.

Bitbucket installation steps are here.

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

Selecting repos You'll be given the option of installing PullApprove on "all repositories" or selecting them individually. You can change this later, so feel free to choose a couple of specific repos to see how it works.

Step 2) Pull request workflows

Within your organization, you will have pull request workflows.

Workflows will often incorporate human code review, but they can also be used to define other requirements for pull requests, and walk people through the process of getting their PR merged.

Pull request workflows

Each workflow has a set of conditions that determine which pull requests it applies to (ex. "dependencies" in pull.labels). A PR will use the first workflow that it matches.

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"

The bulk of your work in PullApprove will be designing workflows and review teams that match how your organization wants to work. 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, and can define their own members, assignment conditions, 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

Next steps

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