GitHub Deployment

Use GitHub Repository as the project source when you want to publish your application from source code and the build flow configured during creation.

Prerequisites

Before selecting a repository, complete these two required steps:

connect your GitHub account to Zenifra
install the Zenifra GitHub App
How to connect your GitHub account to Zenifra

Note: The GitHub App can be installed on a personal account or an organization. In organizations, installation may require administrator approval.

Steps

In the console, click Create Project.
Choose GitHub Repository as the project source.
Select the repository, branch, runtime, and project commands.
Decide whether to enable auto-deploy.
Click Create Project.

Project commands

In GitHub projects, Zenifra runs the runtime's default dependency install and then executes only the commands configured in the project.

pre-build is optional
build is optional
start is required

This means some projects only need start, while others also use pre-build and build.

Auto-deploy

When auto-deploy is enabled during project creation, each push to the selected branch triggers a new automatic update.

When auto-deploy is disabled, the project does not update automatically on push.

Use Preview Environments to give each pull request a temporary URL without replacing the primary project. First enable the feature in the project's Previews tab and store the API Key in a GitHub secret.

The recommended workflow uses opened, synchronize, reopened, and closed events. With PREVIEW_ACTION=auto, the Action upserts on the first three events and removes the preview when the pull request closes. The same pull request reuses the automatic pr-<number> key.

name: Zenifra preview

on:
  pull_request:
    types: [opened, synchronize, reopened, closed]

permissions:
  contents: read

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Create or remove preview
        uses: zenifra/action-zenifra-deploy@v1
        with:
          PROJECT_ID: ${{ vars.ZENIFRA_PROJECT_ID }}
          API_KEY: ${{ secrets.ZENIFRA_API_KEY }}
          IMAGE: ${{ vars.ZENIFRA_PREVIEW_IMAGE }}
          PREVIEW: true
          PREVIEW_ACTION: auto
          PREVIEW_TTL: 24h
          WAIT_TIMEOUT: 10m

For a run outside a pull request, use workflow_dispatch and provide a stable PREVIEW_KEY:

on:
  workflow_dispatch:
    inputs:
      preview_key:
        description: Preview Environment key
        required: true
        type: string
      action:
        description: Operation
        required: true
        default: upsert
        type: choice
        options: [upsert, delete]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: zenifra/action-zenifra-deploy@v1
        with:
          PROJECT_ID: ${{ vars.ZENIFRA_PROJECT_ID }}
          API_KEY: ${{ secrets.ZENIFRA_API_KEY }}
          IMAGE: ${{ vars.ZENIFRA_PREVIEW_IMAGE }}
          PREVIEW: true
          PREVIEW_KEY: ${{ inputs.preview_key }}
          PREVIEW_ACTION: ${{ inputs.action }}

Outside a pull request, the key is required. A preview is billed hourly in BRL, has a default TTL of 24 hours, and accepts 1 to 168 hours. User variables are always copied inside Zenifra, but they may point to the same services as the primary project. Storage starts empty and isolated; data, custom domains, and custom image commands are not inherited.

The Action waits for availability with bounded polling and provides preview_id, preview_url, expires_at, operation_id, and preview_status. It never publishes API Keys or variable values in the Job Summary or logs.

What stays fixed after creation

In GitHub-based projects, these fields are defined during creation and are not available for editing later:

project source
branch
runtime
runtime version
auto-deploy

After creation, the confirmed editable settings for GitHub projects are pre-build, build, and start.

Build Logs

After the project is created, follow each publication from the Build Logs tab inside the project page in the console.

This history shows:

recent builds
current build status
dependency installation output
pre-build output, when present
build output, when present

Public build logs are filtered to prioritize useful project output.

The log modal updates in real time while the build is running.

Retention

GitHub build history is retained for up to:

30 builds per project
30 days of age

Whichever limit is reached first removes the oldest records.

URL

All plans receive a Zenifra URL in *.clients.zenifra.com. In higher plans, the subdomain name may be customizable.