Authentication & Setup Guide

This guide covers how to authenticate with Git Wizard and set up your account to start analyzing your repositories.

Table of Contents

Supported Providers

Git Wizard supports authentication and repository analysis from three major Git providers:

  • GitHub - Connect via OAuth
  • GitLab - Connect via OAuth (supports GitLab.com and self-hosted instances)
  • Azure DevOps - Connect via Azure AD OAuth + Personal Access Token (PAT)

You can authenticate with any of these providers to analyze repositories from that platform. Azure DevOps users can also connect their Azure DevOps organization to sync repositories.

GitHub Authentication

Step 1: Sign In with GitHub

  1. Navigate to the Git Wizard application
  2. Click "Sign in with GitHub" on the landing page
  3. You'll be redirected to GitHub to authorize the application
  4. Review the requested permissions and click "Authorize"
  5. You'll be redirected back to Git Wizard and logged in

Step 2: Grant Permissions

Git Wizard requires the following GitHub permissions:

  • Read access to repositories - To analyze your code and pull requests
  • Read access to user profile - To identify you and display your information

What Happens After Authentication

  • Your GitHub account is linked to your Git Wizard account
  • You can now add and analyze GitHub repositories
  • Your access token is securely stored for API access

GitLab Authentication

Step 1: Configure GitLab OAuth (Self-Hosted)

If you're using a self-hosted GitLab instance, you'll need to configure the OAuth application URL in your environment. By default, Git Wizard connects to GitLab.com.

Step 2: Sign In with GitLab

  1. Navigate to the Git Wizard application
  2. Click "Sign in with GitLab" on the landing page
  3. You'll be redirected to GitLab to authorize the application
  4. Review the requested permissions and click "Authorize"
  5. You'll be redirected back to Git Wizard and logged in

Step 3: Grant Permissions

Git Wizard requires the following GitLab permissions:

  • Read access to repositories - To analyze your code and pull requests
  • Read access to user profile - To identify you and display your information

What Happens After Authentication

  • Your GitLab account is linked to your Git Wizard account
  • You can now add and analyze GitLab repositories
  • Your access token is securely stored for API access

Azure DevOps Authentication

Azure DevOps authentication is a two-step process: OAuth authentication followed by organization connection.

Step 1: Sign In with Azure AD

  1. Navigate to the Git Wizard application
  2. Click "Sign in with Azure" on the landing page
  3. You'll be redirected to Microsoft Azure AD to sign in
  4. Sign in with your Microsoft account (work or personal)
  5. Review the requested permissions and click "Accept"
  6. You'll be redirected back to Git Wizard and logged in

Step 2: Connect Azure DevOps Organization

After signing in with Azure AD, you need to connect your Azure DevOps organization:

  1. Create a Personal Access Token (PAT) in Azure DevOps:
    • Go to your Azure DevOps organization
    • Navigate to User Settings → Personal Access Tokens
    • Click "New Token"
    • Give it a name (e.g., "Git Wizard")
    • Set expiration (recommended: 90 days or custom)
    • Select scopes: Code (Read) and Project and Team (Read)
    • Click "Create" and copy the token (you won't see it again)
  2. Connect in Git Wizard:
    • You'll see a prompt to connect Azure DevOps after logging in
    • Enter your Organization name (e.g., my-org for dev.azure.com/my-org)
    • Paste your Personal Access Token
    • Click "Connect"

Step 3: Discover Repositories

After connecting your organization:

  1. Click "Discover Repositories" in the Azure DevOps section
  2. Select your organization from the dropdown
  3. Click "Discover" to scan for available projects and repositories
  4. Select the repositories you want to track
  5. Click "Add Selected Repositories" to sync them

Important Notes for Azure DevOps

  • Only Azure-authenticated users can connect Azure DevOps organizations
  • Azure DevOps repositories must be synced through the discovery flow (not manually added)
  • You can connect multiple organizations by repeating the connection process
  • PAT tokens should be rotated periodically for security

Initial Setup

First-Time User Flow

  1. Authenticate with your preferred provider (GitHub, GitLab, or Azure)
  2. Add repositories you want to analyze (see Connecting Repositories)
  3. Select a timeframe (7 days, 30 days, 90 days, or custom range)
  4. Start exploring your metrics on the Dashboard Overview

Profile Setup

After authentication, you can customize your profile:

  1. Navigate to Profile from the sidebar
  2. Review your account information
  3. Update your display preferences
  4. Manage connected providers

Connecting Repositories

GitHub & GitLab Repositories

For GitHub and GitLab, you can add repositories manually:

  1. Go to Dashboard Overview or Settings
  2. In the repository picker, click "Add Repository"
  3. Enter the repository in format: owner/repository-name
    • Example: facebook/react or my-org/my-repo
  4. Click "Add" to validate and add the repository
  5. The repository will be validated to ensure:
    • It exists
    • You have access to it
    • It's accessible with your current permissions

Azure DevOps Repositories

Azure DevOps repositories must be synced through the discovery flow:

  1. Ensure you've connected your Azure DevOps organization (see Azure DevOps Authentication)
  2. Use the Azure DevOps Repository Discovery component
  3. Select your organization
  4. Click "Discover" to scan for repositories
  5. Select the repositories you want to track
  6. Click "Add Selected Repositories"

Repository Selection

After adding repositories:

  • Select repositories to analyze by checking them in the repository picker
  • Filter by provider using the provider badges (GitHub, GitLab, Azure DevOps)
  • Search repositories using the search bar
  • Select all or deselect all using the bulk actions

Repository Access Requirements

  • You must have read access to repositories you want to analyze
  • Private repositories require appropriate permissions
  • Organization repositories require organization-level access
  • Azure DevOps repositories require project-level read permissions

Troubleshooting

Authentication Issues

"client_id is required" Error

  • Cause: GitHub/GitLab OAuth credentials not configured
  • Solution: Ensure GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET (or GitLab equivalents) are set in environment variables

"NO_SECRET" Error

  • Cause: NextAuth secret not configured
  • Solution: Generate and set NEXTAUTH_SECRET using: openssl rand -base64 32

Login Redirects but Shows Error

  • Cause: Callback URL mismatch
  • Solution: Verify the callback URL in your OAuth app settings matches: https://yourdomain.com/api/auth/callback/github (or /gitlab, /azure-ad)

Can't Access Dashboard After Login

  • Cause: API connection issue or missing user data
  • Solution:
    • Check API container logs: docker-compose logs api
    • Verify NEXT_PUBLIC_API_URL is set correctly
    • Ensure database migrations have run

Repository Connection Issues

"Repository not found" Error

  • Cause: Repository doesn't exist or you don't have access
  • Solution:
    • Verify the repository name format: owner/repo-name
    • Check you have read access to the repository
    • For private repos, ensure your OAuth token has appropriate scopes

"Failed to validate repository" Error

  • Cause: API error or network issue
  • Solution:
    • Check your internet connection
    • Verify the API is running and accessible
    • Check API logs for detailed error messages

Azure DevOps: "Organization not found"

  • Cause: Organization name incorrect or PAT invalid
  • Solution:
    • Verify organization name matches your Azure DevOps URL
    • Regenerate your PAT token
    • Ensure PAT has Code (Read) and Project and Team (Read) scopes

Azure DevOps: "No repositories found"

  • Cause: No repositories in selected projects or insufficient permissions
  • Solution:
    • Verify you have access to projects containing repositories
    • Check PAT permissions include project access
    • Try discovering from a different organization

Token Expiration

GitHub/GitLab Token Expired

  • Symptom: Can't fetch repository data, 401 errors
  • Solution: Sign out and sign back in to refresh your token

Azure DevOps PAT Expired

  • Symptom: Can't sync repositories, authentication errors
  • Solution:
    • Generate a new PAT in Azure DevOps
    • Reconnect your organization with the new token
    • Update the connection in Settings if available

Multiple Provider Support

Switching Between Providers

  • You can sign out and sign in with a different provider
  • Each provider maintains separate repository lists
  • Azure users can see repositories from all providers (if configured)

Cross-Provider Repository Access

  • Currently, repositories are provider-specific
  • GitHub users see only GitHub repositories
  • GitLab users see only GitLab repositories
  • Azure users can see all repositories (GitHub, GitLab, Azure DevOps)

Security Best Practices

  1. Rotate Access Tokens Regularly
    • GitHub/GitLab: Re-authenticate periodically
    • Azure DevOps: Regenerate PAT tokens every 90 days
  2. Use Minimal Required Permissions
    • Only grant read access to repositories
    • Don't grant write or admin permissions unless necessary
  3. Secure PAT Storage
    • Azure DevOps PATs are encrypted in the database
    • Never share PATs or tokens
  4. Monitor Access
    • Review connected applications in your provider settings
    • Revoke access if you no longer use Git Wizard

Next Steps

After completing authentication and setup:

  1. Read the Usage Guide to learn how to navigate the dashboard
  2. Explore the Sections Guide to understand each metric and feature
  3. Start analyzing your repositories and tracking your team's performance