Forge Helpers

This repository contains various helpers used for migrating Fedora QA repositories from Pagure into Fedora Forge (based on Forgejo), and mass-changing the target tickets if there is some subsequent action needed.

Setup

# Create and activate virtualenv
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Pagure API Token

Several scripts require a Pagure API token for authentication. To create one:

1. Log in to Pagure
2. Go to your API settings
3. Click "Create new API key"
4. Select the required ACLs:
   • Comment on a ticket (issue_comment) — required for posting migration comments
   • Update an issue, status, comments, custom fields... (issue_update) — required for closing issues
   • Create a new ticket (issue_create) — required for pagure_create_issues.py
5. Save the token to a file (e.g., ~/.pagure-token) for use with --token-file

Forge (Forgejo) API Token

Several scripts require a Forge API token for authentication. To create one:

1. Log in to Fedora Forge
2. Go to your Applications settings
3. Under "Manage Access Tokens", enter a token name and select the required scopes (e.g., "write:issue" for modifying issues)
4. Click "Generate Token"
5. Save the token to a file (e.g., ~/.forge-token) for use with --token-file

Scripts

pagure_add_migration_comment.py

Adds a migration notice comment to Pagure tickets, linking to their new Forge location. By default, open issues are also closed after the comment is posted.

Usage:

# Dry run on all issues (preview without making changes)
python pagure_add_migration_comment.py https://pagure.io/fedora-qa/some-repo \
    https://forge.fedoraproject.org/quality/some-repo \
    --token-file ~/.pagure-token --dry-run

# Process specific issues on staging instances
python pagure_add_migration_comment.py https://stg.pagure.io/fedora-qa/some-repo \
    https://forge.stg.fedoraproject.org/quality/some-repo \
    --token-file ~/.pagure-token --issues 1 2 3

# Comment only, without closing
python pagure_add_migration_comment.py https://pagure.io/fedora-qa/some-repo \
    https://forge.fedoraproject.org/quality/some-repo \
    --token-file ~/.pagure-token --skip-close

# Close open issues that already have a migration comment
python pagure_add_migration_comment.py https://pagure.io/fedora-qa/some-repo \
    https://forge.fedoraproject.org/quality/some-repo \
    --token-file ~/.pagure-token --skip-comment --issue-status open

Notable options: --issue-status (open, closed, all), --skip-close, --skip-comment.

Run with --help for all available options.

pagure_create_issues.py

Creates numbered test issues in a Pagure repository. Useful for testing or setting up migration scenarios.

Usage:

# Dry run creating 5 issues (preview without making changes)
python pagure_create_issues.py https://pagure.io/fedora-qa/some-repo \
    --count 5 --token-file ~/.pagure-token --dry-run

# Create 10 issues on staging Pagure
python pagure_create_issues.py https://stg.pagure.io/fedora-qa/some-repo \
    --count 10 --token-file ~/.pagure-token

# Create issues with longer delay between calls
python pagure_create_issues.py https://pagure.io/fedora-qa/some-repo \
    --count 3 --token-file ~/.pagure-token --delay 2.0

Run with --help for all available options.

forge_migrate_story_points.py

Migrates story points from Pagure custom fields to Forge labels. Reads the story_points custom field from Pagure issues and applies corresponding point labels (points/01, points/02, points/03, points/05, points/08, points/13) to the matching Forge issues.

Usage:

# Dry run on all issues (preview without making changes)
python forge_migrate_story_points.py https://pagure.io/fedora-qa/some-repo \
    https://forge.fedoraproject.org/quality/some-repo \
    --token-file ~/.forge-token --dry-run

# Process specific issues
python forge_migrate_story_points.py https://pagure.io/fedora-qa/some-repo \
    https://forge.fedoraproject.org/quality/some-repo \
    --token-file ~/.forge-token --issues 1 2 3

Run with --help for all available options.

forge_convert_labels.py

Intended to convert migrated issues from auto-converted, repo-specific labels to forge-wide and/or organization-wide 'standard' labels.

Usage:

# Dry run on all issues (preview without making changes)
python forge_convert_labels.py https://forge.fedoraproject.org/quality/some-repo \
    --token-file ~/.forge-token --dry-run

# Real run with custom replacement mapping
python forge_convert_labels.py https://forge.fedoraproject.org/quality/some-repo \
    --token-file ~/.forge-token --replacements-file /path/to/mymapping.json

Configuration:

As orgs and repos may use different 'standard' labels, you may need to configure the mapping. The default mapping, labels-default.json, is appropriate for the Quality team's migration. The format of the file is a dict of dicts:

{
    "priority/critical": {
        "color": "ff00ff",
        "id": 2058
    },
    "priority/high": {
        "color": "ff00ff",
        "id": 1136
    },
    ...
}

Each dict is an instruction to replace any label of the specified name and color with the label that has the given id. So if an issue has a label named "priority/critical" with the color ff00ff, it will be replaced with the label whose id is 2058. You can adjust the default file or write your own from scratch to achieve the exact replacements that are appropriate for your situation. You can find label names and colors in the Forge web UI. In the repository, go to Issues and then click Labels. Assuming you have admin access to the repository, labels with ''Edit'' and ''Delete'' buttons are specific to that repository; you can see each label's name and color by clicking ''Edit''. You can find label IDs via the API. To find the org-wide labels for a given org, go to https://forge.fedoraproject.org/api/v1/orgs/(orgname)/labels.

Run with --help for all available options.

Note

Most of the code in this repository is AI-generated using Claude (Anthropic) via Cursor IDE.