GitHub Handbook
In the coming months the VA will be starting an effort to migrate most of its GitHub infrastructure to a single cloud enterprise in a new US instance of GitHub’s Enterprise Cloud with data residency product (GHEC-US). This environment will eventually be a fully authorized FedRAMP moderate environment, in the meantime the VA is in the process of issuing an interim ATO to use GHEC-US before it is fully FedRAMP moderate authorized.
The GitHub team is delivering a set of migration tools that VA engineering teams can use to migrate their own repositories, on their own schedules. The current plan is for the migration tooling to be available to VA engineering teams in June, however there are many moving pieces to this effort and we will keep this page updated as the plan and schedule evolves.
The GitHub team will migrate archived repositories for the VA, but for active repositories the migration responsibility will lie with the owners of those repositories. This is primarily because GitHub’s migration product does not support migrating all aspects of a repository therefore VA teams will need to develop a plan for rebuilding missing pieces and accounting for potential downtime after migrations while workflows and processes are re-established.
More specific guidance on using the migration tooling will be provided as the migration timeline draws closer. VA’s
migrations will begin with the VA GHEC organization. The
GHEC-EMU enterprise and the VA’s on-premise GitHub
Enterprise Server (GHES) at github.ec.va.gov will also migrate to GHEC-US, but those migrations will begin after VA
GHEC migrations are running smoothly and more specific guidance on those migrations will be provided as their time
comes. For now this content is for GHEC migrations only and is intended to inform VA teams about what you need to know
now to begin preparing for and planning your migrations.
Support
The GitHub team is available to provide support and consultation, both pre- and post-migration. The best way to request
support is by creating a
support request issue
in the VA’s github-user-requests repository,
but you can also reach us at va-delivery@github.com or find us in the
VA OIT DevOps Slack workspace.
Access Control
GHEC-US will be integrated with VA’s Entra ID using the same configuration used for the VA’s current GHEC-EMU enterprise. You will no longer use your personal github.com user accounts, these accounts will be provisioned and owned by VA. Users will gain permissions to access GHEC-US through the GitHub Entra ID application, which will support a self-serve workflow where users can request and be granted access automatically. GitHub teams can also be based on Entra ID groups, such that membership in the team is determined by membership in the Entra ID group. This will be optional, VA teams can also create GitHub teams independent of Entra ID, as you do today in GHEC. Users, teams, and repository access permissions will need to be re-established in GHEC-US.
No Public Repositories
GHEC-US will not allow public repositories. The GitHub team is still working with VA leadership to determine a path for the public repositories in VA GHEC. We will have updated guidance before migrations begin.
No Outside Collaborators
GHEC-US will not allow outside collaborators, which are users that are not organization members, but have been granted explicit access to some repositories in the organization. GHEC-US will require that all users with access to the system be onboarded to VA, have a va.gov account, and be granted access to GitHub in the VA’s Entra ID. The current VA GHEC organization has around 150 outside collaborators, however our analysis indicates that many of these outside collaborators are in fact VA contractors or other personnel that should be properly onboarded to VA. If you believe that your repositories are being accessed by outside collaborators that are not candidates for full VA onboarding then reach out to the GitHub team to let us know.
Migration Guidance
See the other pages in this section for more detailed information on planning and performing your migrations: