GitHub

GitHub is a closed-source platform for open-source communities. It allows us to collaborate on documentation and code, both internally and with a broader audience.

Documentation

Setup

Because GitHub is a web application, there’s no installation necessary, but you may find the desktop app useful.

If you don’t have a GitHub account, you must use your work email (rather than your personal email) to sign up, as this helps us with records retention and identification. If you do have a GitHub account, please add your work email to your profile as your primary email, and ensure it is visible on your public GitHub profile.

1. Complete your profile

Include the following:

  • Name: Your first or first and last name.
  • Company: Your government agency. (If you also use GitHub for personal projects, consider specifying “agency (work) + personal projects” to make it clear that some of your GitHub projects may be personal in nature.)
  • Location: Your primary work location (city, state).
  • Photo: A headshot photo, or an image that is unique to you.
  • Email: Your @gsa.gov email address

2. Set up two-factor authentication

Enable two-factor authentication (2FA):

  • Use your work email rather than your personal email for work-related commits. This only applies to people with more than one email address tied to their GitHub account. Note that this is different than setting notifications to go to a specific email address. If you make commits via GitHub’s web interface, it will use your “primary” email address for those commits, so check your email settings before making web commits.

  • 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 with your personal email, or use a tool like karn. If you have both emails in your GitHub settings, they will both be tied to your GitHub account anyway.

3. Turn notifications on

Turn notifications on and adjust the settings as needed. Some people watch every repo; others only watch when they’re mentioned.

You will get a lot of emails when you turn notifications on. To help stem the tide, you can set up a Gmail filter to automatically archive emails from notifications@github.com. However, you probably want to let through those emails that contain your GitHub username or are posted to a repo you’re watching. Since on GitHub, each repo is considered its own mailing list, checking for that identifier is one reliable way to allow these notifications through. For example, if the repo name in GitHub is 18F/calc, the mailing list will be calc.18F.github.com. You can also find this by opening an email from the desired repo, clicking the “more info” arrow in the “To” field, and copying the bracketed address in the “mailing list” field. Adding list:(calc.18F.github.com) to your filter’s exceptions will allow any issues posted to that repo to reach your inbox.

4. Join the 18F organization

After you’ve enabled 2FA and added your government email address to your profile, hop into #admins-github on Slack and post the following: “I’ve enabled two-factor authentication – please add me (@username) to https://github.com/orgs/18F/teams/18f on GitHub.” An admin will add you, after which you’ll need to accept their invite by going here.

5. Make your membership public

Go to the 18F people page. Click where it says private next to your name. Change that to public.

Rules

  • Abide by the 18F Code of Conduct. If you see anyone violating our Code of Conduct, please contact Holly Allen.

  • Do not grant Admin rights to anyone but 18F staff.

  • Do not store sensitive information in GitHub, including environment variables, private configuration data, or sensitive information about the public (including but not limited to PII). In the event that such variables or configuration data is pushed to a GitHub repository accidentally, even momentarily, consider it compromised and revoke or change the credentials immediately. Do not delete the commit itself. Then immediately follow the directions on the incident response handbook page. If you’re unsure how to protect this information, consult with Infrastructure on GitHub or in the #admins-github channel in Slack. Some projects use Citadel to store secrets. Also refer to the 18F Handbook page on sensitive information and guidance on sensitive information in our open source policy.

  • Ask Infrastructure before integrating a service with GitHub or creating private repositories. Many websites offer the option to “Sign in with GitHub” and may further request permission to access your “personal user data.” Providing this level of access can not only share your public or private email address, but it can also grant the ability to access 18F’s private repositories. For this reason, we ask that all organization members refrain from authorizing integrations and request any desired integrations through a Infrastructure issue.

  • Ask Infrastructure before creating private repositories. We pay GitHub for the ability to create private repositories and need to bill clients for repositories created on their behalf. Before you do anything, drop into #admins-github and explain what you’d like to do and why. Be sure to include a link in your repo README to a document that explains why it is private. (See the Exceptions section of the 18F Open Source policy.)

  • You do not need approval to create public repositories.

  • Ask Infrastructure before deleting repositories. As a government team, we can’t delete repositories without Infrastructure first reviewing them for information that they may need to retain/archive (including issues, pull request comments, commit history, and other information). If you want to delete a repository, go to #admins-github and explain what you’d like to do and why, and wait for approval before deleting it. Feel free to clearly mark repositories “DEPRECATED” at any time.

Working with outside collaborators

Giving contractors and federal partners read or write access to your repository is both allowed and encouraged to facilitate the flow of ideas and build a stronger, more decentralized community.

Here’s our current process to address both operational and security concerns:

  1. If the user is a member of the federal government, confirm we have an active inter-agency agreement (IAA) or other legal document authorizing the work.
  2. If the user is a contractor, confirm we have an active and valid contract with them, or their company.
  3. Ask the collaborator(s) to go through the setup steps.
    • They will need to confirm they’ve done this before you continue.
  4. (Ask #admins-github to) create a team whose access we can turn off/on with one button. Separate a staff-only team from a contractor/mixed/collaborator team for a project, and name it something like Project name - Collaborators | Skillset.
  5. In the “Description” of the team, put something reasonable plus a point-of-contact email address for the collaborators.
    • Ideally this is the address of someone senior — someone you can email if issues come up and who can rally the troops.
  6. (Ask #admins-github to) add the members.
    • The 18F GitHub Organization requires 2FA for its members. Users without 2FA cannot be added to the GitHub Organization.
  7. Give the team read/write permissions on the relevant repositories. Admin rights should be limited exclusively to 18F staff.

When the engagement is over, you must let #admins-github know so the access can be removed.

Usage

Git and GitHub are the standard tools for revision control at 18F. Git is an open-source version control system, and GitHub is a closed-source, commercial service that hosts Git repositories and adds extra features to support them, such as pull requests and issue tracking. Although this sounds super technical, these tools are not just for developers hacking code; 18F employees use GitHub to author blog posts, manage documentation, and comment on one another’s work.

In other words, you’ll probably use GitHub a lot at 18F. We recommend you get familiar with the basics. If you’re new to GitHub and feel confused at first, that’s normal. Try a few guides, review our documentation, and ask your teammates for help. GitHub also has a handy document that explains the typical GitHub Workflow.

Process

  • Document your workflow. There are many different ways to use GitHub, and each different team of people at 18F (likely) uses it differently. That said, teams should document their desired git workflow for each project, such as in your repository’s contributing.md file. The 18F-Site team offers a good example with their GitHub wiki. In 18F’s development guide, there are code review questions that your team may want to go over as you think about documentation.

  • Do you fork or do you branch? Git allows you to both “fork” and “branch” repositories to make a place to work on changes before you submit them for integration into the main code. Making a fork creates a copy of the repository in your own GitHub account. Making a branch of the main repository means you’re working in your own little space, but it’s still part of the main repository — which helps keep the project organized, since everyone can easily see what teammates are working on.

Pull requests

18F defaults to using branches, though teams are welcome to decide they prefer using forks instead. Regardless of whether you branch or fork, changes happen via pull requests.

In the process of receiving feedback in a pull request, some individuals on some teams may choose to amend, reorder, or squash commits. This type of “re-writing history” is compliant with the Freedom of Information Act (FOIA) when it occurs on a pull request because git branches are considered a work in progress. These actions are not allowed on the master branch because that is considered the canonical source of information.

Issues

If you want to make a suggestion to an 18F project without making a specific change to its code, such as if you aren’t sure how to fix a problem or want clarification before fixing something, file an issue on that project via GitHub. Try searching the list of open issues before you add one; the error you see might already be on the team’s radar.

Permissions

Teams can give groups of people administrative, write, or read permissions to 18F repositories. Even if you have write access into a repository, we strongly encourage the submission of pull requests for improvements or fixes (see “we prefer branching to forking when we’re working together on 18F projects,” above).

Contractors or external government collaborators should only be added to teams with scoped write permissions to the repositories 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.

Organizations

18F/TTS manages (or is heavily involved with) the following GitHub organizations:

Resources

  • Githug is designed to give you a practical way of learning git. It has a series of levels, each requiring you to use git commands to arrive at a correct answer.

  • This self-paced training provided by GitHub could be helpful to note in these GitHub materials for newcomers as well.

  • Try Git


Still have questions?

Ask in Slack: #git, #admins-github, #dev

GSA IT has staff that manage GSA’s GitHub org. See more information about that in this Slack archive message.