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.
GSA IT has staff that manage GSA’s GitHub org. See more information about that in the GSA GitHub documentation.
GitHub is a web application, so 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.
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.
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 or GSA organization
18F team members: After you’ve completed the above steps, hop into #admins-github on Slack and post the following: “I’ve enabled two-factor authentication – please add me (
https://github.com/username) to https://github.com/orgs/18F/teams/18f-staff/members on GitHub.” An admin will verify compliance and add you, after which you’ll need to accept their invite by going here.
OPP team members: Email firstname.lastname@example.org the following: “Please add me (
https://github.com/username) to https://github.com/GSA”. An admin will verify compliance and add you, after which you’ll to need accept their invite by going here.
Members of OPP needing access to the 18F GitHub org should hop into #admins-github on Slack and post the following: “I’ve enabled two-factor authentication – please add me (
https://github.com/username) to https://github.com/orgs/18F/teams/opp/members on GitHub.” An admin will verify compliance and add you, after which you’ll need to accept their invite by going here.
- Anyone else in TTS After you’ve completed the above steps, hop into #admins-github on Slack and post the following: “I’ve enabled two-factor authentication – please add me (
https://github.com/username) to https://github.com/orgs/18F/teams/tts-gsa-partners/teams on GitHub - I work at (
PIF/COE/Ops/TTS Office of Acqusition).” An admin will verify compliance and 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.
Abide by the TTS Code of Conduct. If you see anyone violating our Code of Conduct, see the reporting section.
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. 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 an 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.
You do not need approval to archive a repository. As discussed in the 18F open source policy, feel free to archive a repository (or ask #admins-github if you don’t have permissions to do so) to deprecate it. Here is a script to do so en masse. Note that archiving a repository is not the same as deleting a repository.
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.
You do not need approval to transfer a repository. In some cases, it may make sense to transfer a repository to a client. The person performing the transfer will need to be a member of both organizations. After transferring the repository to the client’s organization, create a fork of it in the 18F organization.
The 18F Open Source Style Guide covers conventions and best practices.
Git and GitHub 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.
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.
Confusingly, no one should be an “outside collaborator” in GitHub parlance. Instead, we should manage repo access exclusively via teams.
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 first three setup steps.
- They will need to confirm they’ve done this before you continue.
- They will also need to add an e-mail address to the GitHub profile so we can contact them later when doing clean-up in our org.
- Do not ask the admins to add the collaborator to the 18F or OPP teams as detailed in step 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. You only need to set a
parent teamfor your new team if you need your team to inherit existing permissions from an existing team (for example, if this team should automatically have access to a base set of repos). If your new team is for external collaborators, you will generally not want to add a parent team.
- 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 to the team.
- 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 team can be deleted and access removed.
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.
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.
In GitHub parlance, where repos all have admins, org-wide administrators are called “owners.”
- When you take care of an ask, give it a :check: reaction in Slack. If you have questions about an ask, please start a thread so that the channel stays clean.
- Whenever possible, owners should push decisions as to be as close as possible to those most affected - like whoever owns or last worked on a repo.
- If you aren’t sure about the answer to something, its always better to check with someone else instead of guessing.
- If you aren’t helping out as an owner, please give up your permissions to help minimize our risk.
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.