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.
Greg Boone gives a brief class on GitHub and the 18F website.
Melody Kramer and Greg Boone co-wrote a guide to using GitHub and the Terminal.
The 18F Open Source Style Guide covers conventions and best practices.
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
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
email@example.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.
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.
- To help you not commit sensitive information to Github, please read about Git Seekrets.
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:
- 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.
- If the user is a contractor, confirm we have an active and valid contract with them, or their company.
- Ask the collaborator(s) to go through the setup steps.
- They will need to confirm they’ve done this before you continue.
- (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.
- 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.
- (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.
- 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.
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.
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.mdfile. 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.
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.
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.
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.
18F/TTS manages (or is heavily involved with) the following GitHub organizations:
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.