GLAC 0.1.1-beta

GLAC - GitLab API Client

A comprehensive .NET REST client library for GitLab API v4, providing easy access to all GitLab resources and operations.

Features

• Complete API Coverage: Access to all major GitLab API endpoints including projects, issues, merge requests, users, groups, pipelines, and administrative functions
• Multi-Framework Support: Compatible with .NET 8.0 and .NET 9.0
• Authentication Support: Supports both personal access tokens and OAuth tokens
• Type-Safe: Fully typed request/response models with comprehensive XML documentation
• Async/Await: Modern async/await pattern throughout the library
• Error Handling: Structured exception handling with detailed error information
• Configurable: Support for custom HTTP handlers, timeouts, and SSL configuration

Installation

Install the package via NuGet Package Manager:

dotnet add package GLAC

Or via Package Manager Console:

Install-Package GLAC

Quick Start

Basic Usage

using GLAC;

// Create client with GitLab instance URL and access token
var client = new GitLabClient("https://gitlab.example.com", "your-access-token");

// Get all projects
var projects = await client.Projects.GetAllAsync();

// Get specific project
var project = await client.Projects.GetAsync(123);

// Create an issue
var newIssue = await client.Issues.CreateAsync(projectId, new CreateIssueRequest
{
    Title = "Bug report",
    Description = "Found a critical bug that needs fixing"
});

Authentication

GLAC supports multiple authentication methods:

// Personal Access Token (20-63 characters)
var client = new GitLabClient("https://gitlab.example.com", "glpat-xxxxxxxxxxxxxxxxxxxx");

// OAuth Token (64 characters)
var client = new GitLabClient("https://gitlab.example.com", "your-64-character-oauth-token");

// No authentication (for public APIs)
var client = new GitLabClient("https://gitlab.example.com");

Custom Configuration

// Custom timeout
var client = new GitLabClient(
    "https://gitlab.example.com", 
    "your-token",
    clientTimeout: TimeSpan.FromMinutes(5)
);

// Custom HTTP handler (e.g., for SSL configuration)
var handler = new HttpClientHandler();
var client = new GitLabClient(
    "https://gitlab.example.com", 
    "your-token", 
    httpMessageHandler: handler
);

API Coverage

GLAC provides access to the following GitLab API resources:

Core Resources

• Projects - Create, update, delete, and manage projects
• Issues - Full issue lifecycle management with notes and attachments
• Merge Requests - Create, review, and merge code changes
• Users - User management and profile operations
• Groups - Group and subgroup management
• Repositories - Repository content, branches, tags, and commits

Development & CI/CD

• Pipelines - Pipeline creation, monitoring, and management
• Jobs - Job execution and artifact management
• Runners - Runner registration and configuration
• Files - Repository file operations (create, read, update, delete)
• Commits - Commit information and operations
• Branches - Branch management
• Tags - Tag creation and management

Administrative

• Admin CI Variables - Global CI/CD variable management
• Admin Clusters - Kubernetes cluster administration
• Admin Batched Background Migrations - Database migration management
• Broadcast Messages - System-wide message broadcasting
• Metadata - GitLab instance information and version details

Additional Features

• Webhooks - Webhook configuration and management
• Deploy Keys - SSH key management for deployments
• Applications - OAuth application management
• Uploads - File upload operations
• Markdown - Markdown rendering service
• Badges - Project and group badge management
• Alert Management - Incident and alert handling
• Access Requests - Group and project access request management
• Avatar - User and group avatar management
• ToDo List - User todo item management
• Iterations - Iteration and milestone management
• Bulk Imports - Mass import operations
• Trees - Repository tree browsing

Examples

Working with Projects

// Get all accessible projects
var projects = await client.Projects.GetAllAsync();

// Search projects
var searchResults = await client.Projects.SearchAsync("my-project");

// Create a new project
var newProject = await client.Projects.CreateAsync(new CreateProjectRequest
{
    Name = "My New Project",
    Description = "A sample project",
    Visibility = ProjectVisibility.Private
});

// Update project settings
await client.Projects.UpdateAsync(projectId, new UpdateProjectRequest
{
    Description = "Updated description"
});

Managing Issues

// Get all issues for a project
var issues = await client.Issues.GetAllAsync(projectId);

// Create an issue with labels and assignee
var issue = await client.Issues.CreateAsync(projectId, new CreateIssueRequest
{
    Title = "Feature Request",
    Description = "Need to implement new feature",
    Labels = new[] { "enhancement", "priority::high" },
    AssigneeId = userId
});

// Add a note to an issue
await client.Issues.CreateNoteAsync(projectId, issueId, "Working on this issue");

// Close an issue
await client.Issues.UpdateAsync(projectId, issueId, new UpdateIssueRequest
{
    StateEvent = IssueStateEvent.Close
});

Pipeline Operations

// Get project pipelines
var pipelines = await client.Pipelines.GetAllAsync(projectId);

// Create a new pipeline
var pipeline = await client.Pipelines.CreateAsync(projectId, new CreatePipelineRequest
{
    Ref = "main"
});

// Get pipeline jobs
var jobs = await client.Pipelines.GetJobsAsync(projectId, pipelineId);

// Cancel a pipeline
await client.Pipelines.CancelAsync(projectId, pipelineId);

User Management

// Get current user
var currentUser = await client.Users.GetCurrentUserAsync();

// Search users
var users = await client.Users.SearchAsync("john");

// Get user projects
var userProjects = await client.Users.GetProjectsAsync(userId);

Error Handling

GLAC provides structured error handling through the GitLabException class:

try
{
    var project = await client.Projects.GetAsync(123);
}
catch (GitLabException ex)
{
    Console.WriteLine($"GitLab API Error: {ex.HttpStatusCode} - {ex.Message}");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Network Error: {ex.Message}");
}

Configuration

Host URL Formats

GLAC accepts various GitLab URL formats:

// All of these are valid:
new GitLabClient("https://gitlab.example.com");
new GitLabClient("https://gitlab.example.com/");
new GitLabClient("https://gitlab.example.com/api/v4");
new GitLabClient("https://gitlab.example.com/api/v4/");

Timeout Configuration

Configure HTTP client timeout for large file operations:

var client = new GitLabClient(
    "https://gitlab.example.com",
    "your-token",
    clientTimeout: TimeSpan.FromMinutes(10) // For large file uploads
);

Development

Building from Source

git clone https://github.com/homolibere/GLAC.git
cd GLAC
dotnet build

Running Tests

dotnet test

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes following the coding standards
4. Add tests for new functionality
5. Submit a pull request

Documentation

• GitLab API Documentation
• API Reference

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Create an issue on GitHub
• Check existing documentation and examples
• Review GitLab's official API documentation

Acknowledgments

• Built for the GitLab community
• Inspired by the need for a comprehensive .NET GitLab API client
• Thanks to all contributors and users
• Inspired by GitLabApiClient