Git Repository Reference

Use this guide when you need more than the basic “connect a repo and deploy” flow.

It explains how Git-based deployments work in Hubfly Space, what repository access models are supported, how branch and root directory selection affect builds, how automatic redeploys behave, and what to expect when you connect a self-hosted Git server.

Overview

Git deployments in Hubfly Space support:

• GitHub repository browsing
• Manual repository URL entry
• Branch selection
• Root directory selection for monorepos and nested apps
• Automatic redeploys on code push
• Automatic redeploys after CI success
• Automatic build detection
• Manual build configuration when detection is not enough

This page is the detailed companion to Deploy From Git.

What Git Deployments Are Best For

Use Git deployments when:

• Your application source lives in a Git repository
• You want builds to come from source instead of from a prebuilt image
• You want branch-specific deployments
• You want monorepo deployments without splitting repositories
• You want redeploys to happen from repository activity

Use Deploy From Image instead when:

• Your CI pipeline already publishes production images
• You want total control over image creation outside Hubfly Space
• You do not want Hubfly Space to build from source code

Supported Repository Access Models

Hubfly Space currently exposes two user-facing Git source modes in the container deploy flow:

• GitHub
• Self-hosted

GitHub

The GitHub flow is the most complete path. It supports:

• Browsing repositories from the deploy modal
• Manual repository URL entry
• Branch loading and branch search
• Personal account repositories
• Organization repositories through GitHub App installations
• Auto-deploy based on GitHub push or CI webhooks

Self-Hosted

The self-hosted flow is for repositories outside github.com.

It supports:

• Manual repository URL entry
• Explicit Git host entry
• Personal access token authentication
• Branch loading after repository access is verified
• Auto-deploy behavior when matching webhook events reach Hubfly Space

GitHub Account Linking And App Installations

Hubfly Space uses two related GitHub concepts that do different jobs.

1. GitHub OAuth link

Your GitHub account link is used to:

• identify the GitHub user
• refresh GitHub access when needed
• browse repositories tied to your account session

If your GitHub session expires, the deploy flow may ask you to reconnect before repository access works again.

2. GitHub App installation

The GitHub App installation is what grants repository access for deployment, especially for organization-owned repositories.

This matters because many teams assume linking GitHub alone is enough. It is not always enough for org repositories. In practice:

• OAuth identifies you
• the GitHub App installation grants deployment access to repositories

Personal Account Repositories

If the GitHub App is installed on your personal account, Hubfly Space can browse and deploy repositories that installation can access.

Organization Repositories

If the repository belongs to an organization, the GitHub App must be installed on that organization or on the specific repositories you want to deploy.

Without that installation, the Git deploy flow may show your GitHub account as linked but still fail to access the repository for deployment.

Add Installation

If you already linked GitHub but need access to more repositories:

1. Open the GitHub repository browser in the deploy flow.
2. Use the GitHub App installation action.
3. Install the app on the personal account or organization that owns the repository.
4. Return to the deploy flow and reload the repository list.

This is the normal fix when:

• the repository is organization-owned
• the repository browser is empty
• access works for some repos but not others

Repository URL Formats

GitHub Repository Input

For GitHub, the safest input formats are:

owner/repo
https://github.com/owner/repo
git@github.com:owner/repo.git

Hubfly Space normalizes GitHub repository input to the canonical owner/repo form in the deploy flow.

Best Practice

Prefer owner/repo when you already know the repository.

Prefer the built-in browser when:

• the repository lives in an organization
• you want to confirm the app installation can actually see the repo
• you want the least friction for branch loading

Self-Hosted Repository Input

For self-hosted Git, common inputs are:

org/repo
https://git.example.com/org/repo
git@git.example.com:org/repo.git

If you enter only org/repo, you also need a Git Host such as:

git.example.com

If you paste a full HTTPS or SSH repository URL, Hubfly Space can often derive the host automatically.

What The Git Host Field Means

The Git Host field identifies the server that owns the repository, for example:

• git.example.com
• code.company.internal
• ghe.example.com

Use it when:

• you entered the repository as org/repo
• your self-hosted platform is not obvious from the repository path alone
• you want Hubfly Space to match the repository against the correct webhook source

Host Input Recommendations

• Use the exact hostname your Git server uses publicly or internally.
• Do not include extra path segments.
• If your Git server is served over HTTPS, the hostname alone is usually enough.
• If you paste a full repository URL, make sure the hostname in that URL is the one your webhooks also use.

Consistency matters. If the repository URL uses one host and your webhooks come from another host, automatic redeploy matching can become unreliable.

Access Tokens For Self-Hosted Git

The self-hosted Git flow requires a personal access token.

Use a token that can:

• read repository metadata
• read branches
• read commits

Best Practices

• Create a dedicated read-oriented token for deployment access when possible.
• Avoid using a broad administrator token.
• Rotate the token if repository access stops working unexpectedly.
• Reconnect and test branch loading after token rotation.

Repository Connection Flow

Hubfly Space does not unlock the full Git build settings immediately. The repository must connect successfully first.

Until the repository is connected successfully, the deploy flow may not populate branches or enable the full build configuration.

Branch Selection

The selected branch is the branch Hubfly Space tracks for:

• the initial build
• later automatic redeploys
• later manual rebuilds from the same source config

GitHub Branch Behavior

For GitHub repositories:

• the default branch is prioritized when branches are loaded
• the branch picker can search branch names
• branch search is useful for repositories with many release or feature branches

Operational Recommendation

Use long-lived branches for environments.

Examples:

• main for production
• develop for staging
• release/* for controlled release candidates

Avoid pointing production containers at short-lived feature branches unless that is an intentional preview workflow.

Root Directory

The Root Directory tells Hubfly Space where the deployable application lives inside the repository.

Leave it blank when:

• the app lives at repository root
• your Dockerfile is at repository root
• your build config assumes the root of the repository

Set it when:

• you deploy from a monorepo
• the application lives in a subdirectory
• multiple deployable apps share one repository

Examples:

apps/web
services/api
deployments/customer-portal

Why Root Directory Matters

This setting affects where Hubfly Space looks when it builds from source. A wrong root directory usually causes one of these outcomes:

• build files are not found
• the wrong package or service is built
• automatic detection identifies the wrong app
• Dockerfile-based builds run from the wrong place

Monorepo Recommendations

• Keep one container bound to one branch and one root directory.
• Use separate containers for separate deployable apps.
• Name containers after the service, not after the monorepo.
• Document the exact app path your team expects to deploy.

Deploy On Push Vs Deploy On CI Success

Git deployments support two automatic redeploy triggers.

Deploy On Push

Choose Deploy on push when you want a new deployment as soon as code is pushed to the tracked branch.

Best for:

• small teams
• fast iteration
• preview environments
• repositories where branch protection already ensures quality

Benefits:

• shortest path from commit to deployment
• simple mental model
• good fit for staging or internal services

Tradeoffs:

• every qualifying push can trigger a new deployment
• broken commits can deploy if your branch policy allows them

Deploy On CI Success

Choose Deploy on CI success when deployment should wait for a successful CI result on the tracked branch.

Best for:

• production workloads
• teams with required test suites
• repositories with formal release checks
• environments where deployment should only follow a green pipeline

Benefits:

• aligns deployment with CI gating
• reduces accidental deploys from failing commits
• fits stronger release discipline

Tradeoffs:

• deployment depends on correct CI status reporting
• slower than direct push-based deployment

How To Decide

Use Deploy on push if speed matters more than CI gating.

Use Deploy on CI success if correctness, policy, or release controls matter more than immediacy.

For most production services, Deploy on CI success is the safer default.

Self-Hosted Git: What “Supported” Means In Practice

The self-hosted webhook compatibility layer covers multiple event styles, including:

• GitLab push events
• GitLab pipeline success events
• Bitbucket Server or Data Center push events
• Bitbucket Server or Data Center build-status events
• Gitea push events
• Gitea or Forgejo success-status events

These events power the self-hosted redeploy hook. When a matching event reaches Hubfly Space, Hubfly Space can queue a fresh build for the container that is connected to that repository and branch.

That does not mean every self-hosted platform behaves exactly like GitHub in the UI.

Practical Expectation

The interactive repository connection flow works best when your Git server exposes repository APIs that Hubfly Space can use for:

• branch discovery
• commit lookup
• repository validation

If you are standardizing on self-hosted Git across a company, validate all of these before rollout:

• repository URL format
• host value
• token scope
• branch loading
• webhook delivery
• CI event delivery if you plan to use Deploy on CI success

Self-Hosted Redeploy Hook

Self-hosted Git repositories can trigger automatic redeploys by sending webhook events to Hubfly Space.

Use this endpoint as the webhook target:

https://hubfly.space/api/selfhosted/webhook

What The Hook Matches

Hubfly Space only redeploys a self-hosted Git container when the incoming event matches the saved deployment source.

The event must match:

• the repository path or clone URL
• the Git host
• the configured branch
• the selected auto-deploy trigger

For Deploy on push, Hubfly Space expects a push event for the configured branch.

For Deploy on CI success, Hubfly Space expects a successful CI, pipeline, status, build-status, or commit-status event that can be tied back to the configured branch.

Supported Hook Events

Use the provider event that matches your trigger:

• GitLab: push events for Deploy on push
• GitLab: pipeline success events for Deploy on CI success
• Bitbucket Server or Data Center: repo:refs_changed for Deploy on push
• Bitbucket Server or Data Center: build status or commit status events for Deploy on CI success
• Gitea and Forgejo: push events for Deploy on push
• Gitea and Forgejo: success status events for Deploy on CI success

Setup Steps

1. Deploy or connect a container using the Self-hosted Git provider.
2. Enter the repository path or URL, Git host, access token, branch, and root directory.
3. Choose Deploy on push or Deploy on CI success.
4. Finish the first deployment so Hubfly Space stores the repository source configuration.
5. In your Git server, create a webhook that sends JSON payloads to /api/selfhosted/webhook.
6. Select the matching push, pipeline, build-status, commit-status, or status event.
7. Push to the configured branch or complete a successful CI run to verify the hook queues a new build.

Operational Notes

• The hook redeploys existing connected containers. It does not create a new container from an unknown repository.
• The saved branch controls matching. A push to another branch is ignored for that container.
• The saved deploy trigger controls matching. A container configured for ci does not redeploy from a push-only event.
• Successful CI matching may require Hubfly Space to confirm that the reported commit is at the head of the configured branch, so the self-hosted token must still be valid.
• Hostname consistency matters. Use the same host in the deploy form and in the webhook payload whenever possible.

Build Modes With Git Sources

After the repository connects, you can continue with either automatic or manual build settings.

Automatic Build

Automatic build is the fastest default.

Hubfly Space first looks for a Dockerfile. If one is not found in the expected location, it falls back to app detection and builder-driven source builds.

Use automatic mode when:

• your repository follows common framework conventions
• you already keep a valid Dockerfile
• you want the least amount of build configuration

Manual Build

Manual build is better when:

• your runtime needs are non-standard
• your monorepo needs explicit commands
• your install/build/start commands differ from defaults
• auto-detection picks the wrong strategy

When manual mode is enabled, the run command becomes especially important. If your app does not have a valid runtime start command, the deployment may build successfully but fail at launch.

Production Recommendations

• Use a dedicated production branch such as main or release.
• Prefer Deploy on CI success for production services.
• Keep root directories explicit in monorepos.
• Install the GitHub App on the owning organization, not only on personal accounts.
• Use least-privilege access tokens for self-hosted Git.
• Separate preview, staging, and production containers by branch.
• Keep repository hostnames consistent between clone URLs and webhook sources.

Common Mistakes

• Linking GitHub OAuth but not installing the GitHub App on the organization
• Leaving the root directory blank for a nested monorepo app
• Pointing production at a temporary feature branch
• Choosing Deploy on push when the team actually expects CI-gated releases
• Using a self-hosted token without repository read permissions
• Mixing repository URLs and webhook hosts from different domains

Troubleshooting

Repository Does Not Appear In The GitHub Browser

Check:

• GitHub account is linked
• GitHub session is not expired
• the GitHub App is installed on the personal account or organization that owns the repo
• the installation includes the target repository

Branches Do Not Load

Check:

• the repository was connected successfully
• the repository path is correct
• the selected provider matches the actual host
• the self-hosted token can read repository metadata
• the Git host field matches the repository server

Auto Deploy Is Not Triggering

Check:

• the configured branch matches the branch receiving commits
• the trigger is set to push or ci as intended
• CI is actually reporting a successful result when using Deploy on CI success
• the repository host and webhook source host match the saved repository configuration

Wrong App Builds In A Monorepo

Check:

• Root Directory points to the intended app
• the branch contains that app path
• your Dockerfile or build commands are valid relative to that root directory

FAQ

Do I need both GitHub login and GitHub App installation?

For many real deployments, yes. OAuth links the account, while the GitHub App installation is what grants repository deployment access, especially for organization-owned repositories.

Can I deploy from an organization repository?

Yes, as long as the GitHub App is installed on that organization or on the specific repositories you want Hubfly Space to access.

Can I use monorepos?

Yes. Set the correct Root Directory for each deployable app and keep each container aligned to the service path it should build.

Should I choose push or CI for production?

Deploy on CI success is the safer production default. Deploy on push is better for fast iteration and less controlled environments.

Can I use a full repository URL instead of owner/repo?

Yes. That is supported for GitHub and self-hosted Git, and Hubfly Space normalizes supported inputs where possible.

See Also

• Deploy From Git
• Quick Start
• Deploy From Image
• Compose Stacks