GitHub integration

Use this guide when App Services should build from GitHub repositories. GitHub is usually connected with the GitHub App so dFlow can list repositories, clone for builds, and (when configured) react to pushes.

For the shortest dFlow Cloud path, see Integrations overview under Integrations in the sidebar. This page goes deeper on GitHub-specific choices and failure modes.

Before you startCopy Anchor Link

• You can sign in to GitHub as a user who may install GitHub Apps on the target user or organisation account.
• You know which repositories and branches map to which Application and Environment (see How dFlow is structured under Core Concepts in the sidebar).
• Review Integration permissions and prerequisites for least-privilege and token hygiene.

1. Open GitHub in IntegrationsCopy Anchor Link

1. Sign in to the dFlow dashboard (for example app.dflow.sh on dFlow Cloud).
2. Open Integrations (or Settings → Integrations, depending on your UI version).
3. Select GitHub.
   • Install path (dFlow Cloud, or self-hosted with GITHUB_APP_* configured): choose Install GitHub App. You do not create an app in the dashboard.
   • Create path (self-hosted without GITHUB_APP_*): use Create GitHub App / Connect (manifest flow registers an app pointed at your instance).

2. Install or connect the appCopy Anchor Link

1. When prompted, pick Organisation or Personal account so the installation matches where your repositories live.

2. On the create path, give the GitHub App a clear name if asked. On the install path the app is already registered (cloud’s public dFlow app, or your operator’s app from env) — you only install it.

3. Complete redirect to GitHub and click Install (or Configure if you are updating an existing installation).

4. Choose repository access:

   • All repositories: simplest if many services deploy from the same org.
   • Only select repositories: narrower access; add repos when you create new Services.

5. Confirm Install and return to dFlow.

Expected outcome: GitHub shows as connected and repository pickers list the repos you granted.

Existing connections that used a customer-owned GitHub App keep working; new cloud connections use the public dFlow app.

3. Use GitHub on an App ServiceCopy Anchor Link

1. Open the Application, choose the Environment, then add or edit an App Service.
2. In the GitHub source UI, pick the installation (account), repository, and branch (or tag) the build should track.
3. Set deploy behavior (manual vs automatic) as the UI allows. Automatic deploys depend on webhooks from the GitHub App installation.
4. Save and Deploy or Redeploy so the next build clones from GitHub.

Permission and access errorsCopy Anchor Link

Organisation owners may restrict third-party access; if installs are blocked, work with your GitHub admin. See Roles and permissions under Security and Team Management in the sidebar for who may manage integrations in dFlow.

RelatedCopy Anchor Link

• Git source integrations
• App services
• Integration troubleshooting
• Integration issues