- 1 Requesting addition of new repositories (overlays)
- 2 Debugging common issues
- 3 Reporting bugs on repositories
Requesting addition of new repositories (overlays)
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:
- The repository must be publicly accessible through one of the protocols/VCS-es supported by layman. For best portability, git+https:// is recommended.
- 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).
- The repository owner must have a Gentoo Bugzilla account. Bugzilla will be used for all official communications regarding the repository.
- 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:
git clone email@example.com:myuser/api-gentoo-org.git
Then add your repository to files/overlays/repositories.xml 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.
xmllint --noout --schema $(portageq get_repo_path / gentoo)/metadata/xml-schema/repositories.xsd repositories.xml
git commit repositories.xml -m 'repositories: Add foo-overlay'
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)
Please note that this method is discouraged. Pull requests are handled faster.
If your repository is already hosted somewhere, please create a bug in Gentoo Infra product, Gentoo Overlays component and provide the following information:
- requested repository name (must be equal to one in profiles/repo_name, filling it is just a confirmation),
- short description,
- homepage URL,
- repository owners,
- repository type and URLs,
- repository commit feed URLs (if any).
Alternatively, you can provide a repositories.xml - formatted 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
Please note that git.gentoo.org hosting does not provide any administrative interface. All requests regarding the repositories are manually handled by project members, therefore delays may occur.
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:
- requested repository name in repo/user/... namespace (the URL will be git.gentoo.org/repo/user/...),
- short description,
- external homepage URL if you are planning to use one,
- your public SSH key if you have not provided one for git.gentoo.org before,
- a list of other people (and their public SSH keys, if appropriate) who should have write or admin access,
- 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 hosting, 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.
Automatic mirroring works one way only and is destructive. All branches and tags from git.g.o will be force pushed to the mirrors, and all remaining branches and tags will be pruned. All commits that get pushed to GitHub/external hosting and not to git.g.o are automatically discarded on next git.g.o push.
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:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCoJNoPdn0LtNjscz50rlJms7RSZF95wfwhz+3pgKQ3z9hr8u3wXcVngl0G17D1VYZJonrMQGDBbpAQyYVI6bu7HqUg7DmLvoTqnh9nfH5vrXcVmYKTWDWV2fANF8U2NX0VpD4VIS/aB/5uNscUtZ1ApkpxgW+j+qO/kthQZn97ILAsQ4KsoGF25+cXMkpwDxsemOKjE+mKeA0hzHiyERxViClwxvKNx4s65CWFqUBlEKTG1QaCAoNpnowYHcqWFzaH3wlEzwfDM1orvpZ3fFma4U9F32x+HuyfkbqY7YchvKQj8boqapbqy7fJn4FUtXa/XNC6JX43xrxHMaxqF+tV gentoo mirroring
Afterwards, open a bug requesting mirroring. When done, push to git.g.o to test the mirror updates.
Debugging common issues
Testing access to git.gentoo.org repositories
If you have problems accessing git.gentoo.org hosted repositories, please start by typing in:
ssh firstname.lastname@example.org info
hello email@example.com, this is git@oystercatcher running gitolite3 gitolite-gentoo-9999-gentoo on git 2.8.2 R W data/api R W data/dtd R W data/gentoo-changelogs R W data/gentoo-news R data/glsa ... Please see http://wiki.gentoo.org/wiki/Gitolite for more help
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:
git clone firstname.lastname@example.org:repo/path.git
Debugging SSH key issues
OpenSSH 7.0 no longer allows using DSA keys by default. If you are using DSA keys, take a look at the OpenSSH 7.0 news item.
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:
4096 SHA256:RNizcaEs7yUE3nMio4W/OOZ3fE68foNv5nUA9ubz32M (none) (RSA)
ssh-keygen -l -f /path/to/id_*
4096 SHA256:RNizcaEs7yUE3nMio4W/OOZ3fE68foNv5nUA9ubz32M (none) (RSA)
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.