Gitea Integration¶

Taskbase can optionally mirror tasks as Gitea issues — one issue per task in the linked repository. The sync is bidirectional for issue lifecycle events: outbound (Taskbase → Gitea) for task create/update/close/reopen and agent progress comments, inbound (Gitea → Taskbase) via webhooks for issue edits, state changes, comments, and PR references. See the Gitea → Taskbase (Webhooks) section for the inbound flow.

Activation¶

Sync is opt-in at the project level. Both the organization's gitea_org field and the project's gitea_repo field must be set for sync to be active on that project. Once both are set, the API auto-registers a webhook on the target repo — no manual per-repo setup.

The sections below walk through each step. If you are enabling sync for an existing Taskbase project, jump straight to Enabling a project.

Prerequisites (platform-level, one-time)¶

These are done once per Taskbase deployment and already in place for the prod environment. You only need to revisit them when standing up a new deployment or rotating credentials.

After changing any OpenBao value, trigger an ExternalSecret refresh and restart the deployment so the new secret reaches the pod:

kubectl -n tasks-prod annotate externalsecret tasks-gitea force-sync="$(date +%s)" --overwrite
kubectl -n tasks-prod rollout restart deploy platform-tasks-api

Enabling a Gitea org on a Taskbase organization¶

Per org, done once. The bot must be a member of the Gitea org with Admin on the repos that will be linked — webhook management requires Admin, not Write. Easiest path: add taskbase-bot to the Owners team of the Gitea org. If you prefer a narrower team, grant it Code: Admin on the repos you plan to link.

Then set gitea_org on the Taskbase organization:

curl -sH "X-API-Key: $TASKBASE_PROD_API_KEY" -XPUT \
  https://taskbase.skatzi.com/api/organizations/{orgId} \
  -H 'Content-Type: application/json' \
  -d '{"name":"Skatzi","description":"...","gitea_org":"Skatzi"}'

gitea_org is the owner name as it appears in Gitea URLs (gitea.prod.skatzi.com/<gitea_org>/<repo>). It's case-sensitive.

Enabling a project¶

Per project, done once. Set gitea_repo to the repository name (not a URL):

curl -sH "X-API-Key: $TASKBASE_PROD_API_KEY" -XPUT \
  https://taskbase.skatzi.com/api/projects/{id} \
  -H 'Content-Type: application/json' \
  -d '{"name":"Platform","description":"...","gitea_repo":"platform"}'

The API validates that the repo exists before persisting the link. If Gitea responds with 404, the PUT is rejected with HTTP 400 and {"error":"gitea repo not found"} — catches typos and wrong capitalisation before they produce a broken project. Other errors (network, 5xx) are treated as soft-fails: the link is saved and the webhook registration step is attempted anyway, so a Gitea outage can't block project edits.

As soon as this PUT succeeds, the API:

1. Calls POST /api/v1/repos/{gitea_org}/{gitea_repo}/hooks to register the webhook.
2. Stores the returned hook ID in projects.gitea_webhook_id.

Verify:

curl -sH "X-API-Key: $TASKBASE_PROD_API_KEY" \
  https://taskbase.skatzi.com/api/projects/{id} | jq '{gitea_repo, gitea_webhook_id}'

gitea_webhook_id should be non-null. You should also see a new webhook at gitea.prod.skatzi.com/{gitea_org}/{gitea_repo}/settings/hooks. Smoke-test by editing an issue title in Gitea and confirming the linked task updates in Taskbase.

Disabling sync¶

Clearing gitea_repo (PUT with null) deletes the webhook and stops sync for that project. Deleting the project itself also deletes the webhook. Existing issues in Gitea stay untouched.

Troubleshooting¶

What gets synced¶

Tasks created before sync was enabled are not back-filled. Only changes after activation trigger Gitea calls.

Gitea API — Investigation Notes¶

Gitea exposes a REST API at https://gitea.prod.skatzi.com/api/v1/.

Auth¶

Personal Access Token (PAT) via Authorization: token <pat> header. A service account PAT with read:user, write:issue, and write:repository scopes is required. No OAuth app is needed for server-side sync.

The PAT is stored in OpenBao at hetzner-mgmt/taskbase/gitea under key token and injected as GITEA_TOKEN env var in the Taskbase API deployment via External Secrets Operator. See Prerequisites above for the full secret layout.

Endpoints used¶

The POST /issues response includes a stable number field (the issue number within the repo) that Taskbase stores in tasks.gitea_issue_number for subsequent updates.

Rate limits¶

Our self-hosted Gitea has no enforced rate limits. If limits are added in future, the client should handle 429 Too Many Requests with exponential backoff.

Error handling¶

Gitea sync failures are non-fatal — a task update succeeds even if the Gitea API call fails. Errors are logged by the Taskbase API server. In v1 there is no retry queue; the operator can manually sync if needed.

Configuration¶

GITEA_TOKEN, GITEA_BASE_URL are all optional. If GITEA_TOKEN is empty, Gitea sync (both directions) is globally disabled regardless of per-project configuration.

Gitea → Taskbase (Webhooks)¶

Inbound webhooks keep Taskbase state in sync with changes made on the Gitea side: issue edits, state changes, comments, and pull requests that reference an issue.

Endpoint¶

POST /api/webhooks/gitea — single endpoint, dispatches on the X-Gitea-Event header.

Event scope (v1)¶

Label, assignee, and milestone events are out of scope for v1; they will 200 and log.

Signature verification¶

Gitea signs webhook bodies with HMAC-SHA256 using the configured secret. The hex digest is sent in X-Gitea-Signature. The handler:

1. Reads the raw request body.
2. Computes hmac.SHA256(GITEA_WEBHOOK_SECRET, body) and compares (constant-time) to the header value.
3. On mismatch, returns 401 and does not process.

Task lookup¶

1. repository.full_name (e.g. Skatzi/platform) is split and matched to a project via organizations.gitea_org + projects.gitea_repo.
2. issue.number is matched to a task via tasks.gitea_issue_number + that project id.
3. If either lookup fails, respond 200 with a log line. This prevents Gitea from retrying forever on unlinked repos or orphan issues.

Idempotency and redelivery¶

Handlers are idempotent by construction — every operation is "set state to X" or "upsert by Gitea ID". Redelivery is safe. The X-Gitea-Delivery UUID is recorded in the structured log for debugging but is not stored.

Loop prevention¶

When Taskbase writes to Gitea, Gitea immediately fires the webhook back. The handler drops events whose sender.login == GITEA_BOT_LOGIN. This string-match is sufficient as long as the bot PAT is not used by any other automation.

Auto-registration¶

Webhooks are registered automatically by the Taskbase API when a project's gitea_repo is set (or changes) — no manual setup per repo. All three of the following must be true:

• the project has a non-empty gitea_repo
• its organization has a non-empty gitea_org
• the deployment has PUBLIC_BASE_URL and GITEA_WEBHOOK_SECRET set

When these conditions are met, the API calls:

POST /api/v1/repos/{owner}/{repo}/hooks
{
  "type": "gitea",
  "active": true,
  "events": ["issues", "issue_comment", "pull_request"],
  "config": {
    "url": "{PUBLIC_BASE_URL}/api/webhooks/gitea",
    "content_type": "json",
    "secret": "{GITEA_WEBHOOK_SECRET}"
  }
}

The returned hook ID is stored on the project in the gitea_webhook_id column so it can be removed later. When gitea_repo changes, the old hook is deleted (DELETE /repos/{owner}/{repo}/hooks/{id}) and a new one is registered against the new repo. Clearing gitea_repo or deleting the project also deletes the hook. Registration failures are non-fatal — they log and leave gitea_webhook_id null; the project CRUD call itself still succeeds. An operator can rerun registration by toggling the gitea_repo field.

In local development PUBLIC_BASE_URL is typically unset, in which case registration is a no-op (dev is not reachable from the prod Gitea anyway).

Schema additions¶

ALTER TABLE projects
    ADD COLUMN gitea_webhook_id BIGINT DEFAULT NULL;

CREATE TABLE task_comments (
    id               BIGSERIAL PRIMARY KEY,
    task_id          BIGINT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
    gitea_comment_id BIGINT UNIQUE,
    author_login     TEXT NOT NULL,
    body             TEXT NOT NULL,
    created_at       TIMESTAMPTZ NOT NULL,
    updated_at       TIMESTAMPTZ NOT NULL,
    deleted_at       TIMESTAMPTZ DEFAULT NULL
);

CREATE INDEX ON task_comments (task_id, created_at);

gitea_comment_id is unique to deduplicate redelivery; nullable so the table can later hold Taskbase-originated comments. Deletion is soft so a user who accidentally deletes in Gitea can see the ghost row in history.

Surfacing activity in the UI¶

Mirrored comments and PR activity are exposed at GET /api/tasks/{id}/comments and rendered as an Activity section in the task detail modal. Comments with a non-null gitea_comment_id deep-link back to the issue page on Gitea; synthetic PR-activity rows render with a dashed border to distinguish them from real comments.

Out of scope (deferred to v2)¶

• Bi-directional comment authoring (v1 is read-only; users comment in Gitea).
• Assignee / label / milestone sync.
• Bulk import of pre-existing Gitea issues as tasks.
• Automatic issue close on PR merge (kept as human action so the kanban stays the source of truth for workflow state).