Deploy a project¶

English | 日本語

AI Teams can coordinate an existing GitHub Actions deployment workflow and resume an interrupted operation. It reports deployed, exposed and validated separately. Validation confirms the deployed environment is healthy; it does not establish that a product Goal succeeded.

This is optional and separate from updating the AI Teams Plugin. You need a reviewed workflow in your repository, authenticated GitHub CLI with permission to dispatch it, and separate approval for each operation. AI Teams does not install a workflow, configure an environment, or copy credentials.

Prepare a request¶

Use an owner-private directory outside the repository for the Control Lite SQLite database, request and approvals. Keep the database when restarting; deleting it can lose the record of an operation already sent to GitHub.

The request format is illustrated below. Replace all example identities with your accepted artifact, its SHA-256 digest, the prior artifact and exposure, and a reviewed workflow ref and commit. The workflow ID is GitHub's numeric ID.

{
  "schema": "ai-teams-project-deployment/v1",
  "request_id": "staging-42",
  "repository": "example/service",
  "issue_number": 42,
  "environment": "staging",
  "artifact": {
    "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
  },
  "exposure": "canary",
  "rollback": {
    "artifact": {
      "revision": "cccccccccccccccccccccccccccccccccccccccc",
      "digest": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
    },
    "exposure": "public"
  },
  "workflow": {
    "id": 17,
    "ref": "deploy-v1",
    "revision": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
  }
}

Invoke the installed Plugin's skills/ai-teams/scripts/project_deployment.py with a supported Python runtime. The following examples use project_deployment.py as shorthand for that exact installed path:

python3 project_deployment.py start --database control.sqlite --request request.json
python3 project_deployment.py status --database control.sqlite --request request.json

start records a local request and returns its request_digest. It sends no deployment. A changed request under the same identity is rejected; start a new request only after the prior environment operation is terminal and reconciled.

Approve, dispatch and observe¶

An approval document contains schema: ai-teams-project-deployment-approval/v1, the exact request_digest returned by start, operation (deploy, expose, verify or rollback), an approval_ref naming the owner's actual decision, and a timezone-aware expires_at. Use that decision's real expiration time. A copied reference or generated JSON does not itself grant approval.

python3 project_deployment.py dispatch --database control.sqlite --request request.json --approval approval.json
python3 project_deployment.py resume --database control.sqlite --request request.json

dispatch selects the next stage. Start with approval for deploy; after its readback, approve expose, then verify. Each dispatch starts one workflow, including verification. resume reads the current run once and returns while it is pending. Repeat observation deliberately when useful; no background polling or automatic retry is installed.

If dispatch returned an uncertain result, inspect the exact GitHub run and use resume --run-id NUMBER. AI Teams checks the run's repository, workflow, revision, attempt and deterministic name before binding it. Repeating dispatch does not resend a reserved operation. A workflow rerun is rejected because it could repeat an environment effect.

Roll back¶

Once the pending run has finished, provide a separate rollback approval:

python3 project_deployment.py rollback --database control.sqlite --request request.json --approval rollback-approval.json
python3 project_deployment.py resume --database control.sqlite --request request.json

Rollback completes only after the prior artifact and exposure read back exactly and health is confirmed. An uncertain or failed rollback remains unresolved and keeps the environment occupied. An older request cannot roll back over a newer deployment. Source changes, a failed run or a closed Issue never authorize a live rollback.

Workflow integration¶

The reviewed workflow accepts one workflow_dispatch string input named deployment. Set its run name to ${{ fromJSON(inputs.deployment).attempt_id }}. Before the first environment effect, verify its workflow revision and fetched artifact digest, enforce the environment's approval policy, and deduplicate the attempt identity. Serialize the repository/environment without cancelling an active deployment.

After performing one requested operation, read the environment provider and upload result.json in the artifact named ai-teams-deployment-${{ fromJSON(inputs.deployment).attempt_id }}. Do not echo input values as observed evidence. The result must bind the exact request, operation, artifact, environment, exposure and health. Missing or mismatched readback never advances a successful stage.

The canonical deployment contract specifies the complete result schema, limits and workflow responsibilities. The adapter targets GitHub.com API version 2026-03-10; it requires dispatch responses containing a run ID. Local protocol tests cover this interface; a real target environment still needs its own reviewed integration and smoke test.