{% extends "base.html" %} {% load provider_login_url from socialaccount %} {% load trans blocktrans from i18n %} {% block title %} {% trans "Migrate account to GitHub App" %} {% endblock title %} {% block content %}

{% trans "Migrate account to GitHub App" %}

{% if step == "overview" %}

{% blocktrans trimmed with blog_post="https://about.readthedocs.com/blog/2025/06/announcing-our-github-app-beta/" %} We’re introducing a new GitHub App to replace our old GitHub OAuth app. This new app offers more granular permissions and better GitHub integration. Learn more in our blog post. {% endblocktrans %}

{% if old_github_accounts.count > 1 %}
{% url 'socialaccount_connections' as socialaccount_connections %} {% blocktrans trimmed with socialaccount_connections=socialaccount_connections %} You have multiple GitHub accounts linked, make sure you complete the steps while logged in to the correct GitHub account. {% endblocktrans %}
{% endif %}

{% blocktrans trimmed %} This guide will help you migrate your account to the new GitHub App. Some things you should know: {% endblocktrans %}

  • {% blocktrans trimmed %} Migrating all projects is optional, you can skip the "Install GitHub App" and "Migrate Projects" steps. {% endblocktrans %}
  • {% blocktrans trimmed %} Connecting your account to our new GitHub App and revoking access to our old GitHub OAuth app is required, as the old app is deprecated and will be removed. {% endblocktrans %}
  • {% blocktrans trimmed %} Some steps require you to make changes on GitHub. Refresh the page after making the changes to see updates. {% endblocktrans %}
  • {% blocktrans trimmed %} New projects created after connecting your account to the new GitHub App don't need migration, as they will be automatically connected to the new GitHub App. {% endblocktrans %}
  • {% blocktrans trimmed with connect_docs="https://docs.readthedocs.com/platform/stable/reference/git-integration.html#connect-a-repository-to-an-existing-project" %} Projects not linked to a GitHub repository can be linked after connecting your account. These don't need migration. {% endblocktrans %}
  • {% blocktrans trimmed %} You can go back to this page page at any time to see the status of your migration, or to complete the migration later. {% endblocktrans %}

{% trans "Start" %} {% elif step == "connect" %}

{% blocktrans trimmed %} First, start by connecting your Read the Docs account to our GitHub App. You'll be prompted to grant access to the app. {% endblocktrans %}

{% include "profiles/partials/github_oauth_list.html" with objects=old_github_accounts %}
{% trans "Next" %} {% elif step == "install" %}

{% blocktrans trimmed %} Next, you will install our GitHub App on each organization and account that has attached repositories. While approving access you will be able to select and deselect individual repositories. {% endblocktrans %}

{% include "profiles/partials/github_app_target_list.html" with objects=installation_target_groups skip_pagination=True %} {% if installation_target_groups %}
{% blocktrans trimmed with manual_migration_docs="https://docs.readthedocs.com/platform/stable/reference/git-integration.html#manually-migrating-a-project" %} If you skip installation during migration, you will need to manually migrate your project to keep it working. {% endblocktrans %}
{% endif %}
{% trans "Next" %} {% trans "Skip installation and continue" %} {% elif step == "migrate" %}

{% blocktrans trimmed with manual_migration_docs="https://docs.readthedocs.com/platform/stable/reference/git-integration.html#manually-migrating-a-project" connect_docs="https://docs.readthedocs.com/platform/stable/reference/git-integration.html#connect-a-repository-to-an-existing-project" %} After installing our GitHub App on each of your repositories, you will need to migrate your Read the Docs projects to use the new connection. If your project isn't listed, you may need to manually migrate it or connect it to a GitHub repository. {% endblocktrans %}

{% if migration_targets %}

{% trans "Migrate all projects" %}

{% blocktrans trimmed %} You might need to take additional steps for some projects that can't be migrated automatically. {% endblocktrans %}

{% csrf_token %}
{% endif %} {% include "profiles/partials/github_app_project_list.html" with objects=migration_targets skip_pagination=True %} {% if manual_migration_required.exists %}
{% trans "Manual migration required" %}

{% blocktrans trimmed with manual_migration_docs="https://docs.readthedocs.com/platform/stable/reference/git-integration.html#manually-migrating-a-project" %} The following projects aren't connected to a repository, you need to manually migrate them to use the new GitHub App. {% endblocktrans %}

{% include "profiles/partials/github_app_project_manual_migration_list.html" with objects=manual_migration_required skip_pagination=True %} {% endif %}
{% trans "Projects already migrated" %}
{% include "profiles/partials/github_app_project_migrated_list.html" with objects=migrated_projects skip_pagination=True %}
{% trans "Next" %} {% elif step == "revoke" %}

{% blocktrans trimmed %} Revoke access to our old GitHub OAuth app. You'll be redirected to GitHub, where you need to click on "Revoke access". {% endblocktrans %}

{% if has_projects_pending_migration and not step_revoke_completed %}
{% blocktrans trimmed with migrate_step="?step=migrate" manual_migration_docs="https://docs.readthedocs.com/platform/stable/reference/git-integration.html#manually-migrating-a-project" %} You have projects that need to be migrated. If you revoke access now, you'll need to manually migrate them. {% endblocktrans %}
{% endif %} {% include "profiles/partials/github_oauth_revoke_list.html" with objects=old_github_accounts current_page=request.get_full_path %}
{% trans "Next" %} {% elif step == "disconnect" %}

{% blocktrans trimmed %} Disconnect the old GitHub OAuth app from your Read the Docs account. {% endblocktrans %}

{% blocktrans trimmed with manual_migration_docs="https://docs.readthedocs.com/platform/stable/reference/git-integration.html#manually-migrating-a-project" %} After disconnecting the old GitHub OAuth app, you won't be able to see this page again. If you have projects that need to be migrated, you'll need to manually migrate them. {% endblocktrans %}
{% include "profiles/partials/github_oauth_disconnect_list.html" with objects=old_github_accounts %}
{% endif %}
{% endblock content %}