mitasu – forge issues and pull requests as a filesystem

mitasu exposes your forge (Gitea/Forgejo) issues and pull requests as a 9P filesystem. Edit issue titles, descriptions, labels, assignees, and due dates by writing to plain text files. Browse aggregated dashboards as JSON.

Features

• Read‑only dashboards: JSON summaries of repositories, issues, and PRs.
• Write‑back synchronization: Modify issue fields by writing to files.
• Conflict detection: Optimistic locking prevents overwriting concurrent changes.
• Flexible authentication: Token or basic auth.
• Multiple transports: TCP (:564) or Unix socket.
• CLI tools: mitasu serve, mitasu check, mitasu mount.

Quick start

1. Install

   git clone https://git.lan.thwap.org/thwap/mitasu
   cd mitasu
   go install ./cmd/mitasu
   

2. Create a configuration file (~/.mitasu.yaml):

   forge:
     url: https://git.lan.thwap.org
     token: your-personal-access-token
   # 9p:
   #   addr: ":564"                 # listen on TCP port 564
   #   socket_path: /tmp/mitasu.sock # listen on Unix socket (default)
   

3. Test the connection

   mitasu check
   

4. Start the server

   mitasu serve
   

5. Mount the filesystem

   sudo mkdir -p /mnt/mitasu
   sudo mount -t 9p -o trans=unix,uname=$(whoami),version=9p2000.u /tmp/mitasu.sock /mnt/mitasu
   

   Or use the helper:

   mitasu mount | sh
   

6. Browse

   ls /mnt/mitasu/$USER
   cat /mnt/mitasu/$USER/dashboard | jq .
   

Configuration

See the example files:

• example.single.yaml – single‑user setup
• example.org.yaml – organization with repository filters

Environment variables

All configuration fields can be overridden by environment variables:

Variable	Overrides
MITASU_FORGE_URL	forge.url
MITASU_TOKEN	forge.token
MITASU_SOCKET	9p.socket_path
MITASU_ADDR	9p.addr

Authentication

• Token (default): create a token in your forge settings with repo scope.
• Basic auth: set auth_method: basic and provide username/password.

Filesystem layout

/<username>/
├── dashboard               # JSON summary of all repositories
└── <repo-name>/
    ├── dashboard           # JSON list of issues/PRs (first 50 each)
    ├── labels              # JSON array of repository labels
    ├── issues/
    │   └── 000001/
    │       ├── title       # writable
    │       ├── description # writable
    │       ├── labels      # writable (CSV)
    │       ├── assigned_to # writable (username or empty)
    │       ├── due_date    # writable (ISO 8601, issues only)
    │       └── status      # read‑only (open/closed)
    └── prs/
        └── 000001/         # same fields as issues, except due_date ignored

Writable fields

• title – plain text, single line.
• description – plain text, multi‑line.
• labels – comma‑separated list of label names.
• assigned_to – a single username; empty to unassign.
• due_date – ISO 8601 date (2025-12-31T23:59:59Z) or empty.

Changes are synchronized when the file is closed (write‑back). If the issue/PR has been updated on the forge since the file was opened, the write will be rejected with a conflict error.

Usage examples

Edit an issue title

echo "Fix critical bug" > /mnt/mitasu/$USER/myproject/issues/42/title

Update labels

echo "bug,urgent" > /mnt/mitasu/$USER/myproject/issues/42/labels

View open issues across all repositories

cat /mnt/mitasu/$USER/dashboard | jq '.repositories[] | select(.issues.open > 0)'

System integration

systemd

Example unit files are provided in examples/.
Copy examples/mitasu.service to ~/.config/systemd/user/ and enable it:

systemctl --user enable --now mitasu.service

Docker

A multi‑stage Dockerfile is included. Build and run with:

docker build -t mitasu .
docker run -p 564:564 mitasu

See examples/docker-compose.yml for a complete example.

Troubleshooting

• Connection errors: run mitasu check to verify configuration and authentication.
• Permission denied: ensure the Unix socket is writable by the user running mitasu serve.
• Mount fails: ensure the 9p kernel module is loaded (modprobe 9p). On macOS, use mac9p.

Development

Code Quality

The project uses pre-commit hooks to ensure code quality. To set up:

# Install pre-commit
pip install pre-commit
# or on macOS with Homebrew
brew install pre-commit

# Install the hooks
make pre-commit

# Run hooks manually on all files
make pre-commit-all

The hooks include:

• Go: gofmt, goimports, golangci-lint, go vet
• YAML: Syntax validation and linting
• Markdown: Style and formatting
• Dockerfile: Best practices and security
• General: Trailing whitespace, end-of-file newlines

Development Workflow

# Clone and setup
git clone https://git.lan.thwap.org/thwap/mitasu
cd mitasu
make install

# Build and test
make build
make test

# Run linters
make lint

# Format code
make format

See CONTRIBUTING.md for detailed contribution guidelines.

Project Planning

See ROADMAP.md for the project plan and completed features.

License

MIT (see LICENSE file).