forked from forge/documentation
Add email sync doc
This commit is contained in:
parent
d6324ec303
commit
87fa8ed072
2 changed files with 191 additions and 0 deletions
|
|
@ -15,6 +15,7 @@
|
|||
** xref:creating_a_new_org.adoc[Creating a new Organization]
|
||||
** xref:creating_a_new_team.adoc[Creating a new Team]
|
||||
** xref:fas_group_naming_standards.adoc[FAS Group Naming Standards]
|
||||
** xref:admin_email_sync_script.adoc[Email Sync Script for Migrated Users]
|
||||
* Known Issues
|
||||
** xref:known_issue_cannot_create_user.adoc[Unable to Log in - "Cannot Create Account"]
|
||||
** xref:known_issue_organization_projects.adoc[Adding Issues to Organization Projects Doesn't "Stick"]
|
||||
|
|
|
|||
190
modules/ROOT/pages/admin_email_sync_script.adoc
Normal file
190
modules/ROOT/pages/admin_email_sync_script.adoc
Normal file
|
|
@ -0,0 +1,190 @@
|
|||
= Email Sync Script for Migrated Users
|
||||
:navtitle: Email Sync Script
|
||||
|
||||
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.
|
||||
|
||||
IMPORTANT: 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:
|
||||
|
||||
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 `username+fasnotfound@fedoraproject.org`
|
||||
|
||||
== Prerequisites
|
||||
|
||||
=== Required Packages
|
||||
|
||||
Install the required Python packages on your system:
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
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::
|
||||
[source,bash]
|
||||
----
|
||||
kinit your_username@STG.FEDORAPROJECT.ORG
|
||||
----
|
||||
|
||||
For production::
|
||||
[source,bash]
|
||||
----
|
||||
kinit your_username@FEDORAPROJECT.ORG
|
||||
----
|
||||
|
||||
== Usage
|
||||
|
||||
=== Basic Commands
|
||||
|
||||
Preview changes against staging (safe, no modifications)::
|
||||
[source,bash]
|
||||
----
|
||||
./update-forge-fas-emails.py --dry-run --token YOUR_API_TOKEN
|
||||
----
|
||||
|
||||
Fix placeholder emails on staging::
|
||||
[source,bash]
|
||||
----
|
||||
./update-forge-fas-emails.py --token YOUR_API_TOKEN
|
||||
----
|
||||
|
||||
Preview changes against production::
|
||||
[source,bash]
|
||||
----
|
||||
./update-forge-fas-emails.py --production --dry-run --token YOUR_API_TOKEN
|
||||
----
|
||||
|
||||
Fix placeholder emails on production::
|
||||
[source,bash]
|
||||
----
|
||||
./update-forge-fas-emails.py --production --token YOUR_API_TOKEN
|
||||
----
|
||||
|
||||
=== Environment Variable
|
||||
|
||||
For automation or security, use an environment variable for the token:
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
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
|
||||
|
||||
[cols="1,3"]
|
||||
|===
|
||||
|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
|
||||
|
||||
[source]
|
||||
----
|
||||
========================================================================================================================
|
||||
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: ryanlerch
|
||||
|
||||
Fetching users from Forge...
|
||||
Found 1247 total users on Forge
|
||||
|
||||
------------------------------------------------------------------------------------------------------------------------
|
||||
Username Current Email Action New Email
|
||||
------------------------------------------------------------------------------------------------------------------------
|
||||
kparal kparal@fedoraproject.org WOULD UPDATE kparal@redhat.com
|
||||
ryanlerch-testuser1 ryanlerch-testuser1@fedoraproject.org WOULD UPDATE rlerch+testuser1@redhat.com
|
||||
testermctesterson testermctesterson@fedoraproject.org WOULD UPDATE ryanlerch+testermctesterson@redhat.com
|
||||
------------------------------------------------------------------------------------------------------------------------
|
||||
|
||||
========================================================================================================================
|
||||
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`)
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue