Deploy Plays with GitHub Actions

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:

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:

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:

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:

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.

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.

Play SDK quickstart

Create, check, and run a custom Play.

Production integration

Integrate published Plays into a production application.

Tutorials

How-to guides

Explanation

Reference

Deploy Plays with GitHub Actions

1. Add Play source to the repository

2. Pin the Deepline CLI

3. Configure Deepline credentials

4. Add the workflow

5. Test and operate the workflow

Play SDK quickstart

Production integration

​1. Add Play source to the repository

​2. Pin the Deepline CLI

​3. Configure Deepline credentials

​4. Add the workflow

​5. Test and operate the workflow

Play SDK quickstart

Production integration

1. Add Play source to the repository

2. Pin the Deepline CLI

3. Configure Deepline credentials

4. Add the workflow

5. Test and operate the workflow