GitHub Migrations FAQ

Why are we migrating?

These migrations and the effort to consolidate into a single environment are primarily motivated by a VA compliance and security decision that determined that VA needs a FedRAMP Moderate environment for its DevOps platform, and the current GitHub.com cloud enterprise is not sufficient and could not be made suitable for FedRAMP Moderate.

Migrations will require a lot of work, especially since many aspects of my repositories do not migrate. Do we have to migrate?

Unfortunately the answer is yes, because these migrations are motivated by a VA compliance and security decision. We understand that migrating will involve a lot of work and downtime for VA engineering teams. We are doing everything we can to make the migration process as smooth and painless as we can, however the unfortunate reality is that we cannot migrate repositories for VA teams ourselves. The GitHub team is available to support VA teams in any way we can.

When will I be required to migrate my repositories?

The VA GitHub project team will send out announcements for VA engineering teams and organizations to know the schedule of when your team should migrate your repositories. There will be a schedule but the details are still being planned.

Will I still be able to access GitHub from my personal or corporate laptop?

Eventually, yes. Currently the system requires users to access it from a VA managed device, meaning GFE, CAG, or AVD. However we have already received approval for exempting GitHub from this policy and the paperwork is in process to remove this requirement. We expect users to be able to access GHEC-US from personal or corporate devices by the time GHEC migrations are enabled. Note that users will still need to login with their va.gov Entra ID accounts and PIV cards. If users do not currently have a PIV reader they will need to get one.

Also note that for GHEC-EMU users the current login and access process is the same as what you are currently doing to access GHEC-EMU. When the VA device exemption is implemented you will no longer need a VA device to access GHEC-US.

How do I create an account in GHEC-US or get onboarded to the new environment?

The GitHub team will bulk onboard all active users from the GHEC-EMU and GHEC enterprises, so for most users you will be automatically onboarded and will not need to do anything to access GHEC-US (other than logging in with va.gov and PIV). Otherwise, new GitHub users will be able to self-serve access to GHEC-US through Entra ID, by finding the GitHub enterprise application in Entra ID and requesting access to it. We will provide more explicit instructions on the Entra ID self-serve process soon.

What is the structure or layout of GHEC-US? Will I still be able to create personal repositories?

There will be a single organization that all VA teams use in GHEC-US, named software. We have had requests for VA groups to have their own organizations. GitHub has future plans for releasing a group feature for GitHub organizations, which we plan to leverage for VA when it becomes available. We believe that allowing multiple organizations at this time will make it more difficult to migrate to the future group feature, so we are staying with a single software organization for now.

GHEC-US is currently configured to prevent users from creating their own repositories in their personal namespace. However we are reconsidering this limitation since personal namespace repositories in GHEC-US do not present the same security problems that personal namespace repositories do on GitHub.com (essentially, because user accounts are still owned by the VA in GHEC-US, and individuals would no longer have access to their personal accounts after leaving the VA).

Will I still be able to use service accounts or GitHub personal access tokens (PATs)?

Yes, however we strongly recommend replacing the use of service accounts and PATs with custom GitHub Apps. Service accounts will need to be va.gov accounts with Entra ID access, but there is a VA process for creating such accounts and it will essentially be the same as what we have currently documented for the GHEC-EMU environment which also uses Entra ID authentication. PATs can still be created for all GHEC-US accounts, both user and service accounts.

GitHub Apps are easier to maintain, do not require the creation of va.gov accounts, and enable the use of short lived authentication tokens. See Service Accounts and PATs for more information on switching from service account PATs to GitHub apps.

My team’s repositories are public, GHEC-US doesn’t support public repositories. Does this mean we aren’t migrating?

We are still working with the VA GitHub project team and engineering leadership to finalize a plan for the public repositories. At this point the most likely outcome is that public repositories will be migrated and therefore become private or internal, but an automated process will be implemented to mirror a read-only copy of the repository contents to the public repositories on github.com.

My team is using a GitHub feature that is not available in GHEC-US. How do I continue using this feature after migration?

GitHub is working with VA to offer strategies and mitigations for all features that are not available in GHEC-US. The GHEC-US Limitations page has details on the missing features that we believe are the most impactful for VA, and our proposals for mitigations. Some of the features that are currently missing, like macOS runners and Codespaces, should be available in GHEC-US at some point in the future. If these features are critical for your team’s GitHub workflows then work with your VA leadership and the VA GitHub project team to delay scheduling the migration of your repositories until those feature are available in GHEC-US.

My team relies on GitHub Apps and OAuth Apps for integration with various external services. Are these apps being migrated?

Apps are not migrated automatically, VA users and teams will need to recreate them in the new environment. GitHub is working with VA to re-establish the third party apps that are installed in all repositories - Slack and Jira. Otherwise, VA teams will need to go through the same/similar process as was used when your apps were originally created. However note that third party apps (or custom apps that have webhooks) will be scrutinized moreso than in the past, since we are now in a more formal FedRAMP Moderate system. There is a VA compliance process to follow for establishing connections between authorized systems, and that process must now be followed for all apps that enable connectivity to external systems. We are still working with VA to establish this process, it will be documented in the GHEC-US handbook when it is finalized. At minimum, the external system must have an ATO and we suspect that there will be some type of documentation or process to track the interconnect between GitHub and the external system.

Also note that going forward, Apps must be owned by the organization instead of being owned by users. Users can still create apps but ownership must be transferred to the organization in order for them to have access to organization repositories.

See GHEC-US Limitations for more information on Apps and App limitations in GHEC-US.

Will I still be able to use Copilot in GHEC-US?

The short answer is yes, though we are still working through some questions around exactly which Copilot features will be available due to whether those features are within the FedRAMP Moderate boundary.

Will I still be able to use the GitHub APIs? Will the APIs for GHEC-US be different? Are the rate limits different?

You will still be able to use GitHub APIs and they are generally the same, but the hostname for most API requests will be api.va.ghe.com instead of api.github.com. Rate limits are the same. However note that authentication tokens for va.ghe.com will not work against github.com, and vice versa. See the GHE.com network details documentation for more information.

Will I still be able to use custom actions from GitHub.com in my GitHub Actions workflows?

Yes, but there are some points to consider:

1. When you use an action from GitHub.com for the first time in GHEC-US, the namespace associated with that action (e.g. actions/checkout) is retired in GHEC-US. This means that no one can create an organization or repository with the same namespace. If you later want to create a custom action in your enterprise with the same namespace, you must unretire the namespace. See Making retired namespaces available on GHE.com for more.
2. Some actions may not work as expected in GHEC-US if they are hardcoded to make API requests against api.github.com.
3. The Actions workflow token will not have permissions to make API requests against api.github.com. However any use of github.com APIs from GHEC-US resources should be scrutinized to ensure that data is not leaking out of the GHEC-US boundary.

My team uses GitHub Packages extensively. Are Packages available in GHEC-US? Will Packages migrate?

GitHub Packages is supported in GHEC-US, with the exception of the Maven/Gradle package type. We are working with VA to use a publicly available Nexus server as a replacement for Maven packages, but that work is ongoing and we will provide more information on that solution when it becomes available. Our analysis of VA GHEC shows that there is use of Maven/Gradle, Container, NuGet, and npm packages. Containers, NuGet, and npm packages are fully supported in GHEC-US however the package URLs will be different, as mentioned in planning.

We have developed a custom migration workflow for migrating packages from GHEC to GHEC-US. There are considerable limitations to our ability to migrate packages so each VA engineering team will need to understand these limitations and determine whether it makes sense to migrate the packages or simply republish them from source in GHEC-US. A few examples of the problems we have ran into are:

1. Some older NuGet target frameworks are not supported by the utilities we are using to pull and republish the NuGet packages
2. Workflows surrounding package publishing are not invoked by our migration workflow, e.g. npm pre- or post-package scripts.

We will provide more details on the Packages migration workflow and its limitations in the GHEC-US handbook migration instructions.

Can GHEC-US communicate with my team’s resources on the private VA network?

GHEC-US is on the public internet just like GHEC and GitHub.com. Any resources reachable from GitHub.com workflows should also be reachable by workflows on GHEC-US. However if any firewall rules have been created to enable ingress traffic from GitHub.com those firewall rules would need to be updated to enable US GHE.com ingress, as defined in Network Details for GHE.com.

Such integrations are typically accomplished by either making GitHub API requests (i.e. polling) or by receiving webhooks from GitHub. Polling will work the same as it currently does, although the polling configuration would need to be updated to use the new URLs to the GHEC-US repositories and the authentication token would need to be updated to use a GHEC-US token.

GitHub has analyzed all active repository webhooks in VA GHEC and we have not found any webhook hosts that are not reachable from the internet. Thus we do not expect any network issues when establishing the same webhooks in GHEC-US. However we were not involved in creating and configuring these webhooks and we can’t absolutely confirm that they will work in GHEC-US, so ultimately VA teams will need to re-establish these webhooks and perform their own testing.

Is the history of my repository migrated? What about other repository resources such as PRs and Issues?

Yes, repository content history is completely migrated. For other resources such as PRs and Issues, those are also migrated including the meaningful aspects of their history including the actions taken on them such as adding comments and approving PRs. The edit history of resources such as PRs and Issues is not migrated but this should not affect any functionality.

Are GitHub Actions and related resources such as Actions secrets and variables, environments, and runners migrated?

GitHub Actions workflows are migrated because they are just content in your repositories. Runners are not migrated automatically, but GitHub has already recreated all of the Larger GitHub hosted runner configurations that exist in both GHEC and GHEC-EMU. Self-hosted runners are not migrated and will need to be recreated by VA engineering teams. There are a few Organization level self-hosted runners, GitHub has already recreated the runner groups that contain these runners in GHEC-US, and we will work with the VA teams that own these runners to recreate them in GHEC-US.

Actions secrets, variables, and environments are not migrated automatically but we are working on adding custom support for migrating variables and environments. Secrets cannot be migrated because we cannot retrieve the secret values.

GitHub’s GEI documentation states that LFS files are not migrated. Will we need to recreate LFS files?

No, we have added custom support for LFS files/objects. LFS objects should be migrated automatically with repositories.

Will links from GitHub commits and other resources to third party systems be maintained, such Jira links and smart commits?

It will depend on how these links are implemented in GitHub and the third party system. These are typically facilitated in one of two ways:

1. Autolink references in GitHub repository settings: Autolink references are not automatically migrated, but it is on our list of items to consider if we have time. Once the Autolink references are recreated in the new repositories, then all autolink functionality will be restored as in the original repository. Note that this covers links from the GitHub/GHE.com user interface to other systems, not from other systems to GitHub.
2. GitHub webhooks sending commit messages and other data into third party systems: Jira smart commits work this way, facilitated by the Jira GitHub App. The Jira GitHub App subscribes to webhook events for commits and other data, and Jira processes those events to perform the smart commit operations and whatever else Jira does with that data. The Jira GitHub App will be installed in GHEC-US so new commits to repositories in GHEC-US should generate the same result as in GHEC. However new webhook events are not generated for existing data, so “old” smart commit links or other Jira links that point to commits and repositories on github.com will not be automatically updated to point to va.ghe.com. Unfortunately there is nothing we can do about this since this is data maintained in the external system. Our research suggests that there are configuration options in Jira to change the GitHub repository URL(s) that a Jira project is related to, which might be leveraged to re-establish those links.

How do I update my local system after my repositories are migrated?

We cannot predict every activity that each VA GitHub user will need to perform on their local system because that is heavily dependent on the utilities and workflows for each user. However we have provided some basic guidelines in the updating local configuration section.

What happens if there is an error while migrating my repositories? Or what if I want to undo a migration?

In case of migration failure, the migration process should add descriptive comments to your migration issue to explain the failures or link to the migration Actions workflow where commands and failures can be examined. VA users can also create support requests to get assistance from the GitHub team. We have already performed test migrations of all VA repositories and the vast majority migrated with no issues.

If you have performed a dry run migration there is no need to undo anything because the source repository was not locked or otherwise modified. You can choose to delete the migrated repositories if you wish. Users that wish to undo a production migration by unlocking the source repository can create a support request with the details including the source repository name/link, and the GitHub team will unlock the repository for you.

Can I migrate more than one repository at a time?

Yes, you can migrate multiple repositories at the same time but you will have to create a separate migration issue for each repository. The issue template described in the process documentation notes that only a single repository can be migrated per issue, but you can create multiple issues. See the process documentation for more information on how to create migration issues.