Email Sync Script for Migrated Users

This document describes the update-forge-fas-emails.py script used to fix placeholder email addresses created during pagure.io to Forge migrations.

Overview

When users are migrated from pagure.io to Forge, the migrator creates placeholder @fedoraproject.org email addresses (like [email protected]) because it doesn’t have access to users' real email addresses. This script replaces those placeholder addresses with users' actual email addresses from Fedora Accounts.

This script is not a general email synchronization tool. It only processes users who already have @fedoraproject.org email addresses that are migrator placeholders. Users with real email addresses from other domains are left untouched.

Script Location: The script is located in the forge/forge repository at scripts/update-forge-fas-emails.py

How It Works

The script handles three scenarios for users with @fedoraproject.org email addresses:

  1. User exists in Fedora Accounts with email(s) - Replaces placeholder with first Fedora Accounts email

  2. User exists in Fedora Accounts but has no emails - Logs as ERROR (this should never happen)

  3. User not found in Fedora Accounts - Sets to [email protected]

Prerequisites

Required Packages

Install the required Python packages on your system:

dnf install python3-click python3-requests python3-fasjson-client

API Token

You need an admin-level API token from your Forge instance:

  1. Log into your Forge instance (staging or production)

  2. Go to Settings → Applications → Generate New Token

  3. Give it a descriptive name like "Email Sync Script"

  4. Select the "admin" scope (required for user management)

  5. Copy the generated token

Kerberos Authentication

The script uses Fedora Accounts which requires Kerberos authentication:

For staging
kinit [email protected]
For production
kinit [email protected]

Usage

Basic Commands

Preview changes against staging (safe, no modifications)
./update-forge-fas-emails.py --dry-run --token YOUR_API_TOKEN
Fix placeholder emails on staging
./update-forge-fas-emails.py --token YOUR_API_TOKEN
Preview changes against production
./update-forge-fas-emails.py --production --dry-run --token YOUR_API_TOKEN
Fix placeholder emails on production
./update-forge-fas-emails.py --production --token YOUR_API_TOKEN

Environment Variable

For automation or security, use an environment variable for the token:

export FORGE_TOKEN=your_api_token
./update-forge-fas-emails.py --production

Command Options

--production

Run against production environment (default: staging)

--dry-run

Preview changes without making them

--token

Forge API token for authentication (can use FORGE_TOKEN environment variable)

--help

Show help message and examples

Understanding the Output

The script provides detailed output showing:

  • Which environment it’s running against

  • Authentication status with Fedora Accounts

  • Progress through all Forge users

  • Actions taken for each user

  • Summary statistics at the end

Action Meanings

Action Description

SKIP

User doesn’t have @fedoraproject.org email (not a migrator placeholder) - silently skipped

NO CHANGE

User’s placeholder email already matches their Fedora Accounts email

UPDATED/WOULD UPDATE

Placeholder email was replaced with real Fedora Accounts email (or would be in dry-run mode)

FAILED

API call to update email failed

ERROR

Unexpected error occurred (usually Fedora Accounts connectivity issues or Fedora Accounts user with no emails)

Sample Output

========================================================================================================================
Forge Email Sync from Fedora Accounts
Environment: STAGING
Forge URL: https://forge.stg.fedoraproject.org
Fedora Accounts URL: https://fasjson.stg.fedoraproject.org
*** DRY RUN MODE - NO CHANGES WILL BE MADE ***
========================================================================================================================

Authenticated with Fedora Accounts as: adminuser

Fetching users from Forge...
Found 1247 total users on Forge

------------------------------------------------------------------------------------------------------------------------
Username                  Current Email                       Action          New Email
------------------------------------------------------------------------------------------------------------------------
dudemcpants               [email protected]       WOULD UPDATE    [email protected]
testermctesterson         [email protected] WOULD UPDATE    [email protected]
fergieforge               [email protected]       WOULD UPDATE    [email protected]
------------------------------------------------------------------------------------------------------------------------

========================================================================================================================
SUMMARY
========================================================================================================================
Total Forge users:                              1247

Skipped ([email protected] email):         1200
Skipped (already processed +fasnotfound):       40
Skipped (Fedora Accounts error):                0

No change needed:                               0
Updated from Fedora Accounts:                   3
Updated to +fasnotfound (not in Fedora Accounts): 4
Update failed:                                  0

Total @fedoraproject.org users processed:       7
Total changes would be made:                    7

*** DRY RUN MODE - Use --production flag without --dry-run to make actual changes ***
========================================================================================================================

Safety Features

  • Dry-run mode lets you preview changes before making them

  • Only processes @fedoraproject.org placeholder email addresses

  • Leaves users with real email addresses untouched

  • Comprehensive logging of all actions taken

  • Staging environment available for testing

  • Skips already processed users (those with +[email protected])

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