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 local Git configuration

3. Adjust notification settings

Take a look at your notification settings. In particular, it’s suggested that you turn off Automatically watch repositories. You may also want to take a look at tips for filtering GitHub notifications in email.

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 TTS. We 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.
  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. In short, that means we are no longer maintaining them, including keeping dependencies up-to-date. No approval is needed to 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.

Creating a new GitHub organization

Create an issue and follow the steps.

Actions

GitHub Actions can be used for continuous integration/deployment on public repositories, but is not currently available for private repositories in (most of) our GitHub organizations for billing reasons.

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
@cloud-gov 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