fjctl

CLI for maintaining Forgejo repositories as IaC.

Installation

Binary

Note

Due to the limitation of my self-hosted Forgejo Actions runner, we only build Linux binaries right now.

curl -L "https://codeberg.org/pbrisbin/fjctl/releases/download/v${VERSION}/fjctl-${VERSION}-Linux-x86_64.tar.gz" | tar xvzf -
cd fjctl
make install PREFIX=$HOME/.local # user installation
sudo make install # global installation, likely needs root

Installation includes man-pages fjctl.1 (the CLI) and fjctl.5 (the configuration file) and shell completions for bash, fish, and zsh.

Source

Building from source requires a Haskell tool-chain, specifically Stack.

git clone https://codeberg.org/pbrisbin/fjctl && cd fjctl
just dist-check # to install everything (in ~/.local)
stack install # to install just the binary
stack exec -- fjctl ... # to run without installation

Getting Started

1. Create ~/.config/fjctl/config.yaml (assuming default $XDG variables)

2. Add a defaults key with properties you want for all repositories

   defaults:has_actions:trueallow_merge_commits:falsedefault_delete_branch_after_merge:truedefault_merge_style:fast-forward-onlydefault_update_style:rebase

3. Add a repositories key with name-properties pairs

   To accept all defaults, use {}. Otherwise, add the properties that differ from defaults for this repository.

   repositories:pbrisbin/hs-shellwords:description:Parse a string into a list of words, like a shell wouldhas_releases:trueallow_merge_commits:true

4. Run fjctl to compare the on-disk state to the server state and report any differences

5. Add --apply to make the server state match the on-disk state

For an example, see my own (work in progress) config.yaml.

Migration

The --create-via-migrate option can be used to migrate, instead of create, any configured repositories that do not exist on the server. By default, this migrates the same-named repository from GitHub and uses no authentication. This can be adjusted by adding a migrate_options stanza in the configuration file:

migrate_options:clone_addr_template:"https://github.com/{owner}/{name}.git"auth_token:nullauth_username:nullauth_password:nulllabels:falsemilestones:false

Deletion

fjctl will report, but not delete, things that exist on the server but not in the configuration. This includes variables, branch-protections, and whole repositories.

It's an open feature to handle deletes in a safe and intuitive way.

Usage

See fjctl(1) for CLI usage and fjctl(5) for documentation of the configuration file.

License

This project is licensed AGPLv3. See COPYING.