# Welcome ### 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?**](/guides/whats-warp) — A more detailed description of Warp, what it does, and its key features. * [**Quickstart**](/guides/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**](/product/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**](/security/warp-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**](/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!” {% hint style="info" %} If you need help with anything that isn't yet covered in our documentation, please don’t hesitate to [create an Issue](https://github.com/packfiles/kb.packfiles.io/issues/new/choose), [open a Pull Request](https://github.com/packfiles/kb.packfiles.io/compare), or [share feedback](https://pack.fm/warp/feedback) with our team. {% endhint %} ### Jump In


What's Warp?	Let's Start With the Gist	/pages/pcWSqkpeHYTA3mhvmMIP
Quickstart Guide	Get started with Warp and Azure DevOps	/pages/CyH2xJQs9yWJ1S8BYNav
Support	Understand Warp's Support Options	/pages/rWfKM2j1JPNRCInldc4G

# What's Warp? Let's Start With the Gist Warp is a next-generation solution for organizations seeking to adopt GitHub's products. It's designed by [Packfiles](https://packfiles.io) 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 composed of multiple components that all work together to coordinate your migration to GitHub. The first component is the [Warp GitHub App](https://pack.fm/warp) 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](/billing-and-licensing/free-trial), it's easy for teams to assess Warp's capabilities flexibly, on their own schedule, and with no upfront financial commitments. The second component is the [Warp Control Plane](https://warp.packfiles.io), a web application that communicates with the Warp GitHub App to perform work on your behalf. The control plane also provides reporting tools, migration team member management, and other admin tools. The third component is the [Warp Runner Agent](/using-warp/migration-hq/runner-agent) that operates on GitHub runners in your environment either GitHub cloud or self-hosted. Runner Agents have all of the tools needed to perform migration operations on your behalf at your request and are coordinated by the control plane. The fourth component is the [Warp Vault](/using-warp/warp-vault), a desktop application that keeps your credentials encrypted while in the Migration HQ repository. Only the Runner Agent can decrypt your `vault.age` file at runtime (and only with the your vault master key stowed in [GitHub's repository secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository)). The last component is the Migration HQ repository that Warp automatically generates during the Warp installation and configuration process of your migration project. It's here in the Migration HQ repository that you can update the runtime configuration settings for Warp Runner Agents (see the [warp.yml](/using-warp/migration-hq/warp.yml) file). Warp will create a [GitHub Issue for each git repository in your source](/using-warp/migration-hq/issues) (e.g., ADO Organization). From there you can plan, coordinate, and collaborate on your migration to GitHub. The following diagram shows how these components fit together: ![Warp Toplogy](/files/TkErsPri3uHftYwWc769) Warp has everything you need to achieve success on your migration journey, including: * [Advanced security features](/security/warp-security-model) that are seamless, easy to use, mitigate risk, and respect your privacy, * A fair, flexible, and transparent [licensing model](/billing-and-licensing/overview) with no surprises, * Built in [reporting](/using-warp/projects/dashboard) and [project management](/using-warp/migration-hq/issues) tools that make work visible, collaborative, and straightforward to plan, * A [GitHub-native experience](/using-warp/migration-hq) that lets your team use the tools they already know and love, and * A wide range of available [support options](/using-warp/support) to assure the success of your team, directly from [our team](/using-warp/support#product-support) and from our [expert partners](/using-warp/support/partners). # Setup Guide A friendly step-by-step guide to your first migration with Warp. 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.](/guides/quickstart/install-the-prerequisites) * [Create and configure a new project to migrate repositories to GitHub.](/guides/quickstart/create-and-configure-your-project) * [Set up a vault to securely store the credentials and a vault key to unlock them.](/guides/quickstart/set-up-your-vault) * [Scan your sources for repositories.](/guides/quickstart/scan-your-sources-for-repositories) * [Migrate a repository from Azure DevOps to GitHub.](/guides/quickstart/migrate-a-repository) # Install the Prerequisites How to install the required applications on your local computer. ### Objective Before you can use Warp, you must install [Warp Vault](/using-warp/warp-vault/download-warp-vault) on your local computer. Once you've installed Warp Vault, you can [proceed to the next step](/guides/quickstart/create-and-configure-your-project) 🙌 ### # Create and Configure Your Project Create a new Project, install Warp’s GitHub App, and configure the Project. ### 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.** {% hint style="info" %} Search for the 🛠️ emoji if you’d like to skim through this content while focusing on the steps you need to follow. {% endhint %} ### Sign In to the Warp Web Application 🛠️ Open a browser tab or window to the [Warp web application](https://warp.packfiles.io) at [warp.packfiles.io](https://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:

Warp's "Projects" page, with a single project and the "Create a New Project" area. — Warp’s *Projects* page, which you’ll see immediately after signing in.

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:

Close-up of the expanded "Create a New Project" area, with the steps for creating a new project and the "Install Warp from the GitHub Marketplace" button. — The *Create a New Project* area, after you’ve expanded it.

🛠️ 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](https://github.com/marketplace/packfiles-warp):

The top of the Warp app's page in GitHub Marketplace. The "Add" button is near the upper right corner of the page. — The Warp app’s page in GitHub Marketplace.

🛠️ 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:

The bottom of the Warp app's page in GitHub. The "Account" and "Install it for free" buttons button is near the bottom of the page. — The Warp app’s page in GitHub Marketplace, scrolled to the bottom.

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

Close-up of the "Account" drop-down menu and "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. {% hint style="info" %} The example destination organization for this quickstart is **Hypotheticorp01**. {% endhint %} 🛠️ Click the **Install it for free** button. You’ll be taken to the **Review Your Order** page:

The "Review your order" page in GitHub Marketplace. It shows that the user is getting Warp for free, and that the version supports 1 user, 10 repositories, and migrates from Azure DevOps to GHEC. — The *Review Your Order* page in GitHub Marketplace.

🛠️ 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.

The "Install Packfiles Warp" page on GitHub. It shows that Warp will be included for the user's organization for all repositories, with a long list of permissions. — The *Install Packfiles Warp* page in GitHub.

🛠️ 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:

The "Welcome to Warp" page in the Warp web app. Key items are the user's destination organization and the "Next" button. — The *Welcome to Warp* page.

🛠️ Click the **Next** button. This will take to you the *Configure Your Project* page:

The "Configure Your Project" page in the Warp web app. Key items are the user's project name and the "Next" button. — 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. {% hint style="info" %} As the creator of the project, you don’t have to add yourself to the team. You are already a member of the project with *Admin* access. {% endhint %} 🛠️ 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:

The "Connect Your Sources" page in the Warp web app. Key items are the user's project name and the "Next" button. The key item on this page is the “Migration HQ” button. — The *Connect Your Sources* page.

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 "Code" page of the "Migration HQ" repository in GitHub. — The *Migration HQ* page for your project.

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. {% hint style="success" %} You’ve successfully set up your project — nicely done! Make sure that you’ve cloned *Migration HQ* to your local computer, then [proceed to the next step.](/guides/quickstart/set-up-your-vault) {% endhint %} # Set Up Your Vault How to create your Vault, a secure place to store the credentials for your migration. ### 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.** {% hint style="info" %} Search for the 🛠️ emoji if you’d like to skim through this content while focusing on the steps you need to follow. {% endhint %} ### Before You Begin If you haven't already, you'll need to [install Warp Vault](/using-warp/warp-vault/download-warp-vault) on your local machine before proceeding with the following steps. {% hint style="info" %} Looking for a quick tour of Warp Vault's features and interface? Check out [this demo](https://packfiles.navattic.com/ybw09zv). {% endhint %} ### 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". {% embed url="" %} Creating a New Vault {% endembed %} 🛠️ 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**. {% hint style="warning" %} It's important to get this right. If you don't choose the **config** folder in your local **Migration HQ** clone, Warp won't be able to access your credentials in later steps. {% endhint %} {% embed url="" %} Selecting a Vault's Location on Disk {% endembed %} 🛠️ 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). {% embed url="" %} Filling in a Vault's Name and Description {% endembed %} 🛠️ 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. {% hint style="warning" %} Securely store your Master Key in a password manager. **If you lose track of it, the contents of your Vault will be lost**, and you won't be able to proceed with the rest of the setup process. {% endhint %} {% embed url="" %} Unlocking a Vault with its Master Key {% endembed %} ### 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*. {% hint style="success" %} For a list of credential types supported by Warp Vault and how to configure them, refer to the [Supported Credential Providers](/using-warp/warp-vault/supported-credential-providers) page in this document. {% endhint %} 🛠️ 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)](/using-warp/warp-vault/supported-credential-providers/get-your-github-credentials) 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. {% embed url="" %} Adding Credentials to Warp Vault {% endembed %} ### 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](https://packfiles.navattic.com/ybw09zv). 🛠️ 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. {% embed url="" %} Testing Credentials in Warp Vault {% endembed %} ### 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. {% hint style="success" %} #### Is this secure? **Yes.** Warp's model for securely storing your secrets as an encrypted file in your Migration HQ repository follows [GitHub's published best practice guidelines](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#storing-large-secrets) for managing large secrets on the platform. {% endhint %} {% embed url="" %} Committing and Pushing a Vault to Migration HQ from VS Code {% endembed %} ### 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:

The "Migration HQ" page in GitHub. — *Migration HQ*.

🛠️ 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:

Migration HQ's "config" directory. The key item is the "vault.age" file. — Migration HQ’s *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*](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) settings. {% embed url="" %} Adding Your Master Key as a Migration-HQ Repository Secret {% endembed %} ### 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.

"Migration HQ’s" "Settings" page. The key item is the "Secrets and variables" item in the left side menu. — *Migration HQ*’s *Settings* page.

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

The "Secrets and variables" menu. The key item is the "Actions" menu item. — The *Secrets and variables* menu.

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

"Migration HQ’s" repository secrets. It contains one secret, whose name is "PKFS_MASTER_KEY". — *Migration HQ’s* repository secrets.

🛠️ 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. {% hint style="success" %} With the Vault file and secret install in *Migration HQ*, Warp now has the credentials to access your source repositories and destination GitHub organization.\ \ You’re ready to [scan your source for repositories](/guides/quickstart/scan-your-sources-for-repositories). {% endhint %} # Scan Your Sources for Repositories ### 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.** {% hint style="info" %} Search for the 🛠️ emoji if you’d like to skim through this content while focusing on the steps you need to follow. {% endhint %} ### 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:

Warp’s “Connect Your Sources” page. The key item is the “Check Credentials” button near the lower right corner of the page. — Warp’s *Connect Your Sources* page.

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...”:

Warp’s “Connect Your Sources” page. The “Verify Credentials” section has been updated to read “We’re checking your Vault’s credentials. This will take a minute or two…” — Warp’s *Connect Your Sources* page, with Warp checking the credentials stored in the Vault.

🛠️ 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:

Migration HQ’s Actions page with an active Warp Runner Agent. — *Migration HQ*’s *Actions* page with an active Warp Runner Agent.

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.

Migration HQ’s Actions page with a Warp Runner Agent that has completed its task. — *Migration HQ*’s *Actions* page with a Warp Runner Agent that has completed its task.

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

Warp’s updated Connect Your Sources page. The "Verify Credentials" section now contains a new subsection called "Your Vault" which contains entries for Azure DevOps and GitHub. — Warp’s updated *Connect Your Sources* page.

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:

The Review and Complete page. The text reads "You’re all set! Check out your Project dashboard to view metrics, manage settings, get support, and more. When you’re ready to start migrating, visit Issues in your Migration HQ repository." — The *Review and Complete* page.

### 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 “Dashboard” page. At the top of the page is a notice that says “Tasks in Progress — Scanning your sources…” The “Trends” section shows repository statistics: Repositories Discovered (0), Repositories Migrated (0), Daily Average (“N/A”), and Overall Progress (“N/A%”). — The *Dashboard* page.

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:

Migration HQ’s "Actions" page with a new active Warp Runner Agent. — The *Actions* page of *Migration HQ*, showing the Runner Agent scanning the Azure DevOps organization for repositories.

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:

Migration HQ’s "Actions" page with the Warp Runner Agent having completed its task. — The *Actions* page of *Migration HQ*, showing the Runner Agent having completed its task.

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

The updated “Dashboard” page. The “Trends” section shows repository statistics: Repositories Discovered (5), Repositories Migrated (0), Daily Average (“N/A”), and Overall Progress (“0.0%”). There is a new section below “Trends” called “By source”, and it has one source: joey-ado-testing (5). — Warp’s *Dashboard* page, after scanning for sources.

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:

Migration HQ’s "Issues" page, which contains 5 issues. — *Migration HQ*’s *Issues* page.

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...

Migration HQ’s "Issues" page, with the open issues list close up. — The open issues list, close up.

...you’ll see that each issue corresponds to a repository from your source. {% hint style="success" %} You’re so close now — it’s time to [start migrating!](/guides/quickstart/migrate-a-repository) {% endhint %} # Migrate a Repository Let’s migrate! ### 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.** {% hint style="info" %} Search for the 🛠️ emoji if you’d like to skim through this content while focusing on the steps you need to follow. {% endhint %} ### 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:

Migration HQ’s Issues page, with a close-up view of the open issues list. — *Migration HQ*’s *Issues* page, with a close-up view of 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:

The page for the TailwindTraders-Website issue. — The page for the *TailwindTraders-Website* issue.

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

The "Add a comment" box at the bottom of the page for the "TailwindTraders-Website" issue. — The *Add a comment* box at the bottom of the page for the *TailwindTraders-Website* issue.

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:

The comments section of the page for the TailwindTraders-Website issue. The first comment, by the user “AccordionGuy”, says “/migrate”. The follow-up comment, by the user “packfiles-warp”, says “@AccordionGuy, your migration’s in progress! We’ll let you know when it’s complete.” — The comments section of the page for the *TailwindTraders-Website* issue.

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:

The logs for the Warp Runner Agent. — The logs for the Warp Runner Agent, while the Agent is running.

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:

The logs for the Warp Runner Agent, after the Agent has completed its task.

🛠️ Click the **Actions** tab to return to the top level of the *Actions* page. You’ll see that the Runner Agent completed its tasks:

Migration HQ’s Actions page after the Warp Runner Agent has completed its task. — *Migration HQ*’s *Actions* page.

### 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:

Migration HQ’s "Issues" page, with the open issues list displayed. The open issues list displays 4 items. — *Migration HQ*’s *Issues* page — the open issues.

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:

Migration HQ’s "Issues" page, with the closed issues list displayed. The closed issues list displays 1 item. — *Migration HQ*’s *Issues* page — the closed issues.

🛠️ Click the issue to view its details:

You’ll see that the issue has been updated:

The updated page for the "TailwindTraders-Website" issue. Its content now indicates that the repository has been migrated. — The updated page for the *TailwindTraders-Website* issue.

🛠️ 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 newest comment on the "TailwindTraders-Website" issue page. The comment says "@AccordionGuy, your migration was successful. Visit your new code’s home at TailwindTraders.TailwindTraders-Website." — The newest comment on the *TailwindTraders-Website* issue page.

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:

The "Code" page for the migrated Tailwind-Traders repository. — The migrated Tailwind-Traders repository.

{% hint style="success" %} 🙌 Congratulations — you did it! 🙌 You successfully migrated a repository! {% endhint %} # Core Concepts Unpacking the Challenge of Migrations 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. # Velocity Speed at Your Own Pace # Visibility Communicate and Share Context # Collaboration Migrations are a Team Sport # Incremental Delivery Remove Bottlenecks, Increase Throughput # Roadmap Learn About Warp's Current and Future Capabilities ### Supported Use Cases #### Sources Warp currently supports migrating data from [Azure DevOps Services](/migrations/azure-devops) and [Bitbucket Server](/migrations/bitbucket-server). #### Destinations Warp currently supports migration to the following GitHub products: * [GitHub Enterprise Cloud](https://docs.github.com/en/enterprise-cloud@latest/admin/overview/about-github-enterprise-cloud) * [GitHub Enterprise Cloud with Enterprise Managed Users](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/about-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](https://github.com/enterprise/data-residency). # Azure DevOps Learn about Warp's Support for Azure DevOps Services

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](https://azure.microsoft.com/en-us/services/devops/migrate/) first. ### Repository Data Warp includes built in support for [data migrated by GitHub Enterprise Importer](https://docs.github.com/en/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/about-migrations-from-azure-devops-to-github-enterprise-cloud), 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](/migrations/azure-devops/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](/migrations/azure-devops/service-connections) for the Azure Pipelines GitHub App. ### Azure Boards If you have installed and connected the [Azure Boards GitHub App](https://learn.microsoft.com/en-us/azure/devops/boards/github/install-github-app?view=azure-devops) to your destination GitHub Organization, Warp can configure this integration for your migrated GitHub repositories with the [/integrate-boards](/using-warp/slash-commands/azure-devops/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](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-autolinks-to-reference-external-resources) feature with the [/autolink-work-items](/using-warp/slash-commands/azure-devops/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](/using-warp/slash-commands/azure-devops) 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](/using-warp/slash-commands). # Service Connections Warp Automatically Shares Service Connections for Azure Pipelines To facilitate the rewiring of Azure Pipelines, Warp automatically manages the sharing of [service connections](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/service-endpoints?view=azure-devops) for the [Azure Pipelines GitHub App](https://github.com/apps/azure-pipelines). Before rewiring Azure Pipelines, the service connection ID of the Azure Pipelines GitHub App must be configured in your Project's [Warp.yml](/using-warp/migration-hq/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.

A shared Azure Pipelines service connection created automatically by Warp. — A shared Azure Pipelines service connection created by Warp.

# Limitations Learn about Limitations for Data Migrated from Azure DevOps Services 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 **40 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. # Bitbucket Server Learn about Warp's Support for Bitbucket Server

This document provides an overview of Warp's capabilities for migrating data from Bitbucket Server to GitHub products. {% hint style="info" %} Warp does not provide a migration path for Bitbucket Cloud. Only Bitbucket Server is supported. {% endhint %} Warp includes built in support for [data migrated by GitHub Enterprise Importer](https://docs.github.com/en/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/about-migrations-from-azure-devops-to-github-enterprise-cloud), 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](/migrations/bitbucket-server/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](https://kb.packfiles.io/using-warp/slash-commands). # Limitations Learn about Limitations for Data Migrated from Bitbucket Server 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 **40 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. # Migration HQ Learn How Warp Organizes your Migration Processes

A Warp Project's "Migration HQ" page on GitHub. — The *Migration HQ* page.

**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***](/using-warp/migration-hq/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/v`ault.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. # Issues Where Warp stores its list of migrations 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:

"Every repository has its own issue" — diagram showing that for every repository in the source, Warp creates a corresponding issue in Migration HQ.

### 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:

The open issues list in the "Issues" page in Migration HQ. — The **open issues list** in the *Issues* page, which displays the Project repositories that have not 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:

The closed issues list in the "Issues" page in Migration HQ. — The **closed issues list** in the *Issues* page, which displays the Project’s migrated and ignored repositories.

**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:\\

The top-level heading for an issue: "[Azure DevOps] TailwindTraders-Website". The "Closed" indicator appears below the headline.

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:\\

The open issues list in the “Issues” page of Migration HQ. One of the issues is checked, and the user has the “Mark as” dropdown menu open and is selecting the “Completed” option. — Marking an issue as *Completed*, which will cause the repository to be ignored.

You can also manually close an issue on its own page — see [*Issue Page*](/using-warp/migration-hq/issues/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:

The closed issues list in the “Issues” page of Migration HQ. One of the issues is checked, and the user has the “Mark as” dropdown menu open and is selecting the “Open” option. — Marking an issue as *Open*, which makes it a candidate for migration again.

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. # Issue Page The interface for managing migrations. ### Overview

Warp creates an issue for each repository it finds at the source.

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...

Title of an issue for a repository that has not yet been migrated.

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

Title of an issue for a repository that has been migrated or ignored.

### 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*](/using-warp/migration-hq/issues)). ### Migration Status

The *Migration Status* section for an issue whose repository has not yet been migrated.

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.

The *Migration Status* section for an issue whose repository has been migrated.

### 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 for an issue whose repository has not yet been migrated.

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.

The *Source & Destination* section for an issue whose repository has been migrated.

### 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:

The *Inventory* section for an issue whose repository has been migrated.

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:

The *Inventory* section for an issue whose repository has not yet been migrated.

### 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](/using-warp/slash-commands). #### 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:

# Labels These help keep your migration projects organized.

Warp’s issue labels, as seen in a list of open issues.

Warp’s issue labels, as seen on an issue’s page.

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.yml Warp’s configuration file. 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: ```yaml # 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" #### # Repository Visibility #### # Controls the visibility of repositories created by Warp during migration. # # Options: # - "private" (default): Repositories are only visible to users with explicit access # - "internal": Repositories are visible to all members of your GitHub organization # # Note: This setting only affects NEW repositories created by Warp. It does not # modify the visibility of existing repositories. # # Uncomment target_repo_visibility and set to "internal" to make migrated repositories visible to # your entire GitHub enterprise organization: # # target_repo_visibility: "internal" #### # 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: # my-org-name: # You can also supply organization-specific defaults # 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, you can configure the visibility of migrated repositories or provide service connection IDs for Azure Pipelines rewiring. 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. ## Repository Visibility By default, Warp creates migrated repositories as **private**. If your organization uses GitHub Enterprise and you’d like migrated repositories to be visible to all organization members, you can set the `target_repo_visibility` option to `"internal"`. ```yaml target_repo_visibility: "internal" ``` The `target_repo_visibility` field accepts two values: * `"private"` (default) — only users with explicit access can see the repository * `"internal"` — all members of your GitHub organization can see the repository If the field is omitted or set to `"private"`, Warp uses its default behavior and creates private repositories. {% hint style="info" %} The `"internal"` visibility option requires a GitHub organization that supports internal repositories, such as [GitHub Enterprise Cloud](https://docs.github.com/en/enterprise-cloud@latest/admin/overview/about-github-enterprise-cloud) or GitHub Enterprise Server. This setting only affects **new** repositories created by Warp — it does not change the visibility of repositories that have already been migrated. {% endhint %} ## Advanced Configuration Beyond basic setup, `warp.yml` supports several advanced features that let you customize your migration workflows. ### Custom Scripts Define custom automation scripts in your Migration HQ’s `bin/` directory and execute them from issue comments using the `/run` slash command. Warp supports Bash, PowerShell, Ruby, and Python scripts with configurable arguments and optional Vault access. [Learn more about Custom Scripts](/using-warp/migration-hq/custom-scripts) ### Access Policies Control who can execute slash commands and perform actions on backlog entry issues. Policies use an opt-in security model — when defined, only explicitly approved users and teams can perform the configured actions. [Learn more about Access Policies](/using-warp/migration-hq/access-policies) ### Custom Tasks Add reusable checklists and task content to issues based on labels. Custom tasks are automatically injected into or removed from issue descriptions when matching labels are added or removed. [Learn more about Custom Tasks](/using-warp/migration-hq/custom-tasks) # Custom Scripts Extend Warp with custom automation scripts. Custom Scripts let you define automation scripts in your Migration HQ repository and execute them directly from issue comments using the [`/run`](/using-warp/slash-commands/global/run) slash command. Use them to automate repetitive tasks, integrate with external systems, or extend your migration workflows. **How it works:** 1. Write a script and place it in the `bin/` directory of your Migration HQ repository 2. Register the script in your `warp.yml` configuration file 3. Execute it from any backlog entry issue with `/run ` Warp supports **Bash**, **PowerShell**, **Ruby**, and **Python** scripts. ## Prerequisites Before using Custom Scripts, ensure you have: * Admin access to your Migration HQ repository * Scripts stored in the `bin/` directory at the root of Migration HQ * Scripts marked as executable (`chmod +x bin/your_script.sh`) * A valid `warp.yml` configuration in the `config/` directory ## Configuration Define scripts in your `warp.yml` file under the `scripts:` key. Each script entry uses a unique identifier as its key. ### Required Fields | Field | Type | Description | | ------------- | ------ | ------------------------------------------------------------ | | `name` | String | Human-friendly name displayed in responses and help messages | | `description` | String | Brief explanation of what the script does | | `language` | String | Script language: `bash`, `pwsh`, `python`, or `ruby` | | `filename` | String | Name of the script file in the `bin/` directory | ### Optional Fields | Field | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------ | | `allow_vault` | Boolean | When `true`, injects `PKFS_MASTER_KEY` into the script's environment | | `arguments` | Object | Named arguments the script accepts (see [Script Arguments](#script-arguments)) | ### Basic Example ```yaml version: "1.0" scripts: notify_team: name: "Notify Team" description: "Send a notification to the team channel" language: bash filename: "notify_team.sh" allow_vault: false ``` With the corresponding script at `bin/notify_team.sh`: ```bash #!/bin/bash set -e echo "Notifying team about migration for ${WARP_BACKLOG_ENTRY_SOURCE}" # Add your notification logic here ``` Execute it from an issue comment: ``` /run notify_team ``` ## Script Arguments Scripts can accept named arguments that are validated by Warp before execution. ### Defining Arguments Add an `arguments` block to your script configuration. Each argument has a `description` (required) and an optional `required` flag. ```yaml scripts: update_wiki: name: "Update Wiki" description: "Update the migration wiki page" language: ruby filename: "update_wiki.rb" allow_vault: false arguments: wiki_page: description: "The wiki page to update" required: true status: description: "Current migration status" required: true notify: description: "Send a notification after updating" ``` Arguments without `required: true` are optional. ### Passing Arguments at Runtime Use the `--script_args` flag followed by space-separated `key=value` pairs: ``` /run update_wiki --script_args wiki_page=migrations status=in_progress ``` Boolean flags are also supported — they set the argument value to `"true"`: ``` /run update_wiki --script_args wiki_page=migrations status=in_progress notify ``` {% hint style="info" %} Warp validates arguments before executing your script. Missing required arguments or unrecognized argument names will produce an error message — your script will not run. {% endhint %} ### How Arguments Are Delivered Arguments are passed to your script as environment variables with the prefix `WARP_SCRIPT_ARGS__`, followed by the argument name converted to uppercase with non-alphanumeric characters replaced by underscores. **Examples:** | Argument Name | Environment Variable | | ------------- | ----------------------------- | | `wiki_page` | `WARP_SCRIPT_ARGS__WIKI_PAGE` | | `tenant-id` | `WARP_SCRIPT_ARGS__TENANT_ID` | | `db.url` | `WARP_SCRIPT_ARGS__DB_URL` | ## Environment Variables Warp injects the following environment variables into every script execution: | Variable | Description | Always Available | | -------------------------------- | ----------------------------------------------- | ----------------------------- | | `WARP_SCRIPT_ID` | The script's identifier from `warp.yml` | Yes | | `WARP_SCRIPT_NAME` | The script's human-friendly name | Yes | | `WARP_SCRIPT_DESCRIPTION` | The script's description | Yes | | `WARP_SCRIPT_ARGS__` | Value for each provided argument | Yes (one per argument) | | `WARP_PROJECT_ID` | The Warp project ID | Yes | | `WARP_BACKLOG_ENTRY_ID` | The backlog entry (issue) ID | Yes | | `WARP_BACKLOG_ENTRY_DESTINATION` | The target repository name | Yes | | `WARP_BACKLOG_ENTRY_SOURCE` | The source repository name | Yes | | `PKFS_MASTER_KEY` | The Vault master key for decrypting credentials | Only when `allow_vault: true` | ## Vault Integration When `allow_vault` is set to `true`, Warp injects the `PKFS_MASTER_KEY` environment variable into your script's execution environment. This allows your script to decrypt and query credentials stored in your Warp Vault. ```yaml scripts: sync_repos: name: "Sync Repositories" description: "Sync repository settings using source credentials" language: bash filename: "sync_repos.sh" allow_vault: true ``` Your script can then use the Warp CLI to query vault credentials: ```bash #!/bin/bash set -e export BBS_USERNAME=$(gh warp vault get '(type:bitbucketserver).credentials.username') export BBS_PASSWORD=$(gh warp vault get '(type:bitbucketserver).credentials.password') echo "Syncing with Bitbucket Server as ${BBS_USERNAME}" # Add your sync logic here ``` {% hint style="warning" %} Enabling `allow_vault` gives the script access to **all credentials** in your Vault. Only enable this for scripts that require credential access. {% endhint %} For details on the Vault query syntax, see [Using Credentials in Scripts](/using-warp/warp-vault/using-credentials-in-scripts). ## Script Examples by Language ### Bash ```bash #!/bin/bash set -e repo_name="${WARP_BACKLOG_ENTRY_DESTINATION}" source_name="${WARP_BACKLOG_ENTRY_SOURCE}" gh_username="${WARP_SCRIPT_ARGS__GH_USERNAME}" echo "Validating repository: ${repo_name} for user: ${gh_username}" gh repo view "${gh_username}/${repo_name}" --json name,isPrivate,visibility ``` ### PowerShell ```powershell #!/usr/bin/env pwsh param() $RepoName = $env:WARP_BACKLOG_ENTRY_DESTINATION $ReportType = $env:WARP_SCRIPT_ARGS__REPORT_TYPE $OutputPath = $env:WARP_SCRIPT_ARGS__OUTPUT_PATH Write-Host "Generating $ReportType report for $RepoName to $OutputPath" # Add your report generation logic here ``` ### Ruby ```ruby #!/usr/bin/env ruby require "bundler/inline" gemfile do source "https://rubygems.org" gem "octokit" end require "octokit" source_repo = ENV["WARP_BACKLOG_ENTRY_SOURCE"] destination_repo = ENV["WARP_BACKLOG_ENTRY_DESTINATION"] owner = ENV["WARP_SCRIPT_ARGS__OWNER"] puts "Syncing labels from #{source_repo} to #{destination_repo} for #{owner}" # Add your label sync logic here ``` ### Python ```python #!/usr/bin/env python3 import os import sys migration_id = os.getenv("WARP_BACKLOG_ENTRY_ID", "unknown") metric_type = os.getenv("WARP_SCRIPT_ARGS__METRIC_TYPE", "commits") print(f"Analyzing {metric_type} for migration: {migration_id}") # Add your analysis logic here ``` ## Access Control Script execution can be restricted using policies in your `warp.yml`. Define a `policies.scripts` block to control who can run each script. ```yaml policies: scripts: sync_repos: teams: ["release-engineering", "dev-ops"] users: ["migration-admin"] ``` When a script policy is defined, only the listed users and teams can execute that script. Users not on the list will see an error message listing who is authorized. When no script policies are defined, all organization members can run all scripts. ## Execution Custom scripts run on a GitHub Actions runner agent within your Migration HQ repository. When a script completes, Warp automatically posts a comment on the issue: * **On success:** A confirmation message with a link to the workflow run * **On failure:** An error message with the exit code and a link to the workflow run logs You can view detailed logs by navigating to the **Actions** tab of your Migration HQ repository and selecting the workflow run. For more information on viewing runner logs, see [Runner Agent](/using-warp/migration-hq/runner-agent). ## Running a Script To execute a custom script, post a comment on a backlog entry issue using the [`/run`](/using-warp/slash-commands/global/run) slash command: ``` /run [--script_args key=value ...] ``` See the [`/run` command reference](/using-warp/slash-commands/global/run) for full usage details. ## Best Practices 1. **Add shebang lines** — Always include `#!/bin/bash`, `#!/usr/bin/env ruby`, etc. at the top of your scripts 2. **Make scripts executable** — Run `chmod +x bin/your_script.sh` before committing 3. **Validate inputs** — Check for required data and provide helpful error messages 4. **Use descriptive names** — Choose clear script identifiers and file names 5. **Document arguments** — Write clear descriptions for each argument in `warp.yml` 6. **Handle errors gracefully** — Use proper exit codes (`set -e` in Bash) and error handling 7. **Test locally first** — Verify scripts work before adding them to `warp.yml` 8. **Keep scripts focused** — Each script should do one thing well ## Troubleshooting | Issue | Solution | | --------------------- | --------------------------------------------------------------------------------------------------------- | | Script not found | Verify the `filename` in `warp.yml` matches the actual file in `bin/` | | Permission denied | Make the script executable: `chmod +x bin/your_script.sh` and commit | | Arguments not working | Use `--script_args key=value` format. Check that argument names match the `arguments` block in `warp.yml` | | Script fails silently | Add error handling and logging to your script. Use `set -e` in Bash scripts | | Unauthorized | Check `policies.scripts` in `warp.yml` and verify your username or team membership | | Script not available | Ensure `warp.yml` has been committed and pushed to your Migration HQ's default branch | # Custom Tasks Define reusable checklists that appear automatically on issues. ### Overview Custom tasks let you define reusable checklists in `warp.yml` that Warp automatically injects into issue descriptions. Tasks can target specific issues by label, or appear on every issue in your project. Custom tasks are configured in your project's `warp.yml` file. For general information about `warp.yml`, see [Warp.yml](/using-warp/migration-hq/warp.yml). ### Configuration Each custom task is defined under the `custom_tasks` block in `warp.yml`. A task entry requires: * A **unique identifier** (the YAML key) — used internally to reference the task * `title` — the display heading that appears in the issue body * `body` — the task content, supporting full Markdown including checklists * `labels` (optional) — an array of label names that control when this task appears ```yaml custom_tasks: my_task_id: # unique identifier title: "My Task" # display heading body: | # supports Markdown - [ ] Step one - [ ] Step two labels: ["my-label"] # optional — omit for global tasks ``` ### Label-Specific Tasks When a task includes a `labels` array, it only appears on issues that have at least one of those labels assigned. Label matching is case-insensitive. ```yaml custom_tasks: migration_kickoff: title: "Migration Kickoff Checklist" body: | - [ ] Schedule kickoff meeting with stakeholders - [ ] Review source repository structure - [ ] Identify dependencies and blockers - [ ] Create migration timeline labels: ["migration", "kickoff"] ``` In this example, the checklist appears when either the `migration` or `kickoff` label is added to an issue. ### Global Tasks Tasks defined without a `labels` key appear on every issue in the project. These are useful for checklists that apply universally, such as compliance or security reviews. ```yaml custom_tasks: security_review: title: "Security Review" body: | - [ ] Review code for security vulnerabilities - [ ] Check for exposed credentials - [ ] Validate input sanitization ``` ### Dynamic Injection Warp automatically manages custom task content in issue descriptions: 1. **Adding a label** — When you add a label to an issue that matches a custom task's `labels` configuration, Warp updates the issue body to include the matching task content. 2. **Removing a label** — When you remove a label, Warp removes the corresponding task content from the issue body. Custom tasks appear in the issue body under a **Tasks From Your Organization** heading, with each task rendered as a subsection using its `title` as the heading and its `body` content displayed verbatim (including any Markdown checklists). > **Important:** Warp manages the issue body automatically. If you manually edit the issue description, your changes may be overwritten the next time labels are added to or removed from that issue. This ensures that custom task content stays synchronized with the issue's labels. ### Multiple Tasks Example You can define multiple tasks with different label triggers. This example combines label-specific and global tasks: ```yaml custom_tasks: frontend_checklist: title: "Frontend Development" body: | - [ ] Implement responsive design - [ ] Test across browsers - [ ] Optimize performance labels: ["frontend", "ui"] backend_checklist: title: "Backend Development" body: | - [ ] Design API endpoints - [ ] Implement data validation - [ ] Write unit tests labels: ["backend", "api"] compliance_review: title: "Compliance Review" body: | - [ ] Verify licensing requirements - [ ] Check data handling policies # No labels — appears on all issues ``` # Access Policies Control who can execute commands with issue and slash command policies. Access policies let you control who can run Warp commands in your *Migration HQ* repository. You configure them in the `policies` section of your [`warp.yml`](/using-warp/migration-hq/warp.yml) file. ## How Policies Work Warp uses an **opt-in security model**. By default — when no policies are defined — all organization members have full access to run any command. Once you define a policy, Warp switches to a restrictive mode where **only the users and teams you specify are allowed to act**. This means: * **No policies defined:** All organization members can run all commands. * **Policies defined:** Only explicitly approved users and teams can run commands that match a policy. There are two types of policies: **issue policies** and **slash command policies**. You can use them independently or together. ## Issue Policies Issue policies control who can run slash commands on Backlog Issues based on the issue's labels. Define them under `policies.issues` in your `warp.yml`. ### How Label Matching Works 1. When a user runs a command on an issue, Warp checks the issue's labels against your configured policies. 2. If any labels match, only the users and teams listed in matching policies can run the command. 3. If no labels match any issue policy, then no access is granted to that issue by issue policies; the command can still run only if a matching slash command policy explicitly allows it. Each issue policy has: * **A unique identifier** — an internal reference name for the policy. * **`labels`** (optional) — a list of issue labels that trigger this policy. If omitted, the policy applies globally to all issues. * **`teams`** (optional) — GitHub team slugs granted access. * **`users`** (optional) — GitHub usernames granted access. When multiple policies match an issue (through overlapping labels or a global policy), their allowed users and teams are **combined** — a user permitted by any matching policy is allowed. ### Example: Limit Access by Label Restrict commands on issues labeled with a specific Azure DevOps (ADO) team to only members of the corresponding GitHub team: ```yaml policies: issues: onboarding: labels: ["ado:team:catball-inc"] teams: ["catball-inc-team"] users: ["chaserx", "johndoe"] ``` In this example, only members of the `catball-inc-team` GitHub team and the users `chaserx` and `johndoe` can run commands on issues that have the `ado:team:catball-inc` label. ### Example: Grant Global Access Create a policy without labels to grant access across all issues, regardless of their labels: ```yaml policies: issues: global_access: teams: ["release-engineering", "dev-ops"] users: ["admin-user"] ``` This gives the `release-engineering` and `dev-ops` teams, along with `admin-user`, access to run commands on every issue. ### Combining Label and Global Policies You can define both label-specific and global policies. When an issue is evaluated, Warp combines the allowed users and teams from all matching policies — including any global policy — to determine access. ```yaml policies: issues: global_access: teams: ["release-engineering"] platform_team: labels: ["ado:team:platform"] teams: ["platform-engineering"] users: ["team-lead"] ``` For an issue labeled `ado:team:platform`, both the `release-engineering` team (from the global policy) and the `platform-engineering` team and `team-lead` user (from the label-specific policy) are allowed. ## Slash Command Policies Slash command policies control access to specific commands across all issues. Define them under `policies.slash_commands` in your `warp.yml`. > **Important:** When you define any slash command policy, Warp denies access to all commands by default. Only the commands you explicitly configure are available. Each slash command policy is keyed by the command name (starting with `/`) and specifies which teams and users can run it. ### Example: Restrict a Single Command ```yaml policies: slash_commands: /migrate: teams: ["release-engineering"] users: ["chaserx"] ``` Only members of `release-engineering` and the user `chaserx` can run `/migrate`. All other slash commands are denied because a slash command policy is defined. ### Example: Configure Multiple Commands ```yaml policies: slash_commands: /help: teams: ["all-staff"] /migrate: teams: ["release-engineering"] users: ["chaserx", "migration-bot"] /rename-destination: teams: ["release-engineering", "dev-ops"] /rewire-pipeline: teams: ["dev-ops"] users: ["pipeline-admin"] /add-team: teams: ["org-admins"] ``` Each command has its own access list. Commands not listed here are unavailable when any slash command policy is defined. ## Policy Precedence When both issue policies and slash command policies are defined, Warp evaluates them in order: 1. **Issue policies** are evaluated first based on the issue's labels. 2. **Slash command policies** are evaluated second based on the command name. 3. **Access is granted** if either policy allows the user. This means a user who is permitted by an issue policy can run a command even if they are not listed in the slash command policy for that command, and vice versa. ## Important Notes * **Policy identifiers must be unique.** Each issue policy needs a distinct key (e.g., `onboarding`, `global_access`). Duplicate keys will cause one to overwrite the other. * **Team slugs and usernames are case-sensitive.** Make sure they exactly match the GitHub team slug and username. For example, `Release-Engineering` is not the same as `release-engineering`. * **Defining any policy activates restriction.** Adding even one issue policy means all issues are subject to policy checks. Adding even one slash command policy means all commands default to denied unless explicitly allowed. ## Complete Example Here is a full `warp.yml` demonstrating both issue and slash command policies: ```yaml version: "1.0" policies: issues: # Global: release engineering can act on any issue release_team_access: teams: ["release-engineering"] users: ["sr-engineer"] # Label-specific: only the platform team can act on platform issues platform_team: labels: ["ado:team:platform", "ado:team:infrastructure"] teams: ["platform-engineering"] users: ["team-lead"] # Label-specific: sensitive operations require senior approval sensitive_ops: labels: ["production", "critical"] teams: ["senior-engineers"] users: ["vp-engineering"] slash_commands: /help: teams: ["all-contributors"] /migrate: teams: ["release-engineering", "dev-ops"] users: ["migration-specialist"] /rename-destination: teams: ["release-engineering"] /add-team: users: ["org-admin"] ``` # Warpspaces GitHub Codespaces...but with Warp! ### 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 during the initialization process.

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:

# Runner Agent How Warp does what it does. ### 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**. # GitHub Copilot Agent Get Help Anytime with Warp's GitHub Copilot Agent **The *****Packfiles GitHub Copilot Agent***** is an AI agent built into the Packfiles Warp app that helps you plan, execute, and troubleshoot migrations without leaving GitHub.** Instead of consulting documentation, manually reviewing repository inventories, or reading runner logs to decode a failure, you can work directly with the agent in the places where migration work already happens: the *Migration HQ* Agents tab, a backlog issue, or a pull request. ## Prerequisites Before using the *Packfiles GitHub Copilot Agent*, **ensure that**: * Your *Migration HQ* repository has been initialized by Warp and a source scan has completed successfully, so that backlog issues have been created for your repositories * GitHub Copilot is enabled for your organization * Packfiles Warp App is installed on your Migration HQ organization * You complete the setup steps outlined below to give the agent the necessary permissions to operate in your Migration HQ repository ### Setup To configure the agent for your Migration HQ repository: 1. Add the following GitHub MCP configuration under `Migration-HQ → Settings → Code & automation → Copilot → Coding agent`: ```json { "mcpServers": { "github-mcp-server": { "type": "http", "url": "https://api.githubcopilot.com/mcp", "tools": ["*"], "headers": { "X-MCP-Toolsets": "issues,pull_requests,repos,actions" } } } } ``` Ensure you've saved the configuration before proceeding to the next step. 2. Create a fine-grained PAT with: * **Issues**: read+write * **Pull requests**: read+write on the `Migration-HQ` repository only. 3. Add the PAT as a secret named `COPILOT_MCP_GITHUB_PERSONAL_ACCESS_TOKEN` in the `Migration-HQ` repository under `Settings → Secrets and variables → Agents`. 4. Follow the instructions in the [GitHub documentation](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/enable-copilot-cloud-agent#enabling-agent-apps-and-third-party-agents) to enable agent apps at the Enterprise level. This setup allows the agent to make diagnostic comments on backlog issues and pull requests, and to create new wave labels for migration planning. For more information on the agent's capabilities and how to invoke them, see the next section. ## What the Agent Can Do The *Packfiles GitHub Copilot Agent* has three capabilities, each invoked from a different entry point in *Migration HQ*: | Capability | Where to invoke it | What it does | | -------------------------------------------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | [**Migration Planning**](/using-warp/migration-hq/github-copilot-agent/migration-planning) | Agents tab | Reads your backlog issues, scores every repository, assigns migration waves, applies wave labels, and produces a complete migration strategy document | | [**Migration Diagnosis**](/using-warp/migration-hq/github-copilot-agent/migration-diagnosis) | Assign a failed backlog issue to the agent | Identifies the root cause of a failure and posts a remediation plan | | [**Validate Configuration**](/using-warp/migration-hq/github-copilot-agent/validate-configuration) | Pull request comment | Reads a `config/warp.yml` diff, validates the configuration against Warp's schema, and posts a structured findings report | The agent supports both **Azure DevOps** and **Bitbucket Server** migrations, including projects with a mix of both sources. ## Further Reading * [Migration Planning](/using-warp/migration-hq/github-copilot-agent/migration-planning) — Plan your migration waves and generate a strategy document * [Migration Diagnosis](/using-warp/migration-hq/github-copilot-agent/migration-diagnosis) — Diagnose and fix failed migrations * [Validate Configuration](/using-warp/migration-hq/github-copilot-agent/validate-configuration) — Validate and author `config/warp.yml` changes # Migration Planning Plan your migration waves and generate a strategy document **The *****Migration Planning***** skill reads every open backlog issue in your *****Migration HQ*****, scores each repository, assigns it to a migration wave, applies wave labels to the issues, and produces a migration strategy document all in a single step from the *****Agents***** tab.** If you're starting a migration and need to understand the scope, sequence, and timeline of the work ahead, this is where to begin. ## How to Use It 1. Navigate to the **Agents** tab in your *Migration HQ* repository. 2. Select **Packfiles Warp** from the dropdown list of available agents. 3. Type a request such as: *"Plan my migration."* The agent reads all open backlog issues, scores each repository, and delivers a complete strategy document with wave assignments for each repository (typically completes within a few minutes, depending on the size of your backlog). {% hint style="info" %} The agent reads from your existing backlog issues. Make sure you have scanned your sources and that repositories appear as open issues in *Migration HQ* before running planning. {% endhint %} ## What the Agent Analyzes For each backlog issue, the agent reads: * **Repository size** * **Commit activity** * **Pull request count** * **Pipeline count** — Azure DevOps only * **Source platform** * **Organization and team** * **Size flags** — from the `too-big` label (repository exceeds 10 GB) No CSV files or external data sources are required. The agent works entirely from the information already in your backlog. ## How Repositories Are Scored Each repository receives a **Migration Compatibility Score** from 0 to 11, made up of three components: **Size Score (0–5 points)** | Repository Size | Points | | --------------- | ----------------------------- | | Less than 10 MB | 5 | | 10 MB – 100 MB | 4 | | 100 MB – 500 MB | 3 | | 500 MB – 5 GB | 2 | | 5 GB – 40 GB | 1 | | 40 GB or larger | 0 — exceeds Warp's size limit | **Activity Score (0–3 points)**, based on commits in the past year: | Commit Activity | Points | | --------------------- | ------ | | 0 commits | 3 | | 1–10 commits | 2 | | 11–100 commits | 1 | | More than 100 commits | 0 | **Simplicity Score (0–3 points)**, based on pull request count. For Azure DevOps repositories, pipeline count is also considered: | Condition | Points | | ---------------------------------------------------- | ------ | | 0 PRs (and ≤ 1 pipeline for ADO) | 3 | | ≤ 10 PRs (and ≤ 3 pipelines for ADO) | 2 | | ≤ 50 PRs (and ≤ 10 pipelines for ADO) | 1 | | More than 50 PRs (or more than 10 pipelines for ADO) | 0 | {% hint style="info" %} Bitbucket Server repositories are scored on pull request count only — Bitbucket Server does not have pipelines managed through Warp. {% endhint %} ## Migration Waves Based on the total score, each repository is assigned to one of four migration waves: | Wave | Score | Risk Level | Description | | ------------- | ----- | -------------- | ------------------------------------------------------ | | Wave 1 | 9–11 | Low Risk | Small, inactive or low-activity, simple repositories | | Wave 2 | 6–8 | Medium Risk | Standard repositories with moderate complexity | | Wave 3 | 3–5 | High Risk | Larger or more complex repositories requiring planning | | Manual Review | 0–2 | Very High Risk | Requires individual assessment before migration | **Override conditions** — regardless of score, a repository is placed in Manual Review if: * Its size is 40 GB or larger (exceeds Warp's absolute size limit) * It has more than 10 pipelines (Azure DevOps only) ## Wave Labels After computing wave assignments, the agent automatically applies a `planning:wave-N` label to each backlog issue. These labels appear in the *Migration HQ* issue list and can be used to filter issues by wave. | Wave | Label | | ------------- | ------------------------ | | Wave 1 | `planning:wave-1` | | Wave 2 | `planning:wave-2` | | Wave 3 | `planning:wave-3` | | Manual Review | `planning:manual-review` | ## The Migration Strategy Document The agent produces a markdown document covering: 1. **Executive Summary** — total repositories, wave distribution, and estimated duration 2. **Repository Inventory Overview** — breakdown by organization, project, and size band 3. **Repository Scoring and Wave Assignment** — scoring methodology and wave summary tables 4. **Migration Wave Strategy** — per-wave details and timeline 5. **Repository Size Analysis** — top 10 largest repositories and size risk assessment 6. **Warp Limitations and Considerations** — what data is and is not migrated 7. **Risk Assessment** — a risk register derived from your actual inventory 8. **Pre-Migration Checklist** — actionable setup steps 9. **Post-Migration Actions** — slash command reference for your source platform 10. **Licensing and Capacity Planning** — capacity recommendation based on your repository count 11. **Key Resources** — links to documentation, support, etc If your migration includes both Azure DevOps and Bitbucket Server repositories, the document presents a combined view with provider-specific sections where the two platforms differ. # Migration Diagnosis Diagnose and fix failed migrations **When a migration fails, use the *****Diagnose Migration***** skill to classify the root cause and post a structured remediation plan as a comment on the issue so your team knows exactly what went wrong and what to do next.** Migration failures can be opaque. A comment on a backlog issue might say "migration failed" and link to a runner log with hundreds of lines. The agent cuts through that noise by reading the evidence and surfacing only what matters. ## How to Use It 1. Open the backlog issue in Migration HQ for the repository whose migration has failed. 2. Assign the issue to the **Packfiles Warp** agent with the instructions: *"Diagnose the migration failure."* The agent categorizes the failure and posts a diagnosis comment directly on the issue. ## What the Diagnosis Contains The agent posts a comment on the issue with: * **Root cause** — a single sentence stating what went wrong * **Remediation steps** — a numbered list of specific actions to resolve the issue, including any Warp Vault changes, slash commands, or source system changes needed * **Retry instruction** — the exact comment to post on the issue to retry the migration once remediation is complete For most failure categories, the retry instruction is simply `/migrate`. {% hint style="warning" %} The `too-big` label (applied by Warp when a repository exceeds 10 GB) is always addressed in the diagnosis, even if another failure category is the primary cause. Size issues are a hard blocker that must be resolved regardless of what else is failing. {% endhint %} # Validate Configuration Validate and review config/warp.yml changes in pull requests **The *****Validate Configuration***** skill reads your `config/warp.yml`, validates it against Warp's configuration schema, and posts a structured findings report so you can merge configuration changes with confidence.** Warp's configuration file supports a range of settings: repository visibility, Azure Pipelines rewiring, access policies, custom task checklists, and scripts. As configurations grow more complex, it becomes easy to introduce errors that only surface at runtime. The agent catches those issues before they do. ## How to Use It 1. Open a pull request that modifies `config/warp.yml`. 2. Post a comment on the pull request mentioning the **Packfiles Warp** agent and ask it to *"validate the configuration."* #### Example: > *"@packfiles-warp Can you validate the config changes in this PR?"* The agent reads the current contents of `config/warp.yml` from the pull request's branch, validates it, and posts a review comment on the pull request with its findings. ## Finding Severity Levels Each finding in the report is assigned one of three severity levels: * **✅ Valid** — the configuration is correct and there are no concerns * **⚠️ Warning** — the configuration is syntactically valid, but has implications worth reviewing before merging * **❌ Error** — the configuration is incorrect or will prevent Warp from working as intended; must be fixed before merging ## Security Checks Beyond schema validation, the agent flags configuration changes that could have security implications. These are surfaced as warnings rather than errors, since they may be intentional. The report explains the implication so you can make an informed decision before merging. ## Further Reading * [Warp.yml](/using-warp/migration-hq/warp.yml) — Full configuration reference * [Access Policies](/using-warp/migration-hq/access-policies) — How to configure slash command and issue policies * [Custom Tasks](/using-warp/migration-hq/custom-tasks) — How to define label-triggered checklists * [Custom Scripts](/using-warp/migration-hq/custom-scripts) — How to register and run automation scripts # Projects How Warp organizes migration engagements ### 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. # Dashboard Provides a high-level overview of the migration Project.

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 display 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. # Team View and manage the people authorized to have access to the Project.

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: | Permission to... | Viewer | Admin | | ------------------------------------------------------------------- | ------ | ----- | | View reports | ✅ | ✅ | | Manage Team members and roles | ❌ | ✅ | | Manage billing and licensing | ❌ | ✅ | | Manage connection of Warp to source environments | ❌ | ✅ | | Delete projects | ❌ | ✅ | | Get product support from Packfiles / migration support from partner | ✅ | ✅ | 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. # Capacity View and manage the number of migrations you can perform.

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.\ \&#xNAN;*(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.\ \&#xNAN;*(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:

Size	Capacity	Price	Cost Per Migration
Small Box	100 migrations	$2,000 USD	$20/repository
Medium Box	1,000 migrations	$15,000 USD	$15/repository

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! # Slash Commands # Global # /help ## Description Summons documentation for any available slash command. [View in Knowledge Base](https://kb.packfiles.io/using-warp/slash-commands/global/help) ## Examples ### With Named Arguments: ``` /help --command-name ``` ### With Positional Arguments: ``` /help ``` ## 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. # /run ## Description Executes a [custom script](/using-warp/migration-hq/custom-scripts) defined in your project's `warp.yml` configuration file. Scripts run on a GitHub Actions runner agent and results are posted as a comment on the issue. [View in Knowledge Base](https://kb.packfiles.io/using-warp/slash-commands/global/run) ## Examples ### Basic (no arguments): ``` /run notify_team ``` ### With Arguments: ``` /run update_wiki --script_args wiki_page=migrations status=in_progress owner=chaserx ``` ### With Boolean Flags: ``` /run cleanup --script_args target=logs dry_run ``` ## Arguments ### script\_id (Required) * The identifier of the script to run, as defined in your project's `warp.yml` configuration under the `scripts:` key. **Value:** * Must match a script identifier configured in `warp.yml`. ### --script\_args (Optional) * Arguments to pass to the script. Provide space-separated `key=value` pairs after the `--script_args` flag. Boolean flags (without a value) are set to `"true"`. **Value:** * Space-separated `key=value` pairs. * Arguments must match those defined in the script's `arguments` configuration in `warp.yml`. Unknown arguments are rejected. * Required arguments (as configured in `warp.yml`) must be provided. ## Authorization * When script policies are configured in `warp.yml` under `policies.scripts`, only the listed users and teams can execute the script. * When no script policies are defined, all members of the repository’s organization can run all scripts. See [Custom Scripts](/using-warp/migration-hq/custom-scripts) for configuration details. # Migration # /migrate ## Description Migrates a repository [View in Knowledge Base](https://kb.packfiles.io/using-warp/slash-commands/migration/migrate) ## Example ``` /migrate ``` ## Authorization * Not required. # /rename-destination ## Description Changes the name of the destination GitHub repository [View in Knowledge Base](https://kb.packfiles.io/using-warp/slash-commands/migration/rename-destination) ## Examples ### With Named Arguments: ``` /rename-destination --new-name ``` ### With Positional Arguments: ``` /rename-destination ``` ## 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. # Backlog Issue # /refresh ## Description Quickly refreshes the content of a Backlog Entry issue. [View in Knowledge Base](https://kb.packfiles.io/using-warp/slash-commands/backlog-issue/refresh) ## Example ``` /refresh ``` ## Authorization * Not required. # Azure DevOps Slash Commands for Azure DevOps Slash commands in this section are supported for Azure DevOps repositories. To learn more about Warp's support for Azure DevOps, refer [our documentation ](/migrations/azure-devops)in the migrations section. # /rewire-pipeline ## Description Rewires an Azure DevOps Pipeline [View in Knowledge Base](https://kb.packfiles.io/using-warp/slash-commands/azure-devops/rewire-pipeline) ## Examples ### With Named Arguments: ``` /rewire-pipeline --id [--again] ``` ### With Positional Arguments: ``` /rewire-pipeline [--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. # /rewire-all-pipelines ## Description Rewires all Azure Pipelines associated with this repository. [View in Knowledge Base](https://kb.packfiles.io/using-warp/slash-commands/azure-devops/rewire-all-pipelines) ## 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. # /integrate-boards ## Description Configures an integration between Azure Boards and the destination GitHub repository. [View in Knowledge Base](https://kb.packfiles.io/using-warp/slash-commands/azure-devops/integrate-boards) {% hint style="warning" %} ADO now rejects GitHub Personal Access Tokens (PAT) with any extra scopes during ADO Boards integration. The GitHub destination PAT (which needs broad scopes) is fundamentally incompatible with the `integrate-boards` command. A possible workaround: 1. Create or use an existing GitHub App connection in ADO (Project Settings > GitHub Connections), created via the OAuth flow. 2. Call the [ADO Boards GitHub Connections API](https://learn.microsoft.com/en-us/rest/api/azure/devops/wit/github-connections/update?view=azure-devops-rest-7.2\&tabs=HTTP) update endpoint directly to add the repo using a POST request to: `https://dev.azure.com/{org}/{project}/_apis/githubconnections/{connectionId}/repos?api-version=7.1-preview.1` **Key details**: * You cannot send plain strings. * `gitHubRepositoryUrls` in the [request body](https://learn.microsoft.com/en-us/rest/api/azure/devops/wit/github-connections/update?view=azure-devops-rest-7.2\&tabs=HTTP#request-body) **must** be an array of objects (each with a `gitHubRepositoryUrl` property) and `operationType` must be `add`. ```json { "gitHubRepositoryUrls": [ { "gitHubRepositoryUrl": "https://github.com/test-account/repo1" }, { "gitHubRepositoryUrl": "https://github.com/test-account/repo2" }, { "gitHubRepositoryUrl": "https://github.com/test-account/repo3" }, { "gitHubRepositoryUrl": "https://github.com/test-account/repo399" } ], "operationType": "add" } ``` See this [Sample Request](https://learn.microsoft.com/en-us/rest/api/azure/devops/wit/github-connections/update?view=azure-devops-rest-7.2\&tabs=HTTP#add-list-of-repos-to-the-specified-github-connection) {% endhint %} ## Example ``` /integrate-boards ``` ## Authorization * Not required. # /autolink-work-items ## Description Configures Autolink References in the destination GitHub repository so that references to Azure Boards work items become clickable hyperlinks. [View in Knowledge Base](https://kb.packfiles.io/using-warp/slash-commands/azure-devops/autolink-work-items) ## Example ``` /autolink-work-items ``` ## Authorization * Not required. ## Code Examples ### TypeScript ```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 ```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 ```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 ```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 ```rust struct WorkItem { id: u32, title: String, } fn autolink_work_items(items: Vec) { 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); } ``` # /lock-ado-repo ## Description Makes the source Azure DevOps repository read-only for all users. [View in Knowledge Base](https://kb.packfiles.io/using-warp/slash-commands/azure-devops/lock-ado-repo) ## Example ``` /lock-ado-repo ``` ## Authorization * Not required. # /disable-ado-repo ## Description Disables the source Azure DevOps repository for all users. [View in Knowledge Base](https://kb.packfiles.io/using-warp/slash-commands/azure-devops/disable-ado-repo) ## Example ``` /disable-ado-repo ``` ## Authorization * Not required. # GitHub # /add-team ## Description Adds a given team to the migrated repository in GitHub with the specified permissions. [View in Knowledge Base](https://kb.packfiles.io/using-warp/slash-commands/github/add-team) ## Examples ### With Named Arguments: ``` /add-team --team-name --permission ``` ### With Positional Arguments: ``` /add-team ``` ## 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. # Support Learn about Warp's Support Options 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. ### Packfiles Partners Packfiles' [Partner Network](/using-warp/support/partners) 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.

Project support tab showing support contact and plan information

### 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](https://pack.fm/warp/feedback) 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](#knowledge-base) page will provide you with some tips and tricks on how to navigate, search, and contribute to it effectively. ### Troubleshooting Encountering an issue with Warp? Our [Troubleshooting](/using-warp/support/troubleshooting) guide covers common issues, their causes, and step-by-step resolution instructions — from failed scans and migrations to installation issues. # Warp for Copilot Get Help Anytime with Warp's Copilot Chat Extension 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.

Warp for Copilot can help you understand and use slash commands.

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.

Warp for Copilot provides personalized support and assistance.

### Further Reading If you have further questions about GitHub Copilot Chat, take a look at GitHub's [Copilot docs](https://pack.fm/using-copilot-extensions) to learn more about using Copilot Chat extensions. # Partners Get Expert Support From Our 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. If you're considering expert support as part of your migration plan, or would like to explore your options, contact our team [here](https://packfiles.io/contact) or at . {% hint style="success" %} Are you a professional services provider with a GitHub focus? We'd love to help you enhance your portfolio with Warp. To explore partnership options, [reach out to our team](https://packfiles.io/partners). {% endhint %} # Knowledge Base Get the Most out of Warp's Knowledge Base 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](https://github.com/packfiles/kb.packfiles.io). Individual pages have a dedicated link to their source content on GitHub, so it's easy to propose changes.

{% hint style="info" %} If you need help with anything that isn't yet covered in our documentation, please don’t hesitate to [create an Issue](https://github.com/packfiles/kb.packfiles.io/issues/new/choose), [open a Pull Request](https://github.com/packfiles/kb.packfiles.io/compare), or [share feedback](https://pack.fm/warp/feedback) with our team. {% endhint %} # Troubleshooting Resolve Common Issues with Warp This section covers common issues you may encounter while using Warp and how to resolve them. {% hint style="info" %} Many issues can be diagnosed by reviewing your Runner Agent's log output. See [Troubleshooting Using a Runner Agent's Logs](/using-warp/migration-hq/runner-agent) for instructions on locating and reading logs. {% endhint %} ## Quick Reference | Issue | Symptoms | Likely Cause | Details | | ------------------------ | -------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- | | Failed Inventory Scan | Scan fails or no repos found | Permissions, expired PAT, outdated vault | [View guide](/using-warp/support/troubleshooting/failed-inventory-scan) | | Failed Migration | Migration action fails with error | Permissions, expired PAT, repo size limits | [View guide](/using-warp/support/troubleshooting/failed-migration) | | Main Branch Requirement | Runner Agent fails, no workflows run | Migration HQ default branch is not `main` | [View guide](/using-warp/support/troubleshooting/main-branch-requirement) | | Marketplace Installation | App not installed after Marketplace purchase | Webhook not delivered to Packfiles | [View guide](/using-warp/support/troubleshooting/marketplace-installation-bypass) | ## Failed Inventory Scan Inventory scans can fail when the credentials in your vault are expired, have insufficient permissions, or when the vault file is outdated. A GitHub outage can also prevent scans from running. For detailed causes and resolution steps, see [Failed Inventory Scan](/using-warp/support/troubleshooting/failed-inventory-scan). ## Failed Migration Migrations can fail for many of the same reasons as inventory scans — expired or under-scoped credentials, outdated vault files, and GitHub outages. Additionally, repository size limitations and invalid destination repository names can cause migration failures. For detailed causes and resolution steps, see [Failed Migration](/using-warp/support/troubleshooting/failed-migration). ## Main Branch Requirement Warp requires the Migration HQ repository's default branch to be named `main`. Organizations with a different default branch naming policy will experience runner failures until the branch is renamed. For the resolution steps, see [Main Branch Requirement](/using-warp/support/troubleshooting/main-branch-requirement). ## Marketplace Installation Bypass In rare cases, installing Warp through the GitHub Marketplace may appear to succeed but the app is never installed. A direct installation link is available as a workaround. For the resolution steps, see [Marketplace Installation Bypass](/using-warp/support/troubleshooting/marketplace-installation-bypass). ## Still Need Help? {% hint style="info" %} If these guides don't resolve your issue, reach out to Product Support via the Support tab in your [Project](/using-warp/projects), or contact a [Packfiles Partner](/using-warp/support/partners) for expert guidance. {% endhint %} # Failed Inventory Scan Resolve Issues with Failed Inventory Scans An inventory scan is how Warp discovers repositories in your source platform. When you run a scan, Warp's Runner Agent connects to your source (Azure DevOps, Bitbucket Server, etc.) using the credentials stored in your vault and retrieves a list of repositories. This page covers the reasons an inventory scan can fail and how to resolve them. ## Symptoms * Scan action fails in the Actions tab of Migration HQ. * Scan completes but no repositories appear in the Issues tab. * Error messages in runner logs referencing authentication or authorization. ## Common Causes and Solutions ### Insufficient Permissions The personal access token (PAT) stored in your vault may not have the scopes required to read repositories from your source platform. **Resolution:** 1. Verify the PAT has the required scopes for your source platform. Refer to the [Set Up Your Vault](/guides/quickstart/set-up-your-vault) guide for the specific scopes needed. 2. If the scopes are incorrect, generate a new PAT with the correct permissions. 3. Update the credential in the Warp Vault app and push the updated vault file to Migration HQ. ### Expired Personal Access Token Personal access tokens have expiration dates. An expired PAT will cause authentication failures during the scan. **Resolution:** 1. Check the expiration date of the PAT on your source platform. 2. Generate a new PAT with the same scopes. 3. Update the credential in the [Warp Vault](/using-warp/warp-vault) app and push the updated vault file to Migration HQ. ### Outdated Vault File If credentials were updated outside of Warp Vault, or a new vault was generated but not pushed to Migration HQ, the vault file may be stale. **Resolution:** 1. Open the [Warp Vault](/using-warp/warp-vault) app and verify your credentials are current. 2. Re-export the vault file. 3. Push the updated `vault.age` file to Migration HQ. ### GitHub Outage If GitHub is experiencing an outage, Runner Agents cannot execute workflows, and scans will fail. **Resolution:** 1. Check [GitHub Status](https://www.githubstatus.com/) for any ongoing incidents. 2. Wait for the incident to be resolved, then retry the scan. ## Checking Runner Logs Runner Agent logs provide detailed error information that can help identify the root cause. See [Troubleshooting Using a Runner Agent's Logs](/using-warp/migration-hq/runner-agent) for instructions on locating and reading log output. ## Related Pages * [Failed Migration](/using-warp/support/troubleshooting/failed-migration) — similar causes apply to migration failures * [Troubleshooting](/using-warp/support/troubleshooting) — index of all common issues * [Support](/using-warp/support) — contact Product Support # Failed Migration Resolve Issues with Failed Migrations When you run a migration, Warp uses GitHub's migration APIs to move repository data from your source platform to GitHub. This page covers the reasons a migration can fail and how to resolve them. ## Symptoms * Migration action fails in the Actions tab of Migration HQ. * Warp posts an error comment on the repository's issue in Migration HQ. * The issue comment includes a **Troubleshoot** section with a link to runner logs. ## Common Causes and Solutions ### Insufficient Permissions The personal access token (PAT) used for the destination GitHub organization may lack the required scopes, or the Warp GitHub App installation may be missing permissions. **Resolution:** 1. Verify the destination PAT has the required scopes. Refer to the [Set Up Your Vault](/guides/quickstart/set-up-your-vault) guide for the specific scopes needed. 2. Verify the Warp GitHub App has the necessary permissions on the destination organization. 3. If scopes are incorrect, generate a new PAT, update the credential in the [Warp Vault](/using-warp/warp-vault) app, and push the updated vault file to Migration HQ. ### Expired Personal Access Token Personal access tokens have expiration dates. An expired PAT will cause authentication failures during migration. **Resolution:** 1. Check the expiration date of the PAT on both your source and destination platforms. 2. Generate a new PAT with the same scopes. 3. Update the credential in the [Warp Vault](/using-warp/warp-vault) app and push the updated vault file to Migration HQ. ### Outdated Vault File If credentials were updated outside of Warp Vault, or a new vault was generated but not pushed to Migration HQ, the vault file may be stale. **Resolution:** 1. Open the [Warp Vault](/using-warp/warp-vault) app and verify your credentials are current. 2. Re-export the vault file. 3. Push the updated `vault.age` file to Migration HQ. ### Repository Size Limitations GitHub's migration APIs have size limits for repository data. Very large repositories may exceed these limits. **Resolution:** 1. Review the limitations for your source platform: [Azure DevOps Limitations](/migrations/azure-devops/limitations) or [Bitbucket Server Limitations](/migrations/bitbucket-server/limitations). 2. Consider reducing repository size before migration (e.g., removing large binary files from history). ### Invalid Destination Repository Name Certain repository naming constraints on GitHub may cause the migration to fail (e.g., names ending in `.wiki` are not permitted). **Resolution:** 1. Use the [`/rename-destination`](/using-warp/slash-commands/migration/rename-destination) slash command to change the destination repository name before retrying the migration. ### GitHub Outage If GitHub is experiencing an outage, Runner Agents cannot execute workflows, and migrations will fail. **Resolution:** 1. Check [GitHub Status](https://www.githubstatus.com/) for any ongoing incidents. 2. Wait for the incident to be resolved, then retry the migration. ## Checking Runner Logs Runner Agent logs provide detailed error information that can help identify the root cause. See [Troubleshooting Using a Runner Agent's Logs](/using-warp/migration-hq/runner-agent) for instructions on locating and reading log output. ## Related Pages * [Failed Inventory Scan](/using-warp/support/troubleshooting/failed-inventory-scan) — similar causes apply to scan failures * [Main Branch Requirement](/using-warp/support/troubleshooting/main-branch-requirement) — runner failures caused by branch naming * [Troubleshooting](/using-warp/support/troubleshooting) — index of all common issues * [Support](/using-warp/support) — contact Product Support # Main Branch Requirement Resolve Runner Failures Caused by Branch Naming Policies Warp requires the Migration HQ repository's default branch to be named `main`. If your GitHub organization enforces a different default branch name (e.g., `master`, `develop`, `trunk`), the Warp Runner Agent will fail to execute. ## Symptoms * Runner Agent fails immediately after any Warp operation. * No workflow runs appear in Migration HQ's Actions tab, or they fail during setup. * Warp does not respond to slash commands. ## Cause Warp's runner workflows are configured to execute on the `main` branch. GitHub organizations can set an organization-level default branch naming policy that overrides the default for all new repositories. When this policy is set to something other than `main`, the Migration HQ repository is created with a different default branch name, and Warp's workflows cannot run. ## Resolution 1. Navigate to the Migration HQ repository on GitHub. 2. Go to **Settings** > **General**. 3. Under **Default branch**, change the branch name to `main`. {% hint style="info" %} If your organization enforces a branch naming policy, you can temporarily change the organization-level default to `main` before installing Warp. Once the Migration HQ repository is created with `main` as its default branch, you can change the organization-level policy back. The Migration HQ repository will retain `main` as its default branch. {% endhint %} ## Prevention Before installing Warp, verify that either: * Your organization's default branch naming policy is set to `main`, or * You are prepared to manually change the Migration HQ repository's default branch to `main` after it is created. ## Related Pages * [Failed Migration](/using-warp/support/troubleshooting/failed-migration) — other causes of migration failures * [Failed Inventory Scan](/using-warp/support/troubleshooting/failed-inventory-scan) — other causes of scan failures * [Troubleshooting](/using-warp/support/troubleshooting) — index of all common issues # Marketplace Installation Bypass Resolve Silent Failures During GitHub Marketplace Installation In rare cases, installing Warp through the GitHub Marketplace may appear to succeed, but the app is never actually installed. This happens when the webhook GitHub sends to Packfiles is not delivered, meaning the installation signal is never received. ## Symptoms * GitHub Marketplace shows Warp as purchased or subscribed. * No Migration HQ repository is created in your organization. * Warp does not appear under your organization's installed GitHub Apps. ## Cause GitHub Marketplace relies on webhooks to notify application providers when a new installation occurs. In rare cases, this webhook is not delivered. The purchase is recorded on GitHub's side, but Packfiles never receives the installation event, so the Warp GitHub App is never installed on your organization. ## Resolution Use the direct installation link to install the Warp GitHub App, bypassing the Marketplace webhook: 1. Navigate to the direct installation URL:\ [`https://github.com/apps/packfiles-warp/installations/new`](https://github.com/apps/packfiles-warp/installations/new) 2. Select the GitHub organization where you want to install Warp. 3. Authorize the installation and grant the required permissions. 4. Warp will begin its setup process and create the Migration HQ repository. {% hint style="info" %} This direct installation link can also be used if you prefer to install the Warp GitHub App without using the Marketplace. {% endhint %} ## Verifying the Installation After using the direct installation link, confirm that the installation succeeded: * Check that the Migration HQ repository was created in your target organization. * Verify that **packfiles-warp** appears under **Organization Settings** > **Installed GitHub Apps**. ## Related Pages * [Troubleshooting](/using-warp/support/troubleshooting) — index of all common issues * [Support](/using-warp/support) — contact Product Support if the direct installation link also fails # Warp Vault 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. {% hint style="info" %} Looking for a quick tour of Warp Vault's features and interface? Check out [this demo](https://packfiles.navattic.com/ybw09zv). {% endhint %}

### 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](/guides/quickstart/set-up-your-vault). ### Installing Warp Vault To install or update Warp Vault on your local machine, review the instructions provided in [Download Warp Vault](/using-warp/warp-vault/download-warp-vault). ### Security Model For detailed information about how Warp Vault keeps your credentials safe and secure, review the [Credential Management](/security/warp-security-model/credential-management) page in the [Warp's Security Model](/security/warp-security-model) section. # Download Warp Vault ### Download Warp Vault Warp Vault is available to download at [vault.packfiles.io](https://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) {% hint style="success" %} All copies of Warp Vault distributed by Packfiles are cryptographically signed to attest to their authenticity and prevent malicious tampering. To learn how to validate these signatures, refer to [this article](/using-warp/warp-vault/download-warp-vault/verify-your-copy-of-warp-vault). {% endhint %} ### Install Warp Vault With a Package Manager #### Homebrew (macOS) Packfiles provides a [Homebrew](https://brew.sh) 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 , 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.

# Verify Your Copy of Warp Vault 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. {% hint style="danger" %} If you experience a verification failure for a Warp Vault release and suspect tampering, please notify the Packfiles Security Team immediately at . {% endhint %} Jump to instructions for: * [macOS](#macos) * [Windows](#windows) * [Linux](#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: ```yaml 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 (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`. {% hint style="success" %} You can safely ignore the `This key is not certified with a trusted signature!`message in the verification output. This message is related to whether the Packfiles PGP key is marked as trusted in your local GPG trust store, and has no bearing on the validity of the PGP signature for the Warp Vault executable. {% endhint %} # Supported Credential Providers Each of the credential providers listed in this section can be configured using Warp Vault: * [Amazon S3 Storage](/using-warp/warp-vault/supported-credential-providers/amazon-s3-storage), * [Azure Blob Storage](/using-warp/warp-vault/supported-credential-providers/azure-blob-storage), * [Azure DevOps Services](/using-warp/warp-vault/supported-credential-providers/azure-devops-services), * [Bitbucket Server](/using-warp/warp-vault/supported-credential-providers/bitbucket-server), * [GitHub (Destination)](/using-warp/warp-vault/supported-credential-providers/get-your-github-credentials)

Warp Vault allows new credentials to be added with a click

# Amazon S3 Storage The Amazon S3 Storage credential type stores the AWS credentials associated with an Amazon S3 bucket. {% hint style="info" %} Intermediate storage is used in migration paths from on-premises sources. These include Bitbucket Server, Gitlab, and GitHub Enterprise Server. {% endhint %} 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html). # Azure Blob Storage The Azure Blob Storage credential type stores the Connection String associated with an Azure Blob Storage bucket. {% hint style="info" %} Intermediate storage is used in migration paths from on-premises sources. These include Bitbucket Server, Gitlab, and GitHub Enterprise Server. {% endhint %} 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](https://learn.microsoft.com/en-gb/azure/storage/common/storage-account-keys-manage?tabs=azure-portal#regenerate-access-keys). # Azure DevOps Services 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 {% hint style="info" %} Search for the 🛠️ emoji if you’d like to skim through this content while focusing on the steps you need to follow. {% endhint %} ### 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:

The organization page in Azure DevOps. The "Projects" tab is on display, and it contains 3 projects: "Parts Unlimited," "Tailwind Traders," and "First Project." — The organization page in Azure DevOps.

{% hint style="info" %} The example Azure DevOps organization for this quickstart is **joey-ado-testing**. {% endhint %} 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/`:

Close-up of the browser's address bar, which displays the URL "dev.azure.com/joey-ado-testing". — The browser's address bar,
while on the organization page in Azure Devops.

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:

The menu that appears when you click the User Settings icon. The key item in the menu is the "Personal access tokens" item. — The menu that appears
when you click the *User Settings* icon.

🛠️ Select **Personal access tokens** from the menu. You will see the *Personal Access Tokens* page:

The Personal Access Tokens page. It is empty and displays the text "You do not have any personal access tokens yet." There are two identical "New Token" buttons on the page; one near the top right corner, and one in the middle. — 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:

The "Create a new personal access token" panel, which is a form. The "Name" field contains "Warp migration 1", the "Organization" field contains "joey-ado-testing", the "Expiration (UTC)" field contains "30 days" and the selected "Scopes" radio button is "Full access". — The *Create a new personal access token* panel.

🛠️ 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**. {% hint style="info" %} For the purposes of this Quickstart, we’ll leave the **Expiration** field at the default value of 30 days. {% endhint %} 🛠️ Click the **Create** button. You should now see the *Success!* panel, which will display the personal access token you just created:

The "Success!" panel, which is a form. There is a text field containing the Personal Access Token. There are instructions to copy the token now because Azure DevOps does not store it and the user will never be able to access its value again. — The *Success!* panel.

🛠️ Copy the token and **save it in a safe place** — preferably a password manager. {% hint style="warning" %} This will be the only time that this Personal Access Token will be presented to you. Make sure you’ve copied it someplace safe before clicking the **Close** button! {% endhint %} 🛠️ 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 Personal Access Tokens page, with the newly-created Personal Access Token. The page now has a list, containing one token: "Warp migration 1", the token that was created just now. — The *Personal Access Tokens* page, with the newly-created Personal Access Token.

# Bitbucket Server 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](/using-warp/warp-vault/supported-credential-providers/amazon-s3-storage) and [Azure Blob Storage](/using-warp/warp-vault/supported-credential-providers/azure-blob-storage) are currently supported. {% hint style="info" %} Intermediate storage is used in migration paths from on-premises sources. These include Bitbucket Server, Gitlab, and GitHub Enterprise Server. {% endhint %} #### 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. # GitHub (Destination) How to get your GitHub organization slug and create a GitHub Personal Access Token. 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](/using-warp/warp-vault/supported-credential-providers/get-your-github-credentials), * 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 {% hint style="info" %} Search for the 🛠️ emoji if you’d like to skim through this content while focusing on the steps you need to follow. {% endhint %} ### 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`:

Close-up of the browser's address bar, which displays the URL "github.com/Hypotheticorp01". — The browser's address bar,
while on the *Migration HQ* page.

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:

The menu that appears when you
click your profile picture.

🛠️ Select **Settings** from the menu. You will be taken to the *Settings* page for your GitHub account:

The "Settings" page for the user's GitHub account. — GitHub account *Settings* page.

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

The "Settings" page for the user's GitHub account, scrolled farther down the page. The key item is the “Developer settings” item at the bottom of the left-side menu. — GitHub account *Settings* page, scrolled farther down.

🛠️ Click on **Developer settings**. This will take you to the *Developer Settings* page:

The "Developer Settings" page. The key item is the “Personal access tokens” item at the bottom of the left-side menu. — The *Developer Settings* page.

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

The Personal access tokens menu. The key item is the “Tokens (classic)” menu item. — The *Personal access tokens* menu.

🛠️ Select **Tokens (classic)** from the menu. You will end up at the *Personal access tokens (classic)* page:

The Personal access tokens (classic) page. The key item is the “Generate new token” button. — 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:

The Generate new token button's menu. The key item is the “Generate new token (classic)” menu item. — The *Generate new token* menu.

🛠️ ...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:

The “Note” field and “Expiration” drop-down menu. The “Note” field contains the text “Warp migration 1” and the “Expiration” drop-down menu has “30 days” selected. — The *Note* field and *Expiration* drop-down menu.

{% hint style="info" %} For the purposes of this Quickstart, we’ll leave the **Expiration** field at the default value of 30 days. {% endhint %} 🛠️ Under **Select scopes**, check the following boxes. Checking these boxes will automatically check their sub-boxes: * **repo** * **workflow** * **write:packages** * **delete:packages** * **admin:org**

The first section of the checkboxes on the “New personal access token (classic)” page, with the “repo”, “workflow”, “write:packages”, “delete:packages”, and “admin:org” checkboxes checked. — The first set of checkboxes.

🛠️ 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**

The next section of the checkboxes on the “New personal access token (classic)” page, with the “admin:repo_hook”, “admin:org_hook”, and “delete_repo” checkboxes checked. — The next set of checkboxes.

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:

The Personal access tokens (classic) page, with the newly-created Personal Access Token. — The *Personal access tokens (classic)* page, with the newly-created Personal Access Token.

🛠️ Copy the token and **save it in a safe place** — preferably a password manager. {% hint style="warning" %} This will be the only time that this Personal Access Token will be presented to you. Make sure you’ve copied it someplace safe before clicking the **Close** button! {% endhint %} {% hint style="info" %} 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 and examine the `Configure SSO`dropdown menu adjacent to your personal access token.

View screenshot

If you receive an error like the following`Resource 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. {% endhint %} # Using Credentials in Scripts 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](/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. {% hint style="success" %} Schemas for each credential provider type are documented in the [Vault Schema](/using-warp/warp-vault/using-credentials-in-scripts/vault-schema) section. Refer to these when writing queries or parsing their results. {% endhint %} ### 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. # Vault Schema 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](/using-warp/warp-vault/using-credentials-in-scripts) 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](/using-warp/warp-vault/using-credentials-in-scripts) to extract any properties you might need in scripts or other parts of your workflow. # Amazon S3 Credential Schema Amazon S3 Credential Schema v1.1.0 ``` { "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' ``` # Azure Blob Storage Credential Schema Azure Blob Storage Credential Schema v1.1.0 ``` { "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' ``` # Azure DevOps Services Credential Schema Azure DevOps Services Credential Schema v1.1.0 ``` { "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' ``` # Bitbucket Server Credential Schema ``` { "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' ``` # GitHub (Destination) Credential Schema GitHub (Destination) Credential Schema v1.1.0 ``` { "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' ``` # Warp CLI 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](/using-warp/warp-vault/using-credentials-in-scripts). Before you can use Warp CLI, you must have the [GitHub CLI](https://cli.github.com/) 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: ```bash 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: ```bash 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](https://cli.github.com/) 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: ```bash gh extension install packfiles/gh-warp ``` Confirm that the Warp command-line extension is installed by running the following command in a terminal window: ```bash 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. ``` # Security at Packfiles Learn how Packfiles Protects Your Data ### 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](/security/warp-security-model/credential-management), [private compute](/security/warp-security-model), and [data privacy](/security/warp-security-model/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 . # Warp's Security Model Learn about Warp's Secure Design 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](/security/warp-security-model/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](/using-warp/migration-hq/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](/security/warp-security-model/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](#data-privacy) section to learn about our commitments and safeguards. # Credential Management Warp Protects Your Credentials with End-to-End Encryption ### 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](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#storing-large-secrets) for storing large secrets on their platform. The Vault uses the [age](https://github.com/FiloSottile/age) encryption library to provide its underlying cryptography. A detailed specification outlining the cryptographic primitives used by age is available [here](https://age-encryption.org/v1). #### Architecture Diagram ```mermaid architecture-beta group github(cloud)[Your GitHub Environment] service repo(disk)[Migration HQ Contains Vault] in github service actions_secrets(database)[Actions Secrets Contains Key] in github repo:R -- L:vault_manager actions_secrets:R -- B:vault_manager group customer_manager(internet)[Your Local Machine] service vault_manager(server)[Vault Manager] in customer_manager ``` # Private Compute Private Compute Puts You in Control 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](https://github.com/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](https://github.com/github/gh-gei/issues/1151) 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 ```mermaid architecture-beta group github(cloud)[Your GitHub Environment] service repo(disk)[Migration HQ Contains Vault] in github service runner_agent(server)[Runner Agent] in github service actions_secrets(database)[Actions Secrets Contains Key] in github repo:R -- L:runner_agent actions_secrets:R -- T:runner_agent group warp(internet)[Packfiles Cloud] service control_plane(cloud)[Warp Control Plane] in warp runner_agent:R -- L:control_plane group customer_sources(internet)[Your Source Environment] service source_environment(server)[Your Source Platform] in customer_sources runner_agent:B -- R:source_environment ``` # Data Privacy Our Commitment to Keeping Your Data Confidential 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](/security/warp-security-model/private-compute) and [Credential Management](/security/warp-security-model/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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) ### 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](https://pack.fm/warp/tos) and [Privacy Policy](https://pack.fm/warp/privacy). 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](/security/packfiles#programs). # Overview Understand Billing and Licensing options in Warp 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](/billing-and-licensing/free-trial) of Capacity when it's first created. Additional Capacity is credited any time you purchase one or more [**Boxes**](#about-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:

Size	Capacity	Price	Cost Per Migration
Small Box	100 migrations	$2,000 USD	$20/repository
Medium Box	1,000 migrations	$15,000 USD	$15/repository

**Custom pricing** is available for organizations planning very large migrations. To explore large-scale pricing options, [contact us](https://pack.fm/warp/contact-sales). ### 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. # Free Trial Learn about Warp's no-strings-attached 14-day Free Trial Every new Migration Project in Warp starts in our **Free Trial**, which gives you a free, no-strings-attached 14-day opportunity to migrate up to 25 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 Trial. When your Project is in the Free Trial, the following limits apply: * Your trial lasts **14 days** from the date of installation, * We'll create a maximum of 25 **Issues**, and * We'll assign a free allotment of **Capacity** to your Project, allowing you to perform up to 25 migrations. ### Issue Limit When your Project is in our Free Trial, 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 25 repositories, you'll only see the first 25. The repositories chosen for Free Trial issues are random. If you'd like to evaluate Warp with a specific selection of repositories in the Free Trial, 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 **25 migrations** to all new Projects when they're created. You can use this Free Trial 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 Trial The Free Trial 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 Trial limits can make it difficult to evaluate Warp in a large production environment with more than 25 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 Free Trial lasts 14 days from the date of installation. Once the trial period ends, you must purchase Capacity to continue using Warp. Your Project is automatically upgraded from the Free Trial 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 Trial limits. When a Project is upgraded from the Free Trial: * 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 25), 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](https://pack.fm/warp/contact-support).