└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Using GitHub 2 | 3 | These are the requirements to join our GitHub organization. None are optional, and everyone on staff _must_ have a GitHub account. 4 | 5 | ## Creating and customizing an account 6 | 7 | If you haven't created a GitHub account yet, do so with your government email, which will assist with [records retention](http://government.github.io/best-practices/records-management/). 8 | 9 | If you already have a GitHub account, simply [add your goverment email to your existing account](https://help.github.com/articles/adding-an-email-address-to-your-github-account/). Do not create a new account. You can also set up custom email routing through the [Notifications Center](https://github.com/settings/notifications). Make sure your commits are [associated with your government email address](https://help.github.com/articles/setting-your-email-in-git). 10 | 11 | Note that associating commits with an email address is different from [setting notifications to go to one or another email address](https://help.github.com/articles/configuring-notification-emails-for-organizations/). You also have to change the official commit email address attached to each repo. 12 | 13 | If you’re using your work computer for personal projects on GitHub and want your personal email tied to those commits, you can set your GSA email as part of the global `.gitconfig`, then [override on a repository level](http://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) with your personal email. If you have both emails [in your GitHub settings](https://github.com/settings/emails), though, they will both be tied to your GitHub account. 14 | 15 | Make sure you have [notifications turned on](https://github.com/settings/notifications) and make sure your notifications are set up they way you'd like them. 16 | 17 | ### Setting up an account profile 18 | 19 | #### [Activate 2-factor Authentication](https://github.com/blog/1614-two-factor-authentication) 20 | 21 | Everyone is *required* to use 2-factor authentication (2FA) for their GitHub access. While you're at it, it's a *very, very* good idea to do this for your [email account](http://lifehacker.com/5932700/please-turn-on-two-factor-authentication/all) and [elsewhere](http://lifehacker.com/5938565/heres-everywhere-you-should-enable-two-factor-authentication-right-now/all). GitHub access _will not_ be provided if 2FA is turned off. Also be sure to [save your recovery codes](https://help.github.com/articles/downloading-your-two-factor-authentication-recovery-codes/) in case you lose access to 2FA. 22 | 23 | #### [Add your information to your account](https://github.com/settings/profile) 24 | 25 | This makes it easier for your team to know who you are, but most of all, it helps a lot with autocomplete! 26 | 27 | A complete [public profile](https://github.com/settings/profile) includes: 28 | 29 | - **Name:** Your first or first and last name. 30 | - **Company:** Your government agency. 31 | - **Location:** Your primary work location (City, State). 32 | - **Email:** A [valid email address](https://help.github.com/articles/verifying-your-email-address/). 33 | 34 | #### [Add a profile avatar](https://help.github.com/articles/how-do-i-set-up-my-profile-picture/) 35 | 36 | This is a courtesy that makes team projects all the more social and fun. It only takes a second but your teammates will _really_ appreciate it. We don't require that it be an actual headshot, but please make it a unique avatar. 37 | 38 | It only takes a moment to go to [your settings page](https://github.com/settings/profile) and upload a picture. 39 | 40 | #### Make your membership public 41 | 42 | Go to the organization's [team page](https://github.com/orgs/18F/people) and click **Make Public**. 43 | 44 | ## Collaborators 45 | 46 | We welcome people from outside our organization as collaborators! Our Federal partners, their current contractors, and staff of other government entities (state, county, city), are welcome to join as long as they comply with the standards here. Anyone else needs to be evaluated on a case by case basis with the DevOps team. 47 | 48 | ## Teams 49 | 50 | Teams can give you [`administrative`, `write`, or `read` permissions](https://help.github.com/articles/permission-levels-for-an-organization-repository/). Even if you have `write` access into a repository, we _strongly_ encourage the submission of pull requests for improvements or fixes. 51 | 52 | Contractors or external government collaborators should only be added to teams with scoped `write` permissions to the respositories they're working on. They should *never* have `administrative` level rights. In order to separate out these permissions, create a team in the format of `projectname-admins` for government staff if necessary. 53 | 54 | ## Additional resources 55 | 56 | * [The GitHub Government Community](https://github.com/government/welcome#readme) 57 | * [GitHub Government Best Practices](http://government.github.io/best-practices/) 58 | * [Amendment to GitHub Terms of Service Applicable to U.S. Federal Government Users](https://help.github.com/articles/amendment-to-github-terms-of-service-applicable-to-u-s-federal-government-users/) 59 | --------------------------------------------------------------------------------