GitHub at Google
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@.
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.
GitHub has three independent email settings for each user: the primary email address (used when creating commits through the GitHub web interface), the profile email address (shown on your profile), and the notification email address (where emails related to your account get sent). You can 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.
WARNING: 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.
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 relevant product or Developer Relations team, who may have additional guidelines or expectations for projects housed there.
WARNING: 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.
Examples of projects that may be appropriate to release in a personal GitHub account include:
- Purely personal projects that have nothing to do with your job
- Slides or sample code for a talk at a non-Google event. Slides and samples for talks at Google-hosted events (I/O, Next, etc) must be hosted in a Google org.
- Unofficial, experimental samples or demos
For sample code, if it is linked to from official docs or blogs, it belongs in an official Google org (go/github/orgs), not in your personal account. Google codelabs, workshops, and their supporting code all belong in an official Google organization. You may be asked to move a project from your personal account into a Google organization if its scope or use significantly changes.
To release into your personal account, follow go/releasing as usual and specify an appropriate GitHub URL in your launch entry. Once your launch to a personal GitHub repo has been approved, you may create additional repositories and organizations to house the project without proceeding through the go/releasing or go/new-github-org processes, but they must not have any Google affiliation or branding.
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.
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).
Open source repositories don’t necessarily stay under active development forever. If you’re thinking about making your repository read only or deleting it, you should instead archive it.
Follow these steps to archive your repository:
- Update the
READMEto indicate to users that the repository is no longer being maintained
- Archive the repository using GitHub’s archive feature
- (Optional) Transfer the repository to googlearchive if you want to keep your organization uncluttered. This can be done at go/github/archive, and will also archive the repository using GitHub’s archiving feature if you didn’t already do so in the previous step.
Using GitHub’s archiving feature means that all aspects of the repository will become read-only, including code, pull requests, issues, wiki, and more. Please read GitHub’s documentation on archiving repositories before archiving a repository.
We maintain a dedicated organization for archived Google repositories and you can request that your repository be transferred to it. Once it has been transferred, you will no longer be able to make modifications to the repository, and will not have permissions to do so. To request the transfer, please see the instructions at go/github-docs/transfer.
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 security assessment (go/vsa).
If the service doesn’t require commit access (
scope), then it’s generally fine to use. Granting read/write access for repo
write:repo_hook scope) and commit status (
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.
Travis began supporting open source projects on travis-ci.com through their new GitHub App. This should not be used since travis-ci.com requires write permission to repos when signing in. Until the required permissions are reduced, use travis-ci.org.
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. Granting Google Container Registry access to a GitHub repository is also fine.
How do I set up and use 2FA with GitHub?
Setting up 2FA with GitHub is straightforward. Visit your security settings and initiate the process. It is highly recommended that you use an app (Authenticator) instead of SMS to provide your second factor. Download and store your recovery codes.
Once you’ve configured the app, you will be prompted for the code that the app generates when you log into GitHub.
As mentioned above, you can also use your security key(s) with GitHub. To
configure them, visit the
2FA configuration page,
and scroll down to the security keys section. Click the
register new device
button and follow the prompts. Now, when you are prompted for your second factor
and have access to your security key, you may use it in place of a code.
Providing your password will no longer work to authenticate you to GitHub on the
command line. Instead, you will need to provide a
personal access token. Visit
your settings to create and configure your
access token. When you are prompted to enter your password on the CLI, enter
this personal access token instead. You should have to do this only when you a)
delete your access token, or b) set up a new computer.
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:
- Login to https://cla.developers.google.com/ with your personal Google account and sign an individual CLA.
- 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.
- 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.
I’ve been removed from a Google-managed organization. How do I get my access back?
If you’ve received a notification saying that you have been removed from github.com/google or another Google-managed organization, your GitHub account likely fell out of compliance with that organization’s security policies. In this case, do not request an invitation to the organization using go/github.
If you’ve been removed from github.com/google: You may use the self-service option at go/github to request an invitation to the organization.
If you’ve been removed from another Google-managed organization: Reach out to the primary contact listed for the organization at go/github/orgs and request for your access to be reinstated. You may want to specify that they need to select the “invite and reinstate” option and not the “start fresh” option when reinstating you.
I’ve lost access to my GitHub account! What do I do?
If you’ve lost access to your account, please contact emailremoved@.
However, if you’ve lost your password, second factor, and backup codes for your GitHub account, GitHub will likely not be able to help you regain access to your account.
IMPORTANT: We do not have the ability to reset your access to your GitHub account. Please store your backup codes in a safe location.
If you cannot regain access, you may create and register a new GitHub account.
Can I unarchive a repository?
If you’ve archived a repository by moving it into Google Archive, send an email to emailremoved@ asking for it to be moved to a different organization (make sure that the organization administrator is supportive of this move).
If you’ve archived a repository by using GitHub’s archiving functionality, you may unarchive it by following GitHub’s instructions.
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.