# 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.

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](/docs/git).

**Console**
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.

**CLI**
```sh
dcloud git repositories import --name my-app \
  --source '{"url":"https://github.com/example/my-app"}'
```

A private source takes `--token`; `--mirror '{"intervalMinutes":15}'` keeps the copy following its
source.

**API:** not available. Importing is a Git operation; see `git.repositories.import` in the _API Reference_.

**Terraform:** not available. An import is a one-time action, not a resource.

## Step 2: Create the app

**Console**
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](create-an-app-from-an-image.md).
8. Choose **Create and deploy**, or, with **Deploy immediately** cleared, **Create app**.

**CLI**
```sh
dcloud deploy apps create --name my-app --builder dockerfile \
  --git-repository-id 6f7a8b9c-0d1e-4f2a-b3c4-d5e6f7a8b9c0 --branch main --root-dir . \
  --deploy-on-push
```

**API**
```http
POST /deploy/api/apps
{
  "name": "my-app",
  "builder": "railpack",
  "gitRepositoryId": "6f7a8b9c-0d1e-4f2a-b3c4-d5e6f7a8b9c0",
  "branch": "main",
  "deployOnPush": true
}
```

**Terraform**
```hcl
resource "dcloud_app" "web" {
  name              = "my-app"
  builder           = "dockerfile"
  git_repository_id = dcloud_git_repository.web.id
  branch            = "main"
  deploy_on_push    = true
}
```

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](turn-on-deploy-on-push.md).

## Related

- [Deploy an app](deploy-an-app.md), which also shows how to follow the build log
- `deploy.apps.create` · `dcloud deploy apps create` · `dcloud_app`
