Git and deployments

VegaFlow treats repository source, published pipeline versions and environment deployments as separate records. A moving branch is never itself a production release.

Git integrations

GET  {api-base}/orgs/{org_id}/workspaces/{workspace_id}/git-integrations
POST {api-base}/orgs/{org_id}/workspaces/{workspace_id}/git-integrations
GET  {api-base}/orgs/{org_id}/workspaces/{workspace_id}/git-integrations/{integration_id}
PUT  {api-base}/orgs/{org_id}/workspaces/{workspace_id}/git-integrations/{integration_id}
DELETE {api-base}/orgs/{org_id}/workspaces/{workspace_id}/git-integrations/{integration_id}

An integration records provider and account identity plus references to credential secrets. Repository tokens, application keys and webhook secrets never appear in project source configuration.

Push reconciliation

An accepted Git push webhook queues reconciliation for projects following the affected repository and branch. Duplicate deliveries are safe: provider delivery identity and observed repository state prevent a delivery from becoming multiple releases.

push event
  → integration validates delivery
  → affected project reconciliation queued
  → commit fetched and source validated
  → pipeline declarations discovered
  → immutable source revision available

A push does not automatically become a published pipeline version or production deployment unless the project policy explicitly permits that promotion path.

Project environments

Environments represent promotion targets such as development, staging and production. They select compute, execution identity, source policy and approval behavior.

GET  /pipeline-projects/{project_id}/environments
POST /pipeline-projects/{project_id}/environments
GET  /pipeline-projects/{project_id}/environments/{environment_id}
PUT  /pipeline-projects/{project_id}/environments/{environment_id}
DELETE /pipeline-projects/{project_id}/environments/{environment_id}

Deleting an environment archives it. Existing deployments and execution history remain addressable.

Preview source approval

An environment can require approval before adopting a newly reconciled preview source revision.

GET  /pipeline-projects/{project_id}/environments/{environment_id}/source-approvals
POST /pipeline-projects/{project_id}/environments/{environment_id}/source-approvals

Approval records the exact source revision and approving principal. If repository head moves later, that new revision needs its own evaluation.

Deployment lifecycle

Deployments are created by reconciliation/promotion workflows and inspected under the project:

GET  /pipeline-projects/{project_id}/deployments
GET  /pipeline-projects/{project_id}/deployments/{deployment_id}
POST /pipeline-projects/{project_id}/deployments/{deployment_id}/approve

preparing → awaiting approval → activating → active
     └──────────────→ failed
active → superseded

The exact state set returned by the API is authoritative. Approval is guarded by resource version and environment policy so an approval for an older candidate cannot activate a newer one accidentally.

Promotion checklist

1. Confirm reconciliation resolved the intended commit and project configuration generation.
2. Review diagnostics and discovered pipeline changes.
3. Publish the required pipeline versions.
4. Confirm target environment, compute and execution identity.
5. Review connection and secret-reference changes without exposing secret values.
6. Preview downstream impact through VegaGraph.
7. Approve the exact deployment generation.
8. Observe the first execution and retain rollback/supersession evidence.

Roll-forward behavior

Published versions and deployment history are immutable evidence. Correct a bad release by publishing and deploying a corrected version, or by promoting a previously published safe version when policy permits. Do not edit the historical version to make it look as though the failed release never existed.