Conéctate a Jenkins

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

Roles requeridos

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
• Secure Source Manager Instance Accessor (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 Cómo otorgar acceso a la instancia a los usuarios.

Configura un activador de webhook

Jenkins usa complementos de activación 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 tu repositorio de código fuente o solo a partir de los cambios que coincidan con ciertos criterios.

Para configurar un activador de webhook de Jenkins genérico, 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álidas en tu servidor de Jenkins. Secure Source Manager solo admite claves de tipo RSA.

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

   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 de 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 la 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 la instancia a la lista de hosts conocidos.

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

   1. Selecciona SSH username with private key.
   2. Pega la clave privada SSH del servidor de Jenkins.
   3. En el menú desplegable Kind, completa los demás campos según sea necesario.

5. Haz clic en Crear.

6. En la interfaz web de Jenkins, crea un nuevo trabajo 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 de 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 Build Triggers, selecciona Generic Webhook Trigger.

   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 Generic Webhook Trigger, puedes ingresar uno en el campo Token.

10. En la sección Build, 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.

   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 Llaves SSH de cuentas de servicio. Se abrirá la página Claves SSH de la cuenta de servicio, en la que se mostrará una lista de las claves existentes que agregaste.

4. Haga clic en Agregar clave.

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

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

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

Otorga 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 otorgarle 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 Cómo otorgar un rol de repositorio a la cuenta de servicio.

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 numérico de cuenta de servicio o de un correo electrónico, como 123456789876543212345 o [e-mail].

   El resultado incluye las vinculaciones existentes o, si no hay ninguna, el valor etag similar al siguiente:

   {
   "etag": "BwUjHYKJUiQ="
   }
   

   Importante: Conserva el valor de etag de la respuesta de get-iam-policy para asegurarte de no reemplazar los cambios en la política de otra persona. Si deseas anular 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 policy.json para agregar lo siguiente:

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

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

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

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

   Reemplaza lo siguiente:

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

Otorga un rol de repositorio a la cuenta de servicio

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 del repositorio de Secure Source Manager.

6. Asigna a la cuenta de servicio el rol securesourcemanager.instanceAccessor ejecutando 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 Add webhook.

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

   Nota: Los IDs de los hooks deben seguir la convención de nomenclatura de recursos. Solo deben incluir letras en minúscula, números o guiones, deben 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 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 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 Activador, selecciona una de las siguientes opciones:

   • Push: Se activa cuando se envía un cambio al repositorio.
   • Pull request state changed: Se activa cuando cambia el estado de la solicitud de extracción.

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

   El campo Branch filter usa el patrón glob, y solo las operaciones en las ramas que coincidan activarán una compilación. Si el campo está vacío o es *, se informarán los eventos push para todas las ramas.

9. Haz clic en Add webhook (Agregar webhook).

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

    Nota: Cuando agregas o editas un webhook, la longitud de Sensitive Query String puede no coincidir con la que ingresaste, lo que es normal, 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 la entrega.

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

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

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

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

¿Qué sigue?

• Explora la documentación de Jenkins.