Transferring or Renaming Repositories

Warning: When renaming or transferring repositories or organizations in your Version Control System (VCS), there's a risk of losing contexts, project build history, and settings in CircleCI. This data loss can occur due to synchronization challenges between CircleCI and your VCS, especially if the previous name is immediately reused for a different organization or repository.

Step-by-Step Guide

Follow these best practices when transferring a repository to another organization, renaming a repository/organization, or transferring ownership:

1. Before Making Changes: Log into CircleCI and manually stop building and remove CircleCI webhooks for any repository you plan to transfer.
2. Make Changes in Your VCS: Log into your VCS and complete the rename or transfer action. Try to avoid renaming your organization multiple times, as this increases the risk of data loss.

3. Verify in CircleCI: Log into CircleCI using your new organization name and verify that:

   • All projects are visible and following correctly
   • Contexts are intact
   • Settings are preserved
   • Billing information is up to date

   Why is this necessary? CircleCI uses OAuth tokens from your VCS provider to authenticate and identify your organizations. When you rename or transfer a repository/organization, your existing session may still reference the old name cached in your authentication token. Logging out and back in forces CircleCI to fetch a fresh OAuth token from your VCS, ensuring it recognizes the renamed organization and updates your permissions accordingly.

4. After Verification: Only after confirming everything is working properly should you create a new organization or repository using the old name in your VCS (if desired).

Accessing Your Renamed Organization

You can access CircleCI with your new organization name by:

• Navigating through CircleCI's homepage and selecting your new organization
• Using this direct URL format: https://app.circleci.com/projects/project-dashboard/:VCS/:NEW_ORG_NAME

Warning: Once the migration is complete, ensure you run pipelines on any affected projects before deleting the organization that was migrated from. If this is not done, you may lose build history when the old org is deleted.

Helpful Resources

• Transferring a repository on GitHub
• Transferring organization ownership on GitHub