---

name: application-integration-authoring metadata: version: "1.0.2" 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.

Attribution

MUST READ: Before executing any gcloud command, REST API call, or Python discovery-client call, you MUST read Usage Attribution. For commands executed directly in the terminal (never in generated scripts, Terraform, ADK agents, or user code), prefix gcloud with CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:application-integration-authoring)" and add agent-skills/1.0 (skill:application-integration-authoring) to the User-Agent header of curl requests.

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.
• Host changes require approval. Before installing packages (pip install) or changing global gcloud or credential state (gcloud config set ... such as auth/impersonate_service_account, gcloud auth application-default login / set-quota-project), show the exact command and wait for the user's approval.
• 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 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 (changes global gcloud state; get the user's approval first):

   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 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 (changes host or credential state; get the user's approval first) 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 and gcloud auth application-default set-quota-project PROJECT_ID (or set GOOGLE_APPLICATION_CREDENTIALS for a service account) (changes host or credential state; get the user's approval first).
   • For service account impersonation: run gcloud config set auth/impersonate_service_account SA_EMAIL (requires roles/iam.serviceAccountTokenCreator) (changes host or credential state; get the user's approval first).
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 integration version to source control | Download version JSON | GET .../versions/VERSION_ID:download?fileFormat=JSON | | Create an integration or add a new DRAFT version from JSON | Upload version JSON (creates the integration if it does not exist, or adds a new DRAFT version; still needs :publish) | POST .../integrations/INTEGRATION_NAME/versions:upload | | Create a brand-new integration and fail on a name clash | Create first DRAFT version with newIntegration=true (returns ALREADY_EXISTS if INTEGRATION_NAME already exists) | POST .../integrations/INTEGRATION_NAME/versions?newIntegration=true | | Edit an existing DRAFT version | Check lockHolder, then patch or upload | PATCH .../versions/VERSION_ID?updateMask=... | | Edit an ACTIVE (published) integration | Upload or create a new DRAFT version | POST .../integrations/INTEGRATION_NAME/versions:upload | | Externalize environment-specific URLs or IDs | Define CONFIG_<NAME> and supply at publish | integrationConfigParameters + versions:publish | | Store API keys, OAuth credentials, or certs | Create an authentication profile | POST .../authConfigs | | Test an integration before production | Publish to a non-production project and invoke :execute | POST .../versions/VERSION_ID:publish then POST .../integrations/INTEGRATION_NAME:execute | | Deploy a DRAFT to serve live traffic | Publish version with configParameters | POST .../versions/VERSION_ID:publish | | Invoke a published integration synchronously | Call :execute with api_trigger/TRIGGER_NAME | POST .../integrations/INTEGRATION_NAME:execute | | Invoke a published integration asynchronously | Call :schedule with scheduleTime | POST .../integrations/INTEGRATION_NAME:schedule | | Promote a version across projects (CI/CD) | Download JSON -> Upload to target -> Publish | :download -> :upload -> :publish |

See references/rest-api-cheatsheet.md for full request parameters, query filters, and IAM permissions for each method.

Core Authoring Workflow

1. List Integrations and Download a Version

List integrations in LOCATION and list versions for a specific INTEGRATION_NAME:

TOKEN="$(gcloud auth print-access-token)"

# List integrations in the region
curl -sS -H "Authorization: Bearer ${TOKEN}" \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations?pageSize=50"

# List versions (ordered by most recently modified)
curl -sS -H "Authorization: Bearer ${TOKEN}" \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions?orderBy=last_modified_time%20desc"

Download a specific version (VERSION_ID is the UUID at the end of the version's name field) as portable JSON:

curl -sS -H "Authorization: Bearer ${TOKEN}" \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions/VERSION_ID:download?fileFormat=JSON" \
  | jq -r '.content' > integration-version.json

2. Understand the IntegrationVersion Structure

An IntegrationVersion JSON object contains four primary arrays and version-level settings:

• triggerConfigs: Entry points that start the workflow. Each entry requires a unique triggerNumber, plus triggerType (such as API or PRIVATE_TRIGGER), optional triggerId (auto-generated from properties if omitted; for API triggers: api_trigger/TRIGGER_NAME), and startTasks pointing to the first taskId.
• taskConfigs: Units of work. Each entry needs task (the task type, such as EmailTask in the public upload sample, or FieldMappingTask in a discovery enum description), a unique taskId, parameters, nextTasks, and optional failurePolicy or errorCatcherId.
• integrationParameters: Input, output, and transient variables (key, dataType such as STRING_VALUE or JSON_VALUE, inputOutputType of IN, OUT, IN_OUT, or IN_OUT_TYPE_UNSPECIFIED, and defaultValue).
• integrationConfigParameters: Environment-specific config variable definitions (parameter with key `CONFIG_<NAME>` and parameter.defaultValue; a top-level value in uploaded or created draft JSON is discarded, so per-environment values go in configParameters at publish).
• runAsServiceAccount: Dedicated user-managed service account email. When set and no authentication profile (authConfig) is configured on the task, it is used to generate the auth token for Connector (Connectors), REST (Call REST Endpoint), and Cloud Function tasks; an authentication profile configured on the task takes precedence over runAsServiceAccount.

Always use triggerConfigs, taskConfigs, and integrationParameters. Never use triggerConfigsInternal, taskConfigsInternal, or integrationParametersInternal because they are deprecated. See references/integration-version-json.md for