What is Warp?

Warp transforms GitHub migration from a tedious, error-prone, manual process on the command line into a smooth, automated, straightforward experience managed within GitHub.

What’s in this documentation?

Warp is a rapidly evolving product, with constant updates and improvements. As a result, you’ll find that its documentation is constantly being updated as well.

Here’s a quick guide If you’re new to Warp, we think you’ll find these sections helpful:

• What’s Warp? — A more detailed description of Warp, what it does, and its key features.

• Quickstart — A complete step-by-step guide to performing a migration using Warp, from installing the local application on your computer to confirming that your migration was successful. If you have a free trial of Warp , you’ll definitely want to check out the Quickstart.

• Roadmap — A quick overview of Warp’s current feature set and the migrations it currently supports, with a glimpse into what we plan to release in the future.

• Warp’s Security Model — A review of Warp’s approach to security, which comes from recognizing that your source code is mission-critical and contains confidential data, and that migrating it requires using highly-privileged credentials.

• Billing and Licensing Overview — Find out how much it costs to use Warp. Best of all, our small (100 migrations) and medium (1,000 migrations) have their prices listed using actual dollar figures instead of “call us!”

Jump In

Warp is a next-generation solution for organizations seeking to adopt GitHub's products. It's designed by Packfiles to unlock speed, efficiency, and collaboration across the entire journey of migrating their data, development processes, and teams away from their original platform and onto the latest and greatest tools available.

Warp is distributed as a GitHub App that can be installed directly from the GitHub Marketplace, with a fully self-service setup and configuration process that takes less time than going to lunch. And because Warp includes a built-in free trial, it's easy for teams to assess Warp's capabilities flexibly, on their own schedule, and with no upfront financial commitments.

Warp has everything you need to achieve success on your migration journey, including:

• Advanced security features that are seamless, easy to use, mitigate risk, and respect your privacy,

• A fair, flexible, and transparent licensing model with no surprises,

• Built in reporting and project management tools that make work visible, collaborative, and straightforward to plan,

• A GitHub-native experience that lets your team use the tools they already know and love, and

• A wide range of available support options to assure the success of your team, from built-in assistance to help from our expert partners.

This Quickstart will guide you through the process of migrating repositories to GitHub using Warp. You’ll create a new project, set up your Vault, connect your source and GitHub organizations to Warp, and then migrate a repository to GitHub.

In this Quickstart, you will:

• Install the prerequisites.

• Create and configure a new project to migrate repositories to GitHub.

• Set up a vault to securely store the credentials and a vault key to unlock them.

• Scan your sources for repositories.

• Migrate a repository from Azure DevOps to GitHub.

Objective

Before you can use Warp, you must install Warp Vault on your local computer.

Once you've installed Warp Vault, you can proceed to the next step 🙌

Objective

In Warp, a Project is an object for managing the migration of repositories to GitHub. Typically, you’ll create a new project for a specific migration engagement, such as moving a collection of repositories for an organization, department, team, or development project.

In this section, you’ll set up a Project by creating it, installing the Warp GitHub app for the organization, and configuring the Project.

At the end of this section, you will have a new Warp project.

Sign In to the Warp Web Application

🛠️ Open a browser tab or window to the Warp web application at warp.packfiles.io

🛠️ Click the Sign in with GitHub button and sign in to Warp using your GitHub account.

Create a New Project

Upon signing in, you will be taken to Warp’s Projects page, which lists your current migration projects:

At the bottom of the list of projects, you’ll see the Create a New Project area.

🛠️ Click anywhere on Create a New Project area to expand it.

The Create a New Project area will expand to display instructions for what to do next:

🛠️ Click the Install Warp from the GitHub Marketplace button.

Install Warp’s Github App

A new browser will open to the GitHub Marketplace page for Warp’s GitHub app:

🛠️ Click the Add button near the upper right corner of the page or scroll to the bottom of the page. You should see the following:

At the bottom of the page, you’ll see the Account drop-down menu and the Install it for free button:

🛠️ In the Account menu, select the account for the destination organization — that is, the organization that you will be migrating repositories to.

🛠️ Click the Install it for free button.

You’ll be taken to the Review Your Order page:

🛠️ Review the order, then click the Complete order button.

You’ll go to the Install Packfiles Warp page, which will show:

• That the Warp GitHub app will have access to all the repositories in the organization, and

• What read, read/write, and admin permissions it will have within the organization and its repositories.

🛠️ Click the Install button at the bottom of the page.

You will return to the Warp web app, and can proceed to the next step.

Configure the Project

You will be at the Welcome to Warp page:

🛠️ Click the Next button.

This will take to you the Configure Your Project page:

You can do two things on this page:

1. You can set the name of your project, or choose to keep the default name.

2. You can invite people on your team to become members of the project.

🛠️ For this Quickstart, simply click the Next button.

You will arrive at the Connect Your Sources page. You’ll use it in the process of connecting your source and GitHub accounts to Warp:

When you created the project, Warp created a repository named Migration HQ for the GitHub organization that you selected earlier. Migration HQ will be the user interface for managing your migrations. It will be where you issue commands to Warp and it will keep track of which repositories to migrate and which ones have already been migrated.

🛠️ Let’s visit Migration HQ. Click the Migration HQ button, located in the Set Up Your Vault section:

A new browser tab or window will open, and you should see the Migration HQ page:

The files contained in Migration HQ are configuration and credentials files that Warp will use in the migration process. You will need to clone Migration HQ to your local computer, where you will create a vault file containing the following:

• Credentials for accessing the repositories at the source (the place where you are migrating repositories from).

• Credentials for accessing the destination GitHub organization (the place where you are migrating repositories to).

After creating the vault file, Warp will automatically push it to Migration HQ, making the credentials available to Warp, enabling it to migrate your repositories.

🛠️ Clone the Migration HQ repository to your local computer.

Objective

Now that you’ve gathered your source and destination credentials, you need to make them available to Warp so that it can perform migrations.

You also need to ensure that these credentials are secured so that only Warp can use them. You’ll do this by setting up a Vault — an encrypted file containing the credentials. To decrypt these credentials, you’ll provide Warp with the Vault key, the decryption key for the Vault file.

In this section, you will:

• Set up your Project's Vault by creating the Vault file

• Push the Vault file to Migration HQ, and

• Installing the Vault key as a secret in Migration HQ.

You’ll do all this by using the Warp Vault desktop app and GitHub.com, and confirm it was done by looking at the updates to Migration HQ.

At the end of this section, you will have a Vault file uploaded to Migration HQ, which will provide Warp with the credentials necessary for performing your migrations.

Before You Begin

If you haven't already, you'll need to install Warp Vault on your local machine before proceeding with the following steps.

Create Your Vault

🛠️ To kick things off, you'll need to create a Vault for your Migration Project. Open the Warp Vault application on your machine, expand the Add Menu, and choose "Create Vault".

🛠️ In the window that appears, click on the button to Select a Directory. You'll need to choose the config folder inside of the local clone of your Migration HQ repository.

🛠️ After choosing the directory to save your Vault, you can choose an Icon, give your Vault a Name, and a Description. These fields are local to your machine, and help you identify your Vault in the list (if you have multiple).

🛠️ Finally, after clicking Create, you'll be presented with your Vault's Master Key. Store this key in a secure location, such as your password manager. You'll need it to complete setup and make changes to your Vault's credentials in the future.

Add Credentials to Your Vault

Your Vault has been created— congratulations! The next step is to add credentials to it.

In order to migrate your repositories, you must provide Warp with two key sets of credentials:

1. Credentials authorizing access to the repositories at the source.

2. Credentials authorizing the creation of new repositories at the destination organization in GitHub.

🛠️ First, let’s get the credentials for the source — that is, the system that you’re migrating repositories from.

🛠️ You'll also need the credentials for your destination — that is, the system that you’re migrating repositories to.

You'll need to configure a separate GitHub Personal Access Token to allow Warp to migrate repositories and data into your destination environment. For configuration instructions, refer to the GitHub (Destination) credential documentation.

Once your credentials have been collected, you'll be ready to add them to your Vault.

🛠️ Use the Add Button in Warp Vault to add each type of credential you need for your Migration Project. Selecting a credential type will add a new entry to your Vault, opening a form where you can edit its details and configuration.

Test Your Credentials

Now that you've added credentials to your Vault, the next step is to test them. This process ensures your credentials are ready to use with Warp, and that you'll be able to perform migrations successfully.

Luckily, Warp Vault has an integrated credential testing feature that makes this process a breeze. An example of how to use this feature is shown in the video snippet below, and you can walk through the process in detail through the Warp Vault demo.

🛠️ Use the Credential Testing feature of Warp Vault to test the credentials you've configured. When each credential you've configured has a Green Check, you can save your changes and proceed.

Commit and Push Your Vault File

Next, you'll need to commit and push your encrypted Vault to your Migration HQ repository.

🛠️ Open your local clone of Migration HQ in your favorite Git client. Then add, commit, and push the file to your Migration HQ.

Confirm That the Vault Was Pushed to Migration HQ

Just to be certain, let’s take a look at Migration HQ to make sure that the Vault was actually pushed there.

🛠️ Open Migration HQ in a browser tab or panel and select the Code tab:

🛠️ Look at the files in the directory and look at the config directory’s last commit message: “Update Vault.”

Also, take note that its commit time is more recent than any of the other items in the repository.

🛠️ Open the config directory:

🛠️ Look at the Vault file — once again, it’s vault.age. Its last commit message and last commit date confirm that it was pushed to Migration HQ at the end of the Vault creation process.

Store the Vault Key in Migration HQ’s Secrets

The next step is to store the key for the Vault in the Migration HQ repository. This will allow Warp’s GitHub Actions to access the personal access tokens you encrypted into the Vault, which in turn will allow them to migrate your repositories from Azure DevOps to GitHub.

You can do this manually by copying the Vault key and pasting it into the Migration HQ repository’s Secrets settings.

Confirm that that Vault and Key are in Migration HQ

You should confirm that your Vault key was successfully stored in Migration HQ by checking the repository’s Secrets section in GitHub.

🛠️ Open a browser tab or window to the Migration HQ repository in GitHub and click the Settings tab.

🛠️ In the menu on the left side of the page, select Secrets and variables to expand it, then select Actions:

You will be taken to the Actions secrets and variables page for Migration HQ :

🛠️ Check the Repository secrets section and confirm that it contains a secret named PKFS_MASTER_KEY.

If you see the PKFS_MASTER_KEY secret, you have successfully stored the Vault key in Migration HQ. If not, you should run the gh warp vault place command again.

Objective

With your Vault set up, Warp now has the necessary credentials to access both your source repositories and the destination GitHub organization.

Warp now needs to scan your source to compile a list of repositories for migration. You’ll do this with the Warp web application and look at the results in Migration HQ.

At the end of this section, you will have a list of repositories for migration.

Verify Your Credentials

🛠️ Go back to the Warp browser tab or window. It should be on the Connect Your Sources page, which should look like this:

The next step is to connect your Azure DevOps account to Warp. This will allow Warp to access the repositories you want to migrate from Azure DevOps to GitHub.

🛠️ Go back to the Warp browser tab or window. Make sure that you’re on the Connect Your Sources page shown above, then click the Check Credentials button near the lower right corner of the page.

The text in the Verify Credentials section will change to “We’re checking your Vault’s credentials. This will take a moment...”:

🛠️ While Warp is examining your vault, switch to the browser tab or window that you were using for the Migration HQ repository in GitHub and select the Actions tab.

This will display the list of Migration HQ’s workflows:

If you switch to the GitHub browser tab or window and clicked the Actions tab quickly enough, you should see a workflow with a spinning yellow icon named Warp Runner Agent. The yellow icon denotes that it is currently running. This workflow is using the vault key you stored in Migration HQ’s secrets to unlock the personal access tokens for Azure DevOps and GitHub.

🛠️ Wait until the spinning yellow icon is replaced by a green checkmark. This means that the vault key was successfully used to unlock the personal access tokens for Azure DevOps and GitHub.

🛠️ Switch back to the browser tab or window for Warp:

You should see a section below Verify Credentials titled Your Vault. It should contain two items:

• An item representing the Azure DevOps Organization containing the repositories you want to migrate, and

• An item representing the GitHub organization where you want to migrate the repositories.

If you don’t see these items, click your browser’s Refresh button.

🛠️ Click the Next button.

You’ll arrive at the All Done! page, which marks the end of the process of configuring the project:

Check the Project’s Status

🛠️ Let’s check the project’s status. Click the Go to Dashboard button.

Check the Project’s Status

The Dashboard page shows the status of the project you just configured:

The Trends section displays the following statistics:

• The number of repositories that Warp found in the Azure DevOps Organization,

• the number of repositories that have been migrated to GitHub,

• the average number of repositories that have been migrated per day, and

• the overall progress of the migration, expressed as a percentage.

The text above the Trends section says “Tasks in Progress” and “Scanning your sources...” Warp is scanning your Azure DevOps organization for repositories. Let’s see this process in action.

🛠️ Switch to the browser tab or window for the Migrations HQ repository and select the Actions tab:

You should see a new workflow with a spinning yellow icon named Warp Runner Agent. The yellow icon denotes that it is currently running. This workflow is scanning the Azure DevOps organization for repositories.

🛠️ Wait for the Warp Runner Agent workflow to start and finish. You’ll know it’s finished when the spinning yellow icon is replaced by a green checkmark. The process may take a few minutes, depending on how many repositories are in your Azure DevOps organization:

🛠️ When the Warp Runner Agent has finished its tasks, switch back to the browser tab or window with the Warp Dashboard:

You should see the updated statistics on the Dashboard page. The number of repositories found in the Azure DevOps Organization should now be displayed.

If you don’t see a count of discovered Azure DevOps repositories, click your browser’s Refresh button.

Of course, the best way to prove that Warp has successfully scanned the source and found repositories is to go to Migration HQ and look at the Issues section.

🛠️ Switch to the browser tab or window with Migration HQ and click the Issues tab.

You’ll be taken to Migration HQ’s open issues list:

You’ll see that the number of issues in the list is that same as the number in the Repositories Discovered entry in the Dashboard.

If you take a closer look at the open issues list...

...you’ll see that each issue corresponds to a repository from your source.

Objective

At last, it’s time to migrate a repository to GitHub! You’ll do this entirely in Migration HQ.

At the end of this section, you will have a repository that has been migrated from its source and into your GitHub organization.

Select a Repository to Migrate

After scanning your source for repositories, you navigated to Migration HQ’s Issues page, where you saw the open issues list:

Each item in the open issues list represents a repository to be migrated. After migrating a repository, Warp automatically closes its issue, which moves it to the closed issues list.

Let’s migrate a repository! For this example, we’ll migrate TailwindTraders-Website, whose issue is at the top of the open issues list pictured above.

🛠️ In your open issues list, click on the issue for the repository you want to migrate.

The page for the issue will appear:

Migrate the Repository

🛠️ Scroll to the comments section at the bottom of the issue page:

You issue commands to Warp in comments by using slash commands — commands that begin with the slash (/) character. One of these commands is /migrate, which tells Warp to migrate the repository represented by this issue.

🛠️ Enter the slash command /migrate into the comment box and click the Comment button.

A couple of seconds later, Warp will confirm that it received the command. The comments section will look like this:

Warp — which will have the user name packfiles-warp — always provides a response to your commands as a follow-up comment. In the example above, it’s notifying you that the migration process has begun.

It typically takes a few minutes to perform a migration. Let’s use this time to watch the migration’s progress.

🛠️ Switch to Migration HQ’s Actions page by clicking the Actions tab:

You’ll see a new Warp Runner Agent running the workflow that performs the migration:

🛠️ Click on the Runner Agent to get a closer look at what it’s doing.

You’ll see the Runner Agent’s page:

Let’s get an even closer look at what the Runner Agent is doing.

🛠️ Click on the job that the Runner Agent is running — it’s any of the objects onscreen labeled Packfiles Warp Runner Agent that has a spinning yellow icon beside it:

You’ll go to a page where you can see the log files that the job is generating in real time:

A couple of minutes later, the migration will be complete. You’ll know this has happened when the Runner Agent’s icon changes from spinning and yellow to a static green checkmark:

🛠️ Click the Actions tab to return to the top level of the Actions page.

You’ll see that the Runner Agent completed its tasks:

Examine Your Migrated Repository

With the Runner Agent’s tasks complete, your repository has been migrated! Let’s look at its issue.

🛠️ Click the Issues tab to view the Issues page.

You’ll see something like this:

Notice that:

• There’s one less item in the open issues list, and

• There one new item in the formerly empty closed issues list.

🛠️ Click the Closed tab to view the closed issues list.

You’ll see the issue for the newly migrated repository:

🛠️ Click the issue to view its details:

You’ll see that the issue has been updated:

🛠️ Scroll to the comments section at the bottom of the page.

You’ll see a new comment from Warp, followed by a new notification:

The comment informs you that the migration was successful and provides a link to the newly migrated repository.

The notification below the comment informs you that Warp automatically closed this issue.

🛠️ Confirm that the migration was successful by clicking the link in the comment. In this example, the link is the text Tailwind-Traders.TailwindTraders-Website.

Here’s what the example migrated repository looks like:

Packfiles was founded by a team of passionate experts with a unique perspective on developer technologies. We've helped countless organizations around the world adopt efficient development practices, streamline their processes, and get the most out of the best tools available, particularly GitHub.

You may wonder why Warp exclusively supports GitHub products as the destination for migrated data. The answer is simple: First, we believe GitHub's offerings are best in class, bar none. And second, we have a long history of working within, around, and across GitHub's business. Our team's collective experience represents longtime users of the platform, former GitHub employees, world-class services partners, and vendors of developer tools that integrate with GitHub.

This section covers the key concepts of our approach to GitHub adoption that we've applied successfully for organizations around the world and across industries. You'll understand the principles, design philosophy, and rationale that have influenced the design of Warp, and how they work together to create an experience that empowers your organization to efficiently and effectively tackle the challenge of GitHub adoption.

Our Beliefs

We believe that:

• Adopting the world's best developer tools should be as easy as using them.

• Our products should put customers in control. They should unlock speed, productivity, and allow you to move at the most comfortable pace for your organization's priorities.

• Our products should be designed to eliminate bottlenecks. And they should empower teams by increasing their ability to communicate, collaborate, and share context.

• We should meet people where they are by delivering a polished, accessible experience that's easy for people to use and understand.

• We must respect our customers' right to the privacy and security of their data, without compromising on usability and safety.

Supported Use Cases

Sources

Warp currently supports migrating data from Azure DevOps Services and Bitbucket Server.

Destinations

Warp currently supports migration to the following GitHub products:

• GitHub Enterprise Cloud

• GitHub Enterprise Cloud with Enterprise Managed Users

Future Roadmap

Source Platforms

Support for these additional sources will arrive this year:

• GitHub Enterprise Server

• Gitlab

Destinations

We are currently implementing support for GitHub Enterprise Cloud with Data Residency.

This document provides an overview of Warp's capabilities for migrating data from Azure DevOps Services to GitHub products.

Warp does not provide a migration path for Azure DevOps Server, only Azure DevOps Services. To migrate from Azure DevOps Server, you'll need to migrate to Azure DevOps Services first.

Repository Data

Warp includes built in support for data migrated by GitHub Enterprise Importer, including:

• Repository contents and Git history,

• Pull requests, including

  • User history,

  • Work item links, and

  • Attachments

• Branch policies

  • User-scoped branch policies and cross-repository branch policies are not included.

For specific information about the limitations on the types and size of data that can be migrated, refer to the Limitations page in this section.

Azure Pipelines

Warp is capable of "rewiring" Azure Pipelines associated with repositories in your source Azure DevOps environment. Rewiring modifies the pipeline to associate it with the migrated copy of your repository in GitHub, rather than the original repository in Azure DevOps.

Rewiring enables a flexible path to GitHub adoption, enabling further migration processes (for instance, re-creating your existing pipelines with GitHub Actions) to proceed incrementally. Your team can enjoy the experience of hosting their code and development process on GitHub, while retaining the flexibility to continue using their existing pipelines until they're ready to replace them with Actions.

To facilitate the pipeline rewiring process, Warp will automatically share and normalize service connections for the Azure Pipelines GitHub App.

Azure Boards

If you have installed and connected the Azure Boards GitHub App to your destination GitHub Organization, Warp can configure this integration for your migrated GitHub repositories with the /integrate-boards slash command.

Autolink References for Work Items

In addition to integrating Azure Boards, Warp is also capable of configuring GitHub's Autolink References feature with the /autolink-work-items slash command.

When this integration is enabled, references to Azure Boards work items in issues, pull requests, commit messages, and release descriptions will automatically become clickable hyperlinks to the work item they reference.

Post-Migration Tasks

Warp supports a variety of utility slash commands for Azure DevOps to automate common tasks like locking or disabling the original repository when a migration has been completed. These are listed in the Azure DevOps section of our slash command documentation.

Warp additionally supports slash commands for common post-migration tasks such as adding teams in GitHub to a repository with specific permissions. Documentation for these commands can be located in our slash commands guide.

To facilitate the rewiring of Azure Pipelines, Warp automatically manages the sharing of service connections for the Azure Pipelines GitHub App.

Before rewiring Azure Pipelines, the service connection ID of the Azure Pipelines GitHub App must be configured in your Project's Warp.yml.

After configuring the service connection ID, Warp will automatically share the App's service connection with any Team Project where it is not already present.

When Azure Pipelines service connections are shared, Warp normalizes the name for your convenience to ensure it matches the name of your destination GitHub organization.

Although we strive to increase the fidelity and richness of Warp's migration capabilities, there are some limitations to the types of data that can be migrated under certain conditions.

Size Limitations

• No single Git commit can exceed 2 gigabytes in size.

• Git references may not exceed 255 bytes in size.

• No single file in the source repository can exceed 400 megabytes in size.

• The absolute size limit for an individual repository is 20 gigabytes.

• The size limit for metadata associated with a repository (including issues, pull requests, releases, and attachments) is 20 gigabytes.

• Migrating Git LFS objects is currently unsupported, but on our roadmap.

To assist you in identifying and remediating repositories that exceed these size limits, Warp will automatically assign a "too-big" label to their Backlog Issue.

This document provides an overview of Warp's capabilities for migrating data from Bitbucket Server to GitHub products.

Warp includes built in support for data migrated by GitHub Enterprise Importer, including:

• Repository contents and Git history,

• Pull requests, including

  • Comments,

  • Pull request reviews,

  • Pull request review comments (both at the file and line level)

  • Required reviewers, and

  • Attachments

For specific information about the limitations on the types and size of data that can be migrated, refer to the Limitations page in this section.

Post-Migration Tasks

Warp supports a variety of utility slash commands for common post-migration tasks such as adding teams in GitHub to a repository with specific permissions. Documentation for these commands can be located in our slash commands guide.

Although we strive to increase the fidelity and richness of Warp's migration capabilities, there are some limitations to the types of data that can be migrated under certain conditions.

Data that is not migrated from Bitbucket Server

Currently, the following data is not migrated from Bitbucket Server.

• Personal repositories owned by individual users,

• Branch permissions,

• Commit comments,

• Repository settings, and

• CI pipelines (Bamboo)

Additionally, the following size limitations remain in effect for migrated data:

Size Limitations

• No single Git commit can exceed 2 gigabytes in size.

• Git references may not exceed 255 bytes in size.

• No single file in the source repository can exceed 400 megabytes in size.

• The absolute size limit for an individual repository is 20 gigabytes.

• The size limit for metadata associated with a repository (including issues, pull requests, releases, and attachments) is 20 gigabytes.

• Migrating Git LFS objects is currently unsupported, but on our roadmap.

To assist you in identifying and remediating repositories that exceed these size limits, Warp will automatically assign a "too-big" label to their Backlog Issue.

The Migration HQ repository — the HQ is short for “headquarters” — is Warp’s primary user interface. When you create a Project, Warp generates a Migration HQ repository for that project; it’s the “control panel” that you use to manage the migration process.

You will use the Issues page of Migration HQ most often. Warp uses this page for the list of migrations. For each repository that Warp finds in the sources you provide (e.g. Azure DevOps), it creates an issue representing that repository. Each issue acts as the user interface for managing the migration of its repository. You enter Warp commands in the issue’s Comments section, including the command to migrate the issue from the source to GitHub.

You also might these Migration HQ pages on occasion:

• Actions: Warp uses GitHub Actions to perform migrations and other tasks. You can see these Action in operations and find out if they’ve completed by visiting the Actions page in Migrations HQ.

• Code: Warp uses Migration HQ’s Code section to store configuration files, including:

  • config/vault.age: “The vault,” a file that stores the encrypted tokens that allow Warp to access the source and destination organizations.

  • config/warp.yml: Warp’s main configuration file, which you can customize for more complex migration actions, such as rewiring Azure DevOps pipelines to point at GitHub.

The Issues page of Migration HQ is the list of the Project’s migrations. For each repository that Warp finds in the sources you provide (e.g. Azure DevOps), it creates an issue representing that repository:

Viewing Open Issues

When you open Migration HQ’s Issues page, you will see the open issues list, which GitHub displays by default. Items in the open issues list correspond to repositories that have not yet been migrated:

To view an open issue, click its name. You will be taken to its issue page, which will display its details, and which you can use to issue commands, including the command to start a migration.

You can filter Migration HQ issues in the same ways you would in a standard GitHub repository: by open/closed status, author, label, and so on.

Viewing Closed Issues

Items in the closed issues list correspond to repositories that have either been migrated or ignored:

To view an closed issue, click its name. You will be taken to its issue page, which will display its details, including information about the migration.

Closing Issues

There are two ways to close an open issue in Migration HQ:

1. Automatically. After a successful migration of a repository to GitHub, Warp changes the status of its corresponding issue to Closed. The issue will move from the open issues list to the closed issues list, and the Closed indicator will appear below the title of its page:

   
2. Manually. You can close one or more issues manually by checking their boxes in the open issues list and selecting either Completed or Not Planned from the Mark as menu:

   

   You can also manually close an issue on its own page — see Issue Page for details. By closing an issue manually, you are choosing to ignore the repository. Ignoring a repository has these effects:

• It moves the issue to the closed issues list.

• Warp will ignore any slash commands (commands that you issue to Warp) entered into the issue’s comments and it will not update the issue’s content.

Re-opening Issues

If you decided that you need to re-migrate a repository, you can do so by re-opening its issue. You can re-open one or more issues by checking their boxes in the closed issues list and selecting Open from the Mark as menu:

Re-opening an issue has these effects:

• It moves the issue to the open issues list.

• Warp will once again pay attention to slash commands entered into the issue’s comments and will update the issue’s content as its status changes.

Overview

Each issue in Migration HQ represents a repository, where:.

• The body of the issue displays detailed information about the repository, including its status.

• The comments act as Warp’s user interface, where you enter commands and get responses.

Issue Name

When Warp creates an issue for a repository to be migrated, it assigns the issue a name using the following format:

[source][repository_name]

• source represents the source of the repository to be migrated (e.g., Azure DevOps).

• repository_name is the name of the repository, as specified in the source.

Repositories that have not yet been migrated are marked with GitHub’s Open indicator...

...and repositories that have been migrated or ignored are marked with GitHub’s Closed indicator:

Start of Body

The issue’s body begins with the author attribution. Any issue or comment generated by Warp is attributed to the user packfiles-warp, followed by a rough date for when the issue was generated (e.g., “opened last week”):

After the attribution, the first line of the issue’s body specifies the purpose of the issue:

The line follows the format “This tracks the migration of the [repository_name] repository from [source_system] to GitHub” where:

• [repository_name] is the name of the repository as it appears in its source system.

• [source_system] is the name of the system that the repository is being migrated from (e.g., Azure DevOps).

If the Migration Is Ignored

If the migration is ignored (i.e., manually marked as Completed or Not Planned), the “⚠️ This Repository Has Been Ignored ⚠️” message appears at the start of the body:

The message informs the user that:

• Since the issue was closed manually, its repository will be ignored.

• Because the repository is ignored, Warp will ignore slash commands typed into the comments and will not update the issue’s comments.

• The repository can be “un-ignored” by manually changing its status from Closed to Open, which can be done at the bottom of the issue page or via the Mark as menu in the closed issues list (see Issues).

Migration Status

The Migration Status section contains:

• The current status of the repository (e.g., “not started”, “complete”).

• A checklist of tasks that need to be completed in order to complete the migration. Warp will automatically check tasks off this list as they are completed.

About

The About section, when expanded, lists details about the repository on the source system. It contains:

• The date when the last commit to the repository was pushed.

• The number of commits made to the repository in the last year.

• The name and email address of the repository’s most active contributor.

• The size of the repository.

Source & Destination

The Source & Destination section, when expanded, provides links to the source and destination repositories. It contains:

• The name and link for the source repository.

• The name of the destination repository, and if the repository has been migrated, the link to the destination repository.

Inventory

The Inventory section, when expanded, displays information about the migrated repository, providing the date and time when the repository was migrated as well as a link to the destination repository:

In an issue for a repository that hasn’t yet been migrated, the Repository Content section simply displays that the repository has not yet been migrated to GitHub:

Help & Support

The Help & Support section appears near the end of the issue’s body. When expanded, it lists the ways you can get help while using Warp.

It provides links to the following resources:

• The Warp Knowledge Base.

• GitHub’s Copilot docs (Warp works with Copilot chat — open it and try sending questions to @packfiles-warp!).

• The link for Packfiles Support.

End of Body

The issue’s body ends with the following:

• GitHub’s Create sub-issue / Add existing issue and emoji menus.

• Author attribution (once again, any issue or comment created by Warp will be attributed to packfiles-warp).

• Any labels for the issue, whether they were added by Warp or a user.

• A rough date for when the issue was generated (e.g., “opened last week”).

Comments and Slash Commands

In any issue created by Warp, comments serve an additional purpose: they’re your interface for issuing migration commands.

Commands to Warp are called slash commands because they start with the “slash” (/) character. You’ll find the full list of slash commands on the Slash Commands documentation page.

Simple Migration Example

Here’s an example of a repository migration.

To migrate a repository, you would open its issue page, scroll to the comments section, and enter the /migrate command into the comment box as shown below:

Seconds later, Warp will respond with a comment informing you that the migration has started, and that it will notify you when the process has completed:

When the process is complete, Warp will post another comment informing you that the migration was successful. The comment will include a link to the new migrated repository:

Warp automatically closes a repository’s issue after it has been migrated. The issue’s “closed” status will be indicated in the issue’s title and in a notice in the comments, which will also provide a rough date for when the issue was closed (e.g., “1 minute ago”):

Ignoring a Repository

You can choose to ignore repositories that you don’t want to migrate. You can mark an issue as ignored by clicking the Close issue button in its comments section...

...or by checking its box in the closed issues list and selecting Open from the Mark as menu:

Warp automatically generates four labels for each issue it creates, which specify:

1. The repository’s source organization. In the examples above, the source organization is joey-ado-testing in Azure DevOps.

2. The repository’s source team. In the examples above, the source team is first project in Azure DevOps.

3. The repository’s source. In the examples above, the source is Azure DevOps.

4. The repository’s activity. In the examples above, the repository is inactive.

In addition to the labels that Warp automatically generates for issues, you can also assign your own labels to any issue.

Warp’s configuration file, warp.yml, is located in Migration HQ’s config directory. Its default version is almost entirely commented out, with the exception of its version number:

# Welcome to your Warp configuration file!

# To learn more about the use and purpose of this file, 
# refer to our documentation at https://pack.fm/about-warp-yml

version: "1.0"

####
# Example - Azure Pipelines Rewiring
####
# To configure the service connection ID of the Azure Pipelines GitHub App,
# which is used to rewire Azure Pipelines to point at GitHub, apply the 
# configuration below.

# azure_devops:
#   global: # For a global default 
#     azure_pipelines_github_app_service_connection_id: <your Azure Pipelines GitHub App Service Connection ID>
#   my-org-name: # You can also supply organization-specific defaults
#     azure_pipelines_github_app_service_connection_id: <your Azure Pipelines GitHub App Service Connection ID>

For simple migrations, you probably won’t need to make any changes to warp.yml. However, with migrations that go beyond just moving code repositories from the source to the destination, you’ll find warp.yml useful for specifying additional details.

For example, if your migration process involves reconfiguring your Azure Pipelines to use GitHub repositories, you’ll need to make changes to the default warp.yml to provide additional required information, such as service connection IDs.

Overview

Before we talk about Warpspaces, let’s review GitHub Codespaces. A Codespace is a fully configured development environment that runs in the cloud, accessible via a web browser or VS Code, and hosted by GitHub. Every Codespace comes with common tools such as git, Python, Node.js, and other programming languages pre-installed. Codespaces can also be customized with other packages.

Warpspaces are Codespaces that have been customized with useful tools for performing migrations, including:

• GitHub’s CLI tools

• GitHub’s migration tools

• Warp’s CLI tools

With a Warpspace, you get a secure, controlled Codespace environment with all the tools you would need to manually run migration tools, perform a manual migration, or manage an edge case where Warp alone will not handle your migration.

Opening a Warpspace

To open a Warpspace for a Project:

• Open the Project’s Migration HQ repository,

• Click the Code button,

• Select the Codespaces tab, and

• Click the + button or, if it’s available, the Create codespace on main button.

The Warpspace will take a couple of minutes to initialize, since it has to import a large set of packages. Once initialized, you’ll be in GitHub’s Codespace environment with a complete set of command-line migration tools and utilities:

Overview

To perform the various tasks that make up the migration process, Warp employs GitHub hosted runners — pre-configured virtual machines provided by GitHub to run workflows. These are Warp’s Runner Agents.

For any Warp operation that takes more than a few seconds to execute, you should be able to open the Actions tab of the Migration HQ repository for your project and see the Warp Runner Agent running that operation:

Some of the operations performed by Warp’s Runner Agents include:

• Verifying the credentials stored in your vault file.

• Scanning the source for repositories.

• Migrating a repository from the source to the destination.

Viewing a Runner Agent’s Logs

To view a Runner Agent’s logs, click on its entry. This will bring up the runner’s details page:

In the runner.yml section, click the button marked Packfiles Warp Runner ... to view the Runner Agent’s collection of logs:

Click on any log title to expand it and view its contents. For example, here’s the log for the Set up job process:

Example: Troubleshooting Using a Runner Agent’s Logs

In the event that Warp encounters a problem while migrating a repository, you’ll see a message like this in comments it the repository’s issue:

If you see a message like this, expand the Troubleshoot section...

...then click the Warp runner logs link. You’ll be taken to the runner’s details page:

To view the Runner Agent’s collection of logs, click the button marked Packfiles Warp Runner ...

The search text field near the upper right corner of the page applies to all of the Runner Agent’s logs. A search for Error reveals the problem:

The end of line 429 shows what happened: Name cannot end in .wiki.

A quick look at the issue’s body reveals the source of the problem: someone specified that the destination repository’s name as PartsUnlimited.wiki:

ℹ️ GitHub repository names cannot end with .wiki; this is because it automatically creates a wiki for each repository using the repository’s name followed by the .wiki extension.

Fortunately, the solution is simple: rename the destination repository using the /rename-destination slash command so that it doesn’t end with .wiki.

What is a Project?

Warp organizes migrations into Projects. In Warp, a Project is an object for managing a migration engagement — that is, an event where you will be migrating repositories to GitHub. Projects allow you to view and manage a set of migrations as a distinct operation with its own team, timeline, and budget.

Projects are one of Warp’s ways to make migrations more manageable:

• If you have a small collection of repositories to migrate, you might choose to perform their migrations in a single engagement and use a single project.

• If you are performing migrations for multiple clients, you might choose to use one project for each client.

• If you’re working with an organization with a large number of repositories to migrate — numbering in the thousands, tens of thousands, or even more — you’ll probably want to divide that task into multiple projects carried out over a period of time.

The Projects Page

When you sign into Warp, you are taken to the Projects page, which contains the following:

• Projects: The list of active migration engagements, a.k.a. Projects.

• Pending Installations: If you have any projects that have not yet been fully set up and configured, they will appear in this list.

• Create a New Project button: Starts the process of creating a new project.

The Projects List

For every active Project, the list contains an item that looks like this:

Each item has the following elements:

• The Project’s name.

• These buttons:

  • : Settings. View and manage the Project’s settings.

  • : Migration HQ. View Migration HQ, the GitHub repository where you manage the migration process.

  • : Dashboard. See a high-level overview of the Project.

The Pending Installations List

For every Project that has been created but not yet set up and configured, the list that contains an item that looks like this:

Each item has the following elements:

• The Project’s name.

• The Start Installation button, which starts the process of setting up and configuring the Project for use.

The Dashboard page provides a high-level overview of the Project’s size and progress. It also provides a link to the Project’s Migration HQ repository.

The key parts of the Dashboard page are described in detail below.

Migration HQ

The Migration HQ button takes you to the Migration HQ repository for this Project. This repository acts as the control panel for the migration process.

Trends

The Trends section provides the following quantitative information about your Project:

• Repositories Discovered: The number of repositories that Warp was able to find after scanning the Azure DevOps organization(s) whose repositories you want to migrate. This display shows the total number of repositories that Warp found, followed by the number that were found in the past 24 hours.

• Repositories Migrated: The number of repositories that were migrated to GitHub. This display shows the total number of repositories that were migrated, followed by the number that were migrated in the past 24 hours.

• Daily Average: The average number of migrations performed per day since the Project’s first migration. This display shows the average (mean) migrations per day since the first one, followed by the number of days since the first migration.

• Overall Progress: The percentage of discovered repositories that have been migrated. This displays shows that percentage, followed by the percentage of discovered repositories yet to be migrated.

By Source

The By Source section lists the sources — that is, the organizations that you’re migrating repositories from.

For each source, this section shows the following:

• Name: The name of the organization.

• Repositories Discovered: The number of repositories discovered in this particular organization.

• Repositories Migrated: The number of repositories that were migrated from this particular organization to GitHub.

The Team page is a list of the members of the Team — the people authorized to have access to the project.

The key parts of the Dashboard page are described in detail below.

Add Members

The Add Members button starts the process of adding one or more people to the Team.

Clicking the Add Members button opens this dialog:

To invite people to join your Team, you must provide the following information for each person:

• Email address: An email address for the person you’re inviting to join the Team. Warp will send an email invitation to this address.

• Role: The role that the person will have, if they join the Team. There are two roles, Admin and Viewer, and they have different permissions:

You can invite multiple people by clicking the + button to add another invitee and the “trash can” button to remove an invitee:

After inviting someone to join the Team, the Pending Redemption list will appear on the Team page, with a list item for each invitee:

Email invitations have a limited lifespan: they expire 7 days after they are sent.

The ... button on the right side of each item in the Pending Redemption list opens a menu containing one or two options:

• Confirm: This option appears only if the invitee has accepted the invitation. Select this item to confirm the addition of the invitee to the Team.

• Discard: This option is always available, whether or not the invitee has accepted the invitation.

An invitee who has accepted the invitation will be able to sign into Warp, but will not be able to view the Project until you have confirmed the addition of the invitee to the Team.

The Invitation Email

The email will come from Packfiles Warp and will inform the invitee that:

• They have been invited to collaborate on a specific project (the email will also specify the name of the Project), and

• They can accept the invitation by clicking on a link provided in the email.

When the invitee clicks on the link in their invitation email, they will be taken to GitHub, where they will be asked to authorize Warp to verify their GitHub identity, know which resources they can access, and act on their behalf:

If the invitee clicks the Authorize Packfiles Warp button and grants the authorizations shown above, this authorization, they are taken to the Warp web application, where they will be asked if they accept the Warp’s terms of use and privacy policy:

If the invitee clicks the Accept button, they will be redirected to the Projects page.

The invitee will have access to only those Projects for which their invitation has been confirmed by an Admin-level member. An invitee whose invitation has not yet been confirmed will still be able to sign into Warp, but will not be able to access any Projects.

Team Members

The Team Members list displays the members of the Team, providing the following information about each of them:

• Their GitHub icon

• Their name

• Their GitHub username

Each item in the list has controls on the right side that allow you to:

• Change the member’s role. To confirm the change, you must click the Save Changes button at the bottom of the list.

• Remove the member from the Team. You will be asked to confirm that you want to remove the member.

The Capacity page displays your Project’s capacity — the number of migrations that have been allocated to your Project — and related statistics. Each migration costs one unit of capacity. You can also purchase more capacity for the Project account on this page.

The key parts of the Capacity page are described in detail below.

Billing Portal

The Billing Portal button takes you to the Warp Billing Portal, where you can do the following:

• View and manage your payment methods.

• View and manage your billing contact information.

• View your invoice history.

Statistics

The Statistics section provides the following quantitative information about your Project:

• Capacity Total: The total amount of capacity purchased for the Project. For every migration, one unit of capacity must be spent.

• Capacity Used: The total number of capacity units used by the Project. Each unit represents one successful migration.

• Capacity Available: The amount of capacity remaining for the Project. You can perform one migration for each one of these units. (The formula is: Capacity Available = Capacity Total - Capacity Used)

• Repositories Ignored: The total number of repositories that you have intentionally ignored (excluded from migration) in the Project.

• Repositories to Migrate: The number of repositories that still need to be migrated. (The formula is: Repositories to Migrate = Discovered Repositories - Migrated Repositories - Ignored Repositories)

Buy Capacity

The Buy Capacity section lets you purchase additional capacity for the Project. It has the following functions:

• It lists the prices for the various boxes, which are “packages” of capacity for purchase.

• It gives you the ability to set the amount of capacity to purchase. You can set this amount in a couple of ways:

  • By entering a quantity in the Quantity field for the Small Box, Medium Box, or both rows.

  • You can click the Optimize button, which automatically enters the optimal quantities for purchasing enough capacity to handle your remaining repositories to migrate. You can clear the effects of the Optimize button by clicking the button.

• You can start the purchase process by clicking the Purchase button. This will take you to the checkout page, where you will specify the payment method and finalize your purchase.

Available Box Sizes

Boxes are available in the following sizes:

Custom pricing is available for organizations planning very large migrations. To explore large-scale pricing options, contact us.

The Settings page is where you view the Project’s settings and configuration files, as well as perform tasks such as scanning the vault file, scanning the source organization for repositories, and deleting the Project.

The key parts of the Dashboard page are described in detail below.

Check Vault

The Check Vault button performs a test on your Project’s vault file, config/vault.age, to confirm that it contains the necessary data, namely:

• The personal access token for the Azure DevOps organization,

• The personal access token for the GitHub organization

When you click the Check Vault button, you’ll see this message...

...and when the process is complete, the results — information about the personal access tokens — will be displayed on the page’s Vault section (see below for details).

Scan Sources

The Scan Sources button starts the process of scanning the Azure DevOps organization for repositories.

When you click the Scan Sources button, you’ll see this message...

...and when the process is complete, the results will be visible in a couple of places:

• In the Dashboard page’s Trends section, under Repositories Discovered. If this is the first time you scanned sources, this value will now contain the number of repositories Warp found in the Azure DevOps organization. If this is not time, this value will be updated to reflect any repositories that have been added since the last scan.

• In the project’s Migration HQ repository, where any repositories discovered since the last scan (or, if this is the first scan, all the repositories Warp was able to find) will be assigned an issue and appear as open issues on the Issues page.

Configuration

The Configuration section shows information about the Project’s configuration files. It displays the following information:

• Warp.yml. The name of the project’s configuration file. You can view and edit this file in GitHub by clicking the button on the right side of this section.

• The partial hash of the Project’s vault file. This is the first 7 characters of the SHA hash of the Project’s vault file, config/vault.age, which contains the encrypted personal access tokens for the Project’s Azure DevOps and GitHub organizations. You can view this file in GitHub by clicking the partial hash.

• The button. Displays a reminder that you can edit warp.yml in GitHub.

Destination

The Destination section shows the GitHub organization where this Project’s repositories are to be migrated. It displays the following for the organization:

• The organization name. In the example above, it’s Hypotheticorp5678.

• The button. Displays a reminder that repositories from your sources will be migrated to this GitHub organization.

• The button. Click this to open a new browser to the organization’s Migration HQ repository.

Vault

The Vault section contains a list of the contents of the vault — the file containing the following personal access tokens that Warp uses to access the source and destination organizations in order to perform migrations.

Each item in this list represents a personal access token and contains the following:

• The name of the token’s platform. In the example above, the first token is for Azure DevOps and the second one is for GitHub.

• The organization for which the token was issued. In the example above, the first token is for the joey-ado-testing organization in Azure DevOps, and the second is for the Hypotheticorp5678 organization in GitHub.

• The unique identifier for the token.

• The button. Clicking this button displays a dialog box showing when the token was last checked using the Check Vault button:

Danger Zone

The Danger Zone contains a single control: the Delete Project button, which deletes the Project.

As a safety precaution, clicking the Delete Project button causes this dialog box to appear:

Clicking the Confirm button will permanently delete the project. Use this feature with caution!

Description

Summons documentation for any available slash command.

View in Knowledge Base

Examples

With Named Arguments:

/help --command-name <command-name>

With Positional Arguments:

/help <command-name> 

Arguments

--command-name (Optional)

• The name of a command you'd like to display documentation for.

Value:

• The name of a slash command, with or without the leading /.

Authorization

• Not required.

Description

Migrates a repository

View in Knowledge Base

Example

/migrate

Authorization

• Not required.

Description

Changes the name of the destination GitHub repository

View in Knowledge Base

Examples

With Named Arguments:

/rename-destination --new-name <new-name>

With Positional Arguments:

/rename-destination <new-name> 

Arguments

--new-name (Required)

• The new name of the destination GitHub repository.

Value:

• A name to use for the GitHub repository. Special characters will be converted to conform to GitHub's requirements.

• The specified repository name must be available in this GitHub organization.

Authorization

• Not required.

Description

Quickly refreshes the content of a Backlog Entry issue.

View in Knowledge Base

Example

/refresh

Authorization

• Not required.

Slash commands in this section are supported for Azure DevOps repositories.

To learn more about Warp's support for Azure DevOps, refer our documentation in the migrations section.

Description

Rewires an Azure DevOps Pipeline

View in Knowledge Base

Examples

With Named Arguments:

/rewire-pipeline --id <id> [--again]

With Positional Arguments:

/rewire-pipeline <id> [--again]

Arguments

--id (Required)

• The ID of the pipeline to rewire. This ID is shown in the Azure Pipelines table under the "Inventory" section of the Backlog Entry.

Value:

• Must be an integer number.

• The requested pipeline ID must match an ID shown in the Azure Pipelines table under the "Inventory" section of the Backlog Entry.

--again (Optional)

• When provided, the rewiring step will be performed again even if the pipeline has been rewired previously.

Value:

• None (boolean flag).

Authorization

• Not required.

Description

Rewires all Azure Pipelines associated with this repository.

View in Knowledge Base

Examples

With Named Arguments:

/rewire-all-pipelines [--again]

With Positional Arguments:

/rewire-all-pipelines  [--again]

Arguments

--again (Optional)

• When provided, the rewiring step will be performed again for all pipelines, even if they have been rewired previously.

Value:

• None (boolean flag).

Authorization

• Not required.

Description

Configures an integration between Azure Boards and the destination GitHub repository.

View in Knowledge Base

Example

/integrate-boards

Authorization

• Not required.

Description

Configures Autolink References in the destination GitHub repository so that references to Azure Boards work items become clickable hyperlinks.

View in Knowledge Base

Example

/autolink-work-items

Authorization

• Not required.

Code Examples

TypeScript

interface WorkItem {
    id: number;
    title: string;
}

function autolinkWorkItems(items: WorkItem[]) {
    items.forEach(item => {
        console.log(`Configuring Autolink for Work Item: ${item.id} - ${item.title}`);
    });
}

const workItems: WorkItem[] = [
    { id: 1, title: "Fix bug in login" },
    { id: 2, title: "Add new feature" }
];

autolinkWorkItems(workItems);

JavaScript

function autolinkWorkItems(items) {
    items.forEach(item => {
        console.log(`Configuring Autolink for Work Item: ${item.id} - ${item.title}`);
    });
}

const workItems = [
    { id: 1, title: "Fix bug in login" },
    { id: 2, title: "Add new feature" }
];

autolinkWorkItems(workItems);

Ruby

WorkItem = Struct.new(:id, :title)

def autolink_work_items(items)
  items.each do |item|
    puts "Configuring Autolink for Work Item: #{item.id} - #{item.title}"
  end
end

work_items = [
  WorkItem.new(1, "Fix bug in login"),
  WorkItem.new(2, "Add new feature")
]

autolink_work_items(work_items)

Go

package main

import "fmt"

type WorkItem struct {
    ID    int
    Title string
}

func autolinkWorkItems(items []WorkItem) {
    for _, item := range items {
        fmt.Printf("Configuring Autolink for Work Item: %d - %s\n", item.ID, item.Title)
    }
}

func main() {
    workItems := []WorkItem{
        {ID: 1, Title: "Fix bug in login"},
        {ID: 2, Title: "Add new feature"},
    }

    autolinkWorkItems(workItems)
}

Rust

struct WorkItem {
    id: u32,
    title: String,
}

fn autolink_work_items(items: Vec<WorkItem>) {
    for item in items {
        println!("Configuring Autolink for Work Item: {} - {}", item.id, item.title);
    }
}

fn main() {
    let work_items = vec![
        WorkItem { id: 1, title: String::from("Fix bug in login") },
        WorkItem { id: 2, title: String::from("Add new feature") },
    ];

    autolink_work_items(work_items);
}

Description

Makes the source Azure DevOps repository read-only for all users.

View in Knowledge Base

Example

/lock-ado-repo

Authorization

• Not required.

Description

Disables the source Azure DevOps repository for all users.

View in Knowledge Base

Example

/disable-ado-repo

Authorization

• Not required.

Description

Adds a given team to the migrated repository in GitHub with the specified permissions.

View in Knowledge Base

Examples

With Named Arguments:

/add-team --team-name <team-name> --permission <permission>

With Positional Arguments:

/add-team <team-name> <permission> 

Arguments

--team-name (Required)

• The slug of the team to add to the repository. Must be the name of a team in this GitHub organization.

Value:

--permission (Optional)

• The permission to grant the team on the migrated repository. We accept the following permissions to be set: pull, triage, push, maintain, admin. You can also specify a custom repository role name, if this organization has defined any. If no permission is specified, the team's permission attribute will be used to determine what permission to grant the team on the migrated repository.

Value:

• Must be one of the following: pull, triage, push, maintain, admin.

Authorization

• The user who invokes this command must be a GitHub organization administrator.

We're proud to offer comprehensive support options as a first-class feature of Warp, with flexible choices for a variety of needs and use cases.

Warp for Copilot

Warp for Copilot is everyone's personal migration expert. It's always available to provide instant, in-context assistance to your team throughout the entire migration process.

Packfiles Partners

Packfiles' Partner Network represents a globally distributed, distinguished cohort of skilled service providers who have vetted expertise with Warp and GitHub migrations. Their depth of experience supporting organizations through the process of adopting GitHub platforms is invaluable for those seeking expert guidance and hands-on support.

Product Support

For support inquiries related to Warp itself, the Packfiles team is here to help. Warp's product support channels can be accessed via the Support tab of your Project.

Product Feedback

We're always looking for ways to improve your experience with Warp. Thoughts, kudos, frustrations, and feature requests are always welcome, and can be shared with the Packfiles team via this form and throughout Warp.

Knowledge Base

This knowledge base is an authoritative, comprehensive resource for everything Packfiles and Warp provides. We strive to write and maintain high-quality documentation, and the Knowledge Base page will provide you with some tips and tricks on how to navigate, search, and contribute to it effectively.

Warp works with GitHub Copilot Chat on GitHub.com, so personalized help is always at your fingertips. And because Warp knows about your repositories, it can give you in-context assistance with migration processes, support questions, and more.

Getting Started

To get started with Warp for Copilot, click the Copilot icon next to the search bar to open a chat window.

In the chat window, just mention @packfiles-warp Copilot Chat text box to have a conversation with Warp.

Warp for Copilot can answer questions about slash commands, migrations, Warp's features, and more.

If you're using Warp for Copilot on GitHub.com, Warp will automatically provide context about the Backlog Issue you're currently viewing for in-context support. With this context, Warp for Copilot can answer questions about a repository and recommend the next actions you should take.

Further Reading

If you have further questions about GitHub Copilot Chat, take a look at GitHub's Copilot docs to learn more about using Copilot Chat extensions.

Packfiles' Partner Network represents a globally distributed, distinguished cohort of skilled service providers who have vetted expertise with Warp and GitHub migrations. Their depth of experience supporting organizations through the process of adopting GitHub platforms is invaluable for those seeking expert guidance and hands-on support.

If you're considering expert support as part of your migration plan, or would like to explore your options, contact our team here or at hello@packfiles.io.

Here are some tips and tricks on how to use, navigate, and contribute to this knowledge base effectively.

Finding Information

The search bar at the top right of the page allows you to search this knowledge base's content. Additionally, this search function supports natural language. Queries provided in natural language will present a summary answer with cross-references to knowledge base articles.

Contributing to the Knowledge Base

Every page in this knowledge base is stored in a public GitHub repository. Individual pages have a dedicated link to their source content on GitHub, so it's easy to propose changes.

Warp Vault is Warp's end-to-end encrypted credential management solution. It's a native application that transparently handles encryption and storage for you, with a friendly interface that makes it easy to securely configure, test, validate, and manage the credentials associated with your Warp installation.

Setting Up Warp Vault

You'll set up Warp Vault as part of the Warp installation process. For more details, refer to Set Up Your Vault in the Warp Setup Guide.

Installing Warp Vault

To install or update Warp Vault on your local machine, review the instructions provided in Download Warp Vault.

Security Model

For detailed information about how Warp Vault keeps your credentials safe and secure, review the Credential Management page in the Warp's Security Model section.

Download Warp Vault

Warp Vault is available to download at vault.packfiles.io for a variety of operating systems and CPU architectures:

• Windows (Intel/AMD x64, MSIX)

• macOS (Universal, DMG)

• Linux (Intel/AMD x64, ZIP)

Install Warp Vault With a Package Manager

Homebrew (macOS)

Packfiles provides a Homebrew tap for macOS users. This allows Warp Vault to be easily installed and updated alongside the other packages managed by Homebrew on your system.

brew tap packfiles/warptools
brew install warp-vault

Update Warp Vault

Warp Vault can be updated by downloading the latest release from https://vault.packfiles.io, or via your package manager (if applicable).

Warp Vault checks for updates on launch. When new versions are available, an indicator will appear to inform you of the latest version.

Packfiles takes the security of our products and protection of our customers extremely seriously.

To prevent tampering, all Warp Vault releases are cryptographically signed using industry-standard techniques. To verify the authenticity and integrity of your Warp Vault download, we recommend following the steps below for your host operating system.

Jump to instructions for:

• macOS

• Windows

• Linux

macOS

On macOS systems, the code signature of Warp Vault can be inspected with the following command:

codesign -dv --verbose=4 /Path/To/Your/Copy/Of/Warp\ Vault.app

This will produce output similar to the below. Verify that the Authority field matches Developer ID Application: Packfiles Inc (LQ28J3F3JH), and that the TeamIdentifier field matches LQ28J3F3JH.

Executable=/Applications/Warp Vault.app/Contents/MacOS/Warp Vault
Identifier=io.packfiles.vault
Format=app bundle with Mach-O universal (x86_64 arm64)
CodeDirectory v=20500 size=99230 flags=0x10000(runtime) hashes=3090+7 location=embedded
VersionPlatform=1
VersionMin=720896
VersionSDK=918784
Hash type=sha256 size=32
CandidateCDHash sha256=ba7c6219f8c7eb29db4f6e80d00364acaff85b1a
CandidateCDHashFull sha256=ba7c6219f8c7eb29db4f6e80d00364acaff85b1a0b832b6fd54663aeda53e0c8
Hash choices=sha256
CMSDigest=ba7c6219f8c7eb29db4f6e80d00364acaff85b1a0b832b6fd54663aeda53e0c8
CMSDigestType=2
Executable Segment base=0
Executable Segment limit=7553024
Executable Segment flags=0x1
Page size=4096
CDHash=ba7c6219f8c7eb29db4f6e80d00364acaff85b1a
Signature size=9046
Authority=Developer ID Application: Packfiles Inc (LQ28J3F3JH)
Authority=Developer ID Certification Authority
Authority=Apple Root CA
Timestamp=Apr 9, 2025 at 18:47:11
Info.plist entries=14
TeamIdentifier=LQ28J3F3JH
Runtime Version=14.5.0
Sealed Resources version=2 rules=13 files=3
Internal requirements count=1 size=180

Windows

On Windows, you can inspect the certificate chain of Warp Vault's MSIX installer or .exe file to verify its authenticity.

Right click on your downloaded copy of the Warp Vault installer and select Properties.

In the Properties view, select Digital Signatures, then click on Details.

In the Details view, select Advanced. Verify that the Serial number field of the signature has a value of 67d7636c9135682d620110e6.

Linux

Linux builds of Warp Vault are signed with the Packfiles' Vault Linux Releases (A) PGP key. This key's fingerprint is:

ED67E8E35FB2EB52F6C81937BD4C2E3452360800

The public key is:

-----BEGIN PGP PUBLIC KEY BLOCK-----

mDMEZ+GTMBYJKwYBBAHaRw8BAQdA/21kfksEyK2OvVPEJ7uUX31gluDDw9P/3WjX
lQ+8pkq0S1BhY2tmaWxlcyBJbmMgQ29kZSBTaWduaW5nIDxzZWN1cml0eUBwYWNr
ZmlsZXMuaW8+IChWYXVsdCBMaW51eCBSZWxlYXNlcyBBKYiTBBMWCgA7FiEE7Wfo
41+y61L2yBk3vUwuNFI2CAAFAmfhkzACGwEFCwkIBwICIgIGFQoJCAsCBBYCAwEC
HgcCF4AACgkQvUwuNFI2CAB2oAEA4n+dkaQtfL1U3tuEiP+xpv92OACuAXaLSo2H
uYUFWIMBAJIlXlE53fZWq5C6Goiy/STYxQ5jmeelLWrNx76DX3sBuDMEZ+GTbxYJ
KwYBBAHaRw8BAQdAmiYHAlbiHQ6A93nMua18iKzXYGy6YRVEhlxB58o+A3OI7wQY
FgoAIBYhBO1n6ONfsutS9sgZN71MLjRSNggABQJn4ZNvAhsCAIEJEL1MLjRSNggA
diAEGRYKAB0WIQRJXfnXxwZbp3cfDD0iGqVnQtjAAwUCZ+GTbwAKCRAiGqVnQtjA
A2kxAQDuB95zcjk7qbmb3+MIvrs3G/3DWgjeLGyGur8zgqFzXwEAi9LX4o1mGFmq
TtkYxE+f2+RA10VlTp5CMXlUe5dr2A0cDQEAlhwlw6aQr0ljMGWyanLJSh0les90
3uleRsO29jMweCYA/3ycEqwlneaKtlLSDZgi2C03dGuK2n3aRVX+woHn5KQE
=Hc3u
-----END PGP PUBLIC KEY BLOCK-----

You can check the signature of a given Warp Vault release with the following process.

1. Import the Key

Save the PGP public key block above to a file on disk. Then run:

gpg --import /path/to/the/public_key.pub

2. Verify the Signature

After downloading a Linux release of Warp Vault, extract the contents of the archive and run the following command to verify the signature.

gpg --verify '/path/to/your/Warp Vault.sig' '/path/to/your/Warp Vault'

You should see output like the following:

gpg: Signature made Mon Mar 24 14:38:25 2025 EDT
gpg:                using EDDSA key 495DF9D7C7065BA7771F0C3D221AA56742D8C003
gpg: Good signature from "Packfiles Inc Code Signing <security@packfiles.io> (Vault Linux Releases A)" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: ED67 E8E3 5FB2 EB52 F6C8  1937 BD4C 2E34 5236 0800
     Subkey fingerprint: 495D F9D7 C706 5BA7 771F  0C3D 221A A567 42D8 C003

In the output from the verification command, ensure that the Primary key fingerprint field matches the Packfiles' Vault Linux Releases (A) PGP key fingerprint of ED67E8E35FB2EB52F6C81937BD4C2E3452360800.

Each of the credential providers listed in this section can be configured using Warp Vault:

• Amazon S3 Storage,

• Azure Blob Storage,

• Azure DevOps Services,

• Bitbucket Server,

• GitHub (Destination)

The Amazon S3 Storage credential type stores the AWS credentials associated with an Amazon S3 bucket.

To configure an Amazon S3 Storage credential, you will need to provide:

• The S3 bucket name,

• An AWS Access Key,

• An AWS Secret Key, and

• The Bucket's AWS Region.

Your AWS Access and Secret keys should have the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucketMultipartUploads",
                "s3:AbortMultipartUpload",
                "s3:ListBucket",
                "s3:DeleteObject",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::your-bucket-name",
                "arn:aws:s3:::your-bucket-name/*"
            ]
        }
    ]
}

For more information about creating an S3 bucket, refer to the AWS documentation.

The Azure Blob Storage credential type stores the Connection String associated with an Azure Blob Storage bucket.

To configure an Azure Blob Storage credential, you will need to provide an Azure Blob Storage Connection String. For more information about generating these, refer to the Azure documentation.

The Azure DevOps credential type stores the Personal Access Token and configuration associated with the Azure DevOps Organization(s) from which you're migrating data with Warp.

To configure an Azure DevOps credential, you'll need:

• A Personal Access Token (Global or Single Organization),

• Your Organization Slug (if you're not using a Global token), and

• The number of days until your token expires (from the day of issue)

Configuration

Get the Organization Slug

🛠️ Sign in to Azure DevOps and navigate to the page for the organization containing the projects whose repositories you want to migrate:

Make a note of the URL in your browser’s address bar. The URL contains the organization slug, which is the part of the URL that uniquely identifies the organization. It’s the part of the URL after dev.azure.com/:

In this example, the URL for the organization’s page is:

dev.azure.com/joey-ado-testing

The organization slug is the part that comes after dev.azure.com/, which means that this example’s organization slug is:

joey-ado-testing

🛠️ Copy the organization slug from your browser’s address bar and paste it someplace safe — you’ll use it when you create the vault file.

Generate a Personal Access Token for Your Organization

It’s time to get a Personal Access Token.

🛠️ Near the top right corner of the page, you’ll see the (User Settings) icon. Click it to reveal its menu:

🛠️ Select Personal access tokens from the menu.

You will see the Personal Access Tokens page:

🛠️ Click any of the New Token buttons on the page.

A panel will appear, prompting you to create a new personal access token:

🛠️ In the Name field, enter a name for the token. To make it easier to identify, we suggest you include “Warp” in the name.

🛠️ Under Scopes, change the option to Full access.

🛠️ Click the Create button.

You should now see the Success! panel, which will display the personal access token you just created:

🛠️ Copy the token and save it in a safe place — preferably a password manager.

🛠️ Click the Close button.

When you close the Success! panel, you will be taken back to the Personal Access Tokens page. You will see the personal access token you just created listed there:

The Bitbucket Server credential type stores the credentials and configuration associated with the Bitbucket Server instance from which you're migrating data with Warp.

To configure a Bitbucket Server credential, you'll need:

• A Username and Password for a Bitbucket Server account with Admin or Super Admin permissions,

• At least one storage bucket, and

• SFTP or SMB access to the Bitbucket Server instance.

Configuring a Storage Bucket

You'll need to configure and select at least one migration storage bucket type when setting up your Bitbucket Server credential. Amazon S3 and Azure Blob Storage are currently supported.

Configuring SFTP Access (Linux)

If your Bitbucket Server instance is hosted on Linux, you will need to provide an SSH private key for SFTP access. This access is used to download archives from Bitbucket Server during the migration process.

This private key must not use a passphrase, and use one of the following supported ciphers:

• aes256-ctr

• 3des-cbc

• aes128-cbc

• aes192-cbc

• aes256-cbc

• blowfish-cbc

• twofish-cbc

• twofish192-cbc

• twofish128-cbc

• twofish256-cbc

• arcfour

• arcfour128

• arcfour256

• cast128-cbc

• aes128-ctr

• aes192-ctr

Configuring SMB Access (Windows)

If your Bitbucket Server instance is hosted on Windows, you will need to provide credentials for accessing the host using SMB. This access is used to download archives from Bitbucket Server during the migration process.

The GitHub Destination credential type stores the Personal Access Token and configuration associated with the GitHub Organization or Enterprise to which you're migrating data with Warp.

To configure a GitHub Destination credential, you'll need:

• A Personal Access Token assigned the correct scopes,

• The Organization Slug associated with the token,

• The days until the token expires, and

• The GitHub Enterprise Cloud product to which you're migrating.

  • If you're migrating to GitHub Enterprise Cloud with Data Residency, you'll be prompted to provide the tenant URL associated with your Enterprise.

Configuration

Get the Organization Slug

🛠️ Switch to the browser tab or window containing Migration HQ.

Make a note of the URL in your browser’s address bar. The URL contains the organization slug, which is the part of the URL that uniquely identifies the organization. It’s the part of the URL after github.com/ and before /Migration-HQ:

In this example, the URL for the organization’s page is:

github.com/Hypotheticorp01/Migration-HQ

The organization slug is the part that comes after github.com/ and before /Migration-HQ, which means that this example’s organization slug is:

Hypotheticorp01

🛠️ Copy the organization slug from your browser’s address bar and paste it someplace safe — you’ll use it when you create the vault file.

Generate a Personal Access Token for Your Account

🛠️ Switch to the browser tab or window containing Migration HQ and click on your profile picture (located near the top right of the page) so that this menu appears:

🛠️ Select Settings from the menu.

You will be taken to the Settings page for your GitHub account:

🛠️ Scroll down the page until you see the Developer settings item appear in the list on the left side:

🛠️ Click on Developer settings.

This will take you to the Developer Settings page:

🛠️ In the menu on the left side of the page, expand the Personal access tokens item:

🛠️ Select Tokens (classic) from the menu.

You will end up at the Personal access tokens (classic) page:

Towards the top right of the page, you’ll see the Generate new token button.

🛠️ Click the Generate new token button to make its menu appear:

🛠️ ...then select Generate new token (classic) from the menu.

You will arrive at the New personal access token (classic) page, where you’ll need to provide enough information to create a new personal access token:

🛠️ Enter a name or some other text to help you identify the token in the Note field. To make it easier to identify, we suggest you include “Warp” in the name:

🛠️ Under Select scopes, check the following boxes. Checking these boxes will automatically check their sub-boxes:

• repo

• workflow

• write:packages

• delete:packages

• admin:org

🛠️ Then scroll down the page and check these boxes. Once again, checking these boxes will automatically check their sub-boxes:

• admin:repo_hook

• admin:org_hook

• delete_repo

Feel free to use the checklist below to double-check that you’ve checked all the necessary checkboxes. It’s important to make sure you’ve checked all of them!

• repo

• workflow

• write:packages

• delete:packages

• admin:org

• admin:repo_hook

• admin:org_hook

• delete_repo

🛠️ Scroll to the bottom of the page and click the Generate token button:

You should now see this page, which will display the personal access token you just created:

🛠️ Copy the token and save it in a safe place — preferably a password manager.

Depending on your GitHub organization settings, you may also need to authorize your personal access token you issued for your Vault with SSO as well.

Visit https://github.com/settings/tokens and examine the Configure SSOdropdown menu adjacent to your personal access token.

View screenshot

If you receive an error like the followingResource protected by organization SAML enforcement. You must grant your OAuth token access to this organization. in the terminal or in a runner log, then review your Personal Access Token SSO authorizations as seen above.

Warp Vault provides a simple Query Language (VaultQL) that allows you to search for and extract specific credential provider configurations stored in your vault. This feature helps you extract any properties you might need in scripts or other parts of your workflow.

Using the Warp CLI command gh warp vault query, you can supply a query to locate one or more credentials and optionally retrieve only a specific property or nested value.

Quick Example

The following example demonstrates how VaultQL can be used in a shell scripting scenario. Credentials are queried from Warp Vault and passed into GitHub Enterprise Importer.

export PKFS_MASTER_KEY="AGE-SECRET-KEY-..."

export BBS_USERNAME=`gh warp vault get '(type:bitbucketserver).credentials.username'`
export BBS_PASSWORD=`gh warp vault get '(type:bitbucketserver).credentials.password'`
export BBS_URL=`gh warp vault get '(type:bitbucketserver).url'`

gh bbs2gh inventory-report --bbs-server-url $BBS_URL --bbs-username $BBS_USERNAME --bbs-password $BBS_PASSWORD --verbose

Query Syntax

A query is specified at the beginning of the command and must be enclosed in parentheses. An optional extraction path (to pull out a specific property) is appended immediately after the closing parenthesis.

General Format

gh warp vault get '(QUERY ELEMENTS)'[.EXTRACTION_PATH]

• Query Elements: A comma-separated list of key/value pairs used to match provider properties.

• Extraction Path: A dot-prefixed path indicating which property to return from the matched provider.

Both query elements and extraction paths are case-insensitive.

Query Elements

Each element in the query helps narrow down your search. There are two types of elements:

Top-Level Properties

These match properties at the root level of a provider’s JSON.

Supported Keys

The type and uuid keys are always available.

Syntax Example:

Searches for a provider with the specified UUID:

(uuid:C3AA88A0-0B1A-4567-B45F-6DB024F15FDE)

Searches for providers of type GitHubDestination:

(type:GitHubDestination)

Data Path Elements

These match properties within the provider’s "data" field. When using these in a query, begin the element with a period (.).

Syntax Example

Matches a provider whose data contains the key organization_slug with the value your-github-org-slug:

(.organization_slug:"your-github-org-slug")

Optional Elements

You can use the ? prefix to mark a query element as optional. This helps refine the search when some properties might not be available on every provider.

Syntax Example

The following query indicates that while it’s preferable for the returned provider to have an organization_slug of org3, it isn’t mandatory for the match:

(?.organization_slug:"org3")

Multiple elements are separated by commas. All non-optional elements must match for a provider to be considered, while optional elements contribute to a "best match" ranking if several providers qualify.

Extraction Paths

After the closing parenthesis of your query, you can specify an extraction path to return just one property instead of the entire provider JSON.

Syntax Example

Returns the value of organization_slug from the matching provider:

gh warp vault get '(uuid:C3AA88A0-0B1A-4567-B45F-6DB024F15FDE).organization_slug'

Syntax Example - Nested Properties

Retrieves the nested password field inside the credentials object of a Bitbucket Server provider:

gh warp vault get '(type:BitbucketServer).credentials.password'

Examples

Full Provider Retrieval

Returns the complete JSON object for the provider with the specified UUID:

gh warp vault get '(uuid:C3AA88A0-0B1A-4567-B45F-6DB024F15FDE)'

Specific Property Extraction

Returns only the organization slug from the matched provider:

gh warp vault get '(uuid:C3AA88A0-0B1A-4567-B45F-6DB024F15FDE).organization_slug'

Nested Property Extraction

Returns the nested password value (e.g., "bbs-password") from within the provider’s credentials:

gh warp vault get '(uuid:474F6208-B195-4CE4-AFA7-80CF182A43BC).credentials.password'

Using Optional Elements for Flexible Matching

gh warp vault get '(type:DemoProvider,?.organization_slug:"org3",?.access_scope:"global").pat'

Query

Mandatory

• type:DemoProvider

  • Only providers of type DemoProvider are considered.

Optional

• ?.organization_slug:"org3"

  • Prefers a provider with an organization slug of org3.

• ?.access_scope:"global"

  • Alternatively, a provider with global access_scope is acceptable.

Extraction

• .pat

  • Returns only the personal access token from the matched provider.

Return Value

The pat value of the provider that best matches the criteria.

Strict Queries

The following strict query requires a DemoProvider with an exact organization_slug of org3. If no provider meets all criteria, nothing is returned (and an error is reported).

gh warp vault get '(type:DemoProvider,.organization_slug:"org3").pat'

Matching Behavior & Tips

Mandatory vs. Optional Providers must match all mandatory (non-optional) elements. Optional elements help select the best match when multiple providers qualify.

Case Sensitivity Query keys and values are normalized (case-insensitive), so you can use uppercase or lowercase letters interchangeably.

No Matches If no provider meets the mandatory criteria, the command will return an error indicating that no provider matches the query.

Extraction Fallback If you omit an extraction path, the command returns the complete JSON of the best-matching provider.

Under the hood, Warp Vault stores credentials in a versioned schema format, so they're easy to work with in scripts.

When you configure credentials in Warp Vault's graphical interface, they're stored as JSON in an encrypted container. To access these credentials in scripts, you can use Warp Vault's Query Interface to locate and extract properties of you credentials based on their schema.

This section provides schema references for each of Warp Vault's supported credential types to help you write VaultQL queries to extract any properties you might need in scripts or other parts of your workflow.

{
   "data" : {
      "aws_access_key_id" : "",
      "aws_region" : "",
      "aws_secret_access_key" : "",
      "bucket_name" : "",
      "created_at" : "0001-01-01T00:00:00Z",
      "updated_at" : "0001-01-01T00:00:00Z",
      "uuid" : "3d934d71-2166-47e1-b396-69714a979d29"
   },
   "type" : "AmazonS3",
   "uuid" : "3d934d71-2166-47e1-b396-69714a979d29"
}

Example Query

gh warp vault get '(type:AmazonS3).bucket_name'

{
   "data" : {
      "azure_storage_connection_string" : "",
      "created_at" : "0001-01-01T00:00:00Z",
      "updated_at" : "0001-01-01T00:00:00Z",
      "uuid" : "8875afab-2f5f-4659-a627-330f86c40046"
   },
   "type" : "AzureBlobStorage",
   "uuid" : "8875afab-2f5f-4659-a627-330f86c40046"
}

Example Query

gh warp vault get '(type:AzureBlobStorage).azure_storage_connection_string'

{
   "data" : {
      "access_scope" : "global",
      "created_at" : "0001-01-01T00:00:00Z",
      "expiration_days" : 30,
      "organization_slug" : "",
      "pat" : "",
      "updated_at" : "0001-01-01T00:00:00Z",
      "uuid" : "5a8f91e4-14a3-4129-8e5b-c0f50b4cc096"
   },
   "type" : "AzureDevOps",
   "uuid" : "5a8f91e4-14a3-4129-8e5b-c0f50b4cc096"
}

Example Query

gh warp vault get '(type:AzureDevOps).pat'

{
   "data" : {
      "created_at" : "0001-01-01T00:00:00Z",
      "credentials" : {
         "password" : "",
         "username" : ""
      },
      "disable_ssl_verification" : false,
      "host_configuration" : {
         "archive_download_host" : "",
         "shared_home_directory" : "",
         "smb_domain" : "",
         "smb_password" : "",
         "smb_username" : "",
         "ssh_key" : "",
         "ssh_port" : 0,
         "ssh_username" : ""
      },
      "host_platform" : "",
      "storage_configuration" : {
         "migration_storage_provider_uuid" : "",
         "migration_storage_type" : ""
      },
      "updated_at" : "0001-01-01T00:00:00Z",
      "url" : "",
      "uuid" : "d27cb06d-0a7d-4ffa-8d9a-85ec646ecd35"
   },
   "type" : "BitbucketServer",
   "uuid" : "d27cb06d-0a7d-4ffa-8d9a-85ec646ecd35"
}

Example Query

gh warp vault get '(type:BitbucketServer).credentials.password'

{
   "data" : {
      "created_at" : "0001-01-01T00:00:00Z",
      "destination_type" : "ghec | ghec_emu | ghec_dr",
      "expiration_days" : 0,
      "ghec_dr_domain" : "",
      "organization_slug" : "",
      "pat" : "",
      "updated_at" : "0001-01-01T00:00:00Z",
      "uuid" : "d469e3f3-1937-4a1c-8fc2-2237a4efdf13"
   },
   "type" : "GitHubDestination",
   "uuid" : "d469e3f3-1937-4a1c-8fc2-2237a4efdf13"
}

Example Query

gh warp vault get '(type:GitHubDestination).pat'

The Warp CLI gives you access to certain features of Warp directly from your terminal. In particular, it allows you to work with the credentials you've stored in Warp Vault from the command line.

Before you can use Warp CLI, you must have the GitHub CLI installed on your machine.

Install the GitHub CLI

First, see if the GitHub CLI is installed on your computer.

Open your terminal application (on Windows, it’s Windows PowerShell or Command Prompt; on macOS and Linux, the default terminal is named Terminal).

Enter the following command:

gh --version

If the GitHub CLI is installed, you’ll see a message showing its version number and the URL for its release notes. Here’s an example:

gh version 2.63.1 (2024-12-03)
https://github.com/cli/cli/releases/tag/v2.63.1

If you see an error message instead, you’ll need to install the GitHub CLI. Go to the GitHub CLI page and follow the instructions there.

Install the Warp CLI Extension

Once you’ve confirmed that the GitHub CLI is installed on your computer, enter the following command to install the Warp command-line extension:

gh extension install packfiles/gh-warp

Confirm that the Warp command-line extension is installed by running the following command in a terminal window:

gh warp

You should see this response:

      _ _ _                  
     | | | |___ ___ ___      
     | | | | .'|  _| . |     
     |_____|__,|_| |  _|     
Gets You To GitHub |_| vx.x.x
   With ❤️ From Packfiles.io 
                             
You're running the latest version of gh-warp (vx.x.x)
                                                     
GitHub migration superpowers, at your fingertips.

Introduction

Packfiles designs security into the core of our products. As part of our mission to create the world's leading platform for enterprise-scale GitHub adoption, we cannot understate the importance of protecting our customers, their data, and the trust they've placed in us.

Packfiles' ultimate goal is to keep our customers safe. We achieve this with a combination of technologies, architectural choices, and best practices that work together to deliver a user experience that is as approachable and transparent as it is maximally secure.

Key security features in Warp, such as customer-owned credential management, private compute, and data privacy can't be disabled or configured improperly by mistake. Because these features are inherently part of Warp's design, customers don't need to perform extensive or complicated configurations to enjoy the benefits of these protections. They're always present and active for Projects of any size.

Our Principles

At Packfiles, we believe security isn't just a feature of our products: it defines them. That's why we always start our design process by thinking about our values and principles.

We believe:

Effective security is designed to be accessible.

World-class security technologies are transparent and easy to use. Great security controls shouldn't require advanced expertise or assumed knowledge on behalf of the customer to be effective. Instead, best practices should be distilled into product design at a fundamental level.

Rather than forcing customers to learn and apply a complicated set of security settings or configuration, we believe that the product itself should be their guide, and it should work in a way that guarantees their success.

In other words, "secure by design" is better than "secure by default", or even "secure with a bit of extra configuration". Opinionated, secure defaults that work transparently on behalf of customers raise the bar for everyone.

Security comes standard.

Customers shouldn't have to pay a premium for great security. Rather than segmenting our customers into security haves and have-nots, we believe the most critical security protections should come standard across all of our products, in a polished form that adheres to our accessibility principle.

Security is a core primitive.

At Packfiles, we've known from the start that an excellent security architecture is the first and most important thing to get right. That's why we take a long-term view of our security technology and architectural choices.

A strong security foundation is essential to enabling core experiences, developing innovative new features, and creating great experiences for our users. When a system is carefully designed with security as a core primitive, those properties and guarantees extend seamlessly throughout.

Security is a differentiator.

Our unique perspective on security isn't just about building great products like Warp. We hope to push the industry forward in designing great solutions that respect customers' right to security and privacy. Because executing on those principles while maintaining a high level of polish and usability isn't just possible, it's something that customers can and should expect.

Programs

We're committed to helping protect our customers with leading security and privacy technologies, comprehensive security and compliance programs, and a dedicated security team that supports all Packfiles products.

Packfiles understands that our own security posture is critical in protecting our customers. That's why we maintain strict controls across our workplace, development processes, and infrastructure. To ensure these controls are effective, we regularly engage with third-party security firms to perform thorough, comprehensive audits and security testing.

Contact our Security Team

The Packfiles security team can be contacted at security@packfiles.io.

Much has been said about "Zero-Trust" security architecture, but in practice, few vendors are able to truly deliver on that vision. Doing so requires a deep commitment to protecting the security and confidentiality of customer data, along with the drive and technical skill needed to solve the host of engineering challenges that make it possible to deliver scalable, resilient systems with these properties.

When we originally set out to design Warp, we were met with the following security challenges:

• Most migration tools, including first-party tools published by GitHub, require a combination of many highly privileged credentials to perform their work.

• Any individual operating migration tools, whether for their own use or on behalf of another organization, is required to have the privileged credentials mentioned previously to carry out migration tasks.

  • Due to the privileged nature of these credentials, the number of these individuals is typically small, further constraining the throughput of the migration process.

• Because migrations necessarily involve the processing of nearly all an organization's software artifacts, including those of a business-critical or trade-secret nature, customers require the utmost transparency, security, and governance of these processes.

Based on these challenges, we identified the following key problems to solve:

• Storing and managing credentials securely,

• Executing migration tools without exposing credentials or compromising the integrity of the runtime environment, and

• Ensuring the confidentiality, integrity, and privacy of customer data.

Credential Management

To solve the problem of securing the management and storage of credentials, Warp's Vault protects your key material with end-to-end encryption.

When you use Warp, your credentials, along with the key used to encrypt the Vault that contains them, are never known to Packfiles. Your key material is encrypted and maintained exclusively in your GitHub environment, on infrastructure you control, and is never stored or processed on Packfiles' infrastructure or in a form accessible by our staff.

To learn more about the Vault, have a look at the Credential Management section.

Private Compute

To execute migration tools and processes securely, while also placing control in the hands of our customers, we designed the Warp Runner Agent.

When you use Warp to invoke any process that operates on your source environment, it's carried out by the Warp Runner Agent. The Warp Runner Agent executes exclusively in your environment, on infrastructure you own and control.

The Warp Runner Agent is the only component of Warp responsible for invoking migration tools and connecting to your source environment. To learn about the security properties of its design, check out the Private Compute section.

Data Privacy

We've taken strong and intentional steps to ensure the confidentiality and privacy of our customers' data. Review the Data Privacy section to learn about our commitments and safeguards.

Overview

To facilitate the secure storage and retrieval of credentials required for migrations, Packfiles has designed a credential management application specifically for Warp known as the Vault, which protects your key material with end-to-end encryption.

When you use Warp, your credentials, along with the key used to encrypt the Vault that contains them, are never known to Packfiles. Your key material is encrypted and maintained exclusively in your GitHub environment, on infrastructure you control, and is never stored or processed on Packfiles' infrastructure or in a form accessible by our staff.

Packfiles expects customers to designate a trusted administrator in their organization with the responsibility of populating and maintaining the Vault's contents. Management of the contents of the Vault occurs on an administrator's local machine via a native application, and internet connectivity is not required or used for this process.

When the individual responsible for maintaining a Vault creates or modifies its contents, encryption is performed on their local machine with a randomly generated Master Key. This key is generated on the local machine of the individual managing the vault, is unique to each Project, and is never shared with Packfiles.

A Vault's contents, and the Master Key used for encryption, are maintained in custody of the customer. Customers are expected to maintain their Master Key in a secure location, such as a password manager, and in their Migration HQ repository's GitHub Actions secrets. Packfiles does not store or manage the Master Key of the Vault at any time.

Technical Description

The encrypted contents of the Vault are stored in a file located in your Migration HQ repository on GitHub. This follows GitHub's published best practice for storing large secrets on their platform.

The Vault uses the age encryption library to provide its underlying cryptography. A detailed specification outlining the cryptographic primitives used by age is available here.

Architecture Diagram

When you use Warp to invoke any process that operates on your source environment, it's carried out by the Warp Runner Agent. The Warp Runner Agent is the "muscle" of our migration platform, and it's the only component of Warp responsible for invoking migration tools and connecting to your source environment.

The Warp Runner Agent executes exclusively in your environment, on infrastructure you own and control. Although Packfiles is responsible for developing, packaging, and distributing the software that constitutes the Agent, the Agent itself is never executed on our infrastructure. This reduces potential attack surface considerably, providing an exceptional level of isolation and ensuring that Packfiles and its staff cannot directly access your source environment, your credentials, or otherwise impact the confidentiality or integrity of the data you're migrating.

Lifecycle & Technical Description

The Runner Agent communicates with Warp's Control Plane to exchange status information and coordinate its work while minimizing the exposure of data about your environment.

Processes carried out by the Warp Runner Agent follow a set lifecycle:

• When a job is scheduled on behalf of a Warp customer, the Control Plane dispatches a GitHub Actions workflow maintained in the customer's Migration HQ repository.

• GitHub Actions executes the workflow, which calls Packfiles' runner-agent action and supplies the following inputs:

  • An ephemeral API token for the Warp Control Plane, whose permissions are restricted specifically to that job,

  • A checked-out clone of the Migration HQ repository's Git contents, and

  • The Credential Vault master key, which is maintained in the Migration HQ repository's GitHub Actions secrets.

• The runner-agent action retrieves the Warp Runner Agent container image from Packfiles' container registry, and initializes it with the data mentioned in the previous step.

• The Warp Runner Agent container is started, and the Agent is initialized by a supervisor process. This process exchanges metadata about the container's environment and retrieves information about the job to be performed via authenticated requests to Warp's Control Plane API.

• The Agent carries out the requested job, and reports status information to the Control Plane over the course of that job's lifecycle.

• Upon completion of the job, the Warp Runner Agent reports its status to the Control Plane, and uploads its logs and artifacts to GitHub Actions Artifacts.

  • As an additional layer of security, all logs and artifacts produced by the Agent are scanned by a scrubber process to prevent the inadvertent exposure of key material by its subprocesses.

• The ephemeral API token for the job is revoked upon successful completion of the job.

  • As a failsafe measure, the token is purged if the supervisor process crashes, or when the token's lifespan reaches its limit.

Architecture Diagram

Organizations are increasingly concerned about the collection, storage, and processing of their data, and Packfiles is no exception.

Just as Packfiles maintains strong core values around security, we do the same with data privacy. Packfiles strives to ensure customers are protected by comprehensively minimizing our exposure to privileged information or administrative access to the greatest extent possible. That's why we've taken steps to ensure our products respect your organization's right to privacy and transparency in how your data is processed.

The design of Warp's Private Compute and Credential Management techniques guarantee that any processing of your private data (source code, commit history, credentials, and so on) occurs in an environment you own and on infrastructure you control. Combined with our strong commitments and controls around privacy and data residency, we aim to categorically mitigate risks associated with the storage and processing of your organization's information.

Data Residency

All infrastructure and persistent storage related to Warp's Control Plane is hosted in the eu-west-1 region of Amazon Web Services. This AWS region is geographically located in Dublin, Ireland.

AWS Regions Documentation

Data Privacy

The Warp Control Plane maintains an inventory of repositories and associated resources discovered in your environment to provide you with migration services. This index is used exclusively to render migration services to customers. It includes only information about the existence and location of resources in your environment, but does not store their contents.

For example, a repository discovered in your environment as a result of a scanning process would store the name, url, and metadata (such as its size in bytes and level of activity) in the Control Plane. However, the content of the repository (its source code, commit history, and so on) is never stored by Packfiles.

Packfiles does not mine your organization's data for any purposes not outlined above or in our Terms of Service and Privacy Policy. We do not traffic in your organization's information, and will not sell or otherwise expose that data to third parties for any purpose.

Data Security

The Warp Control Plane uses advanced encryption techniques to ensure the security, privacy, and integrity of customer data. Information about your Project, Sources, and environment are stored securely in our Control Plane's database with row-level encryption techniques.

Packfiles maintains a dedicated team of security experts and comprehensive programs to ensure our company, our customers, and their data are protected. To learn more, review our Security Programs Documentation.

At Packfiles, we're passionate about treating our customers with care and respect. Our values define everything from the core experience and overall design of Warp, to our clear and intentional approach to billing and licensing.

We've designed Warp to provide our customers with an unprecedented level of transparency and control over their migration process. To achieve this, we've created a simple and flexible volume pricing model that puts customers in control. We refer to this model as Capacity.

About Capacity

Capacity is Warp's unit of account for successful distinct migrations.

Capacity is recorded in your Project's Meter. When you use Warp to migrate a repository from your Source environments to your destination on GitHub, you'll consume units of Capacity that are debited against your Project's Meter.

Your Project's Meter is credited with a free trial allotment of Capacity when it's first created. Additional Capacity is credited any time you purchase one or more Boxes.

Capacity purchased on behalf of your Project is available for consumption immediately after your payment is processed. Purchased Capacity associated with your Project does not expire.

About Boxes

Capacity is sold in prepackaged bundles known as Boxes. Boxes provide you with flexibility and control over licensing for your Project, giving you the option to commit to adopting Warp in incremental phases, or fully up front.

You can purchase Boxes from the Capacity page of your Project at any time.

Boxes are available in the following sizes:

Custom pricing is available for organizations planning very large migrations. To explore large-scale pricing options, contact us.

Billable Events

Your Project's Meter is only debited for the repositories you choose to migrate, and you will only be billed for the first successful, distinct migration.

If you migrate the same repository successfully multiple times, you'll only be billed for the first successful migration. Similarly, if you attempt to migrate a repository but are unsuccessful, you will only be billed once for the first time the migration succeeds.

Every new Migration Project in Warp starts in our Free Tier, which gives you a free, no-strings-attached opportunity to migrate up to 100 repositories with Warp.

No matter the size or scale of your overall Migration Project, you are not required to make a purchase or provide billing information to use Warp's Free Tier.

When your Project is in the Free Tier, the following limits apply:

• We'll create a maximum of 100 Issues, and

• We'll assign a free allotment of Capacity to your Project, allowing you to perform up to 100 migrations (equivalent to one Small Box).

Issue Limit

When your Project is in our Free Tier, we'll limit the total number of GitHub Issues we create in your Migration HQ for repositories discovered in your Source environments. That means that if your source environment has more than 100 repositories, you'll only see the first 100.

The repositories chosen for Free Tier issues are random. If you'd like to evaluate Warp with a specific selection of repositories in the Free Tier, we recommend connecting Warp to a small environment you've created specifically for evaluation purposes.

Capacity Limit

To help you get started, we assign a free Capacity allotment of 100 migrations to all new Projects when they're created (equivalent to one Small Box).

You can use this Free Tier allotment to perform migrations for the repositories connected to your Project. Just as with the issue limit, we recommend connecting Warp to a dedicated evaluation environment if you'd like to use this Capacity for testing against a specific group of repositories or migration scenarios.

Getting The Most out of the Free Tier

The Free Tier is a great way to explore Warp's features, without requiring any purchases or even a credit card to be linked to your Project.

Free Tier limits can make it difficult to evaluate Warp in a large production environment with more than 100 repositories. If you're considering Warp as your chosen solution for adopting GitHub, we recommend creating a one-off Project connected to a smaller environment you've created specifically for evaluation purposes.

Upgrading Your Project

Your Project is automatically upgraded from the Free Tier with any purchase of Capacity.

Even if you're planning to migrate a very large number of repositories, only the purchase of our smallest Box size is required to upgrade your Project and exceed the Free Tier limits.

When a Project is upgraded from the Free Tier:

• We'll automatically start to populate any uncreated Backlog Issues for your remaining repositories in your Migration HQ (if your source environment contains more than 100), and

• You'll be able to make use of your purchased Capacity instantly, as soon as your payment has been processed.

If you have questions related to upgrading your Project, please contact support.