Skip to content
ThinkWork ThinkWork

GitHub-Free Customer Deployments

GitHub-free deployment is the default enterprise path for new customer-owned ThinkWork environments. The customer runs one guided CLI bootstrap with temporary AWS administrator access. After bootstrap, deployment authority lives inside the customer’s AWS account through Step Functions, CodeBuild, SSM, AppConfig, Secrets Manager, S3 evidence, and the deployed ThinkWork API.

No customer source fork, customer GitHub repository, or customer GitHub Actions workflow is required.

ThinkWork Dev Dogfood

Section titled “ThinkWork Dev Dogfood”

ThinkWork dev is the first controller-managed environment. GitHub Actions still builds, tests, and publishes release artifacts, but dev release updates should be run by selecting an explicit release manifest and starting the dev deployment controller. In controller mode, GitHub Actions starts Step Functions and skips the legacy direct Terraform apply job.

From a local operator shell:

Terminal window
thinkwork deploy \
  --controller \
  --stage dev \
  --controller-action update \
  --release-version v0.1.0-canary.148 \
  --manifest-url https://github.com/thinkwork-ai/thinkwork/releases/download/v0.1.0-canary.148/thinkwork-release.json \
  --manifest-sha256 <sha256>

From GitHub Actions, run Deploy manually with:

  • use_controller=true
  • controller_action=update
  • release_version=<tag>
  • release_manifest_url=<thinkwork-release.json URL>
  • release_manifest_sha256=<manifest SHA-256>

The controller execution writes evidence under sessions/<session-id>/<action>/ in the deployment evidence bucket. A dev update is not considered proven until the controller execution, runtime profile, and foundation smoke evidence are all recorded.

Use a release where the shared GitHub Release contains the coordinated operator surface: desktop installers/updater metadata for clients plus thinkwork-release.json and platform-artifacts.tar.gz for the deployment controller. The current accepted TEI proof is v0.1.0-canary.148, deployed by the customer-owned controller with manifest SHA-256 5b154f800b8754d00d0b252772005bd02fc1dbbf6096036597efd700d4d6df93.

Deployment Model

Section titled “Deployment Model”
operator laptop -> guided CLI bootstrap -> customer AWS foundation
customer AWS Step Functions -> CodeBuild runner -> Terraform plan/apply/destroy
Spaces Managed Applications -> ThinkWork API -> deployment job evidence
release manifest -> verified artifacts -> customer AWS resources
deployment profile -> desktop/mobile clients

Bootstrap installs only the foundation needed to sign in and operate the environment:

  • Cognito auth and configured identity providers
  • API Gateway and AppSync GraphQL endpoints
  • Aurora database and app secrets
  • Web app
  • Deployment control plane for plan/apply/destroy jobs
  • Release selection and customer-owned config storage
  • First-admin claim metadata
  • Deployment profile outputs for desktop and mobile clients

First Bootstrap

Section titled “First Bootstrap”

  1. Prepare AWS access

    Use an AWS identity in the customer account with temporary administrator access for the first bootstrap.

    Terminal window
    aws sts get-caller-identity

  2. Run guided bootstrap

    Terminal window
    thinkwork deploy --bootstrap

    The CLI asks for customer slug, stage, AWS account, region, first-admin email, release selection, and identity-provider inputs. It does not ask for a GitHub repository on the GitHub-free path.

  3. Record bootstrap outputs

    Save the generated Spaces URL, API URL, AppSync URLs, Cognito domain, and deployment profile JSON. These are also stored in customer AWS config.

  4. Run the foundation smoke

    Terminal window
    node scripts/smoke/foundation-bootstrap-smoke.mjs
    

    SMOKE_ENABLE_FOUNDATION_BOOTSTRAP=1 \
      SMOKE_TERRAFORM_DIR=terraform/examples/greenfield \
      SMOKE_EVIDENCE_FILE=deploy-artifacts/foundation-smoke.json \
      node scripts/smoke/foundation-bootstrap-smoke.mjs

  5. Sign in as first admin

    Open the generated Spaces URL and sign in with the bootstrap first-admin email. The Cognito email must be verified before the pending first-admin claim completes.

  6. Operate from Spaces

    Use Settings -> Managed Applications for Cognee, Twenty CRM, Plane, and later optional applications. Use CLI recovery commands only for support or bootstrap repair.

Evidence Contract

Section titled “Evidence Contract”

Each bootstrap, managed-app, and release-upgrade smoke writes a JSON evidence envelope when SMOKE_EVIDENCE_FILE, SMOKE_WRITE_EVIDENCE=1, or SMOKE_EVIDENCE_S3_URI is set.

Evidence includes:

  • release version and manifest digest
  • Step Functions execution ARN
  • CodeBuild build ARN and id
  • Terraform plan/apply artifact keys when provided
  • smoke result and endpoint status
  • CloudWatch Logs URL when provided
  • app-specific status, URL, and health result

Evidence must not include plaintext secrets, bearer tokens, API keys, database passwords, or raw Terraform variable files.

TEI Proof Status

Section titled “TEI Proof Status”

TEI (tei-e2e) is the first customer-environment proving run. The accepted controller update ran release v0.1.0-canary.148 through Step Functions and CodeBuild, wrote deployment evidence to the TEI evidence bucket, updated the runtime config, and persisted selected-release status under the customer controller SSM prefix.

Recorded as passing:

  • explicit canary release manifest and digest selection
  • customer-owned Step Functions and CodeBuild controller update
  • runtime config publication for web, desktop, and mobile clients
  • first-admin login
  • model catalog and agent settings smoke after the platform migration remediation
  • selected-release status parameters for future update decisions

Still intentionally open before calling the TEI run fully accepted:

  • full Cognee and Twenty optional-app deploy/smoke
  • mobile profile-selection proof
  • teardown proof, deferred while the TEI demo environment stays live

Failure Triage

Section titled “Failure Triage”
SymptomFirst checks
Bootstrap fails before TerraformRe-run CLI validation, AWS identity, region, release manifest verification, and required IdP fields.
Terraform plan failsOpen the CodeBuild build link from the deployment job and inspect the plan artifact.
Apply failsCompare the approved plan digest, manifest digest, and CodeBuild logs. Retry only after the root cause is understood.
Smoke failsUse the smoke evidence JSON plus CloudWatch links. Do not treat an infrastructure apply as successful until smoke passes or records an explicit skip.
First-admin claim does not completeVerify Cognito email, first-admin pending email, tenant claim status, and identity-provider email mapping.
Managed-app job is stuckInspect Step Functions execution state, CodeBuild build status, and deployment job events in Spaces.

Recovery Posture

Section titled “Recovery Posture”

Normal operation is Spaces-first. Recovery CLI commands exist for support when the browser cannot complete an operation, but the customer AWS account remains the deployment authority.

Do not run local Terraform against production as a shortcut around a failed deployment job. Use the customer control plane so evidence, approvals, and selected release digests stay aligned.

Release upgrades for already-bootstrapped external environments should start in Settings -> General -> Releases. The Settings workflow creates a preflight job, verifies runner compatibility and known IAM drift, displays preserved customer configuration, and dispatches only a reviewed release-update job. Use the manual runbook only when Settings blocks and the recovery action has been authorized.