Forgejo & Git Hosting

Tawa provides private Git hosting via Forgejo at git.insureco.io. Push to deploy — no CI config needed.

Getting Started with Forgejo

The tawa login command authenticates both Bio-ID and Forgejo in a single flow. After Bio-ID OAuth completes, the CLI automatically chains a Forgejo OAuth2+PKCE flow so you’re authenticated with the Git server as well.

# Authenticate with Bio-ID and Forgejo
tawa login

Once logged in, create a repository on git.insureco.io with an auto-deploy webhook:

# Create a repo with auto-deploy webhook
tawa git create my-service

Then add the Forgejo remote to your local repository and push:

git remote add origin [email protected]:username/my-service.git
git push -u origin main

That first push triggers the builder automatically — your service will be built, deployed, and live within minutes.

Auto-Deploy Webhooks

When you create a repo with tawa git create, the CLI registers a webhook on Forgejo that notifies the builder on every push. Here’s how it works:

  1. You push to the default branch (main or master)
  2. Forgejo sends a webhook payload to the builder with the commit SHA
  3. The builder clones at that exact commit and runs the full deploy pipeline
  4. Your service is built, pushed to the registry, deployed via Helm, and DNS is configured
Default branch only. The webhook only fires on pushes to the default branch (typically main or master). Pushes to feature branches do not trigger a deploy.

The auto-deploy pipeline is identical to what runs when you use tawa deploy manually — Docker build, Helm deploy, database provisioning, OAuth provisioning, Koko registration, and DNS configuration all happen automatically.

Authentication

There are several ways to authenticate with the Forgejo Git server:

MethodHowBest for
tawa loginOAuth2 flow — stores credentials in ~/.tawa/forgejo-credentials.jsonDay-to-day development
tawa git login <token>Personal Access Token (PAT) — stored in ~/.tawa/forgejo-credentials.jsonCI/headless environments
SSH keysAdd your public key in your git.insureco.io user settingsGit push/pull without token prompts
Web SSOSign in to git.insureco.io via Bio-ID in your browserBrowsing repos, managing settings

CI/Headless Environments

In environments where a browser-based OAuth flow isn’t possible (CI pipelines, Docker containers, remote servers), use a Personal Access Token:

  1. Go to git.insureco.io → Settings → Applications → Generate New Token
  2. Give the token a descriptive name and select the scopes you need
  3. Store the token with the CLI:
tawa git login <token>

For GitHub Actions or other CI systems, set the FORGEJO_TOKEN environment variable instead:

# In your CI config (e.g., .github/workflows/deploy.yml)
env:
  FORGEJO_TOKEN: ${{ secrets.FORGEJO_TOKEN }}

The CLI will detect the environment variable automatically and use it for Forgejo API calls.

Forgejo vs GitHub

You can host your code on either Forgejo or GitHub. Here’s how they compare on the Tawa platform:

FeatureForgejo (git.insureco.io)GitHub / GitLab
HostingPrivate, platform-managedExternal
Auto-deploy on pushYes — webhook fires on default branch pushNo — use tawa deploy manually
SSOBio-ID (same identity as the rest of Tawa)Separate authentication
Setup commandtawa git create <name>tawa link
Deploy pipelineFull pipeline (build, Helm, DNS, OAuth, databases)Same pipeline, triggered via tawa deploy
Tip: If you want push-to-deploy without configuring CI, Forgejo is the simplest path. If your team already uses GitHub, use tawa link to connect the repo and deploy with tawa deploy.

Common Commands

CommandDescription
tawa git create my-siteCreate a repo on git.insureco.io with an auto-deploy webhook
tawa git login <token>Authenticate with a Personal Access Token (for CI/headless use)
tawa linkLink an existing GitHub or GitLab repo to the builder
tawa loginFull OAuth flow — authenticates both Bio-ID and Forgejo
tawa login --skip-gitAuthenticate Bio-ID only, skip Forgejo OAuth chain
tawa deployManual deploy (use when hosting on GitHub instead of Forgejo)

Related