Getting startedQuickstart

Quickstart

Install joflux, set both organizations, export the inventory, then run the remaining stages in order.

Install

Homebrew
From a checkout

brew tap netspeedy/joflux
brew install joflux

macOS and Linux. If Homebrew refuses the new third-party tap, runbrew trust netspeedy/joflux once, then install again.

git clone https://github.com/netspeedy/joflux.git
cd joflux
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .

Python 3.11 or newer, and nothing outside the standard library. For YAML configs, install'.[yaml]' instead of ..

Check it’s on your path:

joflux --version

Point it at both organizations

Copy the example config from the repository and set the GitHub organization you’re moving from and the Forgejo organization you’re moving to:

cp joflux.toml.example joflux.toml

[github]
org = "my-github-org"

[forgejo]
url = "https://codeberg.org"
org = "my-forgejo-org"

[migration]
poll_interval = 30
max_wait_time = 3600
log_level = "INFO"
output_dir = "migration_output"
metadata = true

Create the target organization on Forgejo before you go further; migrate won’t create it for you. Then put both tokens in the environment rather than in the file:

export JOFLUX_GITHUB_TOKEN="ghp_your_github_token"
export JOFLUX_FORGEJO_TOKEN="your_forgejo_token"

Before you migrate covers what each token needs to be able to do.

Export the inventory

export only reads from GitHub, so it’s the safe first step:

joflux --config joflux.toml export

It lists the organization and saves the inventory:

02:39:52 - INFO - Fetching repositories from GitHub org: my-github-org
02:39:52 - INFO - Found 14 repositories
02:39:52 - INFO - Inventory saved: migration_output/repos-inventory.json
02:39:52 - INFO - Exported 14 repositories (3 private, 1 forks, 1 archived)

Read migration_output/repos-inventory.json before going any further, because it’s the list every later stage works from. If forks or repositories that are already archived shouldn’t move, export again with a filter:

joflux --config joflux.toml export --exclude-forks --exclude-archived

Run the rest

When the inventory is right, run the remaining stages in order, all with the same config:

Run the migrations. migrate waits for Forgejo to finish each one:
```
joflux --config joflux.toml migrate
```
Check the ones Forgejo didn’t answer for in time. With none, monitor exits straight away; otherwise it names the repositories it can’t confirm, for you to check in the Forgejo web UI.
```
joflux --config joflux.toml monitor
```
Check what arrived. verify exits with code 1 and names any repository that isn’t on the target.
```
joflux --config joflux.toml verify
```
Archive the GitHub originals once the report looks right:
```
joflux --config joflux.toml archive
```

Next steps

The five stagesThe five stagesWhat each stage reads and writes, and how to re-run one.GuidesConfigurationConfig formats, tokens, GitHub Enterprise Server and older keys.ReferenceOutput filesEvery field in the five JSON files a run leaves behind.ReferenceExit codesWhat 0, 1, 2 and 130 mean, for scripting the stages.