Published on
How do you deploy an application from GitHub or Forgejo on Zenifra?
Connect GitHub (or a Forgejo instance) to your organization, create an HTTP project with a Git repository source, pick the runtime, commands, and update mode, and Zenifra installs dependencies, runs the build, and publishes the application over HTTPS. After that, every push to the branch, or every tag or release that matches the configured pattern, ships a new version, and Build logs show exactly where something failed.
How GitHub deployment works on Zenifra
You connect GitHub (or a Forgejo instance) to your organization, create an HTTP project with a Git repository source, and set the runtime, commands, and update mode. Zenifra installs dependencies, runs the build, publishes the application over HTTPS, and from then on every push, tag, or release you choose becomes a new version.
The flow always runs in the same order, as documented in Runtimes and in Deploying from GitHub: dependency installation for the runtime (for example, npm ci on Node.js), the pre-build command (optional), the build command (optional), and the start command (required), which is the process that keeps running and serves requests. Every step runs inside the project Root directory, which defaults to the repository root. Zenifra does not detect the runtime on its own: you choose Node.js, Python, Bun, Go, Java, or PHP when you create the project, along with its version.
This path is for teams that want the platform to handle the build. If your application uses another language (.NET, Ruby, Rust) or your CI already produces a Docker image, the path is different: publish an OCI image. Both options live side by side in the same organization, so you can have one project of each kind. This guide covers the Git repository path end to end, with the values you fill in on the Console and the errors that show up most often in Build logs.
Before you start, have three things ready: a Zenifra account with the right organization selected, permission to install the Zenifra GitHub App on the GitHub account or organization that owns the repository, and the application running locally with the same commands you are going to configure. On Node.js, for example, that means npm ci, npm run build, and npm start work on your machine with the same major Node.js version you will select for the project.
Step 1: connect GitHub to your organization
The connection has two required steps, and both must be complete before any repository shows up in the Console. First, an owner of the organization links the GitHub account: on console.zenifra.com, with the right organization selected, open Account in the sidebar, start the connection in the GitHub section, and authorize the link. That link only identifies which GitHub user Zenifra will use; on its own it does not grant access to any repository.
The second step is installing the Zenifra GitHub App at github.com/apps/zenifra/installations/new. During installation, GitHub asks where to install it (your personal account or a GitHub organization) and which repositories to grant: All repositories, which also covers future ones, or Only selected repositories. If you want to limit access, choose the manual selection. In GitHub organizations, the installation may need an administrator’s approval, and if you work across several organizations you need to install the app in each one.
To confirm it worked, go back to the Console, start creating a project with a GitHub source, and check that the expected account and repository appear. If the account appears but a specific repository does not, the link is fine and the fix is in the app installation: the repository was probably left out of the selection. If the connection does not complete when you return from GitHub, note that the authorization is single-use, valid for up to 10 minutes, and can only be completed in the browser where it started; switching browsers, blocked cookies, or opening the return link twice means starting over.
Members who are not owners but can create projects can also connect their own GitHub under Account, in the Your GitHub (optional) card, with Connect my GitHub. When creating a project, the organization’s GitHub stays the default; members who connected their own pick My GitHub under Repositories from. That personal connection only applies to that organization, nobody else uses it, and later deploys, including automatic ones, use the GitHub App installed on the repository. Keep the app installed for as long as the project exists.
Step 1 on Forgejo: token and hook connection
If your code lives on a Forgejo instance, including one your company hosts, the connection uses a token and belongs to the organization. You need the instance’s HTTPS address with a valid, trusted TLS certificate, and the instance must be reachable by Zenifra’s connection; opening the address in your own browser does not prove that. Also note the full repository path in the team/application format: the integration does not list or discover repositories, so you type the path in the Console.
The token scope depends on what you want to do. For reading the source and manual deploys, read:repository is enough. To publish automatically on push, tag, release, or pull request, use write:repository with an account that can administer the repository’s hooks. The documentation recommends a dedicated identity with access only to the repositories it needs, and a token created with the All (public, private, and limited) access option; tokens in Specific repositories mode cannot run administrative operations, so they cannot create the hook.
The connection is created right in the project form: under Advanced settings, choose Git repository as the Project source and Forgejo as the Git provider. If there is no connection yet, an owner fills in Instance address, Connection name, Repository path, Username, and Access token, and chooses Connect repository; other members use existing connections. Do not put the domain in the repository path, and never put the token in URLs or Git commands.
There are current limits worth knowing before you pick Forgejo: no repository discovery, no SSH source, no submodules, no Git LFS, and pull requests from forks do not get previews. A GitLab integration is not available today either. Each Forgejo hook accepts up to 120 events per minute, with a body of up to 100 KB per delivery; deliveries without the hook secret signature are rejected with 401.
Step 2: create the HTTP project in the Console
With the connection ready, creation follows the Console’s new project screen. The project name has 6 to 32 characters, lowercase letters, numbers, and hyphens only, and it is used in the automatic subdomain. Next come the plan, the payment model (hourly, monthly, or yearly), and the advanced settings, which hold the source, port, instances, environment variables, storage, and exposure (public or private).
When picking a plan, consider the runtime. Static (R$ 5.90/month or R$ 0.01/hour in the catalog on 11/06/2026) has 0.1 vCPU and 128 MB and was built for lightweight HTTP servers such as NGINX; the static sites guide itself recommends Basic or higher when the application keeps a Node.js process running. Basic costs R$ 29.90/month or R$ 0.05/hour, with 0.5 vCPU and 512 MB. Health checks and custom subdomains start at Premium.
The Port field must match the port the application listens on, and the application must listen on 0.0.0.0, not localhost. The documentation suggests 3000 for Node.js and Bun, 8000 for Python, and 8080 for Go, Java, and PHP, but the value that counts is the one in your code. For production, the documentation recommends at least 2 instances. Once created, the project gets a *.clients.zenifra.com URL with HTTPS; a custom domain is configured afterwards, with up to 20 domains per project.
- In the Console, click Create project and choose HTTP Application.
- Under Advanced Settings, set Project Source to Git repository and Git provider to GitHub (or Forgejo).
- Select the repository, branch, runtime, version, and commands. If the application lives in a subfolder, fill in Root directory (for example, backend or apps/api).
- Choose one of the four update modes: Manual, Automatic by branch (selected by default), By Tag, or By Release.
- Fill in port, instances, environment variables, and storage, then click Create Project. The first build starts right away from the selected branch.
Root directory only accepts relative paths with / as the separator; absolute paths and .. are rejected, ./backend/ is the same as backend, and only that folder goes into the build. Files such as package.json, package-lock.json, and requirements.txt must be inside it. To publish an API and a frontend from the same monorepo, create one project per folder.
Runtimes, versions, and commands per framework
The officially supported runtimes for Git repository builds are Node.js, Python, Bun, Go, Java, and PHP. Each has a fixed install command that runs before pre-build, plus a list of versions you pick in the Console. The table below reproduces the Runtimes page of the documentation, checked on 11/06/2026; always pick the same major version you use in development.
A few runtime details save hours of debugging. On Go, the build is static with CGO disabled: packages that need CGO, such as github.com/mattn/go-sqlite3, compile but fail at startup, and the documentation suggests modernc.org/sqlite. On Java, the build uses Eclipse Temurin with Maven 3.9, and the JVM starts with -XX:MaxRAMPercentage=75, using up to 75% of the plan memory for the heap. On PHP, the application runs on FrankenPHP and the default start command serves the public/ folder used by Laravel, Symfony, Slim, and CodeIgniter. On Python, print() and logging output goes unbuffered to the logs, and the build environment already has a C compiler and the PostgreSQL client libraries.
For the most common frameworks, the documentation lists ready-made build and start values. Next.js uses npm run build and npx next start -H 0.0.0.0 -p 3000. Express or Fastify in JavaScript need no build and start with node index.js; in TypeScript, build is npm run build and start is node dist/index.js. NestJS uses npm run build and node dist/main.js. FastAPI starts with uvicorn main:app --host 0.0.0.0 --port 8000; Flask with gunicorn app:app --bind 0.0.0.0:8000. Django uses python manage.py collectstatic --noinput as the build and gunicorn config.wsgi --bind 0.0.0.0:8000 as the start. Spring Boot with Maven uses mvn -B -DskipTests package and java -jar target/*.jar.
For migrations, the recommendation is to run them at the beginning of start, when the application already has access to the project network, not in pre-build: for example, npx prisma migrate deploy && node dist/main.js, or alembic upgrade head && uvicorn main:app --host 0.0.0.0 --port 8000. With several instances, all of them run start; long migrations delay startup, and for large changes the documentation suggests applying them beforehand from a machine that can reach the database.
| Runtime | Available versions | Dependency install | Suggested port |
|---|---|---|---|
| Node.js | 20, 22, 24, and 26 | npm ci | 3000 |
| Python | 3.11, 3.12, 3.13, and 3.14 | pip install --no-cache-dir -r requirements.txt (when the file exists) | 8000 |
| Bun | 1.2, 1.3, and 1.4 | bun install --frozen-lockfile | 3000 |
| Go | 1.25, 1.26, and 1.27 (default 1.27) | No separate step; modules downloaded by the build | 8080 |
| Java | 17, 21, and 25, all LTS (default 21) | No separate step; Maven or Gradle wrapper in the build | 8080 |
| PHP | 8.3, 8.4, and 8.5 (default 8.4) | composer install --no-dev --optimize-autoloader (when composer.json exists) | 8080 |
Environment variables at build time and runtime
Project variables are available at every step: dependency installation, pre-build, build, and runtime. That is what lets frameworks such as Vite and Next.js embed public values in browser code with VITE_* and NEXT_PUBLIC_*. The side effect matters: anything the build embeds is visible to whoever opens the application, so those prefixes are for public values, such as an API URL, and never for passwords or private keys.
Saving a variable restarts the instances but does not rerun the build. For variables read at runtime, such as DATABASE_URL, that is enough. For variables embedded by the build, the new value only shows up after a new deployment: choose New build in Build logs or push a commit. This is one of the most common causes of “I changed the variable and nothing happened” in Vite and Next.js projects.
DATABASE_URL is not injected automatically into HTTP projects. Copy the connection details of the managed database in the Console and add the variable to the application project; when you rotate the database password, update every application that uses it. The platform injects one variable of its own, ZENIFRA_INSTANCE_VERSION, with the published version serving that instance. Since the build gets neither the Git history nor the git command, use this variable when the application needs to show its version in logs or diagnostics.
| Item | Documented limit |
|---|---|
| Variables per project | 50 |
| Name length | up to 120 characters |
| Value length | up to 32,760 characters |
| Name format | starts with a letter, _, -, or .; then unaccented letters, numbers, _, -, and ., no spaces |
| Where to set them | Console (creation or Edit project), CLI (zenifra project env add/update/remove), or API (PATCH /project/:id/envs) |
When to bring your own Dockerfile
In the Git repository flow, the build uses an environment generated by Zenifra for the selected runtime, and any Dockerfile in the repository is ignored. If you need control over the image (specific system packages, another language, a hand-configured web server), build the image in your CI and create the project with a Docker Image source. The documentation’s rule of thumb: Node.js, Python, Bun, Go, Java, or PHP start with the Git repository; .NET, Ruby, Rust, or sites served by NGINX go through an OCI image.
The image needs a long-running HTTP process listening on 0.0.0.0, on the same port as the Port field, configured through environment variables. Use versioned tags such as 1.4.2 or the commit SHA and avoid latest: besides predictability, that makes rollback easy. On Apple Silicon Macs, build with --platform linux/amd64; without it, Docker produces an ARM image that does not start and shows up as exec format error.
The documented publishing commands use GitHub Container Registry as the example. After the push, create the project with the Project Source set to Docker Image, enter the image address, and, if it is private, configure the registry credentials. To automate build, push, and image updates on every change, Zenifra maintains an official GitHub Action, which also creates Preview environments for image-based projects.
echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_USER --password-stdin
docker build --platform linux/amd64 -t ghcr.io/your-org/my-api:1.0.0 .
docker push ghcr.io/your-org/my-api:1.0.0
# Test first
docker run --rm -p 8080:8080 -e PORT=8080 ghcr.io/your-org/my-api:1.0.0
curl http://localhost:8080/healthAutomatic updates by branch, tag, or release
Each project uses a single update mode at a time, and manual deployment stays available in all of them. In the Console, Automatic by branch is preselected when you create a GitHub project. In By Tag and By Release modes, the pattern is matched against the full tag name, is case-sensitive, accepts 1 to 255 characters, and has only two wildcards: * (any sequence) and ? (one character). So v* matches v1.2.0, but classes such as v[12].* are not accepted. Updating or deleting an existing tag does not start a deployment.
To change the mode later, open the project, expand Git repository, choose Select or change repository, set the Deployment mode and, for By Tag or By Release, the Tag pattern; then click Save repository. Changing only the mode does not start a build; changing the repository or the branch starts a new build right away. On Forgejo, the same change can be made from the CLI with zenifra project source deploy-settings set --project <project-id> --mode <manual|branch|tag|release>.
The New build button in Build logs lets you choose What to publish: a Branch (optionally pinned to an Exact commit SHA), a specific Tag, even outside the pattern, or the Latest version matching the pattern, available in By Tag and By Release modes. The choice applies only to that deployment. Only the most recent build of a project is published: when a new one starts, earlier unfinished builds show as Superseded, which is not a failure and does not change the running application.
GitHub events arrive through the Zenifra GitHub App, with a required signature, a body of up to 100 KB, and up to 300 events per minute per installation; anything above that gets a 429. A rejected delivery does not start a build: publish with New build or a new push. If the app is uninstalled and reinstalled, projects from the previous installation stop receiving automatic updates until you use Reconnect repository.
git tag -a v1.0.0 -m "Release v1.0.0"
git push forgejo v1.0.0| Update mode | What starts a new deployment |
|---|---|
| Manual | A Console action or POST /v1/project/:id/github/deploy; repository changes do not deploy |
| Automatic by branch | A push to the selected branch |
| By Tag | Creating a tag that matches the pattern (e.g., v*) |
| By Release | Publishing a non-draft release whose tag matches the pattern; pre-releases only if enabled |
On Forgejo, pushing the tag to the remote is required: git tag -a v1.0.0 -m "Release v1.0.0" followed by git push forgejo v1.0.0. Creating the tag only in your local copy publishes nothing.
Build logs, cache, and common errors
Build logs, on the project page, show the list of recent builds, the status of each, and every command in the order it runs, formatted as $ command followed by its output: the install step (for example, $ npm ci), pre-build, and build. When a command fails, its output appears in the log followed by a final message with the identified cause. The modal updates in real time while the build runs, and history keeps up to 30 builds per project for up to 30 days, whichever comes first.
The first build installs everything; later builds reuse steps that did not change. Installation only reruns when the dependency files change, pre-build and build rerun when the code in the Root directory changes, and changing a variable reruns every step on the next build. A new build of the same commit with the same variables finishes in a few seconds. The cache belongs to each project and is not shared.
The table below lists the documented errors with cause and fix. Two deserve attention. The first is the lockfile: Node.js uses npm ci, which requires a valid package-lock.json in sync with package.json, inside the Root directory folder. Projects on pnpm or Yarn also need an npm-compatible package-lock.json, or should publish through an OCI image. The second is Git history: the build only receives the commit files, with no history and no git command, so scripts that call git log or git describe fail with spawnSync git ENOENT.
| Error in Build logs | Cause | How to fix |
|---|---|---|
| package-lock.json missing or unusable | Lockfile not in Git or outside the Root directory | Generate it with npm, commit it next to package.json, and create a new build |
| package-lock.json out of sync | Dependencies changed without updating the lockfile | Run npm install, commit the lockfile, validate with npm ci, and create a new build |
| The configured root directory does not exist in the repository. | Folder missing on the deployed branch | Fix Root directory under Git repository and save (this starts a build) |
| spawnSync git ENOENT or git: not found | A build script reads Git history | Generate the data before the commit or use ZENIFRA_INSTANCE_VERSION |
| VITE_* or NEXT_PUBLIC_* missing or stale | Variable saved without a new build | Choose New build in Build logs |
| bun.lock out of sync with package.json | Outdated Bun lockfile | Run bun install, commit bun.lock, and create a new build |
| A requirements.txt package does not exist for Linux or at the requested version | Windows-only package such as pywin32 | Mark it with ; sys_platform == "win32" |
| Composer could not resolve the dependencies | PHP version, package name, or incompatible composer.lock | Validate composer install locally with the same PHP version |
| Access to the GitHub repository rejected | Repository link expired or removed | Use Reconnect repository on the project and try a new build |
If the build passes but the application does not respond, look elsewhere: a port that differs from the configured one, a server listening on localhost, a missing variable, or a startup error visible in the application logs. To go back to a stable version, use New build with the exact commit SHA, or zenifra deploy --project <project-id> --commit-sha <sha>; in By Tag mode, create a new tag pointing to the good commit.
Do I need a Dockerfile to deploy from GitHub?
No. On the Git repository path, Zenifra generates the build environment for the selected runtime, and a Dockerfile in the repository is ignored. You only need the runtime’s dependency files (package.json and package-lock.json, requirements.txt, go.mod, pom.xml, or composer.json) and the right commands.
A Dockerfile comes in when you choose to publish an OCI image: for languages outside the six runtimes, to control system packages, or to reuse an image your CI already builds. The documentation has ready-made Dockerfiles for Go, Spring Boot, Laravel, and ASP.NET Core.
Can I use pnpm or Yarn on the Node.js runtime?
Only if the repository also has an npm-compatible package-lock.json. Installation on the Node.js runtime is always npm ci, and Zenifra does not convert pnpm or Yarn lockfiles or workspaces.
When keeping that lockfile is not possible, publish an OCI image built by your own process. Another option for JavaScript and TypeScript projects is the Bun runtime, which installs with bun install --frozen-lockfile and uses bun.lock.
Is manual deployment still available with an automatic mode on?
Yes. In every update mode, New build in Build logs stays available, and you choose whether to publish a branch, a tag, or the latest version matching the pattern. The choice applies only to that deployment and does not change the project mode.
That is useful to redeploy after changing a variable used by the build, to recover from a rejected event delivery, or to go back to a stable commit by pinning its exact SHA.
How do I deploy an API and a frontend from the same monorepo?
Create one project per folder, each with its own Root directory, for example apps/api and apps/web. Each project has its own runtime, commands, port, variables, and plan, and only the configured folder goes into the build.
Dependency files must be inside each folder: a package-lock.json only at the monorepo root does not work for a project whose Root directory is apps/api. Saving a new Root directory starts a new build.
Does Zenifra deploy from GitLab or Bitbucket?
Today, the native repository integrations are GitHub and Forgejo; the Forgejo documentation states that a GitLab integration is not currently available. Bitbucket is not among the documented sources.
For code hosted elsewhere, the documented path is to build the image in your CI, push it to a registry, and create the project with a Docker Image source, updating the tag for each version through the CLI, the API, or the Console.