GitStore

A Gleam library for interacting with git forge repositiories like Codeberg, Forgejo and GitHub.
GitStore provides a simple API to create, read, update, and delete files in forge repositories through their respective
REST API.

Installation

gleam add git_store

Usage

First, create a config for your forge. For GitHub and Codeberg, provide the repository owner, repository name, and a personal access token. For self-hosted Forgejo instances, also supply the base URL of your instance.

import git_store

// Codeberg
let config = git_store.new_codeberg_config("owner", "my-repo", "token...")

// GitHub
let config = git_store.new_github_config("owner", "my-repo", "ghp_token...")

// Self-hosted Forgejo
let config = git_store.new_forgejo_config("owner", "my-repo", "token...", "https://forgejo.example.com")

CRUD Operations

All operations return Result(PlatformResponse, GitStoreError). File content is automatically base64-encoded on write and decoded on read.

import git_store
import git_store/types

let config = git_store.new_codeberg_config("owner", "my-repo", "token...")

// Create a file
let assert Ok(types.CreateFileResponse(content: file, ..)) =
  git_store.create_file(config, "notes/hello.txt", "Hello, world!")

// Read a file
let assert Ok(types.GetFileResponse(content: text, ..)) =
  git_store.get_file(config, "notes/hello.txt")

// Update a file
let assert Ok(types.UpdateFileResponse(content: file, ..)) =
  git_store.update_file(config, "notes/hello.txt", "Updated content")

// Delete a file
let assert Ok(types.DeleteFileResponse(..)) =
  git_store.delete_file(config, "notes/hello.txt")

Error Handling

import git_store
import git_store/errors
import git_store/types

case git_store.get_file(config, "missing.txt") {
  Ok(types.GetFileResponse(content: text, ..)) -> io.println(text)
  Error(errors.NoFileFound(filename)) -> io.println("Not found: " <> filename)
  Error(errors.ForgeError(status, body)) -> io.println("API error " <> int.to_string(status))
  Error(errors.HTTPError(msg)) -> io.println("HTTP error: " <> msg)
  Error(errors.ParsingError(msg)) -> io.println("Parse error: " <> msg)
  _ -> io.println("Unexpected response type")
}

Development

Pull requests gladly accepted for small bug fixes.

For anything larger, particularly new features, it's best to raise an issue to discuss ahead of commencing with any work.

Testing

Gleeunit and Birdie are both used for testing.

For integration tests, you will need to set the following environment variables:

CODEBERG_REPO_NAME
CODEBERG_REPO_OWNER
CODEBERG_REPO_TOKEN

To get the values, you must create a repository on Codeberg. Your username will be the owner, and the name you set will be the repo name. You can generate a token here. Repository read and write permissions are required.

Documentation

Further documentation can be found at https://hexdocs.pm/git_store.