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 username@fedoraproject.org) 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 forgejo-deployment repository at scripts/update-forge-fas-emails.py

How It Works

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

User exists in Fedora Accounts with email(s) - Replaces placeholder with first Fedora Accounts email
User exists in Fedora Accounts but has no emails - Logs as ERROR (this should never happen)
User not found in Fedora Accounts - Sets to username+fasnotfound@fedoraproject.org

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:

Log into your Forge instance (staging or production)
Go to Settings → Applications → Generate New Token
Give it a descriptive name like "Email Sync Script"
Select the "admin" scope (required for user management)
Copy the generated token

Kerberos Authentication

The script uses Fedora Accounts which requires Kerberos authentication:

For staging

kinit your_username@STG.FEDORAPROJECT.ORG

For production

kinit your_username@FEDORAPROJECT.ORG

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

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)

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               dudemcpants@fedoraproject.org       WOULD UPDATE    dudemcpants@example.com
testermctesterson         testermctesterson@fedoraproject.org WOULD UPDATE    tester@example.org
fergieforge               fergieforge@fedoraproject.org       WOULD UPDATE    fergieforge+fasnotfound@fedoraproject.org
------------------------------------------------------------------------------------------------------------------------

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

Skipped (non-@fedoraproject.org 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 +fasnotfound@fedoraproject.org)

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