Compare commits
3 commits
cc50a21dcd
...
68227f1188
| Author | SHA1 | Date | |
|---|---|---|---|
| 68227f1188 | |||
| 3cfe66a24e | |||
| 9755fb9ec5 |
1 changed files with 132 additions and 0 deletions
132
src/blog/post-9.md
Normal file
132
src/blog/post-9.md
Normal 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.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue