Project:Overlays/Overlays guide

From Gentoo Wiki
Jump to:navigation Jump to:search

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

Requesting addition of new repositories (overlays)

Basic rules

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 the addition of an overlay via Github PRs

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:

user $git clone git@github.com:myuser/api-gentoo-org.git

Then add the repository to the files/overlays/repositories.xml file 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 everything is correct using make check, and commit the change, prefixing the commit message with repositories: keyword.

Note that make check requires dev-libs/libxml2 to be installed.

user $make check
user $git commit files/overlay/repositories.xml -m 'repositories: add foo-overlay'
user $git push

When closing a bug from bugs.g.o, please include the bug number listed in the format of #nnnnnn in the commit message.

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

Requesting the addition of an overlay via bugs.gentoo.org

Note
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:

  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 - 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

Warning
Gentoo-hosted repository requests are not handled timely at the moment. You may wish to prefer hosting your repository on one of the public hosting services instead.
Note
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:

  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 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.

Warning
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:
FILE id_rsa.pubGentoo repository mirroring public 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:

user $ssh git@git.gentoo.org info
hello foo@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 https:/<nowiki/>/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:

user $git clone git@git.gentoo.org:repo/path.git

Debugging SSH key issues

Note
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:

user $ssh-add

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

user $ssh-add -L
ssh-rsa AAAA...

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

user $ssh-add -l
4096 SHA256:RNizcaEs7yUE3nMio4W/OOZ3fE68foNv5nUA9ubz32M (none) (RSA)

and:

user $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.

Retrieved from "https://wiki.gentoo.org/index.php?title=Project:Overlays/Overlays_guide&oldid=1293555"