Transactions Commands

The stategraph tx command group manages transactions in Stategraph. Transactions track infrastructure changes and provide audit trails.

Commands

stategraph tx create

Create a new transaction.

stategraph tx create --tenant <tenant-id> [options]

Options

Example

stategraph tx create \
  --tenant 550e8400-e29b-41d4-a716-446655440000 \
  --tag pipeline=github-actions \
  --tag commit=abc123

Output (JSON):

{
  "id": "...",
  "created_at": "2024-01-15T10:30:00Z",
  "created_by": "user@example.com",
  "completed_at": null,
  "completed_by": null,
  "state": "open",
  "tags": {
    "pipeline": "github-actions",
    "commit": "abc123"
  }
}

stategraph tx create-with-session

Create a transaction and generate an API key for it. Useful for CI/CD pipelines where you want to scope Terraform operations to a single transaction.

stategraph tx create-with-session --tenant <tenant-id> [options]

Options

Example

stategraph tx create-with-session \
  --tenant 550e8400-e29b-41d4-a716-446655440000 \
  --tag pipeline=terraform-ci

Output (API key):

eyJhbGciOiJIUzI1NiIs...

Use this API key for Terraform backend authentication:

export TF_HTTP_PASSWORD=$(stategraph tx create-with-session --tenant $TENANT_ID)
terraform apply

The returned API key can be used with: - The Terraform HTTP backend (as the password) - Direct API calls (as a Bearer token) - The CLI (via STATEGRAPH_API_KEY)

stategraph tx list

List transactions for a tenant.

stategraph tx list --tenant <tenant-id>

Options

Example

stategraph tx list --tenant 550e8400-e29b-41d4-a716-446655440000

Output (JSON):

{
  "results": [
    {
      "id": "...",
      "created_at": "2024-01-15T10:30:00Z",
      "created_by": "user@example.com",
      "completed_at": "2024-01-15T10:30:05Z",
      "completed_by": "user@example.com",
      "state": "completed",
      "tags": {
        "pipeline": "github-actions"
      }
    }
  ]
}

stategraph tx abort

Abort an active transaction.

stategraph tx abort --tx <transaction-id>

Options

Example

stategraph tx abort --tx 550e8400-e29b-41d4-a716-446655440000

stategraph tx logs list

List logs for a transaction.

stategraph tx logs list --tx <transaction-id>

Options

Example

stategraph tx logs list --tx 550e8400-e29b-41d4-a716-446655440000

Output (JSON):

{
  "results": [
    {
      "id": "...",
      "action": "state_set",
      "object_type": "instance",
      "created_at": "2024-01-15T10:30:00Z",
      "state_id": "...",
      "data": { ... }
    }
  ]
}

CI/CD Integration

GitHub Actions Example

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Create transaction
        run: |
          TOKEN=$(docker run --rm \
            -e STATEGRAPH_API_BASE=${{ secrets.STATEGRAPH_URL }} \
            ghcr.io/stategraph/stategraph:<version> stategraph tx create-with-session \
            --tenant ${{ secrets.TENANT_ID }} \
            --tag pipeline=github-actions \
            --tag commit=${{ github.sha }})
          echo "TF_HTTP_PASSWORD=$TOKEN" >> $GITHUB_ENV

      - name: Terraform Apply
        run: terraform apply -auto-approve

GitLab CI Example

terraform:
  script:
    - export TF_HTTP_PASSWORD=$(stategraph tx create-with-session --tenant $TENANT_ID --tag pipeline=gitlab-ci)
    - terraform apply -auto-approve

Transaction States

Next Steps

• States - State management
• Timeline - View transactions in UI
• Backend Transactions - Transaction concepts