Conéctate a Cloud Build

En esta página, se detalla cómo invocar compilaciones automáticamente desde Secure Source Manager con archivos de configuración de Cloud Build y un archivo YAML de activadores en tu repositorio de Secure Source Manager.

De forma predeterminada, Secure Source Manager usa un agente de servicio administrado por Google para interactuar con Cloud Build y otros recursos. Para aislar los permisos del equipo, te recomendamos que configures una identidad por repositorio asociando una cuenta de servicio administrada por el usuario a tu repositorio. Secure Source Manager usa la cuenta de servicio administrada por el usuario asociada al repositorio para activar compilaciones.

A diferencia del agente de servicio predeterminado, puedes configurar una cuenta de servicio administrada por el usuario con el permiso iam.serviceAccounts.actAs en cuentas de servicio personalizadas de Cloud Build. Esto te permite ejecutar compilaciones con cuentas de servicio personalizadas y, al mismo tiempo, restringir los permisos de compilación a ese repositorio.

Antes de comenzar

  1. Crea una instancia de Secure Source Manager.
  2. Crea un repositorio de Secure Source Manager.

  3. Configura una cuenta de servicio especificada por el usuario de Cloud Build. Para permitir que Cloud Build lea desde tu repositorio de Secure Source Manager, otorga a la cuenta de servicio de Cloud Build (ya sea la cuenta de servicio predeterminada o una cuenta de servicio administrada por el usuario) los siguientes roles:

    • Acceso a instancias de Secure Source Manager (roles/securesourcemanager.instanceAccessor) en la instancia de Secure Source Manager.
    • Lector de repositorios de Secure Source Manager en el repositorio

    Según tu caso de uso, es posible que la cuenta de servicio de Cloud Build necesite roles adicionales, por ejemplo:

    • Para almacenar registros de compilación en Cloud Logging, otorga el rol de escritor de registros (roles/logging.logWriter) a la cuenta de servicio de Cloud Build.
    • Para acceder a los secretos en Secret Manager, otorga el rol de Descriptor de acceso a secretos de Secret Manager (roles/secretmanager.secretAccessor) a la cuenta de servicio de Cloud Build.

    Para obtener información sobre los registros de compilación, consulta Cómo configurar registros de compilación.

  4. Si tus compilaciones se ejecutan en grupos de trabajadores, otorga a la cuenta de servicio administrada por el usuario del repositorio el rol Usuario de Cloud Build WorkerPool (roles/cloudbuild.workerPoolUser) en el proyecto en el que se ejecutan las compilaciones.

Roles obligatorios

Para obtener los permisos que necesitas para conectar un repositorio de Secure Source Manager a Cloud Build, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Para obtener información sobre cómo otorgar roles de Secure Source Manager, consulta Control de acceso con IAM y Cómo otorgar acceso a la instancia a los usuarios.

Roles de la cuenta de servicio requeridos

Para conectar Secure Source Manager a Cloud Build, debes configurar los permisos de IAM para una identidad por repositorio.

Configuración de identidad por repositorio

Para usar una identidad por repositorio, debes configurar los permisos.

  1. Usuario: El usuario que configura la cuenta de servicio del repositorio necesita el rol de usuario de cuenta de servicio (roles/iam.serviceAccountUser) en la cuenta de servicio administrada por el usuario. Este permiso se verifica durante la creación o actualización del repositorio.

  2. Agente de servicio de Secure Source Manager: Otorga al agente de servicio de Secure Source Manager para el proyecto del repositorio el rol de Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) en la cuenta de servicio administrada por el usuario.

    El correo electrónico del agente de servicio de Secure Source Manager tiene el formato service-REPOSITORY_PROJECT_NUMBER@gcp-sa-sourcemanager.iam.gserviceaccount.com, en el que REPOSITORY_PROJECT_NUMBER es el número del proyecto que aloja el repositorio.

  3. Cuenta de servicio administrada por el usuario:

    • Otorga a la cuenta de servicio administrada por el usuario el rol de Usuario de cuenta de servicio (roles/iam.serviceAccountUser) en la cuenta de servicio personalizada de Cloud Build (en el proyecto del repositorio).
    • Otorga a la cuenta de servicio administrada por el usuario el rol de Editor de Cloud Build (roles/cloudbuild.builds.editor) y el rol de Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer) en el proyecto en el que se ejecutan las compilaciones.

Para obtener información sobre cómo otorgar roles de IAM, consulta Otorga o revoca un solo rol.

Crea un archivo de configuración de compilación

Un archivo de configuración de compilación define los campos que Cloud Build necesita para realizar tus tareas de compilación. Puedes escribir el archivo de configuración de compilación con la sintaxis YAML.

Puedes crear archivos de configuración de compilación en la rama o las ramas desde las que deseas compilar.

Para crear un archivo de configuración de compilación, haz lo siguiente:

  1. En la interfaz web de Secure Source Manager, selecciona el repositorio que deseas conectar a Cloud Build.
  2. Selecciona la rama desde la que deseas compilar con Cloud Build.

  3. Crea un archivo de configuración de compilación. Para obtener información sobre cómo crear archivos de configuración de compilación, sigue las instrucciones en Crea un archivo de configuración de compilación.

  4. Confirma tus cambios en la rama.

Crea un archivo de activadores

El archivo de configuración de los activadores debe crearse en la rama predeterminada de tu repositorio.

Para crear un archivo de configuración de activadores, sigue estos pasos:

  1. En tu repositorio local o en la interfaz web de Secure Source Manager, cambia a la rama predeterminada.

  2. Crea un archivo llamado .cloudbuild/triggers.yaml.

  3. Configura el activador en el archivo .cloudbuild/triggers.yaml:

    triggers:
- name: TRIGGER_NAME
  project: PROJECT_ID
  configFilePath: CLOUD_BUILD_CONFIG_PATH
  eventType: EVENT_TYPE
  ignoredGitRefs: IGNORED_GIT_REFS
  includedGitRefs: INCLUDED_GIT_REFS
  serviceAccount: SERVICE_ACCOUNT
  includedFiles: INCLUDED_FILES
  ignoredFiles: IGNORED_FILES
  disabled: DISABLED_BOOL
  substitutions:
    _VARIABLE_NAME: VARIABLE_VALUE
    OVERRIDE_VARIABLE_NAME: OVERRIDE_VARIABLE_VALUE

    Reemplaza lo siguiente:

    • TRIGGER_NAME por un nombre para tu activador. Los nombres de los activadores solo pueden contener caracteres alfanuméricos y guiones, y no pueden comenzar ni terminar con un guion. Los nombres de los activadores deben tener menos de 64 caracteres.
    • PROJECT_ID por el ID del proyecto en el que habilitaste Cloud Build. Google Cloud Este campo es opcional. El valor predeterminado es el proyecto de Secure Source Manager.
    • CLOUD_BUILD_CONFIG_PATH con la ruta de acceso al archivo de configuración de Cloud Build que deseas usar para este activador. Este campo es opcional. El valor predeterminado es .cloudbuild/cloudbuild.yaml.

    • EVENT_TYPE con el tipo de evento con el que deseas activar la compilación. Las opciones son las siguientes:

      • push para activar la acción cuando se envíe a las ramas especificadas
      • pull_request para activar una solicitud de extracción en las ramas especificadas

      Este campo es opcional. El valor predeterminado es push.

    • INCLUDED_GIT_REFS con un formato de expresión regular RE2 opcional que coincida con las referencias de Git con las que deseas activar una compilación. El valor predeterminado es vacío. Un valor vacío indica que no hay restricciones.

    • IGNORED_GIT_REFS con una expresión regular opcional que usa el formato de expresión regular RE2 que coincide con las referencias de Git que no quieres que activen una compilación. El valor predeterminado es vacío. Un valor vacío indica que no hay restricciones. El campo ignoredGitRefs se verifica antes que el campo includedGitRefs. Para obtener más información sobre estos campos, consulta Esquema del archivo de activadores.

    • SERVICE_ACCOUNT con la cuenta de servicio de Cloud Build que se usará para la compilación en el formato projects/PROJECT_ID/serviceAccounts/ACCOUNT. Reemplaza ACCOUNT por la dirección de correo electrónico o el ID único de la cuenta de servicio. Puedes usar la cuenta de servicio predeterminada de Cloud Build o una cuenta de servicio administrada por el usuario. No se puede usar la cuenta de servicio heredada de Cloud Build debido a sus limitaciones.

    • INCLUDED_FILES con una expresión regular de formato RE2 opcional que coincida con los archivos que deseas que activen una compilación.

      Si alguno de los archivos modificados no coincide con el campo de filtro ignoredFiles y los archivos modificados coinciden con el campo de filtro includedFiles, se activa una compilación. El valor predeterminado es vacío. Un valor vacío indica que no hay restricciones.

    • IGNORED_FILES con una expresión regular opcional en formato RE2 que coincida con los archivos que no quieres que activen una compilación.

      Si todos los archivos modificados en una confirmación coinciden con este campo de filtro, no se activa una compilación. El valor predeterminado es vacío. Un valor vacío indica que no hay restricciones.

    • DISABLED_BOOL con true para inhabilitar el activador o false para habilitarlo Este campo es opcional. El valor predeterminado es false.

    • VARIABLE_NAME por el nombre de una variable que deseas introducir en tu archivo de activadores

    • VARIABLE_VALUE con el valor de la variable.

    • OVERRIDE_VARIABLE_NAME por el nombre predeterminado de la variable de sustitución de Secure Source Manager. Para obtener información sobre las variables de sustitución predeterminadas disponibles, consulta la sección de sustituciones del esquema del archivo de activadores.

    • OVERRIDE_VARIABLE_VALUE con el valor con el que deseas anular el valor predeterminado de la variable de sustitución predeterminada.

  4. Confirma el archivo de configuración del activador en tu rama predeterminada.

    Después de confirmar el archivo de activadores, Secure Source Manager activará compilaciones según la configuración de tu archivo de activadores.

    Secure Source Manager lee los archivos de configuración y el SHA de la confirmación o la referencia de Git asociados de los siguientes tipos de eventos:

    • En el caso de los eventos push, Secure Source Manager leerá el SHA de la confirmación o la referencia de Git cuando se complete la inserción.
    • En el caso de los eventos pull_request, Secure Source Manager leerá el SHA de confirmación o la referencia de Git cuando se extraigan los cambios de la solicitud de extracción.

Cómo ver el estado de la compilación

Cuando una compilación se activa por un evento de solicitud de extracción o envío, el estado de la confirmación y la compilación se muestra en la interfaz web de Secure Source Manager.

Los valores posibles para el estado de compilación son los siguientes:

  • correctoSUCCESS: La compilación se completó correctamente.
  • advertenciaADVERTENCIA: Se produjo un problema al intentar compilar.
  • fallaFAILURE: La compilación falló durante la ejecución.

Puedes evitar que las confirmaciones con compilaciones fallidas se combinen en ramas importantes si configuras una regla de protección de ramas para que requiera una verificación de estado exitosa de los activadores configurados en tu archivo de activadores. Para obtener más información sobre la protección de ramas, consulta la descripción general de la protección de ramas.

Para ver el estado de compilación de un evento de envío, haz lo siguiente:

  1. En la interfaz web de Secure Source Manager, navega a tu repositorio.

    Si el evento de envío más reciente activó una compilación, el estado se muestra junto al SHA de la confirmación. Para ver los detalles de ese estado, haz clic en él.

  2. Para ver el estado de compilación de las confirmaciones anteriores, selecciona Confirmaciones para ver el historial de confirmaciones y, luego, haz clic en el estado del que deseas ver los detalles.

Para ver el estado de compilación de un evento de solicitud de extracción, haz lo siguiente:

  1. En la interfaz web de Secure Source Manager, haz clic en Pull requests.

  2. Haz clic en la solicitud de extracción que quieras ver.

    Si la solicitud de extracción activó compilaciones, verás una sección titulada All checks were successful o Some checks reported warnings.

Solucionar problemas

Si deseas encontrar métodos para diagnosticar y resolver errores de Cloud Build cuando se conecta con Secure Source Manager, consulta El archivo de activadores no activa la compilación.

¿Qué sigue?