Contributor Import Guide

Bulk import your GitLab contributors by uploading a CSV file with email addresses and GitLab user IDs. The system automatically matches emails to your Slack workspace users and creates contributor records.

Quick Start

  1. 1. Prepare a CSV file with email and gitlab_id columns
  2. 2. Go to Settings and find the "Upload CSV File" card
  3. 3. Upload your CSV file (max 10MB, 10,000 rows)
  4. 4. Monitor progress in real-time and review any errors

CSV File Format

Required Format

Your CSV file must contain exactly two columns with these headers:

email,gitlab_id
john.doe@company.com,12345
jane.smith@company.com,67890
alice.jones@company.com,54321

Column Descriptions:

  • email The email address used in your Slack workspace (must match exactly)
  • gitlab_id The numeric GitLab user ID (find this in GitLab user profiles)

Important Notes

  • • Email addresses must match exactly with Slack workspace emails
  • • GitLab IDs must be positive integers
  • • Maximum file size: 10MB
  • • Maximum rows: 10,000
  • • Only one import can run at a time per workspace

How It Works

Import Process

  1. 1
    CSV Validation

    The file is validated for correct format, size limits, and column headers

  2. 2
    Slack User Lookup

    Each email is looked up in your Slack workspace using the Slack API

  3. 3
    Contributor Creation or Update

    New contributor records are created, or existing records are updated with GitLab IDs

  4. 4
    Real-Time Progress Updates

    Watch the import progress live with detailed row-by-row status

Idempotent Imports

You can safely re-run the same import multiple times. The system will update existing contributors with new GitLab IDs rather than creating duplicates or failing.

Monitoring Import Progress

Import History

After uploading, you'll be automatically redirected to the import detail page where you can:

  • View real-time progress updates as rows are processed
  • See success and failure counts
  • Filter rows by status (all, success, failed, processing)
  • View detailed error messages for failed rows
  • Download an error report CSV for failed rows

Import History List

Access all recent imports from Settings → Import History:

  • View imports from the last 48 hours
  • Click any import to view detailed row-level information
  • Status updates automatically without page refresh

Note: Import history is automatically cleaned up after 48 hours to save space. Download error reports before they expire if you need them for later reference.

Finding GitLab User IDs

GitLab user IDs are numeric identifiers that uniquely identify each user. Here's how to find them:

Method 1: User Profile URL

  1. Navigate to the user's GitLab profile page
  2. Look at the URL: https://gitlab.com/users/12345
  3. The number at the end (12345) is the user ID

Method 2: GitLab API

Use the GitLab API to look up users by username or email:

curl "https://gitlab.com/api/v4/users?username=johndoe"

The response includes an id field with the user ID.

Method 3: Project Members Page

  1. Go to your GitLab project → Project Information → Members
  2. Click on a member's name to visit their profile
  3. Check the profile URL for the user ID

Common Errors and Solutions

Slack user not found for email

Cause: The email address doesn't match any user in your Slack workspace

Solution: Verify the email address is correct and the user exists in Slack with that exact email

GitLab ID already assigned to a different contributor

Cause: Another contributor already has that GitLab ID

Solution: Check for duplicate entries in your CSV or verify the GitLab ID is correct

Invalid email format

Cause: The email address isn't formatted correctly

Solution: Ensure emails follow standard format (user@domain.com)

GitLab ID must be a positive number

Cause: The GitLab ID is not a valid positive integer

Solution: Ensure all GitLab IDs are numeric values greater than zero

Import already in progress

Cause: Another import is currently running for your workspace

Solution: Wait for the current import to complete before starting a new one

Best Practices

Before Import

  • Test with a small CSV file (5-10 rows) first
  • Verify email addresses match Slack exactly
  • Double-check GitLab IDs are correct
  • Remove any duplicate entries

After Import

  • Review the import detail page for errors
  • Download error reports for failed rows
  • Fix errors and re-import failed rows
  • Verify contributors appear in your workspace

FAQ

Can I import the same user multiple times?

Yes! The system is idempotent. If a contributor with the same Slack user already exists, their GitLab ID will be updated instead of creating a duplicate.

What happens if the import fails partway through?

Successful rows are saved even if later rows fail. You can download an error report for failed rows, fix the issues, and re-import just those rows.

How long does an import take?

Processing time depends on the number of rows and Slack API response times. Typically, expect 1-2 seconds per row. A 100-row import usually completes in 2-3 minutes.

Can I cancel an import in progress?

Imports cannot be cancelled once started. However, the import processes rows sequentially with individual error handling, so a few failed rows won't stop the entire import.

Do I need special Slack permissions?

The GitLab Bot app must be installed in your Slack workspace with the users:read and users:read.email scopes to look up users by email.

What happens to import history after 48 hours?

Import records are automatically deleted after 48 hours to save space. Make sure to download any error reports you need before they expire.

← Back to Documentation