Project:Overlays/Overlays guide

Basic rules
The Gentoo Overlays project members maintain the global repository list that powers layman, overlays.gentoo.org and many more Gentoo-oriented services. If you are looking to have your repository listed there, we are here to help.

There are a few rules that must be met by all repositories on the list. Those are:
 * 1) The repository must be publicly accessible through one of the protocols/VCS-es supported by layman. For best portability, git+https:// is recommended.
 * 2) The repository must meet the minimal QA standards: have a valid and unique repository name (in profiles/repo_name, layout.conf is not portable), and have a valid masters= entry in metadata/layout.conf).
 * 3) The repository owner must have a Gentoo Bugzilla account. Bugzilla will be used for all official communications regarding the repository.
 * 4) The repository should be maintained with best effort not to cause issues to users using it. We reserve the right to remove repositories that are reported to pose serious threat to our users.

The repositories can be hosted on your own infrastructure, any public hosting service, or we can host it on git.gentoo.org for you (git only). In the latter case, we also support automatically populating external mirrors of the repository (e.g. on GitHub).

Requesting adding repository hosted elsewhere (the new way)
The new recommended method of adding repositories is to provide pull requests on api.gentoo.org repository, or patches to it.

(Fork and) clone the repository:

Then add your repository to by copying and altering the appropriate template. Remember to update all the URLs, and set the owner to your Gentoo Bugzilla e-mail address (we will be verifying that!). Afterwards, verify that the XML is correct, and commit the change, prefixing the commit message with repositories: keyword.

If you have a bug open, please include #nnnnnn in the commit message. Having a bug open is recommended since it allows us to clearly verify that you are providing the correct e-mail address.

Afterwards, either open a pull request or generate a git patch and attach it to the bug.

Requesting adding repository hosted elsewhere (the old way)
If your repository is already hosted somewhere, please create a bug in Gentoo Infra product, Gentoo Overlays component and provide the following information:


 * 1) requested repository name (must be equal to one in profiles/repo_name, filling it is just a confirmation),
 * 2) short description,
 * 3) homepage URL,
 * 4) repository owners,
 * 5) repository type and URLs,
 * 6) repository commit feed URLs (if any).

Alternatively, you can provide a repositories.xml-format file for your repository and we will copy the information from it.

Note that if you are not the repository owner, you will have to obtain his explicit permission to have the repository added. He will also have to meet the Bugzilla account requirement.

Requesting hosting for a repository
If you would like us to host the repository for you, please create a bug in Gentoo Infra product, Gentoo Overlays component and provide the following information:


 * 1) requested repository name in repo/user/... namespace (the URL will be git.gentoo.org/repo/user/...),
 * 2) short description,
 * 3) external homepage URL if you are planning to use one,
 * 4) your public SSH key if you have not provided one for git.gentoo.org before,
 * 5) a list of other people (and their public SSH keys, if appropriate) who should have write or admin access,
 * 6) request to add external mirroring if that's desired.

This bug will serve both the purpose of creating the git repository and adding it to the list.

Please note that you will be required to accept the following terms of service:

-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- Use of this service is  limited to overlays containing ebuilds and supporting  files  (e.g.  init.d  scripts,  configuration  files, patches,  but not distfiles)  and must follow  the same guidelines as apply to the gentoo-x86 tree of Gentoo. Any or all uses of this service and all files on this service may be  intercepted,  monitored, recorded,  copied,  audited, inspected, and disclosed to authorized site personnel, as well as authorized officials of federal law  enforcement agencies, both domestic and foreign. By using this service,  the user consents to such interception, monitoring, recording, copying, auditing, inspection, and  disclosure  at  the discretion  of  authorized site  personnel. Use of this  service constitutes consent to security monitoring and testing. All activity is logged with  your host name  and IP address. Unauthorized or improper use of this service  may result in civil and criminal penalties. By continuing to use  this service  you indicate your awareness of and consent to these terms and conditions of use. -- Gentoo Linux Infrastructure Admins CEASE USE IMMEDIATELY, if you do not agree to the conditions stated in this warning. ******************* -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --

Requesting automatically mirroring git.g.o repo on GitHub / any external hosting
We support automatically mirroring your git.g.o repository to any number of external git hostings, including GitHub as well as your private git servers (via SSH). The mirroring is done using server-side git hooks, so all changes are propagated immediately to all external mirrors.

For mirroring to work, you need to allow our SSH deployment key push access to the repository. Depending on the hosting used:
 * if it's GitHub, you need to add gentoo-bot user to contributors of your repository,
 * otherwise, you need to add the following deployment key:

Afterwards, open a bug requesting mirroring. When done, push to git.g.o to test the mirror updates.

Testing access to git.gentoo.org repositories
If you have problems accessing git.gentoo.org hosted repositories, please start by typing in:

This should result in gitolite status message stating your e-mail address and ACLs for all repositories. If you get a permission denied error instead, this means that your current SSH key is not registered in gitolite. Please also take a look at debugging SSH key issues.

If you see an incorrect e-mail address, and you have used a different e-mail address in the past, it is possible that both are registered with different SSH keys. Please contact Overlays team to combine your keys to a single address.

If your e-mail address is correct but you see no write access ('W') for a repository you should have one, then please contact the repository owner or the Overlays team, if you are the owner.

If the status indicates that you have write access, then please verify that you are using correct git URI. For write access, you need to use git over SSH:

Debugging SSH key issues
A common cause of permission denied issues is that SSH is not using the correct SSH key.

If you are not using ssh-agent (or gpg-agent with SSH, or gnome-keyring with SSH), load your key first:

In order to obtain your current public SSH key, please type:

In order to confirm that the public key matches the secret key, please compare:

and:

ssh-add will print the fingerprint of the active SSH key while ssh-keygen will print the fingerprint of specified file (it can be either private or public key file). A different fingerprints mean that different keys are used.

If you have ~/.ssh/id_*.pub files, it's a good idea to check that they match the secret key. If any of them has fingerprint different from the secret key file, please remove it since it will confuse SSH and prevent it from using correct private key. Afterwards, you can use ssh-add -L syntax mentioned above to regenerate the public key.

Reporting bugs on repositories
If you would like to report a bug regarding a third-party repository or a package in it, you can either use the repository-specific bugtracker (if any) or the Gentoo Bugzilla. If the request requires explicit action from Gentoo Overlays project members (e.g. removing the repository), it has to be carried via Gentoo Bugzilla.

When reporting bugs on packages in third-party repositories in Gentoo Bugzilla, please remember to explicitly mention from which repository the package comes from. This is usually done using ::repository-name notation (alike Portage). This will ensure that the bug is properly assigned to the repository owner, rather than the maintainer of respective package in Gentoo.