---
title: "An app from a GitHub repository, in one step: read the repository, add what it lacks by pull request, create the app and deploy the newest green build, or wait for the first one"
method: POST
path: "/instances/{instance_id}/apps/import"
tags: ["apps"]
---

# An app from a GitHub repository, in one step: read the repository, add what it lacks by pull request, create the app and deploy the newest green build, or wait for the first one

`POST /instances/{instance_id}/apps/import`

## Request

- Base URL: `https://app.lathe.live/api/v1`
- URL: `https://app.lathe.live/api/v1/instances/{instance_id}/apps/import`
- Auth: none declared

## Path parameters

- `instance_id` string, required

## Request body

- ImportIn
  - `repo` string, required: owner/name, as GitHub spells it: a repository the Lathe app is installed on for this account (GET /github/repos lists them).
  - `name` string: The app's name on the box; the repository's name, made to fit, when empty.
  - `branch` string: The branch whose builds deploy; the repository's default branch when empty.
  - `workflow` string: The workflow file that builds and pushes the image. Empty: the one the repository already has that does, or, if none does, the one Lathe adds by pull request.
  - `image` string: The reference that workflow pushes to. Empty: what the workflow file says, or ghcr.io/<owner>/<name>:<branch> for a workflow Lathe adds.
  - `port` integer, nullable: What the app listens on; the Dockerfile's EXPOSE, or the first free port, when empty.
  - `health_path` string: The path that answers 200 once ready; the Dockerfile's HEALTHCHECK path, or /, when empty.
  - `public` boolean, nullable: Served by the box's front door on a name of its own (the default) or loopback only.
  - `memory_mb` integer, nullable: The app's share of the apps engine's budget; a modest one when empty.
  - `env` object, nullable: The app's environment, if any; saved before the first deploy.
  - `auto` boolean: True: every green run of the workflow deploys the app. False: runs are tracked and shown; deploy by hand.
  - `add_workflow` boolean: When no workflow in the repository builds an image: open a pull request adding one (and a Dockerfile, when the repository has none and its stack is recognised). False: the app waits and the answer carries the workflow text to add yourself. source="actions" only.
  - `source` string: Who builds it. "lathe": Lathe does, on a box of its own, from every push to the branch - from its Dockerfile, or from what its files say it is when there is none (Node, Python, Go, PHP, Ruby, Java, Rust, static sites); no workflow, no image, no registry token of yours, and the first build starts with the import. "actions": your own workflow builds and pushes the image. Empty: "lathe" wherever this deployment can build, else "actions".
  - `target` string: The Dockerfile stage a build of ours stops at, e.g. "runtime" for `FROM python:3.14-slim AS runtime`. Empty builds the last stage in the file, which is what a single-stage Dockerfile and the usual builder-then-runtime pair want; name one when the last stage is not the one that should run. source="lathe" only.
  - `build_env` boolean: True: the app's own environment variables are given to the build as well as to the running container, which is what a front-end bundle and an install from a private package registry need. False: the build is given none of them, for an app whose variables are credentials a build has no use for - they would be written onto the build machine, and into the image config for any name the Dockerfile declares as an ARG. source="lathe" only.
  - `check_command` string: A command that must exit 0 inside the built image before it deploys - `npm test`, `pytest -q`, `tsc --noEmit`. Run in the image itself, with the app's variables, and with no access to the box it runs on. Empty: a green build deploys. A check that fails is a build that made an image and did not deploy; the build page has what it printed. source="lathe" only.
  - `check_target` string: The Dockerfile stage the check runs in, when it is not the one that deploys: a `test` stage that adds the test tooling to the image that ships. Built with the same variables, never pushed. Empty: the check runs in the image that deploys. source="lathe" only.
  - `check_env` object, nullable: Variables for the check and nothing else - not the build, not the running app: the URL of a database to run the tests against is what they are for. Names are letters, digits and underscores. source="lathe" only.
  - `paths` string: Space-separated globs a push must touch for this app to be built at all, e.g. "apps/web/** packages/ui/**". Empty builds every push. What a monorepo needs: a push to one app does not rebuild the other three, and a README does not redeploy anything. A commit whose files cannot be compared is built, never skipped. source="lathe" only.

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/lathe/apis/lathe-customer-api.md) · [All operations](https://skmtc.dev/lathe/apis/lathe-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lathe/apis/lathe-customer-api/revisions/68cfd9bb71c1?raw)