Development

The source is at git.fig.systems/eddie/birdpal.

Build and test

You need Go 1.27 or newer.

go build -o birdpal .

e2e_test.py runs birdpal against fake Bird Buddy, media and Immich servers. It does not touch your accounts.

go build -o birdpal_test_bin . && python3 e2e_test.py

Two environment variables exist for tests: BIRDBUDDY_GRAPHQL_URL points birdpal at a fake Bird Buddy API, and BIRDPAL_VERIFY_WAIT (a Go duration such as 0s) shortens the wait before the check and between API retries. The fake servers do not check GraphQL queries against Bird Buddy's real schema. Test changes to the queries against the real API with --dry-run.

Release

A tag push builds and publishes a release with GoReleaser (.goreleaser.yaml) in Forgejo Actions (.forgejo/workflows/release.yml):

git tag v1.2.3
git push origin v1.2.3

A tag with a suffix, such as v1.2.3-rc.1, makes a pre-release: no latest image tag. Test the release build locally first; nothing is published:

goreleaser check
goreleaser release --snapshot --clean --skip=ko

Secrets (Forgejo user Settings → Actions → Secrets):

Secret	Needed for
RELEASE_TOKEN	Optional: a Forgejo access token (Repository: read and write). Set it only if the automatic token cannot create releases.
QUAY_USERNAME, QUAY_PASSWORD, QUAY_NAMESPACE	Images on quay.io: a robot account (<namespace>+<robot>) with Write on the repository
DOCKERHUB_USERNAME, DOCKERHUB_TOKEN	Images on Docker Hub: an access token with Read & Write

This site

These pages are in docs/ and built with MkDocs and the Terminal theme. Every push to main that changes docs/ or mkdocs.yml, and every release, rebuilds the site with .forgejo/docs.py. The download table on the Install page comes from the latest release.

pip install -r .forgejo/docs-requirements.txt
mkdocs serve