> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy Plays from GitHub

> Link a GitHub repository, validate Plays in pull requests, and deploy them from your production branch.

Git deploys makes a linked repository the source of truth for your Plays.
It reads Play code from one directory in that repository, validates pull
requests, and deploys production changes from one branch.

You do not need a GitHub Actions workflow or a Deepline API key in GitHub.

<Note>
  Git deploys is in beta. Everyone can see `deepline git` in CLI help, but using
  it requires enablement for your Deepline workspace. If it is not enabled for
  your workspace, contact the Deepline team to request enablement.
</Note>

## CLI quickstart

After the Deepline team enables your workspace, sign in to that workspace
with `deepline auth register`. Then:

```bash theme={null}
# Discover the commands and start GitHub App installation.
deepline git --help
deepline git connect

# After approving the installation in your browser:
deepline git status
deepline git repos

# Link a repository and choose the branch that deploys live Plays.
deepline git link acme/growth --branch main
deepline git list

# From your repository checkout, push committed Play changes.
git push origin main

# Inspect the resulting deployment.
deepline git deployments
deepline git deployments DEPLOYMENT_ID
```

Replace `acme/growth` with a repository from `deepline git repos` and
`DEPLOYMENT_ID` with an ID from the deployment list. Linking does not deploy
existing commits; the next push starts a deployment. GitHub App approval is
the browser step; linking, configuration, and deployment inspection are
available through the CLI. Add `--json` for machine-readable results.

## How a linked repository works

A linked repository has four settings:

| Setting               | What it controls                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Repository**        | The GitHub repository Deepline reads and watches.                                                                        |
| **Production branch** | Only pushes to this branch create production deployments.                                                                |
| **Root directory**    | The base directory Deepline searches. Leave it empty for the repository root. Use it to isolate a package in a monorepo. |
| **Manifest**          | A JSON file under the root directory that selects Play files. The default name is `deepline.json`.                       |

Each production push creates one deployment for the linked repository at that
commit. Deepline reads the manifest, then discovers the matching
`*.play.ts` files below the root directory.

Deepline validates every changed Play in that deployment before changing any
live revision. If one validation fails, the previous live revisions stay in
place. If validation succeeds, all changed Plays are promoted together.
Unchanged Plays are skipped by content hash.

This makes a production branch push the only way that link changes live Plays.
Pushes to other branches are ignored unless they are part of a pull request.

## Before you start

You need:

* a Deepline workspace with Git deploys enabled
* workspace owner or admin access
* permission to install a GitHub App for the repository
* at least one `*.play.ts` file in the repository

<Warning>
  Anyone who can push to the production branch can change the Plays that run in
  this workspace.
</Warning>

## Connect GitHub

<Steps>
  <Step title="Open Deploys or Repositories">
    In the Deepline dashboard, open **Deploys** or **Repositories**.
  </Step>

  <Step title="Start the connection">Select **Connect GitHub**.</Step>

  <Step title="Install the app">
    Install the Deepline GitHub App on the organization that owns the
    repository.
  </Step>

  <Step title="Choose repository access">
    Grant access to all repositories or select specific repositories.
  </Step>
</Steps>

GitHub returns you to the repository-linking dialog after installation.

The CLI starts the same browser flow:

```bash theme={null}
deepline git connect
```

Confirm that the workspace connection and its repository access are available:

```bash theme={null}
deepline git status
deepline git repos
```

## Link a repository

On the **Repositories** page, select **Link repository**.
Set the production branch, root directory, and manifest for the linked
repository. Pull-request checks are enabled by default.

The CLI sets the same link settings:

```bash theme={null}
deepline git link acme/growth --branch main
```

For a monorepo, set the root directory. The manifest is read relative to this
directory:

```bash theme={null}
deepline git link acme/growth \
  --branch main \
  --root-dir packages/growth
```

Pass `--manifest` to use another manifest filename, or `--no-pr-checks` to
disable pull-request checks:

```bash theme={null}
deepline git link acme/growth \
  --branch main \
  --root-dir packages/growth \
  --manifest config/deepline.json \
  --no-pr-checks
```

The same repository can have separate links for different root directories or
workspaces. Each link has its own settings and deployment history.

Inspect a link and its effective settings at any time:

```bash theme={null}
deepline git list
deepline git get LINKED_REPOSITORY_ID
```

## Select Plays with a manifest

Without a `deepline.json` file, Deepline finds every `*.play.ts` file under
the linked root directory.

Add a manifest when you need narrower matching:

```json theme={null}
{
  "plays": ["plays/**/*.play.ts"]
}
```

Manifest globs are relative to the linked root directory.
They cannot be absolute or contain `..`.

The manifest describes the complete Play set for a link. A production
deployment evaluates that set together, but promotes only Plays whose content
changed. A deployment supports at most 100 Play files.

Each Play can import files from its own directory or a child directory.
An import cannot escape the Play's directory.

Keep provider credentials and Play secrets in Deepline.
Do not commit credentials, customer data, or live provider responses.

## Validate pull requests

Open a pull request from a branch in the linked repository.
Deepline adds a **Deepline Plays** check run.

A successful check:

* builds and validates the changed Plays
* registers changed Plays as draft revisions
* leaves every live revision unchanged

Draft pull requests do not build.
Mark a draft ready for review to start its first build.

Fork pull requests do not receive a Deepline build or check in the current
version.

Use the deployment details to copy a registered pull-request revision ID and
run it:

```bash theme={null}
REVISION_ID="revision-id-from-deployment-details"
deepline plays run --revision-id "$REVISION_ID" \
  --input '{"example":"value"}' \
  --watch
```

## Deploy to production

Merge the pull request or push directly to the configured production branch.
Deepline creates a production deployment for the pushed commit.

Watch deployments on the dashboard under **Deploys**, or use:

```bash theme={null}
deepline git deployments
```

Inspect one deployment:

```bash theme={null}
DEPLOYMENT_ID="deployment-id-from-deepline-git-deployments"
deepline git deployments "$DEPLOYMENT_ID"
```

The deployment can finish as `succeeded`, `failed`, `superseded`,
`cancelled`, or `reconcile_failed`.

Use `deepline git cancel DEPLOYMENT_ID` to cancel a queued or running
deployment.

## Roll back a deployment

Revert the source commit and push the revert to the production branch.
The revert creates a new, auditable deployment.

## Pause or remove a link

The dashboard lets you change the same settings, enable or disable
pull-request checks, pause a link, or unlink it. The CLI provides the same
controls. Pause new deployments:

```bash theme={null}
LINKED_REPOSITORY_ID="id-from-deepline-git-list"
deepline git set "$LINKED_REPOSITORY_ID" --disabled
```

Resume deployments:

```bash theme={null}
LINKED_REPOSITORY_ID="id-from-deepline-git-list"
deepline git set "$LINKED_REPOSITORY_ID" --enabled
```

Update a branch, root directory, manifest, or pull-request checks with
`deepline git set`. Run `deepline git set --help` for the complete options.

Unlink the repository:

```bash theme={null}
LINKED_REPOSITORY_ID="id-from-deepline-git-list"
deepline git unlink "$LINKED_REPOSITORY_ID"
```

Pausing or unlinking stops new deployments.
It does not stop or archive live Plays.

## Current limits

* Git deploys supports GitHub.com through the Deepline GitHub App.
* Fork pull requests are ignored.
* Non-production branch pushes without a pull request are ignored.
* Build compute is metered and deployment details show the build duration.

If you cannot install the GitHub App, use
[GitHub Actions](/docs/sdk-v2/github-deployments) instead.