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

[Human guide: work with your agent →](https://deepline.com/docs/human/sdk-v2/git-deploys.md)

> [!NOTE]
>
> Link a repository, validate one change, and inspect the deployment outcome
> before relying on recurring automation.

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. For access, contact the Deepline team through the
> support button on your dashboard.

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

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

## Connect GitHub on the Web

In Deepline, open **Deploys** and select **Connect GitHub**:

![Deploys page with the Connect GitHub button](https://mintcdn.com/deepline2/H1mimOdvGMz_VkJe/images/git-deploys-connect-github.png?fit=max\&auto=format\&n=H1mimOdvGMz_VkJe\&q=85\&s=f571b6e443eac326a83a6755650ce470)

If **Link a repository** appears instead, GitHub is already connected. Select
it and continue with [Link a repository](#link-a-repository).

**1. Install the app**

On GitHub, install the Deepline GitHub App on the account that owns the
repository. If an organization owns it, choose that organization.

**2. Choose repository access**

Grant access to all repositories or select specific repositories.

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

## Link a repository

In the repository-linking dialog, select the repository and production branch.
Set a root directory for a monorepo or a different manifest filename if needed.
Pull-request checks are enabled by default. Confirm the link. Linking does not
deploy existing commits. The next push to the production branch starts a
deployment.

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

## CLI quickstart

Sign in to the workspace with `deepline auth register`, then:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
# Start the same GitHub connection in your browser.
deepline git connect
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
deepline git get LINKED_REPOSITORY_ID

# 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. Use `--root-dir
packages/growth` for a monorepo, `--manifest <filename>` for another manifest,
or `--no-pr-checks` to disable pull-request checks. Add `--json` for
machine-readable results.

## 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={"languages":{"custom":["/languages/deepline-prompt.json"]}}
{
  "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={"languages":{"custom":["/languages/deepline-prompt.json"]}}
REVISION_ID="revision-id-from-deployment-details"
deepline plays run --revision-id "$REVISION_ID" \
  --input '{"example":"value"}'
```

## 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={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline git deployments
```

Inspect one deployment:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
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={"languages":{"custom":["/languages/deepline-prompt.json"]}}
LINKED_REPOSITORY_ID="id-from-deepline-git-list"
deepline git set "$LINKED_REPOSITORY_ID" --disabled
```

Resume deployments:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
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={"languages":{"custom":["/languages/deepline-prompt.json"]}}
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](https://deepline.com/docs/sdk-v2/github-deployments.md) instead.

## Verify this task

Review the selected branch, project root, manifest, and deployment result. Confirm the intended published versions and Monitor Jobs.

Ask your agent to explain a failed check before repeating work or expanding the scope.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.