github pages deploy action
v4.7.2
Déployez automatiquement votre projet sur les pages GitHub avec des actions GitHub. Cette action peut être configurée pour pousser votre code prêt pour la production dans n'importe quelle branche que vous souhaitez, y compris GH-Pages et DOC . Il peut également gérer les déploiements du référentiel croisé et fonctionne également avec GitHub Enterprise.
La maintenance de ce projet est rendue possible par tous les contributeurs et sponsors. Si vous souhaitez parrainer ce projet et que votre logo Avatar ou votre entreprise apparaisse ci-dessous, cliquez ici. ?
Vous pouvez inclure l'action dans votre flux de travail pour déclencher sur tout événement que les actions GitHub prennent en charge. Si la branche distante que vous souhaitez déployer n'existe pas déjà, l'action le créera pour vous. Votre flux de travail devra également inclure l'étape actions/checkout avant que ce flux de travail ne fonctionne pour que le déploiement fonctionne. Si vous avez l'intention de faire plusieurs déploiements en succession rapide, vous devrez peut-être tirer parti du paramètre de concurrence dans votre flux de travail pour éviter les chevauchements.
Vous pouvez visualiser un exemple de cela ci-dessous.
name : Build and Deploy
on : [push]
permissions :
contents : write
jobs :
build-and-deploy :
concurrency : ci-${{ github.ref }} # Recommended if you intend to make multiple deployments in quick succession.
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build # The folder the action should deploy. Note
Vous devez configurer votre référentiel pour déployer à partir de la branche vers laquelle vous poussez. Pour ce faire, accédez à vos paramètres de référentiel, cliquez sur Pages et choisissez Deploy from a Branch dans la liste déroulante Source . À partir de là, sélectionnez la succursale que vous avez fournie à l'action. Dans la plupart des cas, ce sera gh-pages car c'est la valeur par défaut.
Si vous souhaitez faire en sorte que le flux de travail ne se déclenche que sur les événements push vers des branches spécifiques, vous pouvez modifier la section on .
on :
push :
branches :
- main Avertissement
Si vous ne fournissez pas l'action avec un jeton d'accès ou une touche SSH, vous devez accéder à vos paramètres de référentiels et fournir Read and Write Permissions au GITHUB_TOKEN fourni, sinon vous aurez potentiellement des problèmes d'autorisation. Vous pouvez également définir ce qui suit dans votre fichier de workflow pour accorder l'action aux autorisations dont il a besoin.
permissions :
contents : write La partie with le workflow doit être configurée avant que l'action ne fonctionne. Vous pouvez les ajouter dans la section with les exemples ci-dessus. Tous secrets doivent être référencés à l'aide de la syntaxe du support et stockés dans le menu Settings/Secrets du référentiel GitHub. Vous pouvez en savoir plus sur la définition des variables d'environnement avec les actions GitHub ici.
Les options suivantes doivent être configurées pour effectuer un déploiement.
| Clé | Valeur des informations | Taper | Requis |
|---|---|---|---|
folder | Le dossier de votre référentiel que vous souhaitez déployer. Si votre script de construction se compile dans un répertoire nommé build , vous le mettriez ici. Si vous souhaitez déployer le répertoire racine, vous pouvez placer a . ici. Vous pouvez également utiliser des chemins de fichier absolus en avant-vente ~ vers votre chemin de dossier. Notez que tous les fichiers / dossiers correspondant aux entrées .gitignore ne seront pas déployés. Certains outils générent automatiquement un fichier .gitignore pour la sortie de build. | with | Oui |
Par défaut, l'action n'a besoin d'aucune configuration de jeton et utilise le jeton GitHub coloré du référentiel fourni pour effectuer le déploiement. Si vous avez besoin de plus de personnalisation, vous pouvez modifier le type de déploiement à l'aide des options suivantes.
| Clé | Valeur des informations | Taper | Requis |
|---|---|---|---|
token | Cette option est par défaut au jeton GitHub coloré du référentiel. Cependant, si vous avez besoin de plus d'autorisations pour des choses telles que le déploiement dans un autre référentiel, vous pouvez ajouter un jeton d'accès personnel (PAT) ici. Cela doit être stocké dans les secrets / with menu comme secret . Nous vous recommandons d'utiliser un compte de service avec le moins d'autorisations nécessaires et de recommander lors de la génération d'un nouveau PAT que vous sélectionnez le moins de portée d'autorisation nécessaire. En savoir plus sur la création et l'utilisation de secrets cryptés ici. | with | Non |
ssh-key | Vous pouvez configurer l'action à déployer à l'aide de SSH en définissant cette option sur une clé SSH privée stockée comme secret . Il peut également être défini sur true pour utiliser une configuration client SSH existante. Pour plus d'informations détaillées sur la façon d'ajouter votre paire de clés SSH publique / privée, veuillez vous référer à la section clé Utilisation d'une clé de cette lecture. | with | Non |
| Clé | Valeur des informations | Taper | Requis |
|---|---|---|---|
branch | Il s'agit de la succursale que vous souhaitez déployer, par exemple, gh-pages ou docs . Par défaut est gh-pages . | with | Non |
git-config-name | Vous permet de personnaliser le nom attaché à la configuration GIT qui est utilisée lors de la poussée des engagements de déploiement. Si cela n'est pas inclus, il utilisera le nom dans le contexte GitHub, suivi du nom de l'action. | with | Non |
git-config-email | Vous permet de personnaliser l'e-mail joint à la configuration GIT qui est utilisée lors de la poussée des engagements de déploiement. Si cela n'est pas inclus, il utilisera l'e-mail dans le contexte GitHub, suivi d'un e-mail générique NORIB GHUBUB. Vous pouvez inclure <> pour la valeur si vous souhaitez omettre complètement ce champ et pousser les commits sans e-mail. | with | Non |
repository-name | Vous permet de spécifier un chemin de référentiel différent tant que vous avez des autorisations pour y pousser. Cela devrait être formaté comme cela: JamesIves/github-pages-deploy-action . Vous devrez utiliser un PAT dans l'entrée token pour cette option de configuration pour fonctionner correctement. | with | Non |
target-folder | Si vous souhaitez pousser le contenu du dossier de déploiement dans un répertoire spécifique de la branche de déploiement, vous pouvez le spécifier ici. | with | Non |
commit-message | Si vous devez personnaliser le message de validation pour une intégration, vous pouvez le faire. | with | Non |
clean | Vous pouvez utiliser cette option pour supprimer les fichiers de votre destination de déploiement qui n'existe plus dans votre source de déploiement. Un cas d'utilisation est si votre projet génère des fichiers hachés qui varient d'une construction à l'autre. L'utilisation clean n'affectera pas les répertoires .git , .github ou .ssh . Cette option est activée par défaut et peut être activée en la définissant sur false . | with | Non |
clean-exclude | Si vous devez utiliser clean mais que vous souhaitez préserver certains fichiers ou dossiers, vous pouvez utiliser cette option. Cela doit contenir chaque modèle en tant que ligne unique dans une chaîne multiline. | with | Non |
dry-run | Ne repoussez pas réellement, mais utilisez à la place des invocations git push --dry-run Git. | with | Non |
single-commit | Cette option peut être basée sur true si vous préférez avoir un seul engagement sur la branche de déploiement au lieu de maintenir la pleine histoire. L'utilisation de cette option entraînera également l'essuyage de tout historique existant à partir de la succursale de déploiement . | with | Non |
force | De nouveaux déploiements de force pour écraser la version précédente; Sinon, essayez de réprimander de nouveaux déploiements sur tous les existants. Cette option est activée par défaut et peut être activée en la définissant sur false , ce qui peut être utile s'il existe plusieurs déploiements dans une seule branche. | with | Non |
attempt-limit | Combien de Rebase tente de faire avant de suspendre le travail. Cette option est par défaut à 3 et peut être utile pour augmenter lorsqu'il y a plusieurs déploiements dans une seule branche. | with | Non |
silent | Tituler la sortie d'action l'empêchant de l'affichage des messages GIT. | with | Non |
tag | Ajoutez une balise au commit. Ne fonctionne que lorsque dry-run n'est pas utilisée. | with | Non |
Avec l'action correctement configurée, vous devriez voir le workflow déclencher le déploiement dans les conditions configurées.
L'action exportera une variable d'environnement appelée deployment_status que vous pouvez utiliser dans votre flux de travail pour déterminer si le déploiement a réussi ou non. Vous pouvez trouver une explication de chaque type de statut ci-dessous.
| Statut | Description |
|---|---|
success | L'état success indique que l'action a pu se déployer avec succès dans la succursale. |
failed | L'état failed indique que l'action a rencontré une erreur lors de la tentative de déploiement. |
skipped | Le statut skipped indique que l'action est sortie tôt car il n'y avait rien de nouveau à déployer. |
Cette valeur est également définie sous forme de sortie de pas en tant que deployment-status .
Si vous préférez utiliser une clé SSH Deploy par opposition à un jeton, vous devez d'abord générer une nouvelle clé SSH en exécutant la commande de terminal suivante, en remplaçant l'e-mail par un connecté à votre compte GitHub.
ssh-keygen -t rsa -m pem -b 4096 -C " [email protected] " -N " " Une fois que vous avez généré la paire de clés, vous devez ajouter le contenu de la clé publique dans le menu de déploiement de votre référentiel. Vous pouvez trouver cette option en allant sur Settings > Deploy Keys , vous pouvez nommer la clé publique comme vous voulez, mais vous devez lui donner un accès en écriture. Ensuite, ajoutez le contenu de la touche privée au menu Settings > Secrets en tant que DEPLOY_KEY .
Avec cette configuration, vous pouvez ensuite définir la partie ssh-key de l'action sur votre clé privée stockée en tant que secret.
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : site
ssh-key : ${{ secrets.DEPLOY_KEY }} name : Build and Deploy
on :
push :
branches :
- main
jobs :
deploy :
concurrency : ci-${{ github.ref }}
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build
clean : true
clean-exclude : |
special-file.txt
some/*.txt
ssh-key : ${{ secrets.DEPLOY_KEY }} Alternativement, si vous avez déjà configuré le client SSH dans une étape précédente, vous pouvez définir l'option ssh-key sur true pour lui permettre de déployer à l'aide d'un client SSH existant. Au lieu d'ajuster la configuration du client, il passera simplement à l'utilisation de points de terminaison SSH de GitHub.
Cette action est principalement développée à l'aide d'Ubuntu. Dans votre configuration de travail de workflow, il est recommandé de définir la propriété runs-on sur ubuntu-latest .
jobs :
build-and-deploy :
runs-on : ubuntu-latest Si vous utilisez un système d'exploitation tel que Windows, vous pouvez solution de contournement à l'aide d'artefacts. Dans votre configuration de workflow, vous pouvez utiliser les actions/upload-artifact et actions/download-artifact pour déplacer votre projet construit sur un travail Windows vers un travail secondaire qui gérera le déploiement.
name : Build and Deploy
on : [push]
permissions :
contents : write
jobs :
build :
runs-on : windows-latest # The first job utilizes windows-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Upload Artifacts ? # The project is then uploaded as an artifact named 'site'.
uses : actions/upload-artifact@v1
with :
name : site
path : build
deploy :
concurrency : ci-${{ github.ref }}
needs : [build] # The second job must depend on the first one to complete before running and uses ubuntu-latest instead of windows.
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Download Artifacts ? # The built project is downloaded into the 'site' folder.
uses : actions/download-artifact@v1
with :
name : site
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : ' site ' # The deployment folder should match the name of the artifact. Even though our project builds into the 'build' folder the artifact name of 'site' must be placed here. Si vous utilisez un conteneur dans votre flux de travail, vous devrez peut-être exécuter une étape supplémentaire pour installer rsync car cette action en dépend. Vous pouvez visualiser un exemple de cela ci-dessous.
- name : Install rsync
run : |
apt-get update && apt-get install -y rsync
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4 Si vous utilisez un domaine personnalisé et avez besoin d'un fichier CNAME , ou si vous avez besoin d'utiliser un fichier .nojekyll , vous pouvez engager ces fichiers directement dans la branche de déploiement sans qu'ils soient remplacés après chaque déploiement, en outre, vous pouvez inclure ces fichiers dans votre dossier de déploiement pour les mettre à jour. Si vous devez ajouter des fichiers supplémentaires au déploiement qui doivent être ignorés par les étapes de nettoyage de construction, vous pouvez utiliser l'option clean-exclude .
name : Build and Deploy
permissions :
contents : write
on :
push :
branches :
- main
jobs :
deploy :
concurrency : ci-${{ github.ref }}
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build
clean : true
clean-exclude : |
special-file.txt
some/*.txtSi vous souhaitez supprimer ces fichiers, vous devez accéder directement à la branche de déploiement pour les supprimer. Il s'agit d'empêcher des changements accidentels dans votre script de déploiement de la création de changements de rupture.
