Bulk Updating User Email Domains in Terraform Enterprise

Introduction

Administrators managing a Terraform Enterprise (TFE) instance may need to perform a bulk update of user email addresses. A common scenario is a company-wide domain change due to rebranding, a merger, or a new email policy.

Because the admin API does not natively support bulk user updates, you can use the Rails console to perform this task efficiently. This guide provides a step-by-step process for updating user email domains directly within your TFE instance.

Prerequisites

• A deployed Terraform Enterprise instance.
• Administrative access to the TFE host to use the Rails console.
• A complete backup of your TFE data.
• The old and new email domains you will be using for the update.

Procedure

Important: This procedure requires administrator permissions and direct access to the Terraform Enterprise host. Always create a complete data backup before making any changes.

1. Access the Rails console.

   Follow the official guide to access the Terraform Enterprise Rails Console. You will run the update script from this console.

2. Prepare the update script.

   The following Ruby script iterates through all users and updates their email address if it matches the old domain. Before running, replace old_domain.com and new_domain.com with your actual domains.

   users = User.all
   users.each do |user|
     parts = user.email.split("@")
     if parts.length() != 2 or parts.last != "old_domain.com"
       puts "Skipping #{user.email}."
       next
     end
   
     new_email = "#{parts.first}@new_domain.com"
     puts "Changing #{user.email} to #{new_email}."
   
     ## The following lines are commented out for the dry run.
     ## user.email = new_email
     ## begin
     ##   user.save!
     ##   puts "Successfully updated #{user.email}."
     ## rescue => e
     ##   puts "Failed to update #{user.email}. Error: #{e.message}"
     ## end
   end

3. Perform a dry run.

   Before making permanent changes, run the script as-is. The lines that modify and save the user data are commented out by default to prevent unintended changes. The script will print the changes it would make, allowing you to verify its behavior.

   The following lines are commented out in the script for safety:

   ## user.email = new_email
   ## user.save!

4. Apply the changes.

   Once you have verified the output of the dry run and are confident the script will perform as expected, uncomment the lines responsible for the update and save operations. Run the script again to apply the email domain changes to all matching users.