Conectarse a Jenkins

Puedes iniciar compilaciones automáticas con activadores de Jenkins y webhooks de Secure Source Manager.

Roles obligatorios

Para obtener los permisos que necesitas para crear activadores de compilación de Jenkins, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:

• Administrador de repositorio de Secure Source Manager (roles/securesourcemanager.repoAdmin) en tu repositorio
• Accessor de instancia de Secure Source Manager (roles/securesourcemanager.instanceAccessor) en la instancia de Secure Source Manager

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Para obtener información sobre cómo conceder roles de Secure Source Manager, consulta los artículos Control de acceso con gestión de identidades y accesos y Conceder acceso a instancias a los usuarios.

Configurar un activador de webhook

Jenkins usa complementos de activadores de compilación para habilitar la automatización de CI/CD. Puedes configurar activadores para que detecten eventos entrantes, como cuando se envía una nueva confirmación a un repositorio o cuando se inicia una solicitud de extracción, y, a continuación, ejecutar automáticamente una compilación cuando se produzcan nuevos eventos. También puedes configurar activadores para compilar el código a partir de cualquier cambio en el repositorio de origen o solo a partir de los cambios que cumplan con ciertos criterios.

Para configurar un activador de webhook genérico de Jenkins, haz lo siguiente:

1. Instala los complementos Git Plugin, SSH Credential Plugin y Generic Webhook Trigger Plugin en tu servidor de Jenkins.

2. Genera un par de claves SSH válido en tu servidor de Jenkins. Secure Source Manager solo admite claves de tipo RSA.

3. Añade el dominio de la instancia de Secure Source Manager al archivo SSH known_hosts del servidor de Jenkins ejecutando el siguiente comando:

   ssh -t git@INSTANCE_ID-INSTANCE_PROJECT_NUMBER-ssh.us-central1.sourcemanager.dev
   

   Donde:

   • INSTANCE_ID es el nombre de tu instancia de Secure Source Manager.
   • INSTANCE_PROJECT_NUMBER es el número de proyecto de tu instancia de Secure Source Manager. Consulta el artículo Identificar proyectos para saber dónde encontrar el número de proyecto.

   Por ejemplo, el siguiente comando añade el dominio de instancia de una instancia llamada prod-test-instance con el número de proyecto 123456789.

   ssh -t [e-mail]
   

   Responde yes para añadir el dominio de la instancia a la lista de hosts conocidos.

4. En la página Manage Credentials (Gestionar credenciales) de Jenkins:

   1. Selecciona Nombre de usuario SSH con clave privada.
   2. Pega la clave privada SSH de tu servidor de Jenkins.
   3. En el menú desplegable Tipo, rellena los demás campos según sea necesario.

5. Haz clic en Crear.

6. En la interfaz web de Jenkins, crea un trabajo de Jenkins.

7. En la página de configuración del trabajo de Jenkins, en la sección Gestión de código fuente, selecciona Git.

8. En la sección Git, pega la URL SSH del repositorio de Secure Source Manager como URL del repositorio, introduce tus ramas de compilación (por ejemplo, */main) y, a continuación, selecciona la credencial de clave SSH privada guardada que has añadido anteriormente en la página Gestionar credenciales.

9. En la sección Crear activadores, selecciona Activador de webhook genérico.

   De forma opcional, puede añadir un token para que el trabajo solo se active si se proporciona ese token al invocarlo. Para añadir un token, en la sección Activador de webhook genérico, puedes introducir un token en el campo Token.

10. En la sección Build (Compilación), proporciona una secuencia de comandos de compilación que quieras usar para este trabajo de Jenkins. Por ejemplo, puedes ejecutar cat README.md para imprimir el contenido de README.md.

11. Haz clic en Guardar para crear el trabajo de Jenkins.

Configurar una cuenta de servicio y conceder los permisos necesarios

1. Si aún no tienes una cuenta de servicio que quieras usar, crea una.

   Asegúrate de que tienes el permiso iam.serviceAccounts.actAs en la cuenta de servicio. Este permiso forma parte del rol Usuario de cuenta de servicio (roles/iam.serviceAccountUser).

2. En la interfaz web de Secure Source Manager, haz clic en el menú más opciones.

3. Haz clic en Claves SSH de cuenta de servicio. Se abrirá la página Claves SSH de cuenta de servicio y se mostrará una lista de las claves que hayas añadido.

4. Haz clic en Añadir clave.

5. En la página Añadir clave SSH, introduce los siguientes valores de tu clave:

   1. Cuenta de servicio: el correo de la cuenta de servicio que quieras usar con la clave SSH en el formato SA_NAME@PROJECT_ID.iam.gserviceaccount.com

      Dónde

      • SA_NAME es el nombre de la cuenta de servicio.
      • PROJECT_ID es el ID del proyecto en el que se ha creado la cuenta de servicio.

   2. Clave pública SSH: tu clave pública SSH de Jenkins.

Conceder permisos al agente de servicio de Secure Source Manager

Si la cuenta de servicio no está en el mismo proyecto que tu instancia de Secure Source Manager, también debes conceder el rol Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) o el permiso iam.serviceAccounts.signJwt al agente de servicio de Secure Source Manager.

Si tu cuenta de servicio está en el mismo proyecto que tu instancia de Secure Source Manager, ve a la sección Conceder un rol de repositorio a la cuenta de servicio.

1. Ejecuta el siguiente comando para obtener la política de IAM de tu cuenta de servicio:

   gcloud iam service-accounts get-iam-policy SERVICE_ACCOUNT \
       --format json
   

   Donde SERVICE_ACCOUNT es la cuenta de servicio que quieres usar. La cuenta debe tener el formato de un ID de cuenta de servicio numérico o de una dirección de correo electrónico, como 123456789876543212345 o [e-mail].

   La salida incluye los enlaces que ya existan o, si no hay ninguno, el valor etag similar al siguiente:

   {
   "etag": "BwUjHYKJUiQ="
   }
   

   Importante: Conserva el valor de etag de la respuesta get-iam-policy para asegurarte de que no sobrescribes los cambios de la política de otro usuario. Si quiere sobrescribir todos los demás cambios, puede quitar el valor etag
   .

2. Copia el resultado en un archivo nuevo llamado policy.json.

3. Para asignar el rol Creador de tokens de cuenta de servicio (roles/iam.ServiceAccountTokenCreator) al agente de servicio de Secure Source Manager, modifica el policy.json para añadir lo siguiente:

   {
       "role": "roles/iam.serviceAccountTokenCreator",
       "members": [
           "serviceAccount:[e-mail]"
       ]
   }
   

   Donde INSTANCE_PROJECT_NUMBER es el número de proyecto de tu instancia de Secure Source Manager.

4. Ejecuta el siguiente comando para sustituir la política de IAM de la cuenta de servicio:

   gcloud iam service-accounts set-iam-policy SERVICE_ACCOUNT POLICY_FILE
   

   Haz los cambios siguientes:

   • SERVICE_ACCOUNT con el ID o el correo de la cuenta de servicio.
   • POLICY_FILE con la ubicación y el nombre del archivo con formato JSON que incluye la nueva política.

Asigna un rol de repositorio a la cuenta de servicio

1. En la interfaz web de Secure Source Manager, vaya al repositorio en el que quiera dar permisos a la cuenta de servicio.
2. Haz clic en la pestaña Permisos.
3. Haz clic en Añadir usuarios.
4. En el campo Añadir principal, introduce la dirección de correo de la cuenta de servicio.
5. En el menú desplegable Rol, selecciona Lector de repositorio de Secure Source Manager.

6. Asigna el rol securesourcemanager.instanceAccessor a la cuenta de servicio ejecutando el siguiente comando:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:SA_EMAIL \
       --role=roles/securesourcemanager.instanceAccessor
   

   Haz los cambios siguientes:

   • PROJECT_ID con el ID del proyecto de la instancia de Secure Source Manager.
   • SA_EMAIL con el correo de la cuenta de servicio.

Configurar un webhook

1. En la interfaz web de Gestor de fuentes seguras, vaya al repositorio para el que quiera crear un webhook.
2. Haz clic en Settings (Configuración).
3. Haz clic en Webhooks y, a continuación, en Add webhook (Añadir webhook).

4. En el campo ID de gancho, introduce un ID para el webhook.

   Nota: Los IDs de los hooks deben seguir la convención de nomenclatura de recursos. Solo pueden incluir letras minúsculas, números o guiones, deben empezar por una letra y no se pueden cambiar después de crear el webhook.

5. En el campo URL de destino, introduce la URL de activación de Jenkins.

6. Si has usado el token opcional al configurar el activador de Jenkins, la URL del activador de Jenkins contendrá ese token al final. Para evitar que se filtre el token, quítalo del final de la URL de destino y cópialo en el campo Cadena de consulta sensible.

   Para encontrar tu token en la URL del activador, busca el texto que empieza por token=

   Por ejemplo, si tu URL es similar a la siguiente: https://jenkins-server.com/generic-webhook-trigger/invoke?token=jenkins-job1

   Copia y elimina la parte que empieza por el signo de interrogación ?token=jenkins-job1 del campo URL de destino. A continuación, elimina el signo de interrogación inicial y mueve la parte restante token=jenkins-job1 al campo Cadena de consulta sensible.

7. En la sección Activar con, seleccione una de las siguientes opciones:

   • Push: se activa cuando se inserta contenido en el repositorio.
   • Estado de solicitud de extracción cambiado: se activa cuando cambia el estado de una solicitud de extracción.

8. Si ha seleccionado Push, puede introducir una lista de permitidos para los eventos push en el campo Filtro de rama.

   El campo Filtro de rama usa el patrón glob y solo las operaciones en las ramas coincidentes activarán una compilación. Si el campo está vacío o es *, se registran los eventos push de todas las ramas.

9. Haz clic en Añadir webhook.

10. El webhook se muestra en la página Webhooks (Webhooks).

    Nota: Cuando añadas o edites un webhook, la longitud de Sensitive Query String podría no coincidir con la que has introducido. Esto es normal, ya que se usan cadenas de marcador de posición para garantizar la seguridad.

Probar el webhook

1. En la página Webhooks (Webhooks) de Secure Source Manager, haga clic en el webhook que quiera probar.

2. Ve a la parte inferior de la página y haz clic en Probar publicación.

   Se añade un evento falso a la cola de entrega. Puede tardar unos segundos en aparecer en el historial de envíos.

3. También puedes usar un comando git para enviar o combinar una solicitud de extracción para probar el webhook.

4. En el proyecto de Jenkins, consulte la compilación activada por el evento de prueba en Historial de compilaciones.

5. También puedes ver la solicitud y la respuesta de la entrega de prueba en la sección Entregas recientes de la página del webhook de Gestor de Fuentes Seguras después de enviar tu primera entrega de prueba.

Siguientes pasos

• Consulta la documentación de Jenkins.