Gate builds on organization policy

Cloud Build enables you to define an organization policy (constraints/cloudbuild.allowedIntegrations) to control which external services can invoke build triggers. For example, if your trigger listens for changes to a GitHub repository and GitHub is denied in the organization policy, your trigger will not run. You can specify any number of allowed or denied values for your organization or project.

This page explains how you can set up the organization policy (constraints/cloudbuild.allowedIntegrations) for integrations using Google Cloud console and the gcloud command-line tool.

Before you Begin

  • Enable the Cloud Build and Organization Policy APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  • To use the command-line examples in this guide, install and configure the Google Cloud SDK.

  • To set, change, or delete an organization policy, you must have the Organization Policy Administrator (roles/orgpolicy.policyAdmin) role. To learn how to add the role to your account, see Add an organization policy administrator.

Setting up organization policy for allowed integrations

This section explains how you can set up the organization policy (constraints/cloudbuild.allowedIntegrations) to define builds for allowed integrations.

Console

  1. Open the Organization policies page in the Google Cloud console.

    Open the Organization policies page

  2. Click on the row containing the Allowed Integrations (Cloud Build) policy.

    You will see the Policy details page.

  3. To edit the policy, click Edit.

    You will see the Edit policy page.

  4. In the Applies to section, select Customize to set the definition for your policy.

  5. In the Policy enforcement section, select Replace to define your own rules for the policy. Otherwise, select Merge with parent to ensure that rules at the parent resource are applied to your settings. To learn more, see Understanding hierarchy evaluation.

  6. In the Rules section, click Add rule to add a new rule for your policy.

  7. Under Policy values, select Allow all to allow builds from all services, select Deny all to deny builds from all services, or select Custom to allow or deny builds from specific services.

    If you select Custom as your value, complete the following steps:

    1. In the Policy type section, select Allow or Deny.

    2. In the Custom values section, enter the host URL of the instance or repository you want to allow or deny builds from. For example, to allow or deny builds from GitHub, enter your URL as github.com or www.github.com.

      You can also enter multiple URLs separated by a space. For example, github.com ghe.staging-test.com.

      Based on the event, the host URL you specify is one of the following:

      • RepoSync event: The host is source.developers.google.com.
      • GitHub app event: The host is derived from the repository.html_url field in your JSON payload, which is always github.com.
      • GitHub Enterprise event: The host is derived from the repository.html_url field in your JSON payload. For example, ghe.staging-test.com.
      • Pub/Sub event: The host is derived from the source specified in your trigger. If there is no source specified in your trigger, there is no organization policy check.
      • Webhook event: The host is derived from the source specified in your trigger. If there is no source specified in your trigger, there is organization policy check.

  8. To save your rule, click Done.

  9. To add another rule, click Add rule. Otherwise, to save your policy, click Save.

gcloud

  1. Open a terminal window.

  2. If you want to allow or deny builds from all services, create a YAML file with the following contents:

    name: projects/PROJECT_NUMBER/policies/cloudbuild.allowedIntegrations
spec:
  inheritFromParent: INHERIT
  rules:
    - ALLOW_OR_DENY: true

    Where:

    • PROJECT_NUMBER is your project number.
    • INHERIT is true if you want your policy rules to be inherited from the parent resource. Otherwise, false.
    • ALLOW_OR_DENY is allowAll if you want to allow builds from all host URLs. Otherwise, denyAll.
    • HOST_URL is your host URL. For example, github.com. You can also specify additional URLs on the following lines.

    If you want to allow or deny builds from selected services, create a YAML file with the following contents:

    name: projects/PROJECT_NUMBER/policies/cloudbuild.allowedIntegrations
spec:
  inheritFromParent: INHERIT
  rules:
    - values:
        ALLOW_OR_DENY:
          HOST_URL
          ...

    Where:

    • PROJECT_NUMBER is your project number.
    • INHERIT is true if you want your policy rules to be inherited from the parent resource. Otherwise, false.
    • ALLOW_OR_DENY is allowedValues if you want to specify host URLs to allow builds from. Otherwise, deniedValues.
    • HOST_URL is your host URL. For example, github.com. You can also specify additional URLs on the following lines.

  3. Set your organization policy by running the following command, where FILE_NAME is the name of your YAML file:

     gcloud org-policies set-policy FILE_NAME

  4. To confirm that your policy has been set, run the following command, where PROJECT_ID is your project ID:

     gcloud org-policies describe cloudbuild.allowedIntegrations --effective --project PROJECT_ID

Testing organization policy for allowed integrations

This section explains how you can test your organization policy (constraints/cloudbuild.allowedIntegrations) using build triggers.

  1. If you have not already done so, create a build trigger.

  2. Push a change to your source.

  3. If your policy is set up to allow builds from your source, you will be able to view build executions from your trigger on the Build history page. Otherwise, your build will not execute. To view history for builds restricted by your policy definition, see the Logs Explorer page for the JSON payload reason and the reason for denial.

What's next