Skip to content
Impreza HostdocsSearch documentationCtrl KOpen portal

Deploy a private Git repository

DeploymentsImpreza documentationRead as Markdown ↗

Connect your repository, choose a build method and deploy to a server on your account. Use an access token for private GitHub.com or GitLab.com HTTPS repositories, or an SSH deploy key for a host that supports SSH.

Before you start

  • Have an online Impreza agent and enough resources for the application and its build.
  • Choose the repository, branch or tag, project folder, build method and container HTTP port.
  • Have permission to read the repository and to deploy on the selected server.
  • Review runtime variables and persistent storage. Keep secrets out of source code and repository URLs.

The default build method expects a Dockerfile. Supported projects can select the documented Node, static npm, Python or PHP recipes. A configuration hint is not proof that the project builds successfully.

Choose repository authentication

Method Repository URL Credential
GitHub or GitLab access token HTTPS on github.com or gitlab.com A repository-scoped read token
SSH deploy key SSH clone URL, including a custom port when needed The public key generated for this deployment

For GitHub, grant Contents: Read to the intended repository. For GitLab, use read_repository. A clone credential and a push webhook have different purposes; see auto-deploy on push when you also want automatic deployment.

Deploy from My Apps

  1. Open My Apps, switch to Advanced view and open App catalog → Deploy a custom app.
  2. Select Git repository and enter the clone URL and branch or tag.
  3. Select the authentication method:
    • Private - GitHub/GitLab access token: enter the read token in the credential field.
    • Private - SSH deploy key: use the SSH clone URL and create the app. Open its Git connection, copy the public key and register it as a read-only Deploy key in the repository.
  4. Select the server and build method. Review the project folder, Dockerfile path or recipe options, HTTP port, domain, runtime variables and storage.
  5. Submit the deployment and follow its progress.

For an SSH key, the first build may fail before the key is registered. Wait for that attempt to finish, then select Key registered - redeploy. The form does not verify repository availability before submission.

Team permissions determine which portal operations a signed-in user can perform.

Deploy through MCP

Ask the assistant to review your server, source and build settings, then use impreza_deploy_custom. Both the remote connector and local MCP can deploy a Git URL; uploading a folder from your computer requires the local path.

Example arguments for an SSH repository with a Dockerfile:

{
  "mode": "dockerfile",
  "name": "my-app",
  "agent_id": "agt_your_server",
  "git_url": "git@github.com:your-team/your-app.git",
  "git_ref": "main",
  "git_auth_method": "deploy_key",
  "dockerfile_path": "Dockerfile",
  "target_port": 8080
}

Use your actual server ID, repository, branch and application port. Register the returned public key with the repository before retrying a failed clone. For token authentication, use an HTTPS URL, git_auth_method: "pat" and the git_pat input through your credential workflow. Omit image for a Git deployment.

Use impreza_list_deployments and impreza_get_logs to inspect the result. Retry only after the previous operation has finished.

Deploy through REST

Send POST /v1/platform/deployments/custom with the source and runtime fields. REST uses git_url to select the Git source; the MCP mode field is not required in this REST example.

{
  "name": "my-app",
  "agent_id": "agt_your_server",
  "git_url": "git@github.com:your-team/your-app.git",
  "git_ref": "main",
  "git_auth_method": "deploy_key",
  "dockerfile_path": "Dockerfile",
  "target_port": 8080
}

Authenticate with your scoped API credentials. Consult the REST reference for the request and response schema. Creating or queuing a deployment is not confirmation that the application is running.

Verify the result

  1. Check that the deployment operation completed.
  2. Review clone and build logs if it failed.
  3. Inspect runtime health, including the observation time.
  4. Open the application URL and check the application itself.

A failed replacement can leave the previous version running. The last operation and current runtime health answer different questions.

Rotate credentials and troubleshoot

  • Expired or revoked token: renew it from the app card's Git connection, then redeploy when the previous operation has finished.
  • SSH permission denied: confirm that the public key belongs to this deployment and is registered for the correct repository.
  • Rotate an SSH key: generate a new key, register it before redeploying, then remove the old key from the repository. Rotation does not interrupt running containers. Private keys are never displayed.
  • Missing branch or Dockerfile: correct the source or build settings using the supported configuration flow. The failed attempt does not establish repository availability.
  • Build or startup failure: read deployment safety and recovery and progress after an agent restart.

For local folder uploads through the CLI, follow the CLI guide. For saved upload versions, use source uploads.

Self-hosted push webhooks

Use the manual webhook connection for self-hosted GitLab, Gitea or Forgejo. Configure the returned URL and secret in your repository; the one-click GitHub connection is not a general forge API connector. Gitea/Forgejo use their Secret field (HMAC-SHA256), not a secret pasted into a query string. Only push events for the configured branch deploy; GitLab tag pushes and unrelated forge events are ignored. Signed deliveries have replay protection. GitLab shared-token requests have different replay semantics. A Gitea/Forgejo branch deletion does not immediately retire a preview: its configured TTL still applies. Repository cloning happens through the existing agent Git path.

Self-hosted forges on Tor

Requires agent 0.6.20+. The portal, REST API and MCP accept the same repository URL; existing servers update explicitly.

A repository can live on a self-hosted forge reachable only as a Tor v3 onion (https://<56 chars>.onion/owner/repo.git). The clone runs on the server through a short-lived Tor client started from the platform's pinned Tor image, with cleanup when the clone finishes. Repository requests go through Tor with remote hostname resolution; they have no direct fallback. This does not anonymize image downloads, builds or unrelated host traffic. Use HTTP or HTTPS on the onion with a fine-grained, read-only token (git_auth_method: pat) or public access. HTTP redirects are refused; SSH deploy keys over .onion are not supported yet. Token verification from the portal also uses Tor. An unavailable proxy reports the probe as unknown without attempting a direct connection.