GitHubKit

GitHubKit is a comprehensive Dart package for interacting with the GitHub API. It provides an easy-to-use interface for common GitHub operations and supports advanced features like GitHub Actions, code scanning, and secret scanning.

Table of Contents

• Features
• Installation
• Usage
  • Initialization
  • Repositories
  • Issues
  • Pull Requests
  • GitHub Actions
  • Code Scanning
  • Secret Scanning
  • GraphQL API
• Error Handling
• Pagination
• Rate Limiting
• Logging
• Testing
• Examples
• Contributing
• License

Features

• Complete coverage of GitHub REST API v3
• Support for GitHub GraphQL API v4
• Repositories management
• Issues and Pull Requests handling
• GitHub Actions workflow management
• Code scanning and Secret scanning APIs
• Automatic pagination handling
• Built-in rate limit handling and automatic retries
• Comprehensive logging system
• Easy error handling with custom exceptions
• Full support for authentication (Personal Access Tokens)
• Extensive documentation and examples

Installation

Add this to your package's pubspec.yaml file:

dependencies:
github_kit: ^1.0.0

Then run:

$ dart pub get

Usage

Initialization

First, import the package and create an instance of GitHubKit:

import'package:github_kit/github_kit.dart';
final gitHubKit =GitHubKit(token:'your_personal_access_token');

Repositories

// Get a repositoryfinal repo =await gitHubKit.repositories.getRepository('octocat', 'Hello-World');
print('Repository: ${repo.fullName}');
// Create a repositoryfinal newRepo =await gitHubKit.repositories.createRepository('New-Repo', private:true);
print('Created new repository: ${newRepo.fullName}');
// List repositoriesfinal repos =await gitHubKit.repositories.listRepositories('octocat');
for (var repo in repos) {
print('Repo: ${repo.name}');
}

Issues

// Create an issuefinal issue =await gitHubKit.issues.createIssue('octocat', 'Hello-World', 'Bug report', body:'This is a bug report');
print('Created issue #${issue.number}');
// Get an issuefinal fetchedIssue =await gitHubKit.issues.getIssue('octocat', 'Hello-World', 1);
print('Issue title: ${fetchedIssue.title}');
// List issuesfinal issues =await gitHubKit.issues.listIssues('octocat', 'Hello-World', state:'open');
for (var issue in issues) {
print('Issue #${issue.number}: ${issue.title}');
}

Pull Requests

// Create a pull requestfinal pr =await gitHubKit.pullRequests.createPullRequest('octocat', 'Hello-World', 'New feature', 'feature-branch', 'main');
print('Created PR #${pr.number}');
// Get a pull requestfinal fetchedPR =await gitHubKit.pullRequests.getPullRequest('octocat', 'Hello-World', 1);
print('PR title: ${fetchedPR.title}');
// List pull requestsfinal prs =await gitHubKit.pullRequests.listPullRequests('octocat', 'Hello-World', state:'open');
for (var pr in prs) {
print('PR #${pr.number}: ${pr.title}');
}

GitHub Actions

// List workflowsfinal workflows =await gitHubKit.actions.listWorkflows('octocat', 'Hello-World');
for (var workflow in workflows) {
print('Workflow: ${workflow.name}');
}
// Create a workflow dispatch eventawait gitHubKit.actions.createWorkflowDispatch('octocat', 'Hello-World', 'main.yml', 'main');
print('Workflow dispatch created');

Code Scanning

// List code scanning alertsfinal alerts =await gitHubKit.codeScanning.listCodeScanningAlerts('octocat', 'Hello-World');
for (var alert in alerts) {
print('Alert #${alert.number}: ${alert.state}');
}

Secret Scanning

// List secret scanning alertsfinal secretAlerts =await gitHubKit.secretScanning.listSecretScanningAlerts('octocat', 'Hello-World');
for (var alert in secretAlerts) {
print('Secret Alert #${alert.number}: ${alert.state}');
}

GraphQL API

final result =await gitHubKit.graphql(''' query { viewer { login repositories(first: 10) { nodes { name stargazerCount } } } }''');
print('Logged in as: ${result['viewer']['login']}');

Error Handling

GitHubKit uses custom exceptions for error handling. Always wrap your API calls in a try-catch block:

try {
final repo =await gitHubKit.repositories.getRepository('octocat', 'Hello-World');
print('Repository: ${repo.fullName}');
} catch (e) {
if (e isGitHubException) {
print('GitHub API Error: ${e.message} (Status: ${e.statusCode})');
} else {
print('Error: $e');
}
}

Pagination

Most list methods in GitHubKit handle pagination automatically. You can control pagination using the perPage and page parameters:

final repos =await gitHubKit.repositories.listRepositories('octocat', perPage:100, page:2);

Rate Limiting

GitHubKit automatically handles rate limiting by retrying requests when limits are hit. You can configure retry behavior when creating the GitHubKit instance:

final gitHubKit =GitHubKit(
token:'your_token',
maxRetries:5,
retryDelay:Duration(seconds:10),
);

Logging

GitHubKit includes a built-in logging system. You can configure logging when creating the GitHubKit instance:

final gitHubKit =GitHubKit(token:'your_token');
gitHubKit.setLogLevel(LogLevel.debug);

Testing

To run the tests for GitHubKit:

$ dart test

Examples

For more examples, check the example folder in the repository.

Contributing

Contributions are welcome! Please read our Contributing Guide for more information.

License

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