GSA GitHub Enterprise Cloud Reference

GSA’s GitHub Enterprise Cloud provides corporate source code repository services to the various Offices throughout GSA. The Website & Platform Management Branch (ICEW) in the Office of Corporate IT Services provides the management and administration of the service. Originally intended to support OMB Memorandum M-16-21 Achieving Efficiency, Transparency, and Innovation through Reusable and Open Source Software through the use of public repositories, the service now also supports private repositories for select programs with over 1,000 repositories in total. You can find out more about the GSA Open Source effort at OpenGSA. GitHub is a web based service, so there’s no installation necessary.

Joining the GSA Enterprise Organization

You will need a GitHub account to join the GSA Org. If you haven't created a GitHub account yet (https://github.com/), do so with your GSA email address. A GSA email address is required to be a member of the GSA Org.
If you already have a GitHub account, simply add your GSA email to your existing account. Do not create a new account. Make sure your commits are associated with your GSA mail address.
If you have another email specified in your GitHub settings, they will both be tied to your GitHub account.
Make sure you have notifications turned on and make sure your notifications are set up the way you'd like them.

Complete your profile

Include the following:

Name: Your first and last name.
Company: Your company or government agency.
Location: Your primary work location (city, state).

Set up two-factor authentication

Two-factor authentication is required for all members and collaborators in the GSA org. You can choose among multiple options to add a second source of authentication to your account. You can configure two-factor authentication using a mobile app or using a security key.

Turning on notifications

Turn notifications on and adjust the settings as needed. Some people watch every repository; 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 each repository is considered to be its own mailing list, checking for the SMTP list-ID identifier is one reliable way to allow these notifications through. For example, if the repository name in GitHub is GSA/reponame, you can create a filter in Gmail with the condition: “has the words” list:(reponame.gsa.GitHub.com) and perform some standard gmail action such as “Apply a label.”

You can also find this by opening an email from the desired repository, clicking the “more info” arrow in the “To” field, and copying the bracketed address in the “mailing list” field. Adding list:(reponame.GSA.GitHub.com) to your filter’s exceptions will allow any issues posted to that repository to reach your inbox.

Join the GSA organization

Email gsa-github.support@gsa.gov the following:

Please add me https://github.com/username to https://github.com/GSA.
GSA Email: user.name@gsa.gov

Please supply your GitHub username and GSA email address.

Also, to make it easier, please describe any team(s) or repo(s) you will need access to. The owner or admin of the requested repo or team will need to grant access. An admin will verify compliance and add you, after which you’ll need to accept their invitation.

Outside Collaborators

Private repositories within the GSA org can only be accessed by members in the organization. If a user needs access to a repository within the organization but is not a GSA employee or a contractor with a GSA email address, they will need to be invited as outside collaborators.

Only a member of the GSA Admin Team can invite an outside collaborator. Outside collaborators with access to a private repository incur charges (like a paid seat).

Outside collaborators will not be allowed access to a private repository, without justification from the requesting Program Office and final approval from a GSA Admin Team member.

In addition, outside collaborators will not be allowed admin access to a repository within the GSA organization.

Make your membership public

Go to the GSA org people page. Click where it says private next to your name. Change that to public.

Each GSA user must

Activate 2-factor Authentication
Add your information to your account
Make your membership public

Each repository should

Have a simple and useful name
Have a user-friendly description
Have a useful README.md

The 18F Team has published a helpful style guide that can be referenced as guidance for describing and documenting repositories.

Private vs. Public repos

Standards for making a private repo

Since GSA is following its own Open Sources policy, by default, projects in gitgub.com/gsa should be public. They should only be made private if it contains information that legally cannot be made public.

Creating new public repositories

At https://github.com/gsa, Click '+ New Repository'.
When choosing the repository's name, try to pick a simple and useful name
Include a brief description of the project.
Change the repository status to “Public” unless it needs to be private.
Note: we recommend the following when exposing your repositories to the public: a. Conduct a manual code review with your team. Go line by line through the code and check for sensitive content. b. Conduct static code analysis with a scanning tool (if available). SonarQube is approved as a standard. Teams can download it in their local environment and scan/remediate. Hopefully we can recommend other tools in the future. c. Utilize a process to remediate security vulnerabilities within the code base or the environment. d. Make environmental variables private or store them on a server
At a minimum, repositories should have a README and LICENSE file providing instructions to future contributors on how to setup and test the application in order to make suggestions. It is encouraged to have CONTRIBUTING and CODE_OF_CONDUCT files. See https://github.com/gsa/code-gov-front-end for some examples.
You will usually not need to worry about adding a “.gitignore” unless you are going to store env variables or other dot file content.
GSA’s Office of General Counsel has determined that all GSA code should be Creative Commons Zero (CC0). Work with your program office / legal counsel if you have any questions. See description of the license types.
Click Create Repository.
If prompted, choose the most appropriate team that you are a member of that should be given permission to the repo.

Creating new private repositories

The above directions are the same except that at step 4, you will choose Private instead of Public.

Creating Teams in the GSA organization

It is recommended to create teams to manage member’s access to a repository. Establish separate teams for each access role: one for team admin users; a different team for your developers with write access; and one for users with read only access. You can assign the Team maintainer role to an individual(s) who would then be able to add / remove members to the repository’s teams. For help in creating teams, please see Creating a team or email gsa-github.support@gsa.gov

Removing access to the GSA organization

Team managers should ensure that they monitor when a member of their GitHub team leaves the project or agency and no longer needs access to the GSA organization.
At that point, they should email 'gsa-github.support@gsa.gov' with a request to remove the user from the GSA organization.
Organization admins should reply to the email with confirmation when the removal is complete.
Team managers may delegate this responsibility but need to ensure that it is in place. If a member leaves GitHub who is the sole owner of the repository, and the repository is not archived or transferred to someone else, it will be deleted.

Reviewing the system log

Users are responsible for reviewing their log file and reporting any unusual activity to the github admins. You can find guidance on accessing your security log at: https://docs.github.com/en/github/authenticating-to-github/reviewing-your-security-log. Report any any usual activity to gsa-github.support@gsa.gov.

Third-party access

If you would like to have third-party access applications use GitHub, first you will need to ensure the application is shown as approved in the GSA IT Enterprise Architecture (GEAR) listing. The program office requesting 3rd-party integration is responsible for gaining IT Standards approval in GEAR and any cost for the application being integrated with GitHub.

Organizing Agency Users

Identify Team Leads.
Ensure everyone has guidance going forward.
Repo owners should certify users to their own repos.
It is recommended to make use of teams for better organization. The repo admin should create a team with admin access for the repository, a team with read-only access, and a team for read/write access. They should then delegate a “team maintainer” for adding or removing members from the team.
Users will need to reply to the annual account recertification. If a user does not reply their account will be disabled.

GSA/GitHub-Administration