ForgejoKit

A native Swift library for the Forgejo API. ForgejoKit provides a typed, async/await interface for interacting with Forgejo instances from Swift applications on macOS and iOS.

Features

Authentication via username/password (with optional OTP) or API tokens
Repositories: search, list, create, fork, star, file contents, commits, branches, tags, releases
Issues: create, edit, list, comment, manage labels and milestones
Pull requests: create, edit, merge, review, diff
Notifications: list, unread count, mark as read
Self-signed certificate support

Installation

Add ForgejoKit as a dependency in your Package.swift:

dependencies: [
    .package(url: "https://codeberg.org/secana/ForgejoKit.git", from: "0.3.2"),
],
targets: [
    .target(
        name: "MyApp",
        dependencies: ["ForgejoKit"]
    ),
]

Usage

import ForgejoKit

// Authenticate with a token
let client = ForgejoClient(serverURL: "https://codeberg.org", username: "user", token: "your-token")

// Or log in with username/password to create an API token
let result = try await ForgejoClient.login(serverURL: "https://codeberg.org", username: "user", password: "pass")
let client = result.client

// Fetch repositories
let repoService = RepositoryService(client: client)
let repos = try await repoService.searchRepositories(query: "swift")

// Work with issues
let issueService = IssueService(client: client)
let issues = try await issueService.fetchIssues(owner: "owner", repo: "repo")

// Check notifications
let notificationService = NotificationService(client: client)
let unread = try await notificationService.fetchUnreadCount()

Development

Prerequisites

Install Nix and enable flakes.

Dev Shell

Enter the development shell with all required tools:

nix develop

This provides swift, swiftformat, and just on all platforms, plus swiftlint and xcbeautify on macOS.

Building and Testing

The project uses just as a command runner. Run just to see all available commands:

just          # list available commands
just build    # build the library
just test     # run tests
just lint     # lint sources with swiftlint
just format   # format sources with swiftformat

Releasing a New Version

Make sure all changes are committed and pushed, then run:

just release 1.0.0

This will verify the tag doesn't already exist, update the version in README.md, commit, tag, and push. Swift Package Manager resolves versions from git tags, so no registry publication is needed.

2.6 KiB Raw Blame History