Goal
Prepare one Git-based web service and managed PostgreSQL through typed operations, then verify an actual application database write and read.Prerequisites
- A connection explicitly authorized for the required actions on the deployed backend.
- A GitHub repository and branch for a web service that can write and read a test record in PostgreSQL.
- Authorized hosting placement and an active PostgreSQL size returned by capabilities. Normal infrastructure quotas and billing apply.
Workflow
1
Discover connection identity, resources and capabilities. Gather repository, branch, service settings and the available PostgreSQL size before proposing work.
2
Review the affected resources and infrastructure estimate. If the estimate is unavailable, keep that limitation explicit rather than inventing a price.
3
Propose application.create with hosted deployment mode and a retained idempotency key. Obtain independent owner approval or an applicable recorded standing-policy decision.
4
Retain the resulting Application identity. Propose service.create and database.create with their own stable keys, then inspect their canonical operation results.
5
Attach the authorized database to the Application where needed, then create the private runtime binding for the web service.
6
Wait for the database private endpoint and configuration to be ready. Propose release.create for the explicit service IDs and follow its actual controller operations.
7
Once the exact deployment is healthy, exercise an application endpoint that writes a unique test record and reads the same value back. Report the resource and release links with this evidence.
Typed objective checks (next release)
Objective and schedule creation accept criteria instead of success_criteria. Send one list, with 1–20 entries. Each entry has description and kind. Checks apply to each selected target and retain the controller-bound plan, source/configuration revision and two-minute evidence lifetime. Each new criterion also records its server-selected verifier and evidence_ttl_seconds (120). Stored evidence records the actual verifier and a fingerprint of the full criterion contract; changing the check parameters invalidates previous evidence. Existing stored histories remain readable. Scheduled HTTP stability requires fresh, distinct observations; rereading one cached result cannot advance the window. application_smoke_test requires smoke.script_path (a relative .sh file included in the deployed image) and smoke.timeout_seconds (1–120). Select a project or explicit Application service IDs. The project.smoke_test.run action requires the inspected deployment_id and image_digest, the same script and timeout, and normal independent approval or an applicable standing policy. The script receives STACKSHIFT_SMOKE_BASE_URL and the retained STACKSHIFT_SMOKE_ID; it must write/read its own unique test record, assert the result, clean up its test data and exit nonzero on failure. It runs with runtime credentials and may cause external effects. No automatic retry follows an unknown execution outcome. A passed script has two-minute evidence tied to the original observation and active image; changing the deployment requires a new test. Raw stdout/stderr are not returned as objective evidence. service_connectivity checks supported private consumer bindings, including PostgreSQL SELECT 1. Node.js uses its native HTTP client or pg driver; other runtimes use curl for HTTP and psql for PostgreSQL. Node.js can fall back to those clients when its driver is unavailable. Images must include the selected client; missing clients return unavailable. PostgreSQL requires a trusted sslrootcert and verified TLS. These probes run inside the consuming workload, and do not return credentials or response bodies as evidence. A connection check alone does not prove application persistence. http_response requires http.path and http.status_code, with optional body_equals and max_duration_ms. The description is a label; the typed fields define the check. controller_health checks the owning runtime controller. HTTP checks use GET on the canonical public HTTPS deployment, forbid redirects and arbitrary hosts, and accept a path without query or fragment. The exact expected status must be 200–299; the optional exact response body is limited to 64 KiB. max_duration_ms is a per-request bound from 1 to 8000, including response-body reading, not a percentile or sustained latency claim. Unknown free-text criteria are rejected instead of being inferred as health or connectivity. Canonical built-in engineering and product-operation criteria remain supported through success_criteria. A healthy response with the wrong status, body or duration cannot satisfy a typed HTTP check. Use application_smoke_test for repository-defined application write/read assertions; HTTP probes alone do not write records or certify persistence.Private database binding
binding.create identifies the exact source service, target database and private environment alias. Its supported access_mode is private_runtime. The alias must be a valid private uppercase environment name, such as DATABASE_URL. Existing controllers deliver the database connection configuration to the service runtime. Do not ask the agent to reveal, copy into source code or return the connection string. Public build aliases and browser-exposed prefixes are rejected. private_runtime describes credential delivery. It does not create a separate SQL user or enforce per-consumer read-only/write roles. read_only, read_write and public_build are unsupported for this direct binding action.Keep permission and execution separate
The initial client login may grant reads only. A connection cannot create resources until the owner explicitly authorizes the required action scopes through a new consent. Follow the client guide to authorize additional actions. Each proposal retains its configuration and affected resource revisions. Review the exact proposal in the owner interface; the external client cannot approve itself. Changed targets require a new valid proposal. A successful proposal or approval does not mean the database is provisioned or the release is healthy. Inspect controller_operations and the resource readiness evidence. Build success and deployment success remain distinct.Reconnect, retry and partial failure
Retain each idempotency key with its exact request. After a lost response, retry the same request/key or inspect the recorded operation. Do not issue a different key merely because the response was lost. A new client session can rediscover authorized resources and current work. Use canonical identities and recorded results to continue; do not match resources by similar names or assume an unavailable history source is empty. Partial failures can leave useful resources. Inspect what exists before retrying. Revoking a connection removes pending authority but does not delete resources or prove an already-dispatched controller stopped. Cleanup is a separate governed request.Verify each application outcome
Retain the exact Application/service/database/release references, readiness outcome and application smoke-test result. A working client connection is separate from the outcome of a particular deployment. The typed objective checks described above are new implementation work for the next release. Existing MCP connections continue to support their available actions.Expected result
Completion requires healthy controller evidence and an application-level PostgreSQL write/read result. Accepted configuration, approved work or HTTP 200 alone is insufficient.
Related guides
Connect your coding agent
Connect an external client, choose its access and inspect its work in StackShift.
Connection access and approvals
Understand selected resources, permitted actions, owner decisions and revocation.
Live workload workspace
Follow a deployment, release or database operation alongside its activity and approval decisions.