Migrating Issue Dependencies and Assignments from Pagure.io to Fedora Forge

DRAFT DOCUMENTATION: This documentation is currently in draft form and may not be fully tested and correct. Please verify all procedures before use and report any issues or inaccuracies.

Purpose

This document provides a comprehensive guide for using the assign_and_depend.py script to restore issue dependencies and assignments after migrating a project from Pagure.io to Fedora Forge. The built-in migrator does not handle this critical metadata, making this script an essential post-migration step.

Scope

This guide applies to Fedora Project contributors who have migrated their projects from Pagure.io to Fedora Forge and need to restore:

  • Issue assignments (who is assigned to work on each issue)

  • Issue dependencies (which issues depend on other issues)

When running this script with an access token from your user account, all issue assignment and dependency changes will be logged in the issue history as actions performed by your user.

If you prefer these changes to be attributed to the system bot account instead, please file a ticket at forge/forge and request that an admin run the script for you. The admin will execute the script using the forgebot user account, which will attribute all changes to the system bot.

Prerequisites

  • Migrated Project: Your project must already be migrated from Pagure.io to Fedora Forge

  • Python Environment: Python 3.6 or later with pip installed

  • Required Dependencies: The following Python packages must be installed:

    • requests - For making HTTP requests to Pagure API

    • backoff - For retry logic with exponential backoff

    • click - For command-line interface

    • pyforgejo - For interacting with Forgejo API

  • API Access:

    • Forgejo API key with write permissions to the target repository

    • Access to Pagure.io API (publicly accessible)

Installation

Installing Required Dependencies

It’s recommended to use a Python virtual environment to avoid conflicts with system packages. Create and activate a virtual environment, then install the required packages:

python -m venv migration-env
source migration-env/bin/activate
pip install requests backoff click pyforgejo

When you’re done with the migration, you can deactivate the virtual environment:

deactivate

Obtaining the Script

The assign_and_depend.py script is available in the official Fedora Forge deployment repository. You can download it directly from:

assign_and_depend.py

To download the script:

curl -O https://forge.fedoraproject.org/forge/forge/raw/branch/main/scripts/assign_and_depend.py

Obtaining Required Information

Forgejo API Key

To obtain a Forgejo API key:

  1. Log in to your Fedora Forge account

  2. Navigate to your user settings (click your avatar in the top-right corner)

  3. In the Left Tab bar, Go to Applications

  4. In the Access tokens section, under Generate new Token enter the name for your token under Token Name (e.g., "Migration Script")

  5. Under Select Permissions, ensure that issue is set to read and write assign script permissions

  6. Click Generate Token

  7. Copy the generated token for use with the script.

Project Information

You’ll need to identify:

  • Pagure Project: The original project name on Pagure.io (e.g., fedora-infra/ansible)

  • Forgejo Project: The migrated project name on Fedora Forge (e.g., infrastructure/fedora-infrastructure)

Usage

Basic Command Structure

The script uses the following command structure:

python assign_and_depend.py \
  --pagure-project "PAGURE_PROJECT_NAME" \
  --forgejo-api-key "YOUR_API_KEY" \
  --forgejo-project "FORGEJO_PROJECT_NAME"

Command-Line Options

  • --pagure-base-url: Base URL for Pagure API (default: https://pagure.io/api/0)

  • --pagure-project: Pagure project name, including namespace if applicable (required)

  • --forgejo-base-url: Base URL for Forgejo API (default: https://forge.fedoraproject.org/api/v1)

  • --forgejo-api-key: Your Forgejo API key (required)

  • --forgejo-project: Forgejo project name in format organization/project (required)

Example Usage

Example 1: Basic Migration

python assign_and_depend.py \
  --pagure-project "fedora-infra/ansible" \
  --forgejo-api-key "gitea_abc123def456..." \
  --forgejo-project "infrastructure/fedora-infrastructure"

Want to help? Learn how to contribute to Fedora Docs ›