pra - The Pull-Request Aggregator

pra is a command line tool designed to allow developers to see the current state of open pull-requests across multiple services. Currently, it supports the following services:

• GitHub
• Stash

You can easily install pra with the following command:

$ gem install pra

The configuration location has moved from ~/.pra.json to ~/.pra/config.json. The current version of pra reads from both locations but it is preferred to move your configuration file to the .pra folder. This folder will automatically be created, if it does not exist, for logging purposes when pra starts.

pra requires one configuration, ~/.pra/config.json, to exist in your home directory. The following is an example config that can be used as a starter. Note: You will need to replace your.username, your.password, your.stash.server, and the repositories and organizations sections of each of the pull sources.

{
  "pull_sources": [
    {
      "type": "stash",
      "config": {
        "protocol": "https",
        "host": "your.stash.server",
        "username": "your.username",
        "password": "your.password",
        "repositories": [
          { "project_slug": "CAP", "repository_slug": "capture_api" },
          { "user_slug": "bob.villa", "repository_slug": "personal_notes" },
          { "project_slug": "RELENG", "repository_slug": "ramboo" }
        ]
      }
    },
    {
      "type": "github",
      "config": {
        "protocol": "https",
        "host": "api.github.com",
        "username": "your.username",
        "password": "your.password",
        "repositories": [
          { "owner": "reachlocal", "repository": "snapdragon" },
          { "owner": "brewster", "repository": "cequel" }
        ],
        "organizations": [
          { "name": "codebreakdown", "exclude": ["snapdragon"]}
        ]
      }
    }
  ],
  "assignee_blacklist": [
    "IPT-Capture",
    "IPT-Core Services"
  ],
  "refresh_interval": 300,
  "log_level": "info"
}

I suggest copying and pasting the above starter file into your ~/.pra/config.json file to get you started. Then simply replace the appropriate fields and the repositories and organizations sections for all the pull sources with the repository information for the repositories you want to watch for open pull requests.

You may have noticed that the above example shows two repository objects in its Stash repositories array.

1. Project Scoped Repository - { "project_slug": "CAP", "repository_slug": "capture_api" },
2. User Scoped Repository - { "user_slug": "bob.villa", "repository_slug": "personal_notes" },

This is because Stash has both the concept of repsositories that are organized under Projects and repositories that are organized under Users. Therefore, you would want to use the User Scoped Repository in scenarios where the repository is housed under a user and the Project Scoped Repository in scenarios where the repository is housed under a project.

Reduces noise to more easily determine which pull requests are unassigned. Names added will not appear in the assignee column.

Instead of listing each repository, an organization can be provided and all pull requests open for projects in that organization will be listed. To exclude any unwanted projects, add the repository name to the exclude array for that organization.

Sadly, at the moment pra doesn't support GitHub's Multi-Factor Authentication. There is a ticket for this ( #5 ).

It is also lacking support for GitHub's OAuth mechanism. There is a ticket for this ( #6 ).

The HTTP Basic Auth will work as long as you don't have multi-factor authentication enabled for your account.

Personal Access Token authentication is currently supported and this is the recommended authentication mechanism to use right now. It is the only authentication mechanism you can use at the moment if you have multi-factor authentication enabled.

Simply go to your GitHub Account Settings, select Applications, click the Create new token button in the Personal Access Token section. Give it the name "Pra" and submit. This will generate your personal access token. Then simply put your personal access token in the ~/.pra/config.json as your GitHub username and "x-oauth-basic" as your GitHub password.

Once you have configured pra as described above you can launch it by simply running the following command:

pra

Once it launches, it will use the information provided in the ~/.pra/config.json configuration file to fetch all the open pull requests and display them. Once, the pull requests are displayed you can perform any of the following actions.

To move the selection up simply press either the k or the up arrow key.

To move the selection down simply press either the j or down arrow key.

If you would like to open the currently selected pull request in your default browser you can press either the o or enter key.

To force a refresh press the r key.

To move between pages press n to go to the next page, and p to go to the previous page.

To filter the list of you pull requests you can press / and start typing. The list will start filtering as you type. Once you have completed typing your filter you can press Return and go back to interacting with the list of pull requests. Refreshing by pressing r will clear out the filter.

If you decide you have had enough and want to exit pra press the q key.

If you would like to contribute to the pra project. You can do so in the following areas:

As with all software I am sure pra will have some bugs. I would very much appreciate any contributions of bug reports. These can be reported on the issues page of the project.

The current state of pra is just the MVP (minimum viable product). This means there is always room for growth. If you would like to contribute your thoughts on features that you would like pra to have you can submit them on the issues page of the project.

If you would like to contribute documentation improvements you should follow the directions below.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

If you want to contribute by writing code for pra you need to know the following:

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

We use RVM or rbenv with pra to encapsulate the dependency gems in our development environments. Therefore, we have the .ruby-version file in the repository which define the current version of ruby that we are developing with.

You should have RVM or rbenv installed of course and when you change into the project root directory it should switch to the proper ruby version if you have it intsalled via RVM or rbenv.

If the proper version of ruby is NOT installed via RVM or rbenv you should first install that version of ruby and then change out of the project root directory, then change back into it and verify that you are in the proper ruby version.

We use Bundler to manage the development dependencies of pra. Once you are setup with RVM or rbenv as described above you should be able to install all the development dependencies using the following command:

bundle

I developed pra using the TDD methodology with RSpec as the testing tool of choice. Therefore, if you are going to contribute code to pra please TDD your code changes using RSpec. If you do not submit your changes with test coverage your request will likely be denied requesting you add appropriate test coverage.

If you have setup RVM or rbenv as described above and installed the development dependencies using Bundler as described above you should be able to run the development version of pra by running the following command:

bundle exec ./bin/pra

Note: The above of course assumes that you have a ~/.pra.json file already configured.