Skip to main content
Warning

Migrations are coming to VA GitHub. See the Migrations section for more information.

Migration Planning

Planning for migrations to GHEC-US

This section provides basic guidelines on how to prepare and plan for your migrations, and tasks that will need to be completed after migration to restore your data and configurations. These are basic guidelines that we have devised based on what we know about VA’s GitHub usage and our analysis of the resources and features used by VA repositories. VA teams should use these as a starting point but teams will be responsible for developing their own migration plans by understanding how the migration process and limitations will impact your use of GitHub, how much downtime may be necessary to restore missing DevOps workflows and functionality, and how to restore whatever integrations may be present with internal or third-party applications. The GitHub team will be available to provide support at every step, so please reach out to us if you need help planning your migrations.

Pre-Migration

General Repository Metadata

The VA is using the migration as an opportunity to capture required information about all repositories. Ensure you have the following information about your repositories before you begin migrations:

  1. eMASS and VASI IDs
  2. Security maintainers
  3. Product Line/organizational structure (format TBD - will update when we know more)

We are still working with VA leadership to define the full set of metadata that will be collected, keep an eye on this section for updates

Planning Downtime

Migrations will incur necessary downtime for the repositories being migrated. When a repository is being migrated it will also be locked so that no one can submit any changes (to prevent data being lost). Migrating a repository takes a bit of time, though we believe that most VA repositories will migrate in under 30 minutes. Teams will also need to rebuild missing configuration and restore integrations and other processes after migrations are complete.

Based on our analysis and internal migration testing, we are confident that most VA repositories will migrate without error. As we help VA teams overcome migration errors that they encounter, we will publish updated guidance and solutions to help other VA teams that may run into the same problems. VA teams will be able to file support requests to request assistance with any migration issues.

Network Details

VA GHEC-US will have its own unique domain name: va.ghe.com. Any other subdomains that you would typically use in github.com should now be based on va.ghe.com, for example instead of api.github.com use api.va.ghe.com. When GHEC-US is generally available our GHE Network Details will include specific IP ranges and other network information for the US infrastructure.

CodeQL Security Scanning

The default CodeQL scanning configuration will be the same as the default configuration in GHEC. Our recommendation is for teams to use the default configuration. If you have needs that aren’t met by the default configuration then you can create your own advanced CodeQL configuration in your repository (or a reusable workflow that can be used across multiple repositories). Migrated repositories will be automatically opted into the default scanning configuration.

Teams should note that two previous code scanning workflows will be deprecated and no longer be supported by the GitHub team. These workflows are contained in the GHEC codeql-tools repository.

Reusable Actions Workflows

The codeql-tools repository contains the reusable action codeql-analysis that implemented CodeQL scanning with requirements from OIS. These OIS-driven requirements are deprecated and no longer necessary, and by extension, the use of the codeql-analysis workflow is no longer necessary or supported. Teams using a code scanning workflow based on this action should transition to the default CodeQL configuration.

Jenkins Shared Libraries

The codeql-tools repository also contains a Jenkins Shared Library for running CodeQL in Jenkins pipelines. This Jenkins Shared Library primarily served two purposes:

  1. Perform compile-time build tracing: At the time, CodeQL required being able to hook into your build process to achieve full fidelity.
  2. Facilitate CodeQL access to private dependencies: CodeQL also required access to the application’s dependencies, both for scanning and to build the application.

CodeQL now supports a buildless mode where it doesn’t need access to your build process or all dependencies to provide quality results. Our recommendation is that teams should use the default configuration and assess whether it meets your security scanning needs. If teams wish to continue using CodeQL from Jenkins workflows they will still have that option, but the codeql-tools repository will be removed in the near future so teams using the Jenkins Shared Library will need to implement their own Shared Libraries leveraging the codeql CLI directly. We will provide more detailed information on how teams can continue to use CodeQL from Jenkins in a future update.

Planning for Reconfiguration and Limitations

After repositories have been successfully migrated, VA teams will need to restore missing configuration. These activities will also impact downtime, so VA teams should analyze their repositories’ use of these resources and develop a plan for how to restore them with minimal disruption. We believe the following resources will be of most concern for VA teams:

  1. Users and teams: The user performing the migration will be a repository admin on the migrated repository. That repository admin will then need to reconfigure repository access for other VA users and teams. Teams will probably want to ensure that all necessary users are onboarded to GHEC-US and establish GitHub teams and membership before performing migrations, so that users and teams can be granted access as soon as the repository is migrated and open for business.
  2. GitHub Apps: Since Marketplace is not available for GHEC-US, all apps will need to be created as custom apps. The process will be the same as with the current GHEC organization - users can create custom apps in their account and request to transfer ownership to the organization. Once ownership has been transferred to the organization, VA teams can submit support requests to install the apps in their desired repositories. There will be a user support repository in GHEC-US, similar to the github-user-requests repository in GHEC. The primary pre-migration activities for VA teams will be:
    1. Inventory the apps your team owns or manages
    2. For third-party apps, research whether the app is supported in GitHub’s Enterprise Cloud with data residency product. You may need to contact the provider of the app to determine this.
    3. For custom apps, create the app and transfer it to the new GHEC-US organization prior to attempting to migrate any repositories that use the app. If there is code behind your custom app, it will need to be updated to support the new API endpoint for VA GHEC-US: https://api.va.ghe.com.
  3. Packages: Packages are not migrated and Maven packages will not be supported in GHEC-US.
    1. With the VA Nexus being the replacement for Maven packages, VA teams need to consider how they can transition to using Nexus. Teams will most likely want to reconfigure maven poms/profiles and Actions workflows to use Nexus ahead of migrations, so they can transition on their own schedule.
    2. For other types of GitHub Packages, teams should consider whether they need to migrate current package versions to the new environment, or simply reconfigure publishing workflows to publish new packages to GHEC-US. The hostname for the package registry will be different in GHEC-US, it will be https://<registry-type>.va.ghe.com where <registry-type> is one of: containers, npm, rubygems, or nuget.
    3. The GitHub team plans on implementing additional support for migrating non-Maven packages automatically. We will provide more information on this support once it is fully implemented.
  4. Other dependency management tools: There may be other dependency management tools that need to be configured to use the new va.ghe.com hostname if they are pulling private VA dependencies directly from GitHub, for example Golang. VA teams consuming private VA dependencies from other teams/repositories will need to coordinate their migrations with those other teams to ensure that dependencies are migrated before the consumers are updated for the new environment.
  5. MacOS Actions runners: Teams using macOS hosted runners will need to transition to self-hosted runners for those Actions workflows. As with Maven packages, teams will probably want to transition before migrations to avoid interruptions.
  6. Self-hosted Actions runners: self-hosted runners are not migrated and will need to be recreated after migration.
    1. For repository runners the process should be relatively straightforward. Once a repository has been exported in the first stage of migration it will be locked therefore no Actions workflows will be invoked from the source repository. Once the migration is complete teams can go through the documented process of adding the existing self-hosted runner system to the new repository in GHEC-US. If teams wish to experiment with adding self-hosted runners to a migrated repository in GHEC-US that used the Test migration option (meaning the source repository remains unlocked and could run Actions workflows), then teams can either provision new systems for the self-hosted runners in GHEC-US or configure a second instance of the runner application on the same system. This is possible as long as the runner application is installed into an entirely separate directory and none of the configuration is shared between the two instances of the runner application.
    2. For organization runners the GitHub team is available to support requests to add and configure self-hosted runners for the VA. There are only a handful of these registered in the current GHEC enterprise and we expect the teams that own these will reach out to us about migrating them to GHEC-US.
  7. Secrets: Secrets of all types will need to be restored after migrations, including Dependabot, Actions, and webhooks. Teams will need to ensure that these secret values are saved in a safe place that can be accessed after migrations, to restore the values in the migrated repositories. Secrets are not migrated by GEI but the GitHub team plans to add additional support to at least create empty secrets that VA teams can populate after migration.
  8. Actions variables and environments: These are not migrated by GEI but the GitHub team plans to add additional support for these resources. That additional support may not be available in the first iteration of the migration tooling so VA teams can choose to proceed with migrations and repopulate these resources themselves, or wait for the additional support in later versions of the migration tooling.
  9. Projects: Projects are not migrated by GEI but the GitHub team is working on additional support for migrating some facets of Projects. This will be implemented as a separate migration workflow, also IssueOps, that can be invoked after all of the related repositories have been migrated. Even with this support there are still important aspects of your projects that will need to be rebuilt manually, including views, the order of items displayed in your views, workflows, and iteration custom fields. You should still have access to your source project to view your current configuration when rebuilding it in GHEC-US, so the primary pre-migration task for VA teams with respect to Projects is to understand these limitations and plan time for running the Projects migration workflow after migrating your repositories, and rebuilding the missing aspects of your Projects after they have been partially migrated.
  10. Issues: Issue types and relationships are not supported by GEI, but the GitHub team is planning to add custom support to migrate both. We will update with more guidance once our issue relationship support is available.
  11. Custom repository properties and Git LFS Objects: While none of these are migrated by GEI, the GitHub team is working on additional support for these resources. We believe we will be able to provide full support for migrating these resources with no additional work required from VA teams. We will update this documentation if that changes.
  12. Repository rulesets: We will support rulesets through custom migration support, but teams will need to make note of the bypass settings for each of their custom rulesets. The actors identified in the bypass settings will not exist in the destination organization, therefore they cannot be migrated.
  13. Actions workflows and any other code or integrations that make GitHub API requests will need to be updated to use the new API endpoint for VA GHEC-US: https://api.va.ghe.com.
  14. Code security scanning: Teams will need to migrate to the default code security scanning configuration as outlined above, or account for the absence of the codeql-tools repository.

Post-Migration

The post-migration requirements for VA teams are mostly aligned with the pre-migration requirements, to rebuild resources and configuration that did not completely migrate, and to ensure the connectivity and function of any GitHub integrations such as GitHub Apps and self-hosted runners.

  1. Users, teams, and repository permissions: VA teams will need to re-establish GitHub access and repository permissions for their users and GitHub teams. GitHub access is facilitated through the GitHub app in Entra ID, which users can onboard to through a self-serve process. GitHub teams can be tied to an Entra ID group so that team membership is controlled by membership in the Entra ID group. GitHub teams can also be managed as they were in GHEC - entirely in GitHub without Entra ID integration.
  2. GitHub resources that reference users and teams will also need to be updated, for example CODEOWNERS files and ruleset bypass rules.
  3. GitHub Apps: VA teams will need to create and transfer custom GitHub apps if they did not do so prior to migrating their repositories. After migration VA teams will need to file support requests to onboard the newly migrated repositories to the GitHub apps. As mentioned in the pre-migration section, GitHub App code that makes API requests will need to be updated to use the new VA GHEC-US API endpoint https://api.va.ghe.com.
  4. Packages:
    1. VA teams will need to ensure that the transition to using VA Nexus for maven packages is working as expected.
    2. For other packages, VA teams may need to run scripts to migrate their existing packages and/or re-publish them from the new repositories, if our custom support for packages is not available. The GitHub team will provide more guidance on this aspect once we are further along in our effort to migrate packages as part of our migration tooling.
    3. Configure local or repository package managers that pull private VA packages directly from github.com to now use va.ghe.com, when those dependencies have also been migrated to GHEC-US.
  5. Self-hosted Actions runners: Teams should ensure that their new self-hosted Actions runners are working as expected (or stand up and register them, if that was not done pre-migration). This applies for all self-hosted runners, including new macOS runners.
  6. Secrets: Teams will need to recreate all secrets in the new repositories. If you migrated your repositories after the GitHub team’s additional support for secrets is in place, then the secrets should already be created for you but you will need to set the actual values for these secrets.
  7. Actions variables and environments: Similar to secrets, if you migrated your repositories after the GitHub team’s additional support for these is in place, then the Actions variables and environments should have already been migrated for you and teams should examine these to ensure that they were migrated correctly. Otherwise, teams will need to recreate these resources.
  8. Projects: Even with the GitHub team’s custom support for migrating Projects, teams will still need to restore the following aspects of their projects: views, item display order in views, workflows, and custom iteration fields.
  9. Issue relationships: Our custom support for issue relationships should migrate some issue relationships for you, but there may be edge cases where all relationships are not covered and those would need to be manually re-established after migration.
  10. Repository rulesets: The rulesets should be migrated by our custom migration support, but teams will need to re-apply the bypass settings for each ruleset to reference the new users and teams in GHEC-US.
  11. Custom repository properties and Git LFS Objects: These should be migrated by our custom migration support therefore no action required by VA teams. We will provide updated documentation if we are not able to migrate these resources.
  12. VA GitHub users will need to configure their local environments to use https://va.ghe.com for standard GitHub access, and https://api.va.ghe.com for API requests. We cannot predict all configurations that may need to change on VA users’ systems, but we will provide some examples for reference.
    1. Visual Studio Code: Update settings to provide the new hostname at Settings > Extensions > GHE.com & GitHub Enterprise Server Authentication, https://va.ghe.com.

These are the general guidelines that we can provide in advance of VA team migrations, but we expect this documentation to grow with more specific guidance as we help VA teams migrate and discover solutions to whatever problems teams encounter. We will work closely with VA teams as you migrate your repositories and integrations, especially the early adopters, and we will continuously update this documentation to provide those solutions to all VA teams.