> ## 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 with GitHub Actions

> Validate Deepline Plays in pull requests and publish approved revisions after merge.

Use GitHub as the source of truth for Deepline Play code. Pull requests validate
changes, and merges to `main` publish them to Deepline.

These instructions work for a human or coding agent.

## 1. Add Play source to the repository

Commit each Deepline Play as a `*.play.ts` file. Each file must contain one
default-exported `definePlay`. Do not put multiple deployable Plays in one file.
The files can live anywhere in the repository.

Keep code and non-secret configuration in GitHub. Store provider credentials in
Deepline. Do not commit customer data, credentials, or live provider responses.

## 2. Pin the Deepline CLI

Choose a tested version:

```bash theme={null}
npm view deepline version
```

Set `DEEPLINE_CLI_VERSION` as a GitHub Actions repository variable. Pinning the
CLI prevents an unreviewed release from changing deployment behavior.

## 3. Configure Deepline credentials

Add these GitHub Actions secrets:

| Secret                   | Scope                                       | Purpose                                               |
| ------------------------ | ------------------------------------------- | ----------------------------------------------------- |
| `DEEPLINE_CHECK_API_KEY` | Repository                                  | Validate against an isolated non-production workspace |
| `DEEPLINE_API_KEY`       | Protected `deepline-production` environment | Publish approved Plays to the production workspace    |

Restrict the production environment to `main`. Add required reviewers if
publication needs a separate approval.

Each key must identify one Deepline workspace. Do not use a production key for
pull-request validation or choose the target workspace from pull-request input.
Configure each workspace with the provider credentials its Plays use and active
Play secrets for every name those Plays declare. Use non-production credentials
in the validation workspace and production credentials in the production
workspace.

This workflow supports pull requests whose branches live in the same repository.
GitHub withholds repository secrets from forked pull requests. To validate a fork,
move the reviewed commit to a maintainer-controlled branch; do not expose secrets
with `pull_request_target`.

## 4. Add the workflow

Create `.github/workflows/deepline.yml`:

```yaml theme={null}
name: Deploy Deepline Plays

on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

env:
  DEEPLINE_HOST_URL: https://code.deepline.com
  DEEPLINE_CLI_VERSION: ${{ vars.DEEPLINE_CLI_VERSION }}

jobs:
  validate:
    name: Validate Plays
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Install Deepline
        shell: bash
        run: |
          set -euo pipefail
          : "${DEEPLINE_CLI_VERSION:?Set the DEEPLINE_CLI_VERSION repository variable}"
          npm install --global "deepline@${DEEPLINE_CLI_VERSION}"
      - name: Check Plays
        shell: bash
        env:
          DEEPLINE_API_KEY: ${{ secrets.DEEPLINE_CHECK_API_KEY }}
        run: |
          set -euo pipefail
          found=0
          while IFS= read -r -d '' play; do
            found=1
            echo "Checking ${play}"
            deepline plays check "${play}" --json
          done < <(git ls-files -z -- '*.play.ts')
          test "${found}" -eq 1

  publish:
    name: Publish Plays
    if: github.event_name != 'pull_request'
    needs: validate
    runs-on: ubuntu-latest
    environment: deepline-production
    concurrency:
      group: deepline-production
      cancel-in-progress: false
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Install Deepline
        shell: bash
        run: |
          set -euo pipefail
          : "${DEEPLINE_CLI_VERSION:?Set the DEEPLINE_CLI_VERSION repository variable}"
          npm install --global "deepline@${DEEPLINE_CLI_VERSION}"
      - name: Publish Plays
        shell: bash
        env:
          DEEPLINE_API_KEY: ${{ secrets.DEEPLINE_API_KEY }}
        run: |
          set -euo pipefail
          while IFS= read -r play; do
            [[ -n "${play}" ]] || continue
            check_json="$(deepline plays check "${play}" --json)"
            artifact_hash="$(jq -r '.artifactHash // empty' <<<"${check_json}")"
            [[ -n "${artifact_hash}" ]] || {
              echo "Missing artifactHash for ${play}" >&2
              exit 1
            }
            deepline plays publish "${play}" \
              --expected-artifact "${artifact_hash}" --json
          done < <(git ls-files -- '*.play.ts' | sort)
```

The workflow checks every tracked `*.play.ts` file. After a merge or manual run,
it republishes every tracked Play so changes to imported helpers and configuration
are included. `--expected-artifact` prevents publication if a file differs from
the artifact that was just checked.

## 5. Test and operate the workflow

Open a pull request that changes a Play and confirm **Validate Plays** passes.
Merge it, then confirm **Publish Plays** succeeds in GitHub Actions.

Verify the live revision:

```bash theme={null}
deepline plays versions --name <play-name> --json
deepline plays describe <play-name> --json
```

For later changes, repeat the same pull request, validation, merge, and
verification flow. Test changed runtime behavior with approved synthetic input
in an internal or test workspace. Do not publish production Plays from a
workstation during normal development.

To roll back, promote the previous known-good immutable revision:

```bash theme={null}
deepline plays versions --name <play-name> --json
deepline plays set-live <play-name> --revision-id <revision-id> --json
```

Then revert or fix the GitHub source so the repository and live revision agree
again.

<Warning>
  Keep production credentials out of pull-request jobs. Deleting a `*.play.ts`
  file does not disable the live Play; decommission its schedules, webhooks, and
  callers separately.
</Warning>

<CardGroup cols={2}>
  <Card title="Play SDK quickstart" icon="play" href="/docs/sdk-v2/quickstart">
    Create, check, and run a custom Play.
  </Card>

  <Card title="Production integration" icon="server" href="/docs/sdk-v2/production-integration">
    Integrate published Plays into a production application.
  </Card>
</CardGroup>