From 9755fb9ec52e5ce6264ff247b90d30ed96080016 Mon Sep 17 00:00:00 2001 From: Daisuke Date: Sun, 1 Feb 2026 21:36:53 +0900 Subject: [PATCH] feat: add forgejo-cli guide blog post - Create comprehensive English blog post on operating self-hosted Forgejo via CLI - Document forgejo-cli installation, configuration, and usage workflow - Include detailed examples for managing issues and pull requests - Follow standard bash code block formatting (input with $, output without prefix) - Use example.com placeholder for privacy and security best practices - Add disclaimer about AI-assisted content review --- src/blog/post-9.md | 132 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 src/blog/post-9.md diff --git a/src/blog/post-9.md b/src/blog/post-9.md new file mode 100644 index 0000000..bdff3c7 --- /dev/null +++ b/src/blog/post-9.md @@ -0,0 +1,132 @@ +--- +title: 'Operating Self-Hosted Forgejo via CLI: A forgejo-cli Guide' +pubDate: 2026-02-01 +author: 'Nakahara Daisuke' +tags: ["Forgejo"] +--- + +# Introduction + +I integrated [forgejo-contrib/forgejo-cli](https://codeberg.org/forgejo-contrib/forgejo-cli) to make it easier for AI coding agents to interact with my self-hosted Forgejo instance. forgejo-cli is similar to [`gh`](https://cli.github.com/), the official CLI tool for GitHub. + +# Installation + +I installed it on a Linux environment using Nix's home-manager. The Nix 25.11 package repository includes forgejo-cli Version 0.3.0. + +```nix +{ + ... + outputs = inputs@{ nixpkgs-old, flake-parts, ... }: + let + mkHome = system: homeDirectory: + inputs.home-manager.lib.homeManagerConfiguration { + pkgs = import inputs.nixpkgs { inherit system; }; + modules = [ + ({ pkgs, ... }: { + home.username = "username"; + home.homeDirectory = homeDirectory; + home.stateVersion = "25.11"; + home.packages = with pkgs; [ + forgejo-cli + ]; + }) + ]; + }; + in + ... +} +``` + +forgejo-cli is launched with the `fj` command: +```bash +$ fj version +fj v0.3.0 +``` + +# Generating an Access Token + +Generate a token from Forgejo's frontend at Settings > Applications > Access tokens > Generate new token. I configured the permissions as follows: +- read:notification +- read:organization +- write:package +- write:issue +- write:repository +- write:user + +# Logging In with a Token + +I stored the generated token in [gnome-keyring](https://gitlab.gnome.org/GNOME/gnome-keyring) first: +```bash +$ echo -n "MY_FORGEJO_PAT" | secret-tool store --label="Forgejo PAT" service forgejo user username@git.example.com +``` + +Register the key using the `auth add-key` subcommand. Note that you must specify the host with `-H git.example.com`; otherwise, it defaults to `github.com`: +```bash +$ echo -n "$(secret-tool lookup service forgejo user username@git.example.com)" | fj -H git.example.com auth add-key username +``` + +```bash +$ fj auth list +username@git.example.com +``` +```bash +$ fj -H git.example.com whoami +currently signed in to username@git.example.com +``` + +# Managing Issues and Pull Requests + +The v0.3.0 `fj` provides `issue` and `pr` commands for managing issues and pull requests. + +## Issues + +Create an issue with `fj issue create`. Note that the `-H` flag for specifying the host must come before the subcommand: +```bash +$ fj -H git.example.com issue create --repo [TITLE] --body +``` + +To search for issues in a specific repository, use `fj issue search`. The `--repo` option is required: +```bash +$ fj issue search --repo +``` + +To view issue details, use `fj issue view body`. Replace `` with the issue number. You can also close issues using the `-w` option to include a comment. Interestingly, this command works correctly without requiring the repository name: +```bash +$ fj -H git.example.com issue close -w +``` + +## Pull Requests + +Create a pull request with `fj pr create`. This creates a pull request requesting to merge the `` branch into the `` branch: +```bash +$ fj pr create --repo --base --head [TITLE] --body +``` + +List pull requests using `fj pr search`. You can filter by state using the `-s` option with either `open` or `closed`: +```bash +$ fj pr search -r -s +``` + +View pull request details (title and body) with `fj pr view [ID] body`. + +You can access help for any command using the `--help` flag. + +# Logging Out + +Logout from a host with `fj auth logout`: +```bash +$ fj auth list +username@git.example.com +$ fj auth logout git.example.com +signed out of username@git.example.com +$ fj auth list +No logins. +``` + +# Conclusion + +By introducing `fj` to AI coding agents, I was able to automate issue-based coding and pull request creation. Tools like forgejo-cli that offer CLI operations are particularly valuable for AI agent automation, and I welcome their development. + +--- + +> **Note**: The review and translation were assisted by an AI generative model. The author is responsible for the final content.