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 repository
final repo = await gitHubKit.repositories.getRepository('octocat', 'Hello-World');
print('Repository: ${repo.fullName}');

// Create a repository
final newRepo = await gitHubKit.repositories.createRepository('New-Repo', private: true);
print('Created new repository: ${newRepo.fullName}');

// List repositories
final repos = await gitHubKit.repositories.listRepositories('octocat');
for (var repo in repos) {
print('Repo: ${repo.name}');
}

Issues

// Create an issue
final issue = await gitHubKit.issues.createIssue('octocat', 'Hello-World', 'Bug report', body: 'This is a bug report');
print('Created issue #${issue.number}');

// Get an issue
final fetchedIssue = await gitHubKit.issues.getIssue('octocat', 'Hello-World', 1);
print('Issue title: ${fetchedIssue.title}');

// List issues
final 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 request
final pr = await gitHubKit.pullRequests.createPullRequest('octocat', 'Hello-World', 'New feature', 'feature-branch', 'main');
print('Created PR #${pr.number}');

// Get a pull request
final fetchedPR = await gitHubKit.pullRequests.getPullRequest('octocat', 'Hello-World', 1);
print('PR title: ${fetchedPR.title}');

// List pull requests
final prs = await gitHubKit.pullRequests.listPullRequests('octocat', 'Hello-World', state: 'open');
for (var pr in prs) {
print('PR #${pr.number}: ${pr.title}');
}

GitHub Actions

// List workflows
final workflows = await gitHubKit.actions.listWorkflows('octocat', 'Hello-World');
for (var workflow in workflows) {
print('Workflow: ${workflow.name}');
}

// Create a workflow dispatch event
await gitHubKit.actions.createWorkflowDispatch('octocat', 'Hello-World', 'main.yml', 'main');
print('Workflow dispatch created');

Code Scanning

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

Secret Scanning

// List secret scanning alerts
final 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 is GitHubException) {
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.