Migration depuis Jenkins avec Actions Importer

Mentions légales

Les instructions ci-dessous vous guident tout au long de la configuration de votre environnement pour utiliser Actions Importer afin de migrer des pipelines Jenkins vers Actions.

Un compte Jenkins ou une organisation avec des pipelines et des travaux que vous souhaitez convertir en workflows Actions.
Accès pour créer un jeton d’API personnel Jenkins pour votre compte ou organisation.
Un environnement dans lequel vous pouvez exécuter des conteneurs basés sur Linux et installer les outils nécessaires.
- Docker est installé et en cours d’exécution.
- L’interface CLI est installée.
Remarque
Le conteneur Actions Importer et l’interface CLI n’ont pas besoin d’être installés sur le même serveur que votre plateforme CI.

Il existe certaines limitations lors de la migration de Jenkins vers Actions avec Actions Importer. Par exemple, vous devez migrer manuellement les constructions suivantes :

Outils de génération obligatoires
Pipelines scriptés
Secrets
Exécuteurs auto-hébergés
Plug-ins inconnus

Pour plus d’informations sur les migrations manuelles, consultez « Migration de Jenkins vers Actions ».

Installez l’extension CLI Actions Importer :

Bash

gh extension install /gh-actions-importer

gh extension install /gh-actions-importer

Vérifiez que l’extension est installée :

$ gh actions-importer -h
Options:
  -?, -h, --help  Show help and usage information

Commands:
  update     Update to the latest version of  Actions Importer.
  version    Display the version of  Actions Importer.
  configure  Start an interactive prompt to configure credentials used to authenticate with your CI server(s).
  audit      Plan your CI/CD migration by analyzing your current CI/CD footprint.
  forecast   Forecast  Actions usage from historical pipeline utilization.
  dry-run    Convert a pipeline to a  Actions workflow and output its yaml file.
  migrate    Convert a pipeline to a  Actions workflow and open a pull request with the changes.

La commande CLI configure est utilisée pour définir les informations d’identification et les options requises pour Actions Importer lors de l’utilisation de Jenkins et de .

Créez un personal access token (classic) . Pour plus d’informations, consultez « Gestion de vos jetons d'accès personnels ».
Votre jeton doit avoir l’étendue workflow.
Après avoir créé le jeton, copiez-le et enregistrez-le dans un emplacement sûr en vue d’une utilisation ultérieure.
Créez un jeton d’API Jenkins. Pour plus d’informations, consultez Authentification des clients scriptés dans la documentation Jenkins.
Après avoir créé le jeton, copiez-le et enregistrez-le dans un emplacement sûr en vue d’une utilisation ultérieure.
Dans votre terminal, exécutez la commande CLI Actions Importer configure :
```
gh actions-importer configure
```
La commande configure vous invite à entrer les informations suivantes :
- Pour « Quels fournisseurs CI configurez-vous ? », utilisez les touches de direction pour sélectionner Jenkins, appuyez sur Espace pour le sélectionner, puis appuyez sur Entrée.
- Pour « Personal access token pour », entrez la valeur du personal access token (classic) que vous avez créé, puis appuyez sur Entrée.
- Pour « URL de base de l'instance », appuyer sur Entrée pour accepter la valeur par défaut (https://.com).
- Pour « Personal access token pour Jenkins », entrez la valeur du jeton d’API personnel Jenkins que vous avez créé, puis appuyez sur Entrée.
- Pour « Nom d’utilisateur Jenkins », entrez votre nom d’utilisateur Jenkins, puis appuyez sur Entrée.
- Pour « URL de base de l’instance Jenkins », entrez l’URL de votre instance Jenkins, puis appuyez sur Entrée.
Voici un exemple de la commande configure :
```
$ gh actions-importer configure
✔ Which CI providers are you configuring?: Jenkins
Enter the following values (leave empty to omit):
✔ Personal access token for : ***************
✔ Base url of the  instance: https://.com
✔ Personal access token for Jenkins: ***************
✔ Username of Jenkins user: admin
✔ Base url of the Jenkins instance: https://localhost
Environment variables successfully updated.
```
Dans votre terminal, exécutez la commande CLI Actions Importer update pour vous connecter au Container registry Packages et vérifier que l’image conteneur est mise à jour vers la dernière version :
```
gh actions-importer update
```
La sortie de la commande doit ressembler à la sortie ci-dessous :
```
Updating ghcr.io/actions-importer/cli:latest...
ghcr.io/actions-importer/cli:latest up-to-date
```

Vous pouvez utiliser la commande audit pour obtenir une vue d’ensemble de tous les pipelines d’un serveur Jenkins.

La commande audit effectue les étapes suivantes :

Extrait tous les projets définis dans un serveur Jenkins.
Convertit chaque pipeline en workflow Actions équivalent.
Génère un rapport qui résume la complexité et l’exhaustivité d’une migration avec Actions Importer.

Pour effectuer un audit d’un serveur Jenkins, exécutez la commande suivante dans votre terminal :

gh actions-importer audit jenkins --output-dir tmp/audit

Les fichiers dans le répertoire de sortie spécifié contiennent les résultats de l’audit. Consultez le fichier audit_summary.md pour obtenir un résumé des résultats de l’audit.

Le résumé de l’audit comporte les sections suivantes.

La section « Pipelines » contient des statistiques générales concernant le taux de conversion effectué par Actions Importer.

Vous trouverez ci-dessous quelques termes clés qui peuvent apparaître dans la section « Pipelines » :

Les pipelines réussis sont ceux dont 100 % des constructions de pipeline et des éléments individuels ont été convertis automatiquement en leur équivalent Actions.
Les pipelines partiellement réussis sont ceux dont la totalité des constructions de pipeline ont été converties ; toutefois, certains éléments individuels n’ont pas été convertis automatiquement en leur équivalent Actions.
Les pipelines non pris en charge sont des types de définition qui ne sont pas pris en charge par Actions Importer.
Les pipelines ayant échoué sont ceux qui ont rencontré une erreur irrécupérable lors de la conversion. Cela peut se produire pour l’une des trois raisons suivantes :
- Le pipeline a été mal configuré à l’origine et n’était pas valide.
- Actions Importer a rencontré une erreur interne lors de sa conversion.
- Une réponse réseau infructueuse a rendu le pipeline inaccessible, ce qui est souvent dû à des informations d’identification non valides.

La section « Étapes de génération » contient une vue d’ensemble des étapes de génération individuelles utilisées dans tous les pipelines ainsi que le nombre d’étapes converties automatiquement par Actions Importer.

Vous trouverez ci-dessous quelques termes clés qui peuvent apparaître dans la section « Étapes de génération » :

Une étape de génération connue est une étape qui a été automatiquement convertie en action équivalente.
Une étape de génération inconnue est une étape qui n’a pas été automatiquement convertie en action équivalente.
Une étape de génération non prise en charge est une étape qui est :
- Fondamentalement non prise en charge par Actions.
- Configuré d’une manière incompatible avec Actions.
Une action est une liste des actions qui ont été utilisées dans les workflows convertis. Cela peut être important pour :
- Rassembler la liste des actions à synchroniser avec votre instance, si vous utilisez Enterprise Server.
- Définir une liste d’autorisation au niveau de l’organisation des actions utilisées. Cette liste d’actions est une liste complète d’actions que vos équipes de sécurité ou de conformité peuvent avoir besoin d’examiner.

La section « Tâches manuelles » contient une vue d’ensemble des tâches que Actions Importer ne peut pas accomplir automatiquement et que vous devez effectuer manuellement.

Vous trouverez ci-dessous quelques termes clés qui peuvent apparaître dans la section « Tâches manuelles » :

Un secret est un secret au niveau de l’organisation ou du dépôt qui est utilisé dans les pipelines convertis. Ces secrets doivent être créés manuellement dans Actions pour que ces pipelines fonctionnent correctement. Pour plus d’informations, consultez « Utilisation de secrets dans Actions ».
Un exécuteur auto-hébergé fait référence à une étiquette d’un exécuteur référencé dans un pipeline converti qui n’est pas un exécuteur hébergé par . Vous devez définir manuellement ces exécuteurs pour que ces pipelines fonctionnent correctement.

La dernière section du rapport d’audit fournit un manifeste de tous les fichiers qui ont été écrits sur le disque pendant l’audit.

À chaque fichier de pipeline correspond une série de fichiers inclus dans l’audit, notamment :

Le pipeline d’origine tel qu’il a été défini dans .
Toutes les réponses réseau utilisées pour convertir le pipeline.
Le fichier de workflow converti.
Les traces de pile qui peuvent être utilisées pour résoudre les problèmes liés à une conversion de pipeline ayant échoué.

De plus, le fichier workflow_usage.csv contient une liste séparée par des virgules de l’ensemble des actions, secrets et exécuteurs qui sont utilisés par chaque pipeline converti avec succès. Cela peut être utile pour déterminer quels workflows utilisent quelles actions, quels secrets ou quels exécuteurs, et pour effectuer des révisions de sécurité.

Vous pouvez utiliser la commande forecast pour prévoir l’utilisation potentielle de Actions en calculant des métriques à partir des exécutions de pipeline terminées sur votre serveur Jenkins.

Pour exécuter la commande forecast sur une instance Jenkins, vous devez installer le plug-in paginated-builds sur votre serveur Jenkins. Ce plug-in permet à Actions Importer de récupérer efficacement les données de génération historiques pour les travaux qui ont un grand nombre de builds. Étant donné que Jenkins ne fournit pas de méthode pour récupérer des données de génération paginées, l’utilisation de ce plug-in empêche les délais d’expiration du serveur Jenkins qui peuvent se produire lors de l’extraction d’une grande quantité de données historiques. Le plug-in paginated-builds est open source et expose un point de terminaison d’API REST pour extraire les données de génération dans les pages, plutôt que tout à la fois.

Pour installer le plug-in paginated-builds :

Sur votre instance Jenkins, accédez à https://<your-jenkins-instance>/pluginManager/available.
Recherchez le plug-in paginated-builds.
Cochez la case à gauche et sélectionnez Installer sans redémarrage.

Pour effectuer une prévision des Actions potentielles, exécutez la commande suivante dans votre terminal. Par défaut, Actions Importer inclut les sept jours précédents dans le rapport de prévision.

gh actions-importer forecast jenkins --output-dir tmp/forecast

Le fichier forecast_report.md dans le répertoire de sortie spécifié contient les résultats de la prévision.

Voici quelques termes clés qui peuvent apparaître dans le rapport de prévision :

Le nombre de travaux correspond au nombre total de travaux terminés.
Le nombre de pipelines correspond au nombre de pipelines uniques utilisés.
Le temps d’exécution décrit le temps passé par un exécuteur sur un travail. Cette métrique peut être utilisée pour planifier le coût des exécuteurs hébergés par .
- Cette métrique est corrélée au montant que vous devez vous attendre à dépenser dans Actions. Cela varie en fonction du matériel utilisé pendant ces minutes. Vous pouvez utiliser la calculatrice de prix Actions pour estimer les coûts.
Les métriques de temps de file d’attente décrivent le temps passé par un travail à attendre qu’un exécuteur soit disponible pour l’exécuter.
Les métriques de travaux simultanés décrivent le nombre de travaux en cours d’exécution à un moment donné. Cette métrique peut être utilisée pour définir le nombre d’exécuteurs que vous devez configurer.

En outre, ces métriques sont définies pour chaque file d’attente d’exécuteurs dans Jenkins. Cela est particulièrement utile s’il existe une combinaison d’exécuteurs hébergés ou auto-hébergés ou de machines à spécifications élevées ou faibles, afin que vous puissiez voir des métriques spécifiques à différents types d’exécuteurs.

Vous pouvez utiliser la commande dry-run pour convertir un pipeline Jenkins en workflow Actions équivalent.

Vous pouvez utiliser la commande dry-run pour convertir un pipeline Jenkins en workflow Actions équivalent. Un test crée les fichiers de sortie dans un répertoire spécifié, mais n’ouvre pas de demande de tirage (pull request) pour migrer le pipeline.

Pour effectuer un test de migration de vos pipelines Jenkins vers Actions, exécutez la commande suivante dans votre terminal, en remplaçant my-jenkins-project par l’URL de votre travail Jenkins.

gh actions-importer dry-run jenkins --source-url my-jenkins-project --output-dir tmp/dry-run

Vous pouvez afficher les journaux de l’exécution test et les fichiers de workflow convertis dans le répertoire de sortie spécifié.

Pour tout ce que Actions Importer n’a pas pu convertir automatiquement, comme des étapes de génération inconnues ou un pipeline partiellement réussi, vous pouvez créer des transformateurs personnalisés pour personnaliser davantage le processus de conversion. Pour plus d’informations, consultez « Extension Actions Importer avec des transformateurs personnalisés ».

Vous pouvez utiliser la commande migrate pour convertir un pipeline Jenkins et ouvrir une demande de tirage avec le workflow Actions équivalent.

Pour migrer un pipeline Jenkins vers Actions, exécutez la commande suivante dans votre terminal, en remplaçant la valeur target-url par l'URL de votre dépôt , et my-jenkins-project par l'URL de votre job Jenkins.

gh actions-importer migrate jenkins --target-url https://.com/:owner/:repo --output-dir tmp/migrate --source-url my-jenkins-project

La sortie de la commande inclut l’URL de la demande de tirage qui ajoute le workflow converti à votre dépôt. Voici un exemple de sortie réussie :

$ gh actions-importer migrate jenkins --target-url https://.com/octo-org/octo-repo --output-dir tmp/migrate --source-url http://localhost:8080/job/monas_dev_work/job/monas_freestyle
[2022-08-20 22:08:20] Logs: 'tmp/migrate/log/actions-importer-20220916-014033.log'
[2022-08-20 22:08:20] Pull request: 'https://.com/octo-org/octo-repo/pull/1'

La sortie d’une exécution réussie de la commande migrate contient un lien vers la nouvelle demande de tirage qui ajoute le workflow converti à votre dépôt.

Voici quelques éléments importants de la demande de tirage :

Dans la description de la demande de tirage, une section appelée Étapes manuelles, qui liste les étapes que vous devez effectuer manuellement avant de pouvoir terminer la migration de vos pipelines vers Actions. Par exemple, cette section peut vous indiquer de créer des secrets utilisés dans vos workflows.
Fichier de workflows converti. Sélectionnez l’onglet Fichiers changés dans la demande de tirage pour afficher le fichier de flux de travail à ajouter à votre référentiel .

Une fois que vous avez terminé d’inspecter la demande de tirage, vous pouvez la fusionner pour ajouter le flux de travail à votre référentiel .

Cette section contient des informations de référence sur les variables d’environnement, les arguments facultatifs et la syntaxe prise en charge lors de l’utilisation de Actions Importer pour effectuer une migration à partir de Jenkins.

Actions Importer utilise des variables d’environnement pour sa configuration d’authentification. Ces variables sont définies lors du processus de configuration au moyen de la commande configure. Pour plus d’informations, consultez la section Configuration des informations d’identification.

Actions Importer utilise les variables d’environnement suivantes pour se connecter à votre instance Jenkins :

_ACCESS_TOKEN : personal access token (classic) utilisé pour créer des demandes de tirage avec un workflow converti (nécessite les étendues repo et workflow).
_INSTANCE_URL : URL de l’instance cible (par exemple, https://.com).
JENKINS_ACCESS_TOKEN : jeton d’API Jenkins utilisé pour afficher les ressources Jenkins.
Remarque
Ce jeton nécessite l'accès à tous les travaux que vous souhaitez migrer ou auditer. Dans les cas où un dossier ou un travail n’hérite pas des listes de contrôle d’accès de leur parent, vous devez accorder des autorisations explicites ou des privilèges d’administrateur complets.
JENKINS_USERNAME : nom d’utilisateur du compte d’utilisateur qui a créé le jeton d’API Jenkins.
JENKINS_INSTANCE_URL : URL de l’instance Jenkins.
JENKINSFILE_ACCESS_TOKEN (facultatif) Jeton d’API utilisé pour récupérer le contenu d’un Jenkinsfile stocké dans le dépôt de builds. Nécessite l’étendue repo. S’il n’est pas fourni, _ACCESS_TOKEN est utilisé à la place.

Ces variables d’environnement peuvent être spécifiées dans un fichier .env.local chargé par Actions Importer lors de son exécution.

Vous pouvez utiliser des arguments facultatifs avec les sous-commandes Actions Importer pour personnaliser votre migration.

Vous pouvez utiliser l’argument --source-file-path avec les sous-commandes forecast, dry-run ou migration.

Par défaut, Actions Importer récupère le contenu du pipeline à partir du contrôle de code source. L’argument --source-file-path indique à Actions Importer d’utiliser le chemin du fichier source spécifié à la place. Vous pouvez utiliser cette option pour les pipelines Jenkinsfile et multibranch.

Si vous souhaitez fournir plusieurs fichiers sources lors de l’exécution de la sous-commande forecast, vous pouvez utiliser la correspondance de modèle dans la valeur du chemin de fichier. Par exemple, gh forecast --source-file-path ./tmp/previous_forecast/jobs/*.json fournit à Actions Importer tous les fichiers sources qui correspondent au chemin de fichier ./tmp/previous_forecast/jobs/*.json.

Dans cet exemple, Actions Importer utilise le fichier Jenkins spécifié comme fichier source pour effectuer un test.

gh actions-importer dry-run jenkins --output-dir path/to/output/ --source-file-path path/to/Jenkinsfile --source-url :url_to_jenkins_job

Vous pouvez utiliser l’argument --config-file-path avec les sous-commandes audit, dry-run et migrate.

Par défaut, Actions Importer récupère le contenu du pipeline à partir du contrôle de code source. L’argument --config-file-path indique à Actions Importer d’utiliser les fichiers sources spécifiés à la place.

Quand vous utilisez l’option --config-file-path avec les sous-commandes dry-run ou migrate, Actions Importer met en correspondance le slug du dépôt avec le travail représenté par l’option --source-url pour sélectionner le pipeline. Il utilise config-file-path pour extraire le fichier source spécifié.

Dans cet exemple, Actions Importer utilise le fichier de configuration YAML spécifié pour effectuer un audit.

gh actions-importer audit jenkins --output-dir path/to/output/ --config-file-path path/to/jenkins/config.yml

Pour auditer une instance Jenkins avec un fichier config, celui-ci doit être au format suivant et chaque valeur repository_slug doit être unique :

source_files:
  - repository_slug: pipeline-name
    path: path/to/Jenkinsfile
  - repository_slug: multi-branch-pipeline-name
    branches:
      - branch: main
        path: path/to/Jenkinsfile
      - branch: node
        path: path/to/Jenkinsfile

Les tableaux suivants montrent le type de propriétés que Actions Importer est en mesure de convertir actuellement. Pour plus d’informations sur l’alignement de la syntaxe des pipelines Jenkins sur Actions, consultez « Migration de Jenkins vers Actions ».

Pour plus d’informations sur les plug-ins Jenkins pris en charge, consultez le dépôt /gh-actions-importer.

Jenkins	Actions	Statut
modèle docker	`jobs.<job_id>.container`	Prise en charge
build	`jobs`	Partiellement pris en charge
environnement d'une build	`env`	Partiellement pris en charge
déclencheurs de build	`on`	Partiellement pris en charge
général	`runners`	Partiellement pris en charge

Jenkins	Actions	Statut
docker	`jobs.<job_id>.container`	Pris en charge
phase	`jobs.<job_id>`	Pris en charge
agent	`runners`	Partiellement pris en charge
Environnement	`env`	Partiellement pris en charge
stages	`jobs`	Partiellement pris en charge
steps	`jobs.<job_id>.steps`	Partiellement pris en charge
Déclencheurs	`on`	Partiellement pris en charge
when	`jobs.<job_id>.if`	Partiellement pris en charge
inputs	`inputs`	Non pris en charge
matrice	`jobs.<job_id>.strategy.matrix`	Non pris en charge
options	`jobs.<job_id>.strategy`	Non pris en charge
parameters	`inputs`	Non pris en charge

Actions Importer utilise le mappage dans le tableau ci-dessous pour convertir les variables d’environnement Jenkins par défaut en l’équivalent le plus proche dans Actions.

Jenkins	Actions
`${BUILD_ID}`	`${{ .run_id }}`
`${BUILD_NUMBER}`	`${{ .run_id }}`
`${BUILD_TAG}`	`${{ .workflow }}-${{ .run_id }}`
`${BUILD_URL}`	`${{ .server_url }}/${{ .repository }}/actions/runs/${{ .run_id }}`
`${JENKINS_URL}`	`${{ .server_url }}`
`${JOB_NAME}`	`${{ .workflow }}`
`${WORKSPACE}`	`${{ .workspace }}`

Certaines parties ont été adaptées à partir de https://.com//gh-actions-importer/ sous la licence MIT :

MIT License

Copyright (c) 2022 

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Migration depuis Jenkins avec Actions Importer

Dans cet article