Conéctate 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, pídele a tu administrador que te otorgue los siguientes roles de IAM:

• Administrador de repositorios de Secure Source Manager (roles/securesourcemanager.repoAdmin) en tu repositorio
• Descriptor de acceso a instancias de Secure Source Manager (roles/securesourcemanager.instanceAccessor) en la instancia de Secure Source Manager

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 Otorga a los usuarios acceso a instancias.

Configura 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 confirmación nueva a un repositorio o cuando se inicia una solicitud de extracción, y, luego, ejecutar automáticamente una compilación cuando lleguen eventos nuevos. También puedes configurar activadores para compilar código a partir de cualquier cambio que se realice en el repositorio de código fuente o solo a partir de los cambios que coincidan con ciertos criterios.

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

1. Instala el complemento de Git, complemento de credenciales SSH y complemento de activador de webhook genérico en tu servidor de Jenkins.

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

3. Para agregar el dominio de la instancia de Secure Source Manager al archivo known_hosts SSH del servidor de Jenkins, ejecuta el siguiente comando:

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

   Aquí:

   • INSTANCE_ID es el nombre de tu instancia de Secure Source Manager.
   • INSTANCE_PROJECT_NUMBER es el número del proyecto de tu instancia de Secure Source Manager. Consulta Identifica proyectos para obtener información sobre dónde encontrar el número de tu proyecto.

   Por ejemplo, el siguiente comando agrega el dominio de instancia para una instancia llamada prod-test-instance con un número de proyecto de 123456789.

   ssh -t [e-mail]
   

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

4. En la página Administrar credenciales de Jenkins, haz lo siguiente:

   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, completa los otros campos según sea necesario.

5. Haz clic en Crear.

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

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

8. En la sección Git , pega la URL SSH del repositorio de Secure Source Manager como la URL del repositorio, ingresa tus ramas de compilación (p.ej., */main) y, luego, selecciona la credencial de clave SSH privada guardada que agregaste anteriormente en la página Administrar credenciales.

9. En la sección Activadores de compilación, selecciona Activador de webhook genérico.

   De manera opcional, puedes agregar un token para que el trabajo solo se active si se proporciona ese token cuando se invoca. Para agregar un token, en la sección Activador de webhook genérico, puedes ingresar un token en el campo Token.

10. En la sección Compilación, proporciona una secuencia de comandos de compilación que te gustaría tener 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.

Configura una cuenta de servicio y otorga los permisos necesarios

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

   Asegúrate de tener el permiso iam.serviceAccounts.actAs en la cuenta de servicio. Este permiso forma parte del rol de 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 la cuenta de servicio. Se abrirá la página Claves SSH de la cuenta de servicio y se mostrará una lista de las claves existentes que agregaste.

4. Haz clic en Agregar clave.

5. En la página Agregar clave SSH, ingresa los siguientes valores para tu clave:

   1. Cuenta de servicio: el correo electrónico de la cuenta de servicio para la cuenta de servicio con la que deseas usar 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 creó la cuenta de servicio.

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

Otorga los permisos del 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 otorgar al agente de servicio de Secure Source Manager el rol de Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) o el permiso iam.serviceAccounts.signJwt.

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

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

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

   Aquí, SERVICE_ACCOUNT es la cuenta de servicio que deseas usar. La cuenta debe tener el formato de un ID de cuenta de servicio numérico o de un correo electrónico, como el siguiente: 123456789876543212345 o [e-mail].

   El resultado incluye cualquier vinculación existente o, si no existe ninguna, el valor etag similar al siguiente:

   {
   "etag": "BwUjHYKJUiQ="
   }
   

   Importante: conserva el valor etag de la respuesta get-iam-policy para asegurarte de no reemplazar los cambios de política de otra persona. Si deseas reemplazar todos los demás cambios, puedes quitar el valor etag.

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

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

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

   Aquí, INSTANCE_PROJECT_NUMBER es el número del proyecto de tu instancia de Secure Source Manager.

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

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

   Reemplaza lo siguiente:

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

Otorga a la cuenta de servicio un rol de repositorio

1. En la interfaz web de Secure Source Manager, navega al repositorio en el que deseas otorgar permisos a la cuenta de servicio.
2. Haz clic en la pestaña Permisos.
3. Haz clic en Agregar usuarios.
4. En el campo Agregar principal, ingresa la dirección de correo electrónico de la cuenta de servicio.
5. En el menú desplegable Rol, selecciona Lector de repositorios de Secure Source Manager.

6. Para asignar a la cuenta de servicio el rol securesourcemanager.instanceAccessor, ejecuta el siguiente comando:

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

   Reemplaza lo siguiente:

   • PROJECT_ID por el ID del proyecto de la instancia de Secure Source Manager.
   • SA_EMAIL por el correo electrónico de la cuenta de servicio.

Configura un webhook

1. En la interfaz web de Secure Source Manager, navega al repositorio para el que deseas crear un webhook.
2. Haz clic en Configuración.
3. Haz clic en Webhooks y, luego, en Agregar webhook.

4. En el campo ID de hook, ingresa un ID para el webhook.

   Nota: Los IDs de hook deben seguir la convención de nomenclatura de recursos. Deben incluir solo letras minúsculas, números o guiones, comenzar con una letra y no se pueden cambiar después de crear el webhook.

5. En el campo URL de destino, ingresa la URL del activador de Jenkins.

6. Si usaste el token opcional cuando configuraste el activador de Jenkins, la URL del activador de Jenkins contendrá ese token al final. Para evitar la filtración del token, quítalo del final de la URL de destino y cópialo en el campo Cadena de consulta sensible.

   Para ubicar tu token en la URL del activador, busca el texto que comienza con token=.

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

   Copia y quita la parte que comienza con el signo de interrogación ?token=jenkins-job1 del campo URL de destino. Luego, quita 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 en, selecciona una de las siguientes opciones:

   • Enviar: Para activar un envío al repositorio.
   • Cambio de estado de la solicitud de extracción: Para activar un cambio en el estado de la solicitud de extracción.

8. Si seleccionaste Enviar, puedes ingresar una lista de entidades permitidas para los eventos de envío en el campo Filtro de ramas.

   El campo Filtro de ramas usa el patrón glob y solo las operaciones en las ramas coincidentes causarán un activador de compilación. Si el campo está vacío o es *, se informan los eventos de envío para todas las ramas.

9. Haz clic en Agregar webhook.

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

    Nota: Cuando agregas o editas un webhook, es posible que la longitud de la Sensitive Query String no sea coherente con la ingresada, lo que se espera, ya que se usan cadenas de marcadores de posición para garantizar la seguridad.

Prueba tu webhook

1. En la página Webhooks de Secure Source Manager, haz clic en el webhook que deseas probar.

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

   Se agrega un evento falso a la cola de entrega. Es posible que tarde unos segundos en aparecer en el historial de entrega.

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

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

5. También puedes ver la Solicitud y la Respuesta a la entrega de prueba en la sección Entregas recientes de la página de webhook de Secure Source Manager después de enviar tu primera entrega de prueba.

¿Qué sigue?

• Explora la documentación de Jenkins.