GitHub

GitHub is a closed-source platform for , external,open-source communities. It allows us to collaborate on documentation and code, both internally and with a broader audience. If you're not familiar with how to use GitHub, see the introduction.

Setup

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

If you don't have a GitHub account, you must use your work email (rather than your personal email) to , external,sign up, as this helps us with records retention and identification. If you do have a GitHub account, please , external,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 local Git configuration

• , external,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 , external,setting notifications to go to a specific email address.
• 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 , external,override on a repository level with your personal email, or use a tool like , external,karn. If you have both emails in your , external,GitHub settings, they will both be tied to your GitHub account anyway.
• If you will be using git ssh, create a ticket in ServiceNow to be added to the TTS - SSH User Group. Follow these steps:
  1. Go to , external,GSA IT Self Service Portal
  2. Click on Service Catalog
  3. Search for "generic"
  4. Select "GSA Generic Request"
  5. Fill in the information requested:
     • Short Description: Zscaler SSH Access >> Route to CISO.Firewall/Zscaler
     • Justification for request: I need to interact with [Github/Gitlab/other] repositories using SSH as part of my core job responsibilities. Issue: Post Zscaler installation, SSH functionality for remote commands (e.g. clone, fetch, pull) has been disrupted. This hinders my work, and I require a solution or workaround to ensure continuity in my tasks.
     • Additional comments:

       >>>> FORWARD TO CISO.Firewall <<<<
       >>>> ATTN: ZSCALER <<<<
       

3. Adjust notification settings

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

4. Join a GSA/TTS organization

Have a current team member request an invitation to the GSA or TTS Organization you need in the , external,TTS-only, #admins-github channel.

An admin will add you, after which you'll need to accept their invitation from the email or by going to the https://github.com/orgs//invitation?via_email=1 page.

5. Make your membership public

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

6. Authorize CircleCI

We use CircleCI for many of our applications to build and test our code in GitHub. In order for your pull requests to trigger the CircleCI release checks, you'll need to authorize CircleCI to access your GitHub profile.

On the , external,CircleCI website, log in with your GitHub profile and you'll be prompted to grant access to CircleCI. Once you grant access your pull requests will trigger the release checks properly. If you've already opened a pull request before authorizing CircleCI, any new commit to your open pull request will trigger the release check.

Rules

• Abide by the TTS Code of Conduct. If you see anyone violating our Code of Conduct, see the reporting section.

• Do not store sensitive information in GitHub.

• Ask TTS Tech Operations 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 TTS private repositories. For this reason, we ask that all organization members refrain from authorizing integrations and request any desired integrations through an TTS Tech Operations issue.

• Ask TTS Tech Operations 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 , external,TTS-only, #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 TTS Tech Operations before deleting repositories. As a government team, we can’t delete repositories without TTS Tech Operations first reviewing them for information that they may need to retain (including issues, pull request comments, commit history, and other information). Archiving is preferred in most cases. If you want to delete a repository, go to , external,TTS-only, #admins-github and explain what you'd like to do and why, and wait for approval before deleting it. This approval is generally contingent on no substantive content having been created within the repository (e.g. new issues, commits, substantive comments). In cases where the content of a repository is no different than that of another repository, it may be considered for deletion.

Handoff to partner agencies

By the time engagements end, repositories developed for another agency should be , external,transferred. After transferring the repository to the client's organization, create a fork of it in one of our organizations. This is so that:

• We have a record of the repository and the work done for that partner.
• We have a copy of the code, should they decide to delete the transferred repository, make it private, etc.

If the repository is no longer in use, it should be archived.

Working with outside collaborators

Giving contractors and federal partners 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 , external,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 email 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) , external,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) , external,add the members to the team.
7. Give the team read/write permissions on the relevant repositories. Admin rights should be limited exclusively to TTS staff.

When the engagement is over, you must let , external,TTS-only, #admins-github know so the team can be deleted and access removed.

Pull requests

TTS 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 , external,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 production branch because that is considered the canonical source of information.

Issues

If you want to make a suggestion to an TTS 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 TTS 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 TTS projects," above).

Contractors or external government collaborators should only be added to teams with permissions to the repositories they're working on. You can create <project>-feds and <project>-partners teams, if necessary.

For 18F projects

The 18F engineering supervisors and principal engineers have write access and the "manage" role on all 18F repositories. If you need help permissions on a repository, such as someone to merge a pull request, please reach out to , external,TTS-only, #18f-eng-leadership on Slack first. If they also don't have the necessary access to help you, they will work with you to get it resolved with , external,TTS-only, #admins-github.

Archiving

As discussed in the , external,18F open source policy, we , external,archive repositories to deprecate them. In short, that means we are no longer maintaining them, including keeping dependencies up-to-date or actively supporting the effort. A repository that is no longer active and archived will have a banner at the top of the page saying "This repository has been archived by the owner. It is now read-only."

Repositories created as part of an engagement with a partner should be transferred to the partner agency, forked back to one of our organizations, and then archived. See the handoff to partner agencies section for more information.

Inactive repositories are automatically archived by the TTS Tech Operations with , external,ghad. A repository is considered "inactive" if there haven't been any new commits or comments on issues or pull requests in a while; or if the repository description includes the terms "deprecated," "not supported," or "no longer supported." The , external,current default is 90 days. For repositories that are still maintained and used but have infrequent commits or comments, maintainers can , external,add the MAINTAINED topic to the repository to exempt it from automatic archiving.

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

• NPM: Use , external,npm deprecate
• PyPI: Publish with a Development Status :: 7 - Inactive , external,classifier
• Ruby gem: Publish with a , external,post-install message

Unarchiving

No approval is needed to archive/unarchive a repository. Feel free to do so yourself, or ask , external,TTS-only, #admins-github for help. Note that archiving a repository is not the same as deleting it.

Once the repository is active, it will need to be maintained, including all security tasks.

Creating a new GitHub organization

, external,Create an issue and follow the steps.

Actions

, external,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

• Document your workflow. There are many different ways to use GitHub, and each different team of people at TTS (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 , external,their GitHub wiki. In TTS' , external,development guide, there are , external,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. , external,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.

For admins

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.

Organizations

TTS is heavily involved in the following GitHub organizations:

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

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

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

Onboarding

When people join TTS, they get added to , external,the 18F org, and possibly others (in list above). Not everyone will end up using GitHub, but they are granted access by default. The following GitHub teams correspond to the different business units:

• , external,18f-staff
• , external,COEs (Centers of Excellence)
• , external,Outreach
• , external,PIF (Presidential Innovation Fellows)
• , external,AcqDiv (TTS Acquisition Division)
• , external,solutions - portfolios will handle adding them to the appropriate team(s) within there
• , external,strategic-partnerships
• , external,tts-bizops

Resources

• , external,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.

• , external,Try Git