Deploy from Git

This publishes source from Git. A built static site (Flutter web, next export, and so on) should use CI deploy-static instead. The pipeline reference is on CI runner.

Caution

If the pipeline publishes the built site, leave this app’s git deploy mode unset or manual. An auto link packages the git tree and replaces the built files.

App types, secrets, and limits are on Hosting. A Kataflax repository is created on Git and must already exist in the same project. A GitHub repository uses a personal access token saved under Settings → Integrations, scoped to you, the project, or the organization. The app then picks that integration plus the GitHub owner and repository. The default hostname shape is on the hosting page.

Create the app

1. Open Hosting. The screen title is Backend Apps.

2. New App opens Create Backend App.

3. Enter App name and Slug. Both are required.

4. App type: Container (build and run) or Static site.

5. Environment: production, staging, or preview.

6. Turn on Link to a Git repository. Choose Kataflax repository or GitHub. For GitHub, pick the integration saved in Settings, then the owner and repository.

7. Deploy mode (API value in parentheses):

   • Auto — default branch (auto). Tracks the repo default branch, or the branch chosen in Default branch (gitDeployBranch).
   • Auto — custom branch (auto_branch). Tracked branch is required (gitAutoDeployBranch).
   • Manual — tag (manual). A push does not deploy.

8. Subdirectory (optional): a monorepo path such as apps/web. Blank means the repo root.

Auto deploy

1. Push a commit to the tracked branch, or merge a merge request into it.

2. Open the app. Overview shows Git source, the mode, and the tracked branch.

3. Container apps: the Deployments tab lists the new deployment (build status, deploy status, commit). Static apps: the Releases tab lists it. The live one is the active release.

auto and auto_branch deploy when that branch’s HEAD moves. The same commit is not deployed twice if it is already the active deployment. Mode manual does not run on push.

A GitHub link uses the same three modes. Save the token under Settings → Integrations at user, project, or organization scope. A classic token needs repository contents access plus admin:repo_hook for auto-deploy. A fine-grained token needs Contents (read) and Webhooks (read and write), and the GitHub user must be able to administer hooks on that repo. Auto and custom-branch modes register a push webhook, which requires PUBLIC_API_BASE_URL. Manual mode does not create a hook. The token stays on the integration and is not stored on the app.

Manual deploy

1. Push the commit or tag. Nothing deploys by itself.

2. On the app, Deploy (container) or Publish (static).

3. Manual mode asks for a tag, then Deploy tag or Publish tag. Deploy from another branch opens a branch list and Deploy Branch.

4. The new row appears on Deployments or Releases, as in auto deploy.

A script uses a platform JWT or a PAT, not the client SDK. Container apps:

POST /api/projects/:projectId/backend/apps/:appId/deployments/from-git

Static apps:

POST /api/projects/:projectId/backend/static-apps/:appId/deployments/from-git

Body, one of:

{ "ref": "<tag>" }

{ "branch": "<branch>" }

An empty ref in manual mode returns ref_required (“Provide a branch or tag to deploy”). The rest of the hosting routes are on Hosting, git, and project management.

Built files

deploy-static tars an already-built directory (index.html at the archive root) and publishes it to a static app. It does not run flutter build or next build. It does not use git auto-deploy. See the deploy-static row on CI runner.