Création de règles de protection de déploiement personnalisées

Utilisez GitHub Apps pour automatiser la protection des déploiements avec des systèmes tiers.

Qui peut utiliser cette fonctionnalité ?

Des règles de protection de déploiement personnalisées sont disponibles dans les dépôts publics pour tous les plans. Pour accéder à des règles de protection de déploiement personnalisées dans des dépôts privés ou internes, vous devez utiliser GitHub Enterprise. Pour plus d’informations, consultez « Plans de GitHub ».

Dans cet article

Remarque : Les règles de protection de déploiement personnalisées sont actuellement en version bêta publique et sont susceptibles d’être modifiées.

À propos des règles de protection de déploiement personnalisées

Vous pouvez activer vos propres règles de protection personnalisées pour contrôler les déploiements avec des services tiers. Par exemple, vous pouvez utiliser des services comme Datadog, Honeycomb et ServiceNow pour fournir des approbations automatisées pour les déploiements sur GitHub.com.

Les règles de protection de déploiement personnalisées sont alimentées par GitHub Apps et s’exécutent en fonction des webhooks et des rappels. L’approbation ou le rejet d’un travail de workflow est basé sur la consommation du webhook deployment_protection_rule. Pour plus d’informations, consultez « Événements et charges utiles du webhook » et « Approbation ou rejet de déploiements ».

Une fois que vous avez créé une règle de protection de déploiement personnalisée et que vous l’avez installée sur votre dépôt, la règle de protection de déploiement personnalisée est automatiquement disponible pour tous les environnements du dépôt.

Utilisation de règles de protection de déploiement personnalisées pour approuver ou rejeter des déploiements

Les déploiements dans un environnement peuvent être approuvés ou rejetés en fonction des conditions définies dans n’importe quel service externe, comme un ticket approuvé dans un système ITSM (gestion des services informatiques), un résultat d’analyse des vulnérabilités sur les dépendances ou des métriques d’intégrité stables d’une ressource cloud. La décision d’approuver ou de rejeter les déploiements est à la discrétion de l’application tierce d’intégration et des conditions que vous définissez dans celles-ci. Voici quelques cas d’usage pour lesquels vous pouvez créer une règle de protection de déploiement.

  • Opérations de sécurité et ITSM : vous pouvez vérifier la préparation du service en validant les processus de qualité, de sécurité et de conformité qui s’assurent de la préparation au déploiement.
  • Systèmes d’observabilité : vous pouvez consulter les systèmes de supervision ou d’observabilité (systèmes de gestion des performances des ressources et agrégateurs de journalisation, systèmes de vérification de l’intégrité des ressources cloud, etc.) pour vérifier la sécurité et la préparation au déploiement.
  • Outils de qualité du code et de test : vous pouvez vérifier les tests automatisés sur les builds CI qui doivent être déployées dans un environnement.

Vous pouvez également écrire vos propres règles de protection pour l’un des cas d’usage ci-dessus ou définir une logique personnalisée pour approuver ou rejeter en toute sécurité les déploiements de préproduction dans les environnements de production.

Création d’une règle de protection de déploiement personnalisée avec GitHub Apps

  1. Créez une GitHub App. Pour plus d’informations, consultez « Inscription d’une application GitHub ». Configurez l’GitHub App comme suit.

    1. Si vous le souhaitez, dans le champ de texte URL de rappel, sous « Identification et autorisation des utilisateurs », entrez l’URL de rappel. Pour plus d’informations, consultez « À propos de l’URL de rappel d’autorisation utilisateur ».
    2. Sous « Autorisations », sélectionnez Autorisations du dépôt.
    3. À droite d’« Actions », cliquez sur le menu déroulant et sélectionnez Accès : lecture seule. Capture d’écran de la section « Autorisations du référentiel » lors de la création d’une nouvelle application GitHub. Le bouton permettant de configurer les autorisations, avec l’autorisation « Lecture seule » sélectionnée pour Actions, est mis en évidence par un rectangle orange foncé.
    4. À droite de « Déploiements », cliquez sur le menu déroulant et sélectionnez Accès : Lecture et écriture. Capture d’écran des paramètres d’autorisation « Déploiements » dans la section « Autorisations du référentiels » lors de la création d’une nouvelle application GitHub. Le bouton permettant de configurer les autorisations, avec l’autorisation « Lecture seule » sélectionnée pour Déploiements, est mis en évidence par un rectangle orange foncé.
    5. Sous « S’abonner aux événements », sélectionnez Règle de protection du déploiement. Capture d’écran de la section « S’abonner aux événements » lors de la création d’une nouvelle application GitHub. La case à cocher pour s’abonner à l’événement de règle de protection du déploiement est mise en évidence par un rectangle orange foncé.

  2. Installez la règle de protection de déploiement personnalisée dans vos dépôts et activez-la pour l’utiliser. Pour plus d’informations, consultez « Configuration de règles de protection de déploiement personnalisées ».

Approbation ou rejet de déploiements

Une fois qu’un workflow atteint un travail qui référence un environnement sur lequel la règle de protection de déploiement personnalisée est activée, GitHub envoie une requête POST à une URL que vous configurez contenant la charge utile deployment_protection_rule. Vous pouvez écrire votre règle de protection du déploiement pour envoyer automatiquement des requêtes d’API REST qui approuvent ou rejettent le déploiement en fonction de la charge utile deployment_protection_rule. Configurez vos requêtes d’API REST comme suit.

  1. Validez la requête POST entrante. Pour plus d’informations, consultez « Validation des livraisons de webhook ».

  2. Utilisez un jeton web JSON pour l’authentification en tant que GitHub App. Pour plus d’informations, consultez « Authentification en tant qu’application GitHub ».

  3. À l’aide de l’ID d’installation de la charge utile deployment_protection_rule du webhook, générez un jeton d’installation. Pour plus d’informations, consultez « À propos de l’authentification avec une application GitHub ».

    curl --request POST \
--url "https://api.github.com/app/installations/INSTALLATION_ID/ACCESS_TOKENS" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer {jwt}" \
--header "Content-Type: application/json" \
--data \
'{ \
   "repository_ids": [321], \
   "permissions": { \
      "deployments": "write" \
   } \
}'

  4. Si vous le souhaitez, pour ajouter un rapport d’état sans effectuer d’autre action sur GitHub.com, envoyez une requête POST à /repos/OWNER/REPO/actions/runs/RUN_ID/deployment_protection_rule. Dans le corps de la requête, omettez le state. Pour plus d’informations, consultez « Points de terminaison d’API REST pour les workflows runs ». Vous pouvez publier un rapport d’état sur le même déploiement jusqu’à 10 fois. Les rapports d’état prennent en charge la mise en forme Markdown et peuvent avoir jusqu’à 1 024 caractères.

  5. Pour approuver ou rejeter une requête, envoyez une requête POST à /repos/OWNER/REPO/actions/runs/RUN_ID/deployment_protection_rule. Dans le corps de la requête, attribuez à la propriété state la valeur approved ou rejected. Pour plus d’informations, consultez « Points de terminaison d’API REST pour les workflows runs ».

  6. Si vous le souhaitez, demandez l’état d’une approbation pour une exécution de workflow en envoyant une requête GET à /repos/OWNER/REPOSITORY_ID/actions/runs/RUN_ID/approvals. Pour plus d’informations, consultez « Points de terminaison d’API REST pour les workflows runs ».

  7. Si vous le souhaitez, passez en revue le déploiement sur GitHub.com. Pour plus d’informations, consultez « Révision des déploiements ».

Publication de règles de protection de déploiement personnalisées dans GitHub Marketplace

Vous pouvez publier votre GitHub App sur la GitHub Marketplace pour permettre aux développeurs de découvrir les règles de protection appropriées et de les installer sur leurs dépôts GitHub. Vous pouvez également parcourir les règles de protection de déploiement personnalisées existantes en fonction de vos besoins. Pour plus d’informations, consultez « À propos de GitHub Marketplace pour les applications » et « Référencer une application dans GitHub Marketplace ».