Learn how to set up PullApprove for your organization.
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.
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.
Selecting reposYou'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.
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:
- Pre-review - "draft" pull requests will be held here until they're ready for review
- In review - by default, all pull requests will require a basic human code review
- 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.
Step 3) Review teams
You'll notice that the "In review" phase has a requirement that says
This is where the "human review" requirement gets tied in.
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.
You will most likely want to make
pullapprove4 a required commit status in your GitHub protected branch settings.
If you have any questions or want suggestions on how to get started, feel free to reach out.