GitHub integration

Install the dFlow GitHub App, choose org or personal access, and use GitHub-backed App Services.

Written By Zoro

Last updated 3 days ago

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 Connect your Git provider under dFlow Cloud in the sidebar. This page goes deeper on GitHub-specific choices and failure modes.

Before you start

  • 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 Integrations

  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 and start the GitHub App flow (for example Create GitHub App or Connect).

2. Create or connect the app

  1. When prompted, pick Organisation or Personal account so the installation matches where your repositories live.
  2. Give the GitHub App a clear name if the product asks for one (for example dFlow GitHub App for your org).
  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 & authorize and return to dFlow.

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

3. Use GitHub on an App Service

  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 errors

SymptomWhat to check
Repository missing in pickerGitHub App installation may not include that repo; widen selection or add the repo on GitHub, then refresh dFlow.
Clone or build fails with permission deniedInstallation removed, suspended, or org policy blocked the app; reconnect from Integrations and re-approve.
Push does not trigger deployAutomatic deploy may be off, branch mismatch, or webhook delivery failed; see Integration troubleshooting.

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.

Related