GitHub Pull Requests

This article explains how to contribute to Gentoo by creating pull requests on GitHub.



How to make a pull request
Making a pull request is explained at length in the various how-tos put together by the GitHub folks, here are two must-read how-tos:

 Fork the Gentoo repository Using pull requests 

Variant a: User configures a local repository
Clone the github mirror of the Gentoo repository under the remote name "upstream" into the directory (substitute  with the directory of choice):

Step into the new directory, then view the 'remote' settings

Fork the Gentoo repository on GitHub

Add it under the remote name "github" to your local repository.

Verify the repository's remote settings

Variant b: Using the git repository as the ::gentoo repository
Add the following to the file:

Add the following, substitute $DEV_USER_NAME with your username as appropriate in the script below.

Then sync the repository.

Fork the Gentoo repository on GitHub

Add it under the remote name "github" to your local repository.

Repository's user configuration
Configure git to use the target key for code signing and to properly sign-off all your commits (a more detailed description of how to create the signingkey is given in the next section):

Add helpful optional settings:

Verify the settings:

GPG configuration
Add the following to :

Now to generate the key:


 * Select the algorithm.
 * Set the key size.
 * Specify how long the key should be valid (No more then 5 years).
 * Confirm the information is correct.
 * Set your name.
 * Set your passphrase, and confirm it.
 * It might take some time if you've chosen a high bit length key.

Retrieve your GPG public keyID via the following command:

The key id is the portion after the / on the line beginning with pub as shown in bold below. If you have more than one key with the specified UID you will need to select the correct key yourself from the list of returned keys. pub  rsa4096/0x000000000000000

Upload your key to the keyserver.

Note that under some circumstances it may be necessary to provide a keyID to the '--send-key' flag. For example

Repoman configuration
In order to properly sign-off all your commits add the following to, see GLEP-76 for more information.

Step 2: User changes a package
Say you are making changes to package. Create a local branch with the changes:

Make the changes and make sure to run to check for basic errors:

Then commit the changes, preferably using.

If the commit is to close or comment bugs on Bugzilla, these should be mentioned in the commit message as suggested by GLEP66. supports this through the  and   options.

Step 3: User makes a pull request
Now that the changes have been made and the local branch updated, it is time to send it off to GitHub and make a PR (Pull Request) for the Gentoo Developers.

Start by pushing the branch with the changes to your GitHub repository:

Then create a pull request from your GitHub repository's local branch to the Gentoo repository's master branch. When the changes have been merged, you may delete the local repository's branch with:

Variant b: By means of the PRam tool
The PRam tool helps developers to merge pull requests.

To merge GitHub PR #12345, enter your local gentoo.git checkout and run:

See also: https://github.com/mgorny/pram

Links to bug report(s)
A bot automatically picks up bug reports if the link(s) to the bug in question appear(s) in the body of the commit message. The bot then writes a message in the bug report and/or closes it. That way, other users quickly get to know a patch or a fix has landed in the tree.

This feature helps Gentoo developers save time as they don't have to switch back and forth between Bugzilla, GitHub, and their terminal to figure out which bug reports may be closed.

How does it work?
The bot can parse two types of header:

Bug: https://bugs.gentoo.org/123456

will automatically write a message in the bug report without closing it.

Closes: https://bugs.gentoo.org/123456

will automatically write a message in the bug report, change the status of the bug report to RESOLVED and the resolution to FIXED.

If the commit involves several bug reports, they can be mentioned and stack the links. The bot will write a message in each bug report:

Bug: https://bugs.gentoo.org/123456 Bug: https://bugs.gentoo.org/456789 Bug: https://bugs.gentoo.org/101010

It also works with the  header:

Closes: https://bugs.gentoo.org/123456 Closes: https://bugs.gentoo.org/456789 Closes: https://bugs.gentoo.org/101010

Feel free to add as much information as possible: upstream forums, mailing lists, discussions, links to changelogs, etc. The bot won't post messages all over the place though, but these useful information will appear in the ChangeLog file of the ebuild.

gentoo-repo-qa-bot is engaging in a conversation with me in the PR. I don't understand.


We have set up an automated CI system which performs various QA checks when a PR is filed. These checks may result in two possible outcomes displayed next to your PR:

 a green check-mark meaning everything's fine and your PR isn't offending the tree. </i>a red cross meaning something is up and your PR needs fixing.</li> </ul>

Our QA bot is chatty when a red cross shows up. At this point, it might point out two types of error:

</i> Issues persisted from underlying repository state:

This error means that unfortunately, you forked the tree whilst it was in a very unstable state (meaning broken). Indeed, every now and then developers break the tree and, tough luck, it turns out you forked the tree into your GitHub profile or synced it up at this very moment. But no big deal as there's nothing for you to do.

</i> New issues:

This error is a bit more serious and means your PR isn't complying with our QA standards. Usually, one or more link(s) are displayed right below for you to visualize in a browser what it's all about. Go ahead, take a look and fix those errors. Push again and wait for the bot to go over your PR again (every 30 minutes) until a green check-mark appears.

Possible issues with signing
It's possible that a message comes up like

In such a case the GPG_TTY environment variable is to be set. To make sure it is always set, it can be added to the or to :

Setting to a terminal-friendly variant, like  or  might also help with this issue.

The available pinentry variants can be listed with eselect:

Set desired the desired handler with For further information about gpg, please visit to the GnuPG article.

External resources

 * GLEP 63
 * GLEP 66