Интеграция с GitHub

Обзор

Проект включает интеграцию с GitHub API для предоставления доступа к репозиторию пользователям, совершившим покупку. Система автоматически отправляет приглашение к репозиторию на email пользователя после подтверждения оплаты.

Основные функции интеграции:

  • Отправка приглашений по email для добавления пользователей в репозиторий
  • Проверка наличия существующих приглашений
  • Получение списка участников репозитория
  • Автоматизация процесса предоставления доступа после покупки

Настройка токена доступа GitHub

1. Создание токена с ограниченной областью действия

В отличие от классических токенов, для этого проекта рекомендуется использовать токены с ограниченной областью действия (fine-grained tokens), которые обеспечивают более высокий уровень безопасности:

  1. Перейдите в настройки вашей учетной записи GitHub по адресу https://github.com/settings/tokens?type=beta
  2. Нажмите на кнопку "Generate new token"
  3. Укажите описательное имя для токена, например "DevShip Collaborator Access"
  4. Для срока действия выберите подходящий период (рекомендуется не менее 90 дней для продакшена)
  5. В разделе "Repository access" выберите "Only select repositories" и укажите только репозиторий, к которому вы хотите предоставлять доступ (например, "MelnNik/devship")

Важно!

Убедитесь, что учетная запись, генерирующая токен, является владельцем или администратором указанного репозитория. В противном случае добавление участников будет невозможно.

2. Настройка необходимых разрешений

В разделе "Permissions" необходимо настроить следующие разрешения:

# Разрешения для Repository
Repository permissions:
✓ Administration: Read and Write
✓ Metadata: Read-only

# Обязательно проверьте, что у вас активированы оба этих разрешения
# "Administration" должно быть установлено в "Read and Write"

После настройки разрешений нажмите кнопку "Generate token" и скопируйте сгенерированный токен. Этот токен будет использоваться для аутентификации в GitHub API.

Важное примечание о безопасности

Токен доступа GitHub следует хранить в секрете и никогда не включать в код, доступный публично. Используйте переменные окружения для хранения токена.

Настройка переменных окружения

Добавьте следующие переменные в ваш файл .env.production (для продакшена) или .env (для разработки):

# GitHub Repository Access for Purchases
GITHUB_OWNER=MelnNik
GITHUB_REPO=devship
GITHUB_ACCESS_TOKEN=github_pat_ваш_токен_доступа

Эти переменные используются в классе GitHubService для подключения к API GitHub и выполнения операций с репозиторием.

Как система добавляет пользователей в репозиторий

Процесс добавления пользователя в репозиторий GitHub состоит из следующих шагов:

1. Обработка покупки

После успешной обработки платежа система:

  1. Проверяет, существует ли пользователь в системе
  2. Если пользователь новый, создает учетную запись
  3. Отправляет email с подтверждением покупки
  4. Вызывает метод добавления пользователя в репозиторий
// Код в EmailService.php
public function createOrUpdateUserFromPurchase(
    string $email,
    string $firstName,
    string $lastName,
    array $purchaseDetails
): User {
    // Создание или обновление пользователя
    // ...

    // Добавление пользователя как GitHub-коллаборатора
    $this->addUserAsGitHubCollaborator($email);
    
    // Отправка email с подтверждением покупки
    $this->sendPurchaseConfirmationEmail($user, $generatedPassword, $purchaseDetails);
    
    return $user;
}

2. Проверка существующих приглашений

Система проверяет, имеет ли пользователь уже доступ к репозиторию или было ли отправлено приглашение:

// Код в EmailService.php
public function addUserAsGitHubCollaborator(string $email): array
{
    try {
        // Проверяем, является ли пользователь уже коллаборатором
        if ($this->githubService->isCollaborator($email)) {
            Log::info("User {$email} is already a collaborator");
            return [
                'success' => true,
                'message' => 'User is already a collaborator',
                'already_collaborator' => true
            ];
        }
        
        // Добавляем пользователя как коллаборатора
        $result = $this->githubService->addCollaborator($email);
        Log::info("Added {$email} as GitHub collaborator with result:", $result);
        
        return $result;
    } catch (Exception $e) {
        Log::error("Failed to add {$email} as GitHub collaborator: " . $e->getMessage());
        return [
            'success' => false,
            'message' => $e->getMessage()
        ];
    }
}

3. Отправка приглашения в репозиторий

Система использует GitHub API для отправки приглашения:

// Код в GitHubService.php
public function addCollaborator(string $usernameOrEmail, string $permission = 'push'): array
{
    try {
        // Проверяем, email это или имя пользователя
        $isEmail = strpos($usernameOrEmail, '@') !== false;
        
        if ($isEmail) {
            // Для email используем эндпоинт invitations
            $url = "{$this->apiBaseUrl}/repos/{$this->owner}/{$this->repo}/invitations";
            
            $response = Http::withHeaders([
                'Accept' => 'application/vnd.github+json',
                'Authorization' => "Bearer {$this->accessToken}",
                'X-GitHub-Api-Version' => '2022-11-28',
            ])->post($url, [
                'email' => $usernameOrEmail,
                'permission' => $permission
            ]);
        } else {
            // Для имени пользователя используем стандартный эндпоинт collaborators
            // ...
        }

        // Проверка ответа и возврат результата
        // ...
    } catch (Exception $e) {
        // Обработка ошибок
        // ...
    }
}

Тестирование интеграции с GitHub

Для проверки корректности настройки токена и доступов используйте встроенную консольную команду:

# В директории проекта выполните:
php artisan github:test-permissions

Эта команда выполнит серию тестов, проверяющих:

  • Доступ к списку существующих приглашений в репозиторий
  • Доступ к списку коллабораторов репозитория
  • Возможность отправки приглашения по email

Если какой-либо из тестов не прошел, команда выведет сообщение об ошибке с указанием возможной причины и рекомендации по решению.

Рекомендация

Рекомендуется запускать тест после каждого обновления токена или изменения конфигурации GitHub, чтобы удостовериться в корректности работы интеграции.

Устранение неполадок

Распространенные ошибки

1. "Resource not accessible by personal access token"

Возможные причины:

  • Недостаточные разрешения токена (убедитесь, что включено "Administration: Read and Write")
  • Токен не имеет доступа к указанному репозиторию (проверьте настройки "Repository access")
  • Владелец токена не имеет прав администратора в репозитории

Решение:

  • Создайте новый токен с правильными разрешениями и ограничениями по репозиторию
  • Убедитесь, что аккаунт, генерирующий токен, имеет права администратора в репозитории

2. "Not Found" при работе с API

Возможные причины:

  • Неверное имя репозитория или владельца (опечатка в переменных окружения)
  • Репозиторий больше не существует или был переименован

Решение:

  • Проверьте и исправьте значения переменных GITHUB_OWNER и GITHUB_REPO в .env файле
  • Удостоверьтесь, что репозиторий существует и доступен

3. "Validation Failed" при отправке приглашения

Возможные причины:

  • Неверный формат email-адреса
  • Неверное значение параметра permission (допустимые значения: pull, push, admin, maintain, triage)

Решение:

  • Проверьте корректность email-адресов
  • Используйте только допустимые значения для permission (рекомендуется "push")