UniGitAPI

A Git-related RESTful API service built with Node.js and TypeScript.

Features

• 🚀 RESTful API built with Express.js and TypeScript
• 📦 Packaged as executable binary (unigitapi command)
• 🔄 CI/CD with GitHub Actions
• 📝 Type-safe with TypeScript
• 🌐 Easy to install via npm

Installation

Global Installation (npm)

npm install -g unigitapi

Local Development

git clone xxx/UniGitAPI.git
cd UniGitAPI
npm install
npm run build

Usage

Running the Service

After global installation:

unigitapi

Or for local development:

npm start

The server will start on port 3000 by default (configurable via PORT environment variable).

Development Mode

npm run dev

API Endpoints

Root Endpoint

GET /

Returns API information and available endpoints.

Health Check

GET /health

Returns server health status.

Create Repository

POST /api/repos

Creates a repository in the selected provider (GitHub or GitLab). Provider can be set globally via env or per-request.

Request body (JSON):

• provider: "github" | "gitlab" (optional; defaults to env GIT_PROVIDER)
• name: string (required)
• description: string (optional)
• private: boolean (optional; GitHub-style)
• visibility: "public" | "private" | "internal" (optional; GitLab-style)
• owner: string (optional; GitHub org name; omit for user account)
• namespaceId: number (optional; GitLab namespace/group id; omit for user account)
• initializeReadme: boolean (optional)

Example (GitHub, under authenticated user):

curl -X POST http://localhost:3000/api/repos \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "github",
    "name": "demo-repo",
    "description": "My demo",
    "private": true,
    "initializeReadme": true
  }'

Example (GitHub, under organization):

curl -X POST http://localhost:3000/api/repos \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "github",
    "name": "demo-repo",
    "owner": "my-org"
  }'

Example (GitLab, under group/namespace):

curl -X POST http://localhost:3000/api/repos \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "gitlab",
    "name": "demo-repo",
    "namespaceId": 123456,
    "visibility": "private"
  }'

Delete Repository

DELETE /api/repos

Deletes a repository in the selected provider.

Request body (JSON):

• provider: "github" | "gitlab" (optional; defaults to env GIT_PROVIDER)
• id: string | number (for GitLab you can pass numeric project id)
• fullName: string (e.g. "owner/repo" for GitHub; "group/subgroup/repo" for GitLab)
• owner: string (GitHub org/user; used with name)
• name: string (repository name; if only name is provided on GitLab, the API will try to resolve via search)
• namespaceId: number (GitLab namespace/group id; used to disambiguate when resolving by name)

Example (GitHub):

curl -X DELETE http://localhost:3000/api/repos \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "github",
    "fullName": "my-org/demo-repo"
  }'

Example (GitLab by id):

curl -X DELETE http://localhost:3000/api/repos \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "gitlab",
    "id": 123456
  }'

Scripts

• npm run build - Build TypeScript to JavaScript
• npm start - Start the production server
• npm run dev - Start development server with ts-node
• npm run clean - Clean build artifacts
• npm test - Run tests

Project Structure

UniGitAPI/
├── src/
│   └── index.ts          # Main application entry point
├── dist/                 # Compiled JavaScript (generated)
├── .github/
│   └── workflows/
│       └── ci-cd.yml     # CI/CD configuration
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md

CI/CD

The project uses GitHub Actions for continuous integration and deployment:

• Build: Runs on Node.js 18.x and 20.x
• Test: Executes test suite
• Publish: Automatically publishes to npm on release

To publish a new version:

1. Update version in package.json
2. Create a GitHub release
3. The package will be automatically published to npm

Environment Variables

• PORT - Server port (default: 3000)
• GIT_PROVIDER - Default provider: github or gitlab (default: github)
• GITHUB_TOKEN - GitHub Personal Access Token (classic or fine-grained) with repo scope
• GITHUB_API_BASE - GitHub API base URL (default: https://api.github.com). For GitHub Enterprise, set e.g. https://github.myco.com/api/v3.
• GITLAB_TOKEN - GitLab Personal Access Token with api scope
• GITLAB_API_BASE - GitLab API base URL (default: https://gitlab.com/api/v4). For self-hosted GitLab, set e.g. https://gitlab.myco.com/api/v4.

Development

Building

npm run build

Running Tests

npm test

License

MIT