Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

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.

Setup

GitHub is a web application, and you may be able to do all of your work within the github.com website. Optionally, you may also install the GitHub desktop application.

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:

2. Set up two-factor authentication

Enable two-factor authentication (2FA):

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

All TTS staff should be added here. Ask in #admins-github to “please add me (https://github.com/username) to [team],” which will be one of the following:

An admin will add you, after which you’ll need to accept their invite from the email or by going here.

You may need access to other GitHub organizations, depending on your job. If that applies to you, your team will get you added as part of their onboarding.

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

How-to

Documentation

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:

  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 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.
  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 team for 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.
  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 to the team.
    • 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 team can be deleted and access removed.

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.

Archiving

As discussed in the 18F open source policy, we archive repositories to deprecate them. No approval is needed archive/unarchive a repository. Feel free to do so yourself, or ask #admins-github for help. Note that archiving a repository is not the same as deleting it.

If the repository is published as a package, please also mark it as deprecated.

Tips

For admins

In GitHub parlance, where repos all have admins, org-wide administrators are called “owners.”

Organizations

TTS is heavily involved in the following GitHub organizations:

Organization Government-owned1 TTS-managed2
@18F Y Y
@cloudfoundry-community N N
@digital-analytics-program Y Y
@digitalgov Y Y
@eregs Y N
@federalist-users Y Y
@fedramp Y Y
@fellows-in-innovation Y Y
@fisma-ready N N
@GSA Y N
@opencontrol N N
@project-open-data Y Y, shared with OMB
@presidential-innovation-fellows Y Y
@usagov Y Y
@uswds Y Y

1: TTS staff, contractors, and partners who are offboarding need to be removed from all government-owned GitHub organizations.

2: For the ones that are TTS-managed, get help in #admins-github.

We automate some administration of our repositories - see ghad for more info.

Resources


Still have questions?

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