/application-integration-authoring

name: application-integration-authoring
metadata:
  version: "1.0.0"
  category: ApplicationDevelopment
description: >-
  Builds, versions, publishes, tests, and executes Google Cloud Application Integration
  workflows through the REST API and Python discovery client, and promotes versions across
  environments. Use when listing integrations, downloading or uploading integration versions
  as JSON, configuring API triggers or config variables, publishing drafts, invoking
  integrations, or automating CI/CD promotion. Do not use for initial region provisioning
  and IAM setup (use application-integration-basics) or diagnosing failed runs and logs (use application-integration-troubleshooting).

Application Integration Authoring

Google Cloud Application Integration workflows are authored, versioned, published, and executed programmatically through the REST API (`https://integrations.googleapis.com/v1/...`) or the discovery-based Google API Python client (`googleapiclient.discovery.build("integrations", "v1")`).

There is no `gcloud integrations` command group, no Google-managed MCP server for Application Integration, and no documented Terraform resource for integrations or versions. Use `gcloud` only for authentication, enabling APIs, and IAM bindings. Use Terraform only for region provisioning (`google_integrations_client`), authentication profiles (`google_integrations_auth_config`), and Integration Connectors (`google_integration_connectors_connection`).

For initial project setup, region provisioning, and IAM role definitions, use the `application-integration-basics` skill. For diagnosing failed or stuck runs, execution logs, and quota errors, use the `application-integration-troubleshooting` skill.

Safety and Confirmation Rules

• **Read-only operations run freely**: `integrations.list`, `integrations:search`, `versions.list`, `versions.get`, `versions:download`, `authConfigs.list`, and `executions.list`.
• **Confirm before any state change or execution**: Before creating, uploading, patching, publishing, unpublishing, testing, executing, scheduling, or deleting an integration or version, or modifying IAM or auth configs, show the exact command and payload to the user and get explicit confirmation.
• Ask the user before installing packages (`pip install`) or changing global gcloud settings such as `gcloud config set auth/impersonate_service_account`; show the exact command first.
• **Never store secrets in config variables**: Config variables (`CONFIG_*`) are stored and exported in plain text. Always use authentication profiles (`projects.locations.authConfigs`) or the Secret Manager access task for credentials.

Prerequisites Checklist

1. **Install Google Cloud SDK**: Follow [Install the gcloud CLI](https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt) if `gcloud` is not installed. 2. **Billing and project**: Ensure the Google Cloud project has an active billing account attached (required even when usage stays within the free tier), then set the target project:

   gcloud config set project PROJECT_ID

3. **Enable required APIs**:

   gcloud services enable integrations.googleapis.com connectors.googleapis.com secretmanager.googleapis.com

4. **Provision the region**: Application Integration is regional: confirm the target region is supported on [Application Integration locations](https://docs.cloud.google.com/application-integration/docs/locations.md.txt) and use `us-central1` as a well-supported default when the user has no preference. The region is the `LOCATION` in every REST path; no `gcloud` default-region setting applies to Application Integration. The target `LOCATION` must be provisioned via the Cloud console or `POST .../clients:provision` before authoring integrations (see `application-integration-basics`). 5. **Authenticate**:

• For `curl`: run `gcloud auth login` and pass `-H "Authorization: Bearer $(gcloud auth print-access-token)"`.
• For the Python client (install with `pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3"`): run `gcloud auth application-default login` (or set `GOOGLE_APPLICATION_CREDENTIALS` for a service account).
• For service account impersonation: run `gcloud config set auth/impersonate_service_account SA_EMAIL` (requires `roles/iam.serviceAccountTokenCreator`).

6. **Verify IAM roles**:

• Create, upload, or edit drafts: `roles/integrations.integrationEditor` (covers `versions:upload`, which needs `integrations.integrationVersions.create`, and `versions:publish`)
• Publish or unpublish: `roles/integrations.integrationDeployer` or `roles/integrations.integrationEditor` (`roles/integrations.integrationDeployer` alone can publish an existing version but cannot upload via `versions:upload`), plus `roles/integrations.serviceAgent` granted to the Application Integration service agent (`service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com`)
• Invoke integrations: `roles/integrations.integrationInvoker`
• Act as the run-as service account: integrations created on or after October 15, 2026 with any trigger other than an API or Private trigger (for example Schedule, Cloud Scheduler, Cloud Pub/Sub, Salesforce, or Connector Event; Private triggers are exempt like API triggers, so a sub-integration whose only trigger is Private can be published without `runAsServiceAccount`) cannot be tested or published unless `runAsServiceAccount` is set (and region governance requires it for all integrations); whenever `runAsServiceAccount` is set, the user publishing or testing the version needs `roles/iam.serviceAccountUser` on it (and at runtime, the invoking caller or trigger service account needs `roles/iam.serviceAccountUser` on it).

Decision Flow

| Goal | Action | Endpoint / Method | | :--- | :--- | :--- | | Inspect existing integrations in a region | List integrations, then list versions | `GET .../integrations` then `GET .../versions` | | Export an