opensource.google.com

Menu

Docs

GitHub at Google

go/github-docs

Because GitHub is a third-party site, we have a few more rules and guidelines concerning its use. These are not meant to discourage you from using or releasing on GitHub. Quite the opposite, they’re to ensure we use the service in an orderly manner. If you need help or have any questions, contact us at emailremoved@.

GitHub accounts

If you have an existing GitHub account, just use that. If you really want to create a new account for work you can, but we generally don’t recommend it. It creates more work for you to keep SSH keys separated, and using your normal GitHub account ensures that your open source contributions are connected to your main GitHub identity, even after you’ve left Google.

All Googlers must register their account at go/github. This allows your coworkers to find you easily on GitHub, and will add you to the Google organization so that you can have the Google badge appear on your GitHub profile. This is also how we ensure that access is revoked when they leave the company.

Add your google.com email address to your GitHub account. You should be using your main work address for any work related commits; adding it to your GitHub account helps ensure that your commits don’t get flagged as needing a CLA. If you have another official email that you use, like golang.org or chromium.org, add that address to your GitHub account. You can also configure GitHub notifications so that they are sent to different email addresses depending on the organization.

Activate two-factor authentication on your GitHub account. GitHub supports the Google Authenticator app as well as your standard-issue security key, so this is easy to setup. Two-factor auth is required for all Googlers who work on open source code for Google. We highly recommend it for personal use as well. However if you really want to, you may maintain two separate accounts for work and personal use.

Whatever you use for two-factor, make sure to generate and save the recovery codes for your account! We do not have the ability to recover your GitHub account if you get locked out.

Add an SSH key to your account to make git much nicer to use on the command line.

Organizations

With few exceptions, open source projects released on GitHub must be housed in one of the official Google organizations – not your personal account. The primary organization for Google is https://github.com/google. Some product areas and larger projects (particularly those with recognizable brands) have separate organizations (go/github/orgs). These organizations are often co-managed by OSPO and the Developer Relations team, who may have additional guidelines or expectations for projects housed there.

Do not create any new organizations for Google projects. If you think one is needed, please see go/new-github-org.

NOTE: Are you an owner for an Organization? Learn about your responsibilities and requirements.

Request a repository

Follow go/releasing to release a new project. Once your Ariane launch is approved, fill out go/github/repo to create the new repo. This will create a new empty repository and give you admin access to it. From there, you can push your code and give your team members access.

You can request a private (hidden) repository to temporarily limit access to just your team. This should generally be used for days or weeks, not months, since there’s a limit on how many private repos the org can have. If you need a long-term private repo, email emailremoved@ to discuss your circumstances. You must still follow the go/releasing process before putting any code on GitHub, even if it’s in a private repository.

WARNING: GitHub Pages are always publicly available, even if their repositories are private. You can run Jekyll locally to preview them offline.

Adding contributors

When a new repository is created through go/github/repo, the Googler who made the request will initially be added as an admin for the repo. They can then add additional contributors directly as collaborators on the repository, or by creating a team. For small single repositories, it’s often easier to just add everyone as a collaborator. If your team has multiple repositories that should be managed as a group, then creating one or more teams may make things easier.

External contributors can be given elevated access to a repository by adding them as collaborators. External contributors should generally never be given Admin access to a Google repo. Additionally, if the contributor is being given write access, they MUST first sign a CLA (go/cla).

Questions and answers

Can I use Travis CI / Jenkins / other third-party service?

Hosted third-party services that require commit access to Google repositories cannot be used without a vendor audit (go/vsa).

If the service doesn’t require commit access (public_repo or repo scope), then it’s generally fine to use. Granting read/write access for repo hooks (write:repo_hook scope) and commit status (repo:status scope) is fine. Note that some services, such as Travis CI, can operate in several different modes depending on how it is configured. These are fine to use provided that they only have read access to our repositories. Some services like Travis will sometimes use deploy keys to access your repository; these are only okay if they are read-only deploy keys.

Code that is completely written and/or controlled by Googlers is also generally fine to use, regardless of access level, however standard security precautions should always be taken (go/external-software-policy). For example, a tool your team wrote to migrate issues or leave comments on pull requests is fine. Similarly, a Jenkins instance running on GCP that is controlled completely by Googlers is fine.

What happens when someone leaves Google?

When a Googler leaves the company, they will be removed from all Google organizations within about 12 hours, removing them from all teams and repositories. From that point forward, they are treated just like any other external contributor, with a CLA (go/cla) being required for any subsequent contributions. They can be re-added as a collaborator with write (but not admin) access, but that is at the discretion of the Google team that is responsible for the repository.

If you know that you, a teammate, or intern will be leaving Google and would like to continue working on a project, you should:

  1. Login to https://cla.developers.google.com/ with your personal Google account and sign an individual CLA.
  2. Talk with your team or manager before you leave and make sure they are okay with you continuing to have access. Note that in many cases you may not need direct write access and can simply continue to submit pull requests.
  3. Once you are removed from the Google organizations (typically within a day of leaving), email your team or manager to have them add you back to the necessary repositories.

If you are the only person that works on the project, and there is no team taking responsibility for it, then your best option is to simply fork the repo into your personal account and continue to maintain it there.

Except as otherwise noted, the content of this page is licensed under CC-BY-4.0 license. Third-party product names and logos may be the trademarks of their respective owners.