# GitHub

Connect a GitHub repository from the Backify portal when you create an application. Install the Backify GitHub App for the repositories you want to use, then choose the repository and branch to build from.

Backify can create repositories in personal accounts and organizations. For a personal account, Backify asks the account owner to authorize the GitHub App as a user and uses that user authorization to create the repository. For an organization, Backify uses the organization's App installation. The App needs Repository creation: read and write or Administration: read and write, approved for the installation. The organization must also allow repository creation. If the installation has Only select repositories access, add a newly created repository to the App installation before connecting it to an application; GitHub does not automatically grant the installation access to every new repository.

Backify uses the selected branch as the application's source. Push changes to that branch to start its configured publishing flow. You can follow deployment status in the portal. Change the connected repository or branch from the application settings when your workflow changes.

In Connect GitHub, GitHub presents the personal accounts and organizations where you may install the Backify App. Backify then displays the connected account's name and type. Choose Create new private repository or Use existing repository in either new application setup or Change repository. Only accounts shared with the current workspace appear in this picker. A workspace GitHub default preselects an account; it does not restrict selection to that account. Organization connection administrators control sharing in Connections.

Personal accounts that need owner authorization show Reconnect GitHub account before creation is allowed. If user authorization has not been configured by the platform operator, you can still select an accessible existing repository. Once configured, reconnecting the account authorizes creation without removing its App installation. Repositories are initialized with a README and use GitHub's default branch.

After creation, Backify checks whether the App installation can access the new repository. If it cannot, the picker retains the created repository and provides Manage repository access in GitHub and Refresh repository access. Add the repository to the installation, refresh, and connect it. Retrying attachment uses the same repository. If creation fails during new application setup, the application remains available and the portal opens its GitHub page to finish setup.

The installations API returns repositoryCreationAuthorization (ready, reconnect_required, or configuration_required) and installationSettingsUrl. ready means the authorization needed for creation is available; GitHub still enforces approved App permissions and organization policy. The creation response includes installationAccessible and installationSettingsUrl alongside the repository identity. Protected authorization and refresh tokens are never included in these responses.

Run npm run test:portal for the mocked browser scenarios; install Chromium first with npx playwright install chromium. GitHub service tests are in GitHubExistingInstallationTests.

To stop deploying from a repository, open the application's Code page and choose Disconnect repository. Backify removes the source connection and its application-specific workflow. Your repository, code, and deployed application are retained. If GitHub access has been revoked, Backify disconnects the source and asks you to remove the workflow manually. Wait for any GitHub connection or deployment in progress to finish before disconnecting.

Choose Disconnect account under GitHub accounts to remove an account from the current Backify organization. Disconnect its application repositories first. Backify clears workspace defaults for that account and removes its saved user authorization. The GitHub App installation remains on GitHub and connections in other Backify organizations are retained.

New Backify Cloud applications receive an application-scoped workflow at .github/workflows/backify-<app-slug>.yml. On each push to the selected branch, GitHub Actions installs dependencies, runs the repository's build script, checks for index.html in the detected static output (dist, build, out, or the repository root), and commits the built output to the branch. That release commit triggers Backify's shared static publisher. The workflow uses the repository's GITHUB_TOKEN with Contents: write permission; no Azure Static Web Apps deployment token is needed. If the repository or organization restricts workflow token permissions to read only, allow write access for this workflow. See wildcard routing for the current publishing limits. Existing Static Web Apps keep their application-scoped workflow and token until they are migrated individually. Customer-owned Azure applications also use an application-scoped workflow.

If the repository is already connected, select it again in the application's Code page to install or refresh the workflow. The Backify GitHub App needs Contents: read and write and Workflows: read and write to create or update files in .github/workflows. Existing Static Web Apps also need Secrets: read and write to store their deployment token; customer-owned Azure applications need Actions: read and write to set their workflow variables. After changing App permissions, approve the updated access for the repository installation before reconnecting. (GitHub secrets API, GitHub workflow file API)