@tailor-platform/sdk 1.62.0 → 1.63.0

package/docs/cli/setup.md

@@ -28,9 +28,9 @@ tailor-sdk setup [command]
 
 **Commands**
 
-| Command                         | Description                                             |
-| ------------------------------- | ------------------------------------------------------- |
-| [`setup github`](#setup-github) | Generate GitHub Actions workflow for deployment. (beta) |
+| Command                         | Description                                       |
+| ------------------------------- | ------------------------------------------------- |
+| [`setup github`](#setup-github) | Generate a GitHub Actions deploy workflow. (beta) |
 
 <!-- politty:command:setup:subcommands:end -->
 
@@ -47,7 +47,7 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 <!-- politty:command:setup github:description:start -->
 
-Generate GitHub Actions workflow for deployment. (beta)
+Generate a GitHub Actions deploy workflow. (beta)
 
 <!-- politty:command:setup github:description:end -->
 
@@ -65,14 +65,16 @@ tailor-sdk setup github [options]
 
 **Options**
 
-| Option                                  | Alias | Description                         | Required | Default |
-| --------------------------------------- | ----- | ----------------------------------- | -------- | ------- |
-| `--workspace-name <WORKSPACE_NAME>`     | `-n`  | Workspace name                      | Yes      | -       |
-| `--workspace-region <WORKSPACE_REGION>` | `-r`  | Workspace region                    | Yes      | -       |
-| `--organization-id <ORGANIZATION_ID>`   | `-o`  | Organization ID                     | Yes      | -       |
-| `--folder-id <FOLDER_ID>`               | `-f`  | Folder ID                           | Yes      | -       |
-| `--dir <DIR>`                           | `-d`  | App directory (for monorepo setups) | No       | `"."`   |
-| `--with-plan`                           | `-p`  | Include plan job for PR previews    | No       | `false` |
+| Option                              | Alias | Description                                                                                                                                       | Required | Default |
+| ----------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
+| `--workspace-name <WORKSPACE_NAME>` | `-n`  | Workspace name (defaults to the config 'name')                                                                                                    | No       | -       |
+| `--branch <BRANCH>`                 | -     | Branch target: deploy trigger branch (defaults to the detected default branch). Tag target: tag-reachability guard branch (no guard when omitted) | No       | -       |
+| `--tag`                             | -     | Generate a tag target (deploy on tag push)                                                                                                        | No       | `false` |
+| `--tag-pattern <TAG_PATTERN>`       | -     | Tag glob to match (requires --tag; defaults to v\*)                                                                                               | No       | -       |
+| `--environment <ENVIRONMENT>`       | -     | GitHub Environment for the plan/deploy jobs (defaults to the workspace name)                                                                      | No       | -       |
+| `--no-plan`                         | -     | Disable the plan job for a branch target (cannot be combined with --tag)                                                                          | No       | `false` |
+| `--dir <DIR>`                       | `-d`  | App directory (for monorepo setups)                                                                                                               | No       | `"."`   |
+| `--force`                           | -     | Discard hand edits / take over unmanaged files and regenerate                                                                                     | No       | `false` |
 
 <!-- politty:command:setup github:options:end -->
 
@@ -81,3 +83,7 @@ tailor-sdk setup github [options]
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 <!-- politty:command:setup github:global-options-link:end -->
+
+## Further reading
+
+- [GitHub Actions Integration](../github-actions.md) — usage guide: targets, generated files, secrets, approval gates, and rollback.

package/docs/cli-reference.md

@@ -287,9 +287,9 @@ Commands for managing crash reports.
 
 Commands for setting up project infrastructure.
 
-| Command                                     | Description                                             |
-| ------------------------------------------- | ------------------------------------------------------- |
-| [setup github](./cli/setup.md#setup-github) | Generate GitHub Actions workflow for deployment. (beta) |
+| Command                                     | Description                                       |
+| ------------------------------------------- | ------------------------------------------------- |
+| [setup github](./cli/setup.md#setup-github) | Generate a GitHub Actions deploy workflow. (beta) |
 
 ### [Upgrade Commands](./cli/upgrade.md)
 

package/docs/github-actions.md

@@ -0,0 +1,337 @@
+# GitHub Actions Integration
+
+`tailor-sdk setup github` generates a GitHub Actions workflow that deploys your
+Tailor Platform application automatically on push or tag.
+
+> **Beta:** This command is under active development. CLI flags, the generated
+> workflow, and the `.github/tailor-sdk.lock` schema may change before general
+> availability.
+
+## Quick start
+
+Run the command from the root of your SDK project (where `tailor.config.ts`
+lives):
+
+```bash
+# Branch target: deploy to stg on every push to main
+tailor-sdk setup github -n my-app-stg
+
+# Tag target: deploy to production when a tag is pushed, with an approval gate
+tailor-sdk setup github -n my-app-prod \
+  --tag --branch main --environment production
+```
+
+After running the command, follow the **Next steps** printed to the terminal to
+set the required secrets, set the `TAILOR_PLATFORM_WORKSPACE_ID` variable, and
+commit the generated files.
+
+The generated workflow deploys to whichever workspace its
+`TAILOR_PLATFORM_WORKSPACE_ID` Environment variable points at — it never
+creates or renames a workspace. Provision the workspace and set that variable
+before the first deploy (see [Targeting a workspace](#targeting-a-workspace)).
+
+## Targets
+
+A _target_ is one workflow file that handles one deployment destination.
+Run `setup github` once per target.
+
+### Branch target (recommended for staging)
+
+The branch target fires on pull requests and pushes to the branch you specify
+(defaulting to the repository's default branch when `--branch` is omitted):
+
+```bash
+tailor-sdk setup github -n my-app-stg
+# Equivalent to:
+tailor-sdk setup github -n my-app-stg --branch main
+```
+
+What it does:
+
+- On **pull request**: runs `generate`, checks that generated files are
+  committed (`generate-check`), and posts a deployment plan as a PR comment.
+  (The plan and deploy jobs are independent; pull requests run plan only.)
+- On **push to the branch**: deploys. The deploy action runs `generate` and
+  applies the config; it does not re-run the PR plan.
+- On **`workflow_dispatch`** with `dry-run: true`: runs plan only (useful for
+  rollback verification — see [Rollback](#rollback)). With `dry-run: false`
+  (default) it deploys, like a push.
+
+Fork pull requests cannot read repository secrets. For forks, the plan step is
+automatically skipped; `generate-check` and other non-secret checks still run.
+
+### Tag target (recommended for production)
+
+The tag target fires when a tag matching `--tag-pattern` (default `v*`) is
+pushed:
+
+```bash
+tailor-sdk setup github -n my-app-prod \
+  --tag --tag-pattern "v*" --branch main --environment production
+```
+
+What it does:
+
+- **`tailor-tag-guard`** (generated when `--branch` is supplied): checks that
+  the tagged commit is reachable from `main`. A tag on an unrelated commit is
+  silently skipped, not an error.
+- **`tailor-plan`**: runs `generate`, `generate-check`, and posts a plan
+  summary to the Actions step summary (no PR comment, because there is no PR).
+- **`tailor-deploy`**: waits for `tailor-plan`, then deploys. If the target
+  environment has required reviewers configured, GitHub requires their approval
+  before the deploy job starts.
+- On **`workflow_dispatch`**: the `tailor-tag-guard` result is ignored — the
+  plan job runs regardless of branch reachability (useful for rolling back to
+  any tag). `dry-run: true` stops before the deploy job.
+
+### Choosing `--branch` for the tag target
+
+`--branch` has two different roles depending on the target kind:
+
+| Target | Role of `--branch`                                                                             |
+| ------ | ---------------------------------------------------------------------------------------------- |
+| Branch | The branch that triggers the workflow (push + PR base). Defaults to the repo's default branch. |
+| Tag    | The branch whose history the tag must be reachable from. Omit to disable the guard entirely.   |
+
+The workspace name (`--workspace-name`, or the config `name` when omitted) must
+be 3–63 characters of lowercase letters, numbers, and hyphens, and cannot start
+or end with a hyphen. It is used for the generated file name, the workflow
+`name:`, the plan label, and the default GitHub Environment name; it does not
+select which workspace gets deployed (see
+[Targeting a workspace](#targeting-a-workspace)).
+
+## Targeting a workspace
+
+The generated `plan` and `deploy` jobs target a workspace by **id**, read from
+the `TAILOR_PLATFORM_WORKSPACE_ID` GitHub Environment variable. They never
+resolve a workspace by name and never create one. Set this variable per
+environment before the first deploy.
+
+Because the variable is scoped to a GitHub Environment, both the `plan` and
+`deploy` jobs declare `environment:` so the value resolves. When you omit
+`--environment`, the environment name defaults to the workspace name.
+
+1. Provision the workspace (once per environment) and obtain its id. For now
+   this is a manual step:
+
+   ```bash
+   tailor-sdk workspace create   # copy the printed workspace id
+   ```
+
+2. Set the id as the Environment variable (the environment name is your
+   `--environment` value, or the workspace name when omitted):
+
+   ```bash
+   gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env my-app-stg
+   ```
+
+If `TAILOR_PLATFORM_WORKSPACE_ID` is unset, `deploy` fails because the target
+workspace is not provisioned, and `plan` reports that the workspace is not
+provisioned yet instead of running a dry-run.
+
+If the target environment has required reviewers, that approval gate applies to
+the `plan` job as well as `deploy`, because `plan` must enter the environment to
+read the variable. (A token-based read that lets `plan` run without entering the
+environment is planned.)
+
+## Generated files
+
+Running `setup github` creates or updates:
+
+### `.github/workflows/tailor-<workspace-name>.yml`
+
+The workflow file. The `name:` field is set to `Tailor (<workspace-name>)` so
+you can distinguish multiple workspaces in the Actions UI.
+
+Jobs and steps whose `id` starts with `tailor-` are managed by the SDK. Do not
+edit or rename them — the SDK tracks them by id.
+
+You can add your own jobs and steps around the managed ones. To add
+project-specific setup (such as private registry authentication or a system
+dependency), add a step _before_ the managed setup steps. For post-install
+extras (such as `playwright install`), add a step _after_ them.
+
+Note that re-running `setup github` currently regenerates the whole file: if
+the file differs from what the SDK last wrote — whether you edited a managed
+step or added your own — the command stops and reports the conflict. Pass
+`--force` to discard your edits and regenerate from the current template, then
+re-apply your own steps. (Preserving user-added steps across regeneration is
+planned.)
+
+### `.github/tailor-sdk.lock`
+
+A machine-owned JSON file that tracks which files the SDK manages, the inputs
+they were generated from, and their content hashes. **Commit this file. Never
+edit it by hand.** The SDK uses it to recognize its own files on re-runs and to
+detect hand edits.
+
+### `tailor.config.ts` (id injection)
+
+If your config does not already have an `id` field, `setup github` injects one.
+This `id` must be committed alongside the workflow file. In CI, `tailor-sdk
+deploy` refuses to inject a new id — if the id were assigned fresh on each CI
+run, every deploy would create a brand-new application and lose ownership of
+previously deployed resources.
+
+If your pipeline intentionally deploys a fresh, throwaway application on every
+run (for example an end-to-end test harness that creates and deletes its own
+workspace), set `TAILOR_PLATFORM_SDK_ALLOW_CI_ID_INJECTION=true` to opt back
+into automatic id injection for that pipeline.
+
+## Secrets
+
+The generated workflow reads two secrets:
+
+| Secret                                       | Description                |
+| -------------------------------------------- | -------------------------- |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | Machine user client ID     |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | Machine user client secret |
+
+Set them on the target GitHub Environment (the `--environment` value, or the
+workspace name when omitted) with the GitHub CLI:
+
+```bash
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env my-app-stg
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env my-app-stg
+```
+
+Setting them at the environment level isolates each target's credentials and
+keeps them alongside that environment's `TAILOR_PLATFORM_WORKSPACE_ID`
+variable. You can also set them as repository-level secrets if every target
+shares one machine user.
+
+## GitHub Environments (approval gate)
+
+Both the `plan` and `deploy` jobs are associated with a GitHub Environment — the
+`--environment` value, or the workspace name when omitted. The environment holds
+that target's `TAILOR_PLATFORM_WORKSPACE_ID` variable and machine-user secrets,
+and lets you:
+
+- **Require reviewer approval** before the jobs run (suitable for production).
+- **Scope secrets and the workspace-id variable** to specific environments so
+  staging and production deploy to separate workspaces with separate machine
+  users.
+
+To configure the environment, go to your repository's **Settings → Environments**
+and create an environment whose name matches the target's environment. Add
+required reviewers, the `TAILOR_PLATFORM_WORKSPACE_ID` variable, and the
+environment-scoped secrets there.
+
+Required reviewers gate the `plan` job as well, because `plan` must enter the
+environment to read `TAILOR_PLATFORM_WORKSPACE_ID`. (A token-based read that
+lets `plan` run without entering the environment is planned.)
+
+## Manual runs and dry-run
+
+You can trigger the workflow manually from **Actions → Run workflow**. The
+`dry-run` input (boolean, default `false`) runs the plan job without
+deploying. Use this to preview what would change before executing a rollback
+or an out-of-band deploy. With `dry-run` off, a branch-target dispatch goes
+straight to deploy (like a push), while a tag-target dispatch runs plan first
+and then deploys.
+
+For tag targets, you can select any branch or tag when dispatching manually. The tag-guard check is skipped for manual dispatches, so
+you can deploy any commit regardless of branch membership.
+
+## Monorepo setup
+
+For a monorepo where your SDK app lives in a subdirectory, pass `--dir`:
+
+```bash
+tailor-sdk setup github -n my-app --dir apps/backend
+```
+
+The generated workflow adds a `paths` filter on `apps/backend/**` so the
+workflow only runs when that subdirectory changes. The `working-directory` for
+SDK commands is set accordingly.
+
+## Rollback
+
+`tailor-sdk deploy` is declarative: redeploying a past configuration returns
+the platform to that state. The recommended rollback approaches are:
+
+### Option 1 — Revert the commit (branch target)
+
+```bash
+git revert <commit-sha>
+git push
+```
+
+The push triggers the deploy job, which applies the reverted configuration. To
+preview the diff first, open the revert as a pull request (the plan job comments
+the diff) or use a `dry-run: true` manual dispatch before merging.
+
+### Option 2 — Advance the tag (tag target)
+
+Move the production tag to an earlier commit:
+
+```bash
+git tag -f v1.2.3 <earlier-commit-sha>
+git push --force-with-lease origin v1.2.3
+```
+
+Or create a new tag that points to the earlier commit:
+
+```bash
+git tag v1.2.4 <earlier-commit-sha>
+git push origin v1.2.4
+```
+
+### Option 3 — Manual dispatch with dry-run verification
+
+1. Go to **Actions → `Tailor (<workspace-name>)` → Run workflow**.
+2. Enter the tag or ref you want to redeploy.
+3. Set `dry-run` to `true` and run. Inspect the plan output.
+4. Run again with `dry-run` set to `false`.
+
+For tag targets, the tag-guard step is bypassed on manual dispatch, so you can
+dispatch from any ref. Environment approval (if configured) applies as usual.
+
+### Rollback limitations
+
+- **Schema and data are not rolled back.** If the older config expects a schema
+  state that no longer exists, the plan may show errors. In that case, review
+  the diff carefully before proceeding.
+- **Seed data** is not part of the deployment pipeline and is unaffected by
+  rollbacks.
+- **Static websites** are not yet integrated into the generated pipeline.
+  Static asset rollbacks must be performed manually.
+
+## Multi-environment example
+
+A typical setup with staging and production:
+
+```bash
+# Staging: main → stg (deploy on every push to main)
+tailor-sdk setup github -n my-app-stg
+
+# Production: tagged commits → prod, with approval gate and branch guard
+tailor-sdk setup github -n my-app-prod \
+  --tag --branch main --environment production
+```
+
+Then provision each workspace and set its id on the matching environment (the
+staging target's environment defaults to `my-app-stg`; production uses
+`production`):
+
+```bash
+gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env my-app-stg
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env my-app-stg
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env my-app-stg
+
+gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env production
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env production
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env production
+```
+
+Commit both workflow files and `.github/tailor-sdk.lock`.
+
+## Updating the generated workflow
+
+When you upgrade the SDK, re-run `setup github` with the same flags to pick up
+template improvements. If the SDK detects that you have hand-edited a managed
+section, it stops and asks you to use `--force` to overwrite your edits, or to
+move your customizations into your own steps before regenerating.
+
+The `.github/tailor-sdk.lock` file records the flags used at generation time,
+so you can check what arguments were used previously.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "1.62.0",
+  "version": "1.63.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -176,14 +176,14 @@
     "pkg-types": "2.3.1",
     "politty": "0.5.1",
     "rolldown": "1.1.0",
-    "semver": "7.8.2",
+    "semver": "7.8.3",
     "sql-highlight": "6.1.0",
     "std-env": "4.1.0",
     "table": "6.9.0",
     "ts-cron-validator": "1.1.5",
     "tsx": "4.22.4",
     "type-fest": "5.7.0",
-    "undici": "8.4.0",
+    "undici": "8.4.1",
     "xdg-basedir": "5.1.0",
     "zod": "4.4.3"
   },