Se connecter à Jenkins

Vous pouvez démarrer des compilations automatiques avec des déclencheurs Jenkins et des webhooks Secure Source Manager.

Rôles requis

Pour obtenir les autorisations nécessaires pour créer des déclencheurs de compilation Jenkins, demandez à votre administrateur de vous accorder les rôles IAM suivants :

• Administrateur de dépôt Secure Source Manager (roles/securesourcemanager.repoAdmin) sur votre dépôt
• Accesseur d'instances Secure Source Manager (roles/securesourcemanager.instanceAccessor) sur l'instance Secure Source Manager

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour en savoir plus sur l'attribution de rôles Secure Source Manager, consultez Contrôle des accès avec IAM et Accorder aux utilisateurs l'accès à une instance.

Configurer un déclencheur de webhook

Jenkins utilise des plug-ins de déclencheur de compilation pour activer l'automatisation CI/CD. Vous pouvez configurer des déclencheurs pour écouter les événements entrants, par exemple lorsqu'un nouveau commit est transféré vers un dépôt ou lorsqu'une demande d'extraction est lancée, puis exécuter automatiquement une compilation lorsque de nouveaux événements arrivent. Vous pouvez également configurer des déclencheurs pour créer du code en cas de modification de votre dépôt source ou uniquement sur les modifications correspondant à certains critères.

Pour configurer un déclencheur de webhook Jenkins générique :

1. Installez les plug-ins Jenkins Git Plugin, SSH Credential Plugin et Generic Webhook Trigger Plugin sur votre serveur Jenkins.

2. Générez une paire de clés SSH valide sur votre serveur Jenkins. Secure Source Manager n'accepte que les clés de type RSA.

3. Ajoutez le domaine de l'instance Secure Source Manager au fichier known_hosts SSH du serveur Jenkins en exécutant la commande suivante :

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

   Où :

   • INSTANCE_ID correspond au nom de votre instance Secure Source Manager.
   • INSTANCE_PROJECT_NUMBER correspond au numéro de projet de votre instance Secure Source Manager. Pour savoir où trouver votre numéro de projet, consultez Identifier des projets.

   Par exemple, la commande suivante ajoute le domaine d'instance pour une instance nommée prod-test-instance avec le numéro de projet 123456789.

   ssh -t [e-mail]
   

   Répondez yes pour ajouter le domaine d'instance à la liste des hôtes connus.

4. Sur la page Manage Credentials (Gérer les identifiants) de Jenkins :

   1. Sélectionnez SSH username with private key (Nom d'utilisateur SSH avec clé privée).
   2. Collez la clé privée SSH de votre serveur Jenkins.
   3. Dans le menu déroulant Kind (Type), remplissez les autres champs selon vos besoins.

5. Cliquez sur Create (Créer).

6. Dans l'interface Web Jenkins, créez une tâche Jenkins.

7. Sur la page de configuration de la tâche Jenkins, dans la section Source Code Management (Gestion du code source), sélectionnez Git.

8. Dans la section Git , collez l'URL SSH du dépôt Secure Source Manager comme URL du dépôt, saisissez vos branches de compilation (par exemple, */main), puis sélectionnez l'identifiant de clé SSH privée enregistré que vous avez ajouté précédemment sur la page Manage Credentials (Gérer les identifiants).

9. Dans la section Build Triggers (Déclencheurs de compilation), sélectionnez Generic Webhook Trigger (Déclencheur de webhook générique).

   Vous pouvez également ajouter un jeton pour que la tâche ne soit déclenchée que si ce jeton est fourni lors de l'appel. Pour ajouter un jeton, dans la section Generic Webhook Trigger (Déclencheur de webhook générique), vous pouvez saisir un jeton dans le champ Token (Jeton).

10. Dans la section Build (Compilation), fournissez un script de compilation que vous souhaitez utiliser pour cette tâche Jenkins. Par exemple, vous pouvez exécuter cat README.md pour afficher le contenu de README.md.

11. Cliquez sur Save (Enregistrer) pour créer la tâche Jenkins.

Configurer un compte de service et accorder les autorisations requises

1. Si vous ne disposez pas encore d'un compte de service que vous souhaitez utiliser, créez-en un.

   Assurez-vous de disposer de l'autorisation iam.serviceAccounts.actAs sur le compte de service. Cette autorisation fait partie du rôle Utilisateur du compte de service (roles/iam.serviceAccountUser).

2. Dans l'interface Web Secure Source Manager, cliquez sur le menu Plus d'options.

3. Cliquez sur Service account SSH keys (Clés SSH du compte de service). La page Service account SSH keys (Clés SSH du compte de service) s'ouvre et affiche la liste des clés existantes que vous avez ajoutées.

4. Cliquez sur Add key (Ajouter une clé).

5. Sur la page Add SSH key (Ajouter une clé SSH), saisissez les valeurs suivantes pour votre clé :

   1. Service account (Compte de service) : adresse e-mail du compte de service avec lequel vous souhaitez utiliser la clé SSH au format SA_NAME@PROJECT_ID.iam.gserviceaccount.com

      Où :

      • SA_NAME correspond au nom du compte de service.
      • PROJECT_ID correspond à l'ID du projet dans lequel le compte de service a été créé.

   2. Clé publique SSH : votre clé SSH publique Jenkins.

Accorder des autorisations à l'agent de service Secure Source Manager

Si le compte de service ne se trouve pas dans le même projet que votre instance Secure Source Manager, vous devez également accorder à l'agent de service Secure Source Manager le rôle Créateur de jetons du compte de service (roles/iam.serviceAccountTokenCreator) ou l'autorisation iam.serviceAccounts.signJwt.

Si votre compte de service se trouve dans le même projet que votre instance Secure Source Manager, passez à Attribuer un rôle de dépôt au compte de service.

1. Exécutez la commande suivante pour obtenir la stratégie IAM existante pour votre compte de service :

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

   Où SERVICE_ACCOUNT correspond au compte de service que vous souhaitez utiliser. Le compte doit être au format d'un ID de compte de service numérique ou d'une adresse e-mail, comme suit : 123456789876543212345 ou [e-mail].

   La sortie inclut toutes les liaisons existantes ou, si aucune n'existe, la valeur etag semblable à la suivante :

   {
   "etag": "BwUjHYKJUiQ="
   }
   

   Important : conservez la valeur etag de la réponse get-iam-policy pour vous assurer de ne pas remplacer les modifications de stratégie d'un autre utilisateur. Si vous souhaitez remplacer toutes les autres modifications, vous pouvez supprimer la valeur etag.

2. Copiez la sortie dans un nouveau fichier nommé policy.json.

3. Pour accorder à l'agent de service Secure Source Manager le rôle Créateur de jetons du compte de service (roles/iam.ServiceAccountTokenCreator), modifiez le fichier policy.json pour ajouter les éléments suivants :

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

   Où INSTANCE_PROJECT_NUMBER correspond au numéro de projet de votre instance Secure Source Manager.

4. Exécutez la commande suivante pour remplacer la stratégie IAM existante pour le compte de service :

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

   Remplacez les éléments suivants :

   • SERVICE_ACCOUNT par l'ID ou l'adresse e-mail du compte de service.
   • POLICY_FILE par l'emplacement et le nom du fichier au format JSON , y compris la nouvelle stratégie.

Attribuer un rôle de dépôt au compte de service

1. Dans l'interface Web Secure Source Manager, accédez au dépôt dans lequel vous souhaitez accorder des autorisations au compte de service.
2. Cliquez sur l'onglet Permissions (Autorisations).
3. Cliquez sur Add Users (Ajouter des utilisateurs).
4. Dans le champ Add principal (Ajouter un compte principal), saisissez l'adresse e-mail du compte de service.
5. Dans le menu déroulant Role (Rôle), sélectionnez Secure Source Manager Repository Reader (Lecteur de dépôt Secure Source Manager).

6. Attribuez le rôle securesourcemanager.instanceAccessor au compte de service en exécutant la commande suivante :

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

   Remplacez les éléments suivants :

   • PROJECT_ID par l'ID du projet d'instance Secure Source Manager.
   • SA_EMAIL par l'adresse e-mail du compte de service.

Configurer un webhook

1. Dans l'interface Web Secure Source Manager, accédez au dépôt pour lequel vous souhaitez créer un webhook.
2. Cliquez sur Settings (Paramètres).
3. Cliquez sur Webhooks, puis sur Add webhook (Ajouter un webhook).

4. Dans le champ Hook ID (ID de hook), saisissez un ID pour le webhook.

   Remarque : Les ID de hook doivent respecter la convention d'attribution de noms des ressources. Ils ne doivent contenir que des lettres minuscules, des chiffres ou des tirets, commencer par une lettre et ne peuvent pas être modifiés après la création du webhook.

5. Dans le champ Target URL (URL cible), saisissez l'URL du déclencheur Jenkins.

6. Si vous avez utilisé le jeton facultatif lors de la configuration de votre déclencheur Jenkins, l'URL du déclencheur Jenkins contiendra ce jeton à la fin. Pour éviter de divulguer le jeton, supprimez-le de la fin de l'URL cible et copiez-le dans le champ Sensitive Query String (Chaîne de requête sensible).

   Pour trouver votre jeton dans l'URL de votre déclencheur, recherchez le texte commençant par token=.

   Par exemple, si votre URL ressemble à ce qui suit : https://jenkins-server.com/generic-webhook-trigger/invoke?token=jenkins-job1

   Copiez et supprimez la partie commençant par le point d'interrogation ?token=jenkins-job1 du champ Target URL (URL cible). Supprimez ensuite le point d'interrogation initial et déplacez la partie restante token=jenkins-job1 vers le champ Sensitive Query String (Chaîne de requête sensible).

7. Dans la section Trigger on (Déclencher sur), sélectionnez l'une des options suivantes :

   • Push : pour déclencher une opération push vers le dépôt.
   • Pull request state changed (État de la demande d'extraction modifié) : pour déclencher une modification de l'état de la demande d'extraction.

8. Si vous avez sélectionné Push, vous pouvez saisir une liste d'autorisation pour les événements push dans le champ Branch filter (Filtre de branche).

   Le champ Branch filter (Filtre de branche) utilise le modèle glob. Seules les opérations sur les branches correspondantes déclenchent une déclencheur de compilation. Si le champ est vide ou contient *, les événements push pour toutes les branches sont signalés.

9. Cliquez sur Add webhook (Ajouter un webhook).

10. Le webhook s'affiche sur la page Webhooks.

    Remarque : Lorsque vous ajoutez ou modifiez un webhook, la longueur de la Sensitive Query String peut être différente de celle que vous avez saisie. Ce comportement est normal, car des chaînes d'espace réservé sont utilisées pour garantir la sécurité.

Tester votre webhook

1. Sur la page Webhooks de Secure Source Manager, cliquez sur le webhook que vous souhaitez tester.

2. En bas de la page, cliquez sur Test delivery (Tester la livraison).

   Un faux événement est ajouté à la file d'attente de livraison. Quelques secondes peuvent être nécessaires avant qu'il ne s'affiche dans l'historique de livraison.

3. Vous pouvez également utiliser une commande git pour envoyer ou fusionner une demande d'extraction afin de tester le webhook.

4. Dans le projet Jenkins, affichez la compilation déclenchée par l'événement de test dans Build History (Historique de compilation).

5. Vous pouvez également afficher la Request (Requête) et la Response (Réponse) à la livraison de test dans la section Recent deliveries (Livraisons récentes) de la page de webhook Secure Source Manager après avoir envoyé votre première livraison de test.

Étape suivante

• Consultez la documentation Jenkins.