create-gitlab-project

CLI-утилита на TypeScript, которая создаёт проект в GitLab по имени текущей директории, инициализирует локальный git, добавляет базовый .gitignore, настраивает origin и отправляет первый пуш.

Работает на Ubuntu 24.04 (и не только). Использует официальное API GitLab.

Возможности

• Создание проекта в GitLab c именем текущей папки (slug формируется автоматически).

• Поддержка namespace (group) через --namespaceId.

• Инициализация локального репозитория: git init (безопасно и повторяемо).

• Автогенерация базового .gitignore (можно отключить).

• Настройка origin (HTTPS или SSH, либо явный URL) и git push -u.

• Аккуратная обработка кейса «проект уже существует»:

  • интерактивный выбор: продолжить с существующим репо или отменить,
  • без интерактива: --ifExists continue|cancel.

• Опциональный pull --rebase, если удалённый репозиторий не пуст (например, создан с README).

• Конфигурация через .env:

  • глобальный: ~/.config/create-gitlab-project/.env,
  • локальный (переопределяет глобальный): ./.env.

Зависимости

• Node.js ≥ 18
• git в $PATH

NPM-пакеты:

• @gitbeaker/node — GitLab API
• yargs — CLI-парсер
• dotenv — переменные окружения
• simple-git — git-операции
• prompts — интерактивные вопросы
• Dev: typescript, ts-node, @types/node, @types/yargs

Установка (локально как глобальный CLI)

# Установите зависимости
npm install
# Сборка
npm run build
# Установка команды глобально
npm link

Проверьте:

create-gitlab-project --help

Альтернатива для другой машины:

npm run build
npm i -g .

Настройка .env

Глобальный (по умолчанию)

Храните токен здесь.

mkdir -p ~/.config/create-gitlab-project
nano ~/.config/create-gitlab-project/.env
chmod 600 ~/.config/create-gitlab-project/.env

Пример:

GITLAB_HOST=https://gitlab.com
GITLAB_TOKEN=glpat_xxx          # Personal Access Token со scope: api
GITLAB_VISIBILITY=private       # private|internal|public
# GITLAB_NAMESPACE_ID=123456    # опционально: ID группы по умолчанию
# GIT_REMOTE=https              # https|ssh
# GIT_DEFAULT_BRANCH=main
# GIT_IF_EXISTS=ask             # ask|continue|cancel

Проектный (локально для конкретной папки)

./.env — переопределяет глобальный.

GITLAB_NAMESPACE_ID=999999
GITLAB_VISIBILITY=public

Добавьте .env в .gitignore.

Использование

Простейший запуск в нужной папке:

create-gitlab-project

Несколько примеров:

# Указать группу и сделать репо публичным
create-gitlab-project --namespaceId 123456 --visibility public

# Явный адрес origin (перекрывает ssh/https)
create-gitlab-project --remoteUrl "https://gitlab.com/yamadetta/create-gitlab-project.git"

# Использовать SSH вместо HTTPS
create-gitlab-project --remote ssh

# Без интерактива: если проект уже существует — продолжить
create-gitlab-project --ifExists continue

# Отключить автогенерацию .gitignore
create-gitlab-project --noGitignore

После успешного выполнения вы получите:

• созданный проект в GitLab,
• инициализированный локальный git,
• настроенный origin,
• пуш в ветку (по умолчанию main).

Поведение при «проект уже существует»

Если GitLab вернул «has already been taken», утилита:

1. Пытается найти существующий проект (по namespaceId и/или по членству).

2. Предлагает выбор:

   • Продолжить — использовать найденный репозиторий (настроит origin, подтянет изменения при необходимости, запушит);
   • Отменить — завершит работу без изменений.

Для CI/скриптов используйте:

--ifExists continue   # или --ifExists cancel

Опции

--host           GitLab host URL (default: $GITLAB_HOST or https://gitlab.com)
--token          Personal Access Token (scope: api) (default: $GITLAB_TOKEN)
--namespaceId    Числовой ID группы/namespace
--visibility     private|internal|public (default: $GITLAB_VISIBILITY or private)
--initReadme     Создавать README в GitLab при создании проекта (default: false)
--remote         https|ssh (default: $GIT_REMOTE or https)
--remoteUrl      Явный URL для origin (перекрывает --remote)
--branch         Имя основной ветки (default: $GIT_DEFAULT_BRANCH or main)
--noGitignore    Не создавать .gitignore автоматически
--ifExists       ask|continue|cancel (default: $GIT_IF_EXISTS or ask)
--help           Показать помощь

Как это работает

1. Читает конфигурацию из ~/.config/create-gitlab-project/.env, затем из ./.env.
2. Создаёт проект через GitLab API (@gitbeaker/node).
3. Всегда выполняет git init (безопасно, повторные запуски поддерживаются).
4. Создаёт базовый .gitignore (если его ещё нет и опция не отключена).
5. Переименовывает ветку в указанную (main по умолчанию).
6. Настраивает origin (HTTPS/SSH/ручной URL).
7. Если удалённый не пуст, делает fetch и pull --rebase.
8. Делает git add ., коммит при наличии изменений и git push -u origin <branch>.

Типичный .gitignore

Генерируется базовый пресет для Node/TS:

• node_modules/, dist/, кэш/логи, *.env*, .vscode/, .idea/, *.swp, .DS_Store. Вы можете отредактировать его после первого запуска или выключить генерацию флагом --noGitignore.

Токен и доступ

• Нужен Personal Access Token со scope: api.
• Для HTTPS-пуша на GitLab.com используйте PAT как пароль (если включена 2FA).
• Для SSH-режима убедитесь, что настроены ключи и добавлены в GitLab.

Решение проблем

• Error: нужен GitLab токен… — задайте --token или переменную GITLAB_TOKEN.

• has already been taken — ожидаемо, если репозиторий существует; используйте интерактивный выбор или --ifExists continue.

• authentication required / push не проходит — проверьте PAT/SSH и права на группу/репо.

• Конфликты после pull --rebase — решите вручную и повторите git push.

• user.name / user.email не настроены — выполните:

  git config --global user.name "Ваше Имя"
  git config --global user.email "[email protected]"

Разработка

# Запуск из исходников
npx ts-node src/create-gitlab-project.ts --help

# Сборка
npm run build