github pages deploy action
v4.7.2
Implante automaticamente seu projeto nas páginas do GitHub com ações do GitHub. Essa ação pode ser configurada para empurrar seu código pronto para produção para qualquer ramo que você desejar, incluindo Páginas GH e Docs . Também pode lidar com implantações de repositório cruzado e trabalha com a GitHub Enterprise também.
A manutenção deste projeto é possível por todos os colaboradores e patrocinadores. Se você deseja patrocinar este projeto e fazer com que seu avatar ou logotipo da empresa apareça abaixo, clique aqui. ?
Você pode incluir a ação em seu fluxo de trabalho para acionar em qualquer evento que as ações do GitHub suportem. Se a filial remota que você deseja implantar já não existir, a ação a criará para você. Seu fluxo de trabalho também precisará incluir a etapa actions/checkout antes que esse fluxo de trabalho seja executado para que a implantação funcione. Se você pretende fazer várias implantações em rápida sucessão, pode ser necessário aproveitar o parâmetro de simultaneidade em seu fluxo de trabalho para evitar sobreposições.
Você pode ver um exemplo disso abaixo.
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. Observação
Você deve configurar seu repositório para implantar a partir da filial em que pressiona. Para fazer isso, vá para as configurações do repositório, clique nas Pages e escolha Deploy from a Branch no suspensão Source . A partir daí, selecione o ramo que você forneceu à ação. Na maioria dos casos, serão gh-pages pois esse é o padrão.
Se você deseja fazê -lo para que o fluxo de trabalho acabe apenas em eventos push para ramificações específicas, você pode modificar a seção on .
on :
push :
branches :
- main Aviso
Se você não fornecer à ação um token de acesso ou uma chave SSH, acesse as configurações de seus repositórios e fornecer Read and Write Permissions para o GITHUB_TOKEN fornecido, caso contrário, você potencialmente encontrará problemas de permissão. Como alternativa, você pode definir o seguinte no seu arquivo de fluxo de trabalho para conceder à ação as permissões necessárias.
permissions :
contents : write A with do fluxo de trabalho deve ser configurada antes que a ação funcione. Você pode adicioná -los na seção with seção encontrada nos exemplos acima. Quaisquer secrets devem ser referenciados usando a sintaxe do suporte e armazenados no menu Settings/Secrets do repositório do GitHub. Você pode aprender mais sobre como definir variáveis de ambiente com ações do GitHub aqui.
As seguintes opções devem ser configuradas para fazer uma implantação.
| Chave | Informações de valor | Tipo | Obrigatório |
|---|---|---|---|
folder | A pasta em seu repositório que você deseja implantar. Se o seu script de construção se compilar em um diretório chamado build você o colocaria aqui. Se você deseja implantar o diretório raiz, pode colocar a . aqui. Você também pode utilizar caminhos de arquivo absolutos, prevendo ~ para o caminho da sua pasta. Observe que quaisquer arquivos/pastas correspondentes .gitignore entradas não serão implantadas. Algumas ferramentas generiam automaticamente um arquivo .gitignore para a saída de construção. | with | Sim |
Por padrão, a ação não precisa de nenhuma configuração de token e usa o token do Github Scoped Repository para fazer a implantação. Se você precisar de mais personalização, poderá modificar o tipo de implantação usando as seguintes opções.
| Chave | Informações de valor | Tipo | Obrigatório |
|---|---|---|---|
token | Esta opção é o padrão do token do repositório do GitHub. No entanto, se você precisar de mais permissões para coisas como implantar para outro repositório, poderá adicionar um token de acesso pessoal (PAT) aqui. Isso deve ser armazenado nos secrets / with o menu como um segredo . Recomendamos o uso de uma conta de serviço com as menores permissões necessárias e recomendamos ao gerar um novo PAT que você seleciona os escopos de menor permissão necessários. Saiba mais sobre como criar e usar segredos criptografados aqui. | with | Não |
ssh-key | Você pode configurar a ação para implantar usando o SSH definindo esta opção para uma chave SSH privada armazenada como um segredo . Ele também pode ser definido como true para usar uma configuração de cliente SSH existente. Para obter informações mais detalhadas sobre como adicionar seu par de chaves ssh público/privado, consulte o uso de uma seção de chave de implantação deste ReadMe. | with | Não |
| Chave | Informações de valor | Tipo | Obrigatório |
|---|---|---|---|
branch | Esta é a filial para a qual você deseja implantar, por exemplo, gh-pages ou docs . Padrões para gh-pages . | with | Não |
git-config-name | Permite personalizar o nome anexado à configuração do Git, que é usada ao pressionar a implantação. Se isso não estiver incluído, ele usará o nome no contexto do GitHub, seguido pelo nome da ação. | with | Não |
git-config-email | Permite personalizar o email anexado à configuração do Git, que é usada ao pressionar a implantação. Se isso não estiver incluído, ele usará o email no contexto do GitHub, seguido por um e -mail genérico de github. Você pode incluir <> para o valor, se desejar omitir completamente esse campo e pressionar os compromissos sem um email. | with | Não |
repository-name | Permite especificar um caminho de repositório diferente, desde que você tenha permissões para pressioná -lo. Isso deve ser formatado assim: JamesIves/github-pages-deploy-action . Você precisará usar um PAT na entrada token para que esta opção de configuração funcione corretamente. | with | Não |
target-folder | Se você quiser empurrar o conteúdo da pasta de implantação em um diretório específico na filial de implantação, poderá especificá -lo aqui. | with | Não |
commit-message | Se você precisar personalizar a mensagem de confirmação para uma integração, poderá fazê -lo. | with | Não |
clean | Você pode usar esta opção para excluir arquivos do seu destino de implantação que não existem mais em sua fonte de implantação. Um caso de uso é se o seu projeto gerar arquivos com hash que variam de compilação para construção. Usar clean não afetará os diretórios .git , .github ou .ssh . Esta opção é ativada por padrão e pode ser eliminada, configurando -a como false . | with | Não |
clean-exclude | Se você precisar usar clean , mas deseja preservar determinados arquivos ou pastas, pode usar esta opção. Isso deve conter cada padrão como uma única linha em uma corda multilina. | with | Não |
dry-run | Na verdade, não empurre para trás, mas use --dry-run em invocações git push . | with | Não |
single-commit | Essa opção pode ser alterada para true se você preferir ter uma única confirmação na filial de implantação em vez de manter o histórico completo. O uso dessa opção também fará com que qualquer histórico existente seja limpo da filial de implantação . | with | Não |
force | Novas implantações de força de força para substituir a versão anterior; Caso contrário, tente refazer novas implantações em quaisquer existentes. Esta opção é ativada por padrão e pode ser eliminada definindo -a como false , o que pode ser útil se houver várias implantações em uma única ramificação. | with | Não |
attempt-limit | Quantas tentativas de rebase de fazer antes de suspender o trabalho. Esta opção é padrão para 3 e pode ser útil para aumentar quando houver várias implantações em uma única ramificação. | with | Não |
silent | Silencia a saída de ação que impede que ele exiba mensagens Git. | with | Não |
tag | Adicione uma tag à confirmação. Funciona apenas quando dry-run não é usada. | with | Não |
Com a ação configurada corretamente, você verá o fluxo de trabalho acionar a implantação nas condições configuradas.
A ação exportará uma variável de ambiente chamada deployment_status que você pode usar no seu fluxo de trabalho para determinar se a implantação foi bem -sucedida ou não. Você pode encontrar uma explicação de cada tipo de status abaixo.
| Status | Descrição |
|---|---|
success | O status success indica que a ação foi capaz de implantar com sucesso a filial. |
failed | O status failed indica que a ação encontrou um erro ao tentar implantar. |
skipped | O status skipped indica que a ação saiu mais cedo, pois não havia nada de novo para implantar. |
Este valor também é definido como uma saída de etapa como deployment-status .
Se você preferir usar uma chave de implantação SSH, em oposição a um token, você deve primeiro gerar uma nova tecla SSH executando o seguinte comando de terminal, substituindo o email por um conectado à sua conta do Github.
ssh-keygen -t rsa -m pem -b 4096 -C " [email protected] " -N " " Depois de gerar o par de chaves, você deve adicionar o conteúdo da chave pública no menu das chaves de implantação do seu repositório. Você pode encontrar essa opção indo para Settings > Deploy Keys , você pode nomear a chave pública o que quiser, mas precisa dar acesso a gravar. Posteriormente, adicione o conteúdo da chave privada ao menu Settings > Secrets como DEPLOY_KEY .
Com isso configurado, você pode definir a parte da ssh-key da ação para sua chave privada armazenada como um segredo.
- 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 }} Como alternativa, se você já configurou o cliente SSH em uma etapa anterior, pode definir a opção ssh-key como true para permitir que ele implante usando um cliente SSH existente. Em vez de ajustar a configuração do cliente, ele simplesmente mudará para o uso dos pontos de extremidade do SSH do Github.
Esta ação é desenvolvida principalmente usando o Ubuntu. Na sua configuração de trabalho de fluxo de trabalho, é recomendável definir a propriedade runs-on como ubuntu-latest .
jobs :
build-and-deploy :
runs-on : ubuntu-latest Se você estiver usando um sistema operacional, como o Windows, poderá alternar isso usando artefatos. Na sua configuração de fluxo de trabalho, você pode utilizar as actions/upload-artifact e actions/download-artifact para mover seu projeto criado em um trabalho do Windows para um trabalho secundário que lidará com a implantação.
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. Se você usar um contêiner no seu fluxo de trabalho, pode ser necessário executar uma etapa adicional para instalar rsync pois essa ação depende dele. Você pode ver um exemplo disso abaixo.
- name : Install rsync
run : |
apt-get update && apt-get install -y rsync
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4 Se você estiver usando um domínio personalizado e precisar de um arquivo CNAME , ou se precisar do uso de um arquivo .nojekyll , poderá confirmar com segurança esses arquivos diretamente na filial de implantação sem que eles sejam substituídos após cada implantação, adicionalmente, poderá incluir esses arquivos na sua pasta de implantação para atualizá -los. Se você precisar adicionar arquivos adicionais à implantação que deve ser ignorada pelas etapas de limpeza de compilação, poderá utilizar a opção 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/*.txtSe você deseja remover esses arquivos, deve entrar na filial de implantação diretamente para removê -los. Isso evita que mudanças acidentais no seu script de implantação criem mudanças de ruptura.
