github pages deploy action
v4.7.2
Implemente automáticamente su proyecto en las páginas de GitHub con acciones de GitHub. Esta acción se puede configurar para empujar su código listo para la producción a cualquier rama que desee, incluidas las páginas y documentos de GH. También puede manejar implementaciones de repositorio cruzado y también funciona con Github Enterprise.
El mantenimiento de este proyecto es posible gracias a todos los contribuyentes y patrocinadores. Si desea patrocinar este proyecto y hacer que su avatar o logotipo de la compañía aparezca a continuación, haga clic aquí. ?
Puede incluir la acción en su flujo de trabajo para activar cualquier evento que las acciones de GitHub admitan. Si la rama remota a la que desea implementar ya no existe, la acción la creará para usted. Su flujo de trabajo también deberá incluir el paso actions/checkout antes de que este flujo de trabajo se ejecute para que la implementación funcione. Si tiene la intención de realizar múltiples implementaciones en rápida sucesión, es posible que deba aprovechar el parámetro de concurrencia en su flujo de trabajo para evitar superposiciones.
Puede ver un ejemplo de esto a continuación.
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. Nota
Debe configurar su repositorio para implementar desde la rama a la que presiona. Para hacer esto, vaya a la configuración de su repositorio, haga clic en Pages y elija Deploy from a Branch desde el menú desplegable Source . Desde allí, seleccione la rama que suministró a la acción. En la mayoría de los casos, estas serán gh-pages ya que esa es el valor predeterminado.
Si desea hacerlo para que el flujo de trabajo solo se desencadene en eventos de empuje a ramas específicas, entonces puede modificar la sección on .
on :
push :
branches :
- main Advertencia
Si no suministra la acción un token de acceso o una clave SSH, debe acceder a la configuración de su repositorios y proporcionar Read and Write Permissions al GITHUB_TOKEN proporcionado, de lo contrario, podría encontrar problemas de permiso. Alternativamente, puede establecer lo siguiente en su archivo de flujo de trabajo para otorgar la acción los permisos que necesita.
permissions :
contents : write La parte with la parte del flujo de trabajo debe configurarse antes de que la acción funcione. Puede agregarlos en la sección with la sección que se encuentra en los ejemplos anteriores. Se debe hacer referencia a cualquier secrets utilizando la sintaxis del soporte y almacenarse en el menú Settings/Secrets del repositorio de GitHub. Puede obtener más información sobre cómo configurar las variables de entorno con acciones de GitHub aquí.
Las siguientes opciones deben configurarse para hacer una implementación.
| Llave | Información de valor | Tipo | Requerido |
|---|---|---|---|
folder | La carpeta en su repositorio que desea implementar. Si su script de compilación se compila en un directorio llamado build , lo pondría aquí. Si desea implementar el directorio raíz, puede colocar a . aquí. También puede utilizar rutas de archivos absolutamente prependiendo ~ en la ruta de su carpeta. Tenga en cuenta que cualquier archivo/carpetas que coincidan .gitignore Las entradas de Gitignore no se implementarán. Algunas herramientas Generar automáticamente un archivo .gitignore para la salida de compilación. | with | Sí |
De manera predeterminada, la acción no necesita ninguna configuración de token y utiliza el token GitHub con alcance de repositorio proporcionado para realizar la implementación. Si necesita más personalización, puede modificar el tipo de implementación utilizando las siguientes opciones.
| Llave | Información de valor | Tipo | Requerido |
|---|---|---|---|
token | Esta opción es predeterminada al token GitHub con alcance del repositorio. Sin embargo, si necesita más permisos para cosas como implementar en otro repositorio, puede agregar un token de acceso personal (PAT) aquí. Esto debe almacenarse en los secrets / with menú como secreto . Recomendamos utilizar una cuenta de servicio con los menos permisos necesarios y recomendarlo al generar una nueva PAT que seleccione el menor permiso necesario. Obtenga más información sobre cómo crear y usar secretos cifrados aquí. | with | No |
ssh-key | Puede configurar la acción para implementar utilizando SSH configurando esta opción en una tecla SSH privada almacenada como un secreto . También se puede configurar en true para usar una configuración de cliente SSH existente. Para obtener información más detallada sobre cómo agregar su par de claves SSH públicas/privadas, consulte la sección Uso de una clave de implementación de este ReadMe. | with | No |
| Llave | Información de valor | Tipo | Requerido |
|---|---|---|---|
branch | Esta es la rama que desea implementar, por ejemplo, gh-pages o docs . El valor predeterminado a gh-pages . | with | No |
git-config-name | Le permite personalizar el nombre que se adjunta a la configuración GIT que se utiliza al presionar las compensaciones de implementación. Si esto no está incluido, usará el nombre en el contexto de GitHub, seguido del nombre de la acción. | with | No |
git-config-email | Le permite personalizar el correo electrónico que se adjunta a la configuración GIT que se utiliza al presionar las confirmaciones de implementación. Si esto no está incluido, usará el correo electrónico en el contexto de GitHub, seguido de un correo electrónico genérico de NorePly GitHub. Puede incluir <> para el valor si desea omitir este campo por completo y presionar las confirmaciones sin un correo electrónico. | with | No |
repository-name | Le permite especificar una ruta de repositorio diferente siempre que tenga permisos para presionarla. Esto debe formatearse así: JamesIves/github-pages-deploy-action . Deberá usar un PAT en la entrada de token para esta opción de configuración para funcionar correctamente. | with | No |
target-folder | Si desea empujar el contenido de la carpeta de implementación en un directorio específico en la rama de implementación, puede especificarlo aquí. | with | No |
commit-message | Si necesita personalizar el mensaje de confirmación para una integración, puede hacerlo. | with | No |
clean | Puede usar esta opción para eliminar archivos de su destino de implementación que ya no existen en su fuente de implementación. Un caso de uso es si su proyecto genera archivos de hash que varían de la compilación hasta la compilación. El uso clean no afectará los directorios .git , .github o .ssh . Esta opción se enciende de forma predeterminada y se puede desactivar al configurarla en false . | with | No |
clean-exclude | Si necesita usar clean pero desea preservar ciertos archivos o carpetas, puede usar esta opción. Esto debe contener cada patrón como una sola línea en una cadena multilínea. | with | No |
dry-run | En realidad, no retroceda, pero use --dry-run en git push Invocations en su lugar. | with | No |
single-commit | Esta opción se puede alternar a true si prefiere tener una sola confirmación en la rama de implementación en lugar de mantener el historial completo. El uso de esta opción también hará que cualquier historial existente se elimine de la rama de implementación . | with | No |
force | New Implements de fuerza de fuerza para sobrescribir la versión anterior; De lo contrario, intente rebotar nuevas implementaciones en cualquiera de las existentes. Esta opción se enciende de forma predeterminada y se puede desactivar al configurarla en false , lo que puede ser útil si hay múltiples implementaciones en una sola rama. | with | No |
attempt-limit | Cuántos intentos de Rebase intentan hacer antes de suspender el trabajo. Esta opción es predeterminada a 3 y puede ser útil para aumentar cuando hay múltiples implementaciones en una sola rama. | with | No |
silent | Silence la salida de acción evitando que muestre mensajes GIT. | with | No |
tag | Agregue una etiqueta a la confirmación. Solo funciona cuando no se usa dry-run . | with | No |
Con la acción configurada correctamente, debe ver que el flujo de trabajo desencadena la implementación en las condiciones configuradas.
La acción exportará una variable de entorno llamada deployment_status que puede usar en su flujo de trabajo para determinar si la implementación fue exitosa o no. Puede encontrar una explicación de cada tipo de estado a continuación.
| Estado | Descripción |
|---|---|
success | El estado success indica que la acción fue capaz de implementar con éxito en la rama. |
failed | El estado failed indica que la acción encontró un error al intentar implementar. |
skipped | El estado skipped indica que la acción salió temprano ya que no había nada nuevo que desplegar. |
Este valor también se establece como una salida de paso como deployment-status .
Si prefiere usar una clave de implementación SSH en lugar de un token, primero debe generar una nueva clave SSH ejecutando el siguiente comando terminal, reemplazando el correo electrónico con uno conectado a su cuenta Github.
ssh-keygen -t rsa -m pem -b 4096 -C " [email protected] " -N " " Una vez que haya generado el par de claves, debe agregar el contenido de la clave pública dentro del menú de llaves de implementación de su repositorio. Puede encontrar esta opción yendo a Settings > Deploy Keys , puede nombrar la clave pública lo que desee, pero debe darle acceso de escritura. Posteriormente, agregue el contenido de la tecla privada a la Settings > Secrets como DEPLOY_KEY .
Con esto configurado, puede establecer la parte ssh-key de la acción en su clave privada almacenada como secreto.
- 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 }} Alternativamente, si ya ha configurado el cliente SSH dentro de un paso anterior, puede establecer la opción ssh-key en true para permitirle implementar utilizando un cliente SSH existente. En lugar de ajustar la configuración del cliente, simplemente cambiará a usar los puntos finales SSH de GitHub.
Esta acción se desarrolla principalmente usando Ubuntu. En su configuración de trabajo de flujo de trabajo, se recomienda establecer la propiedad runs-on en ubuntu-latest .
jobs :
build-and-deploy :
runs-on : ubuntu-latest Si está utilizando un sistema operativo como Windows, puede solucionar esto utilizando artefactos. En la configuración de su flujo de trabajo, puede utilizar las actions/upload-artifact y actions/download-artifact para mover su proyecto construido en un trabajo de Windows a un trabajo secundario que manejará la implementación.
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 usa un contenedor en su flujo de trabajo, es posible que deba ejecutar un paso adicional para instalar rsync , ya que esta acción depende de ello. Puede ver un ejemplo de esto a continuación.
- name : Install rsync
run : |
apt-get update && apt-get install -y rsync
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4 Si está utilizando un dominio personalizado y requiere un archivo CNAME , o si requiere el uso de un archivo .nojekyll , puede confirmar estos archivos directamente en la rama de implementación sin que se anulen después de cada implementación, además, puede incluir estos archivos en su carpeta de implementación para actualizarlos. Si necesita agregar archivos adicionales a la implementación que debe ignorarse con los pasos de limpieza de compilación, puede utilizar la opción 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 desea eliminar estos archivos, debe ingresar directamente a la rama de implementación para eliminarlos. Esto es para evitar cambios accidentales en su script de implementación al crear cambios de ruptura.
