nakada0907/n-daisuke897-blog
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request 'feat: add forgejo-cli guide blog post' (#10) from develop into main

Browse source 
Reviewed-on: #10
This commit is contained in:
Daisuke Nakahara 2026-02-01 12:54:46 +00:00
commit 68227f1188
1 changed files with 132 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

132
src/blog/post-9.md Normal file
View file

@ -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 <REPO> [TITLE] --body <BODY>
```
To search for issues in a specific repository, use `fj issue search`. The `--repo` option is required:
```bash
$ fj issue search --repo <REPO>
```
To view issue details, use `fj issue view <ISSUE> body`. Replace `<ISSUE>` 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 <ISSUE> -w <WITH_MSG>
```
## Pull Requests
Create a pull request with `fj pr create`. This creates a pull request requesting to merge the `<HEAD>` branch into the `<BASE>` branch:
```bash
$ fj pr create --repo <REPO> --base <BASE> --head <HEAD> [TITLE] --body <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 <REPO> -s <STATE>
```
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.