Migration depuis des pipelines Bitbucket avec GitHub Actions Importer

Informations sur la migration depuis des pipelines Bitbucket avec GitHub Actions Importer

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

Prérequis

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 GitHub est installée.
Remarque : Le conteneur GitHub Actions Importer et l’interface CLI n’ont pas besoin d’être installés sur le même serveur que votre plateforme CI.

Limites

Il existe certaines limitations lors de la migration depuis des pipelines Bitbucket vers GitHub Actions avec GitHub Actions Importer.

Les images d’une AWS ECR privée ne sont pas prises en charge.
L’option size des pipelines Bitbucket n’est pas prise en charge. Si des ressources d’exécuteur supplémentaires sont requises dans GitHub Actions, envisagez d’utiliser les exécuteur plus grand. Pour plus d’informations, consultez « Utilisation des exécuteurs plus grands ».
Les mesures détaillant le temps d’attente des tâches ne sont pas prises en charge par la commande forecast.

Les after-scripts Bitbucket sont pris en charge en utilisant le always() GitHub Actions et en cochant également le steps.<step_id>.conclusion de l’étape précédente. Pour plus d’informations, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow ».

L'utilisation de always() avec steps.<step_id>.conclusion est illustrée dans l'exemple suivant.

  - name: After Script 1
    run: |-
      echo "I'm after the script ran!"
      echo "We should be grouped!"
    id: after-script-1
    if: "${{ always() }}"
  - name: After Script 2
    run: |-
      echo "this is really the end"
      echo "goodbye, for now!"
    id: after-script-2
    if: "${{ steps.after-script-1.conclusion == 'success' && always() }}"

Tâches manuelles

Certaines constructions des pipelines Bitbucket doivent être migrées manuellement. Il s’agit notamment des paramètres suivants :

Référentiel sécurisé, espace de travail et variables de déploiement
Clés SSH

Installation de l’extension CLI GitHub Actions Importer

Installez l’extension CLI GitHub Actions Importer :

Bash

gh extension install github/gh-actions-importer

gh extension install github/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 GitHub Actions Importer.
  version    Display the version of GitHub 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 GitHub Actions usage from historical pipeline utilization.
  dry-run    Convert a pipeline to a GitHub Actions workflow and output its yaml file.
  migrate    Convert a pipeline to a GitHub Actions workflow and open a pull request with the changes.

Configuration des informations d’identification

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

Créez un personal access token (classic) GitHub. 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 en lieu sûr en vue de l’utiliser ultérieurement.
Créez un jeton d’accès à l’espace de travail pour les pipelines Bitbucket. Pour plus d’informations, consultez Autorisations du jeton d’accès à l’espace de travail dans la documentation Bitbucket. Votre jeton doit avoir l’étendue read pour les pipelines, les projets et les référentiels.
Dans votre terminal, exécutez la commande CLI GitHub 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 Bitbucket, appuyez sur Espace pour le sélectionner, puis appuyez sur Entrée.
- Pour « Personal access token pour GitHub », entrez la valeur du personal access token (classic) que vous avez créé, puis appuyez sur Entrée.
- Pour « URL de base de l’instance GitHub », appuyez sur Entrée pour accepter la valeur par défaut (https://github.com).
- Pour « Personal access token pour Bitbucket », entrez le jeton d’accès à l’espace de travail que vous avez créé, puis appuyez sur Entrée.
- Pour « URL de base de l’instance Bitbucket », entrez l’URL de votre instance Bitbucket, puis appuyez sur Entrée.
Voici un exemple de la commande configure :
```
$ gh actions-importer configure
✔ Which CI providers are you configuring?: Bitbucket
Enter the following values (leave empty to omit):
✔ Personal access token for GitHub: ***************
✔ Base url of the GitHub instance: https://github.com
✔ Personal access token for Bitbucket: ********************
✔ Base url of the Bitbucket instance: https://bitbucket.example.com
Environment variables successfully updated.
```
Dans votre terminal, exécutez la commande CLI GitHub Actions Importer update pour vous connecter au Container registry GitHub 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 devrait ressembler à la sortie ci-dessous :
```
Updating ghcr.io/actions-importer/cli:latest...
ghcr.io/actions-importer/cli:latest up-to-date
```

Effectuer un audit de l’instance Bitbucket

Vous pouvez utiliser la commande d’audit pour obtenir une vue d’ensemble de tous les pipelines d’une instance Bitbucket.

La commande d’audit effectue les étapes suivantes.

Récupère tous les pipelines d’un espace de travail.
Convertit le pipeline en son workflow GitHub Actions équivalent.
Génère un rapport qui résume la complexité et l’exhaustivité d’une migration avec GitHub Actions Importer.

Exécution de la commande audit

Pour effectuer un audit, exécutez la commande suivante dans votre terminal, en remplaçant :workspace par le nom de l’espace de travail Bitbucket à auditer.

gh actions-importer audit bitbucket --workspace :workspace --output-dir tmp/audit

Si vous le souhaitez, une option --project-key peut être fournie à la commande d’audit pour limiter les résultats seulement aux pipelines associés à un projet.

Dans l’exemple de commande ci-dessous, :project_key doit être remplacé par la clé du projet à auditer. Les clés de projet sont disponibles dans Bitbucket dans la page des projets de l’espace de travail.

gh actions-importer audit bitbucket --workspace :workspace --project-key :project_key --output-dir tmp/audit

Inspection des résultats de l’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.

Pipelines

La section « Pipelines » contient des statistiques générales concernant le taux de conversion effectué par GitHub 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 GitHub 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 GitHub Actions.
Les pipelines non pris en charge sont des types de définition qui ne sont pas pris en charge par GitHub 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.
- GitHub 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.

Étapes de génération

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 GitHub 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 GitHub Actions.
- Configuré d’une manière incompatible avec GitHub 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 GitHub 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.

Tâches manuelles

La section « Tâches manuelles » contient une vue d’ensemble des tâches que GitHub 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 GitHub Actions pour que ces pipelines fonctionnent correctement. Pour plus d’informations, consultez « Utilisation de secrets dans GitHub 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 GitHub. Vous devez définir manuellement ces exécuteurs pour que ces pipelines fonctionnent correctement.

Fichiers

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 GitHub.
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é.

Prévision de l’utilisation

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

Exécution de la commande forecast

Pour effectuer une prévision de l’utilisation potentielle de GitHub Actions, exécutez la commande suivante dans votre terminal, en remplaçant :workspace par le nom de l’espace de travail Bitbucket de la prévision. Par défaut, GitHub Actions Importer inclut les sept jours précédents dans le rapport de prévision.

gh actions-importer forecast bitbucket --workspace :workspace --output-dir tmp/forecast_reports

Prévision d’un projet

Pour limiter la prévision à un projet, vous pouvez utiliser l’option --project-key. Remplacez la valeur pour :project_key par la clé de projet pour le projet à prévoir.

gh actions-importer forecast bitbucket --workspace :workspace --project-key :project_key --output-dir tmp/forecast_reports

Inspection du rapport de prévision

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 GitHub.
- Cette métrique est corrélée au montant que vous devez vous attendre à dépenser dans GitHub Actions. Cela varie en fonction du matériel utilisé pendant ces minutes. Vous pouvez utiliser la calculatrice de prix GitHub Actions pour estimer les coûts.
Les métriques de travaux simultanés décrivent le nombre de travaux en cours d’exécution à un moment donné.

Effectuer un test de migration

Vous pouvez utiliser la commande de test pour convertir un pipeline Bitbucket en workflow(s) GitHub Actions équivalent(s). Une exécution test crée les fichiers de sortie dans un répertoire spécifié, mais n’ouvre pas de demande de tirage pour migrer le pipeline.

Exécution de la commande dry-run

Pour effectuer un test de migration d’un pipeline Bitbucket vers GitHub Actions, exécutez la commande suivante dans votre terminal, en remplaçant :workspace par le nom de l’espace de travail et :repo par le nom du référentiel dans Bitbucket.

gh actions-importer dry-run bitbucket --workspace :workspace --repository :repo --output-dir tmp/dry-run

Inspection des workflows convertis

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 GitHub 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 GitHub Actions Importer avec des transformateurs personnalisés ».

Effectuer une migration en production

Vous pouvez utiliser la commande de migration pour convertir un pipeline Bitbucket et ouvrir une demande de tirage avec le(s) workflow(s) GitHub Actions équivalent(s).

Exécution de la commande migrate

Pour migrer un pipeline Bitbucket vers GitHub Actions, exécutez la commande suivante dans votre terminal, en remplaçant les valeurs suivantes.

Remplacez la valeur target-url par l’URL de votre référentiel GitHub.
Remplacez :repo par le nom du référentiel dans Bitbucket.
Remplacez :workspace par le nom de l’espace de travail.

gh actions-importer migrate bitbucket --workspace :workspace --repository :repo --target-url https://github.com/:owner/:repo --output-dir tmp/dry-run

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 bitbucket --workspace actions-importer --repository custom-trigger --target-url https://github.com/valet-dev-testing/demo-private --output-dir tmp/bitbucket
[2023-07-18 09:56:06] Logs: 'tmp/bitbucket/log/valet-20230718-165606.log'
[2023-07-18 09:56:24] Pull request: 'https://github.com/valet-dev-testing/demo-private/pull/55'

Inspection de la demande de tirage

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 GitHub 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 workflow à ajouter à votre dépôt GitHub.

Une fois que vous avez terminé d’inspecter la demande de tirage, vous pouvez la fusionner pour ajouter le workflow à votre dépôt GitHub.

Référence

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 GitHub Actions Importer pour effectuer une migration à partir des pipelines Bitbucket.

Utilisation de variables d’environnement

GitHub 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 ».

GitHub Actions Importer utilise les variables d’environnement suivantes pour se connecter à votre instance Bitbucket.

GITHUB_ACCESS_TOKEN : Le personal access token (classic) utilisé pour créer des demandes de tirage avec un workflow transformé (nécessite les étendues repo et workflow).
GITHUB_INSTANCE_URL : l’URL de l’instance GitHub cible. (p. ex. https://github.com)
BITBUCKET_ACCESS_TOKEN : le jeton d’accès à l’espace de travail avec étendues de lecture pour le pipeline, le projet et le référentiel.

Ces variables d’environnement peuvent être spécifiées dans un fichier .env.local qui sera chargé par GitHub Actions Importer à l’exécution. L’archive de distribution contient un fichier .env.local.template qui peut être utilisé pour créer ces fichiers.

Arguments facultatifs

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

`--source-file-path`

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

Par défaut, GitHub Actions Importer récupère le contenu du pipeline à partir de l’instance Bitbucket. L’argument --source-file-path indique à GitHub Actions Importer d’utiliser le chemin du fichier source spécifié à la place.

Par exemple :

gh actions-importer dry-run bitbucket --workspace :workspace --repository :repo --output-dir tmp/dry-run --source-file-path path/to/my/pipeline/file.yml

`--config-file-path`

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

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

Exemple Audit

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

gh actions-importer audit bitbucket --workspace :workspace --output-dir tmp/audit --config-file-path "path/to/my/bitbucket/config.yml"

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

source_files:
  - repository_slug: repo_name
    path: path/to/one/source/file.yml
  - repository_slug: another_repo_name
    path: path/to/another/source/file.yml

Syntaxe prise en charge pour les pipelines Bitbucket

Le tableau suivant montre le type de propriétés que GitHub Actions Importer peut actuellement convertir.

Bitbucket	GitHub Actions	État
`after-script`	`jobs.<job_id>.steps[*]`	Prise en charge
`artifacts`	`actions/upload-artifact` & `download-artifact`	Prise en charge
`caches`	`actions/cache`	Prise en charge
`clone`	`actions/checkout`	Prise en charge
`condition`	`job.<job_id>.steps[*].run`	Prise en charge
`deployment`	`jobs.<job_id>.environment`	Prise en charge
`image`	`jobs.<job_id>.container`	Prise en charge
`max-time`	`jobs.<job_id>.steps[*].timeout-minutes`	Pris en charge
`options.docker`	Aucune	Prise en charge
`options.max-time`	`jobs.<job_id>.steps[*].timeout-minutes`	Prise en charge
`parallel`	`jobs.<job_id>`	Prise en charge
`pipelines.branches`	`on.push`	Prise en charge
`pipelines.custom`	`on.workflow_dispatch`	Prise en charge
`pipelines.default`	`on.push`	Prise en charge
`pipelines.pull-requests`	`on.pull_requests`	Prise en charge
`pipelines.tags`	`on.tags`	Prise en charge
`runs-on`	`jobs.<job_id>.runs-on`	Prise en charge
`script`	`job.<job_id>.steps[*].run`	Prise en charge
`services`	`jobs.<job_id>.service`	Prise en charge
`stage`	`jobs.<job_id>`	Prise en charge
`step`	`jobs.<job_id>.steps[*]`	Prise en charge
`trigger`	`on.workflow_dispatch`	Pris en charge
`fail-fast`	Aucune	Non pris en charge
`oidc`	Aucune	Non pris en charge
`options.size`	Aucune	Non pris en charge
`size`	Aucune	Non pris en charge

Correspondances des variables d’environnement

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

Bitbucket	GitHub Actions
`CI`	`true`
`BITBUCKET_BUILD_NUMBER`	`${{ github.run_number }}`
`BITBUCKET_CLONE_DIR`	`${{ github.workspace }}`
`BITBUCKET_COMMIT`	`${{ github.sha }}`
`BITBUCKET_WORKSPACE`	`${{ github.repository_owner }}`
`BITBUCKET_REPO_SLUG`	`${{ github.repository }}`
`BITBUCKET_REPO_UUID`	`${{ github.repository_id }}`
`BITBUCKET_REPO_FULL_NAME`	`${{ github.repository_owner }}`/`${{ github.repository }}`
`BITBUCKET_BRANCH`	`${{ github.ref }}`
`BITBUCKET_TAG`	`${{ github.ref }}`
`BITBUCKET_PR_ID`	`${{ github.event.pull_request.number }}`
`BITBUCKET_PR_DESTINATION_BRANCH`	`${{ github.event.pull_request.base.ref }}`
`BITBUCKET_GIT_HTTP_ORIGIN`	`${{ github.event.repository.clone_url }}`
`BITBUCKET_GIT_SSH_ORIGIN`	`${{ github.event.repository.ssh_url }}`
`BITBUCKET_EXIT_CODE`	`${{ job.status }}`
`BITBUCKET_STEP_UUID`	`${{ job.github_job }}`
`BITBUCKET_PIPELINE_UUID`	`${{ github.workflow }}`
`BITBUCKET_PROJECT_KEY`	`${{ github.repository_owner }}`
`BITBUCKET_PROJECT_UUID`	`${{ github.repository_owner }}`
`BITBUCKET_STEP_TRIGGERER_UUID`	`${{ github.actor_id }}`
`BITBUCKET_SSH_KEY_FILE`	`${{ github.workspace }}/.ssh/id_rsa`
`BITBUCKET_STEP_OIDC_TOKEN`	Aucun mappage
`BITBUCKET_DEPLOYMENT_ENVIRONMENT`	Aucun mappage
`BITBUCKET_DEPLOYMENT_ENVIRONMENT_UUID`	Aucun mappage
`BITBUCKET_BOOKMARK`	Aucun mappage
`BITBUCKET_PARALLEL_STEP`	Aucun mappage
`BITBUCKET_PARALLEL_STEP_COUNT`	Aucun mappage

Variables système

Les variables système utilisées dans les tâches sont transformées en variable d’interpréteur de commandes bash équivalente et sont supposées être disponibles. Par exemple, ${system.<variable.name>} sera transformé en $variable_name. Nous vous recommandons de vérifier cela pour garantir le bon fonctionnement du workflow.

Mentions légales

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

MIT License

Copyright (c) 2022 GitHub

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 des pipelines Bitbucket avec GitHub Actions Importer

Dans cet article