Create an app from a repository

Bring code from GitHub, GitLab or any git host into Git, then create an app the platform builds from it with a Dockerfile or Railpack.

Last updated 18 November 2026View as Markdown

The platform builds from a repository in Git, so code that lives on GitHub, GitLab or any other git host comes in first. Replace my-app with your app's name and https://github.com/example/my-app with your repository's URL.

Prerequisites

  • Permission for deploy:CreateApp, and for importing, git:CreateRepository. To deploy, deploy:DeployApp.
  • For a private source, a GitHub or GitLab token with read access.
  • In the console, also deploy:DescribeApp to open Apps (without it the console shows Access denied and names that action).

Step 1: Import the repository

Importing brings the history, every branch and tag, and (from GitHub and GitLab) the pull requests. Keep in sync makes the copy a mirror that follows its source on a schedule. The repository page shows the import while it runs, and why if it fails. See Git.

  1. Open Git, then Repositories, then choose New repository. From Create app, when the organization has no repositories, Import from GitHub, GitLab or a URL opens the same form and brings you back to the app form; otherwise the Import it link under Repository does.
  2. On the Source and identity step, choose Import from a URL.
  3. For Source URL, enter the https URL of the repository. For a private source, enter the Access token.
  4. Enter the repository's Name.
  5. (Optional) Turn on Keep in sync, and choose how often under Sync.
  6. Choose Continue. On the Access step, choose Import repository. The repository page shows the import as it runs.

Step 2: Create the app

  1. Open Apps, then choose Create app.
  2. On the What to run step, under Where does this app come from?, choose A repository.
  3. For Repository, choose the repository, and for Branch, its branch (the repository's default branch to start with). A repository whose import failed cannot be chosen; one still being imported shows a warning, because a deployment started before the import finishes has nothing to clone.
  4. Under How is the image built?, choose Dockerfile (built with BuildKit from the Dockerfile in the root directory) or Railpack (detects the language and builds without a Dockerfile).
  5. (Optional) For Root directory, enter the build context inside the repository; . is the whole repository.
  6. (Optional) Clear Deploy on push (selected by default) to deploy only when you start a deployment.
  7. Choose Continue, then complete the App, machine and domain and Environment steps as in Create an app from an image.
  8. Choose Create and deploy, or, with Deploy immediately cleared, Create app.

Through the CLI, API and Terraform, deployOnPush is on by default for an app with a repository, and the app is created without a deployment. Without gitRepositoryId the dockerfile and railpack builders are refused (400, The "dockerfile" builder builds from a repository, so a repository is required).

Result

Each deployment builds the image on a temporary build machine, pushes it to your registry and runs it. The build machine is deleted once the image is pushed, and its time is not billed to you; if you bring your own cloud account, it runs and is billed there. With deploy on push, every later push to the branch deploys the pushed commit as the person who pushed; a push by someone who may not deploy the app is recorded in its activity and not deployed. See Turn on deploy on push.

Did this page help you?