Implantar Site
Visão Geral
Use esta skill para orientar a implantação de um site já gerado no GitHub Pages. O projeto esperado é um site estático Astro armazenado em um repositório GitHub, com arquivos fonte commitados e a implantação gerenciada pelo GitHub Actions.
Esta skill presume que o site em si já existe. Não redesenhe o site a menos que o usuário peça.
Modelo de Implantação
Use esta configuração para o fluxo de trabalho atual do site pessoal:
- Rastreie o código fonte no Git.
- Ignore pastas geradas ou de dependência, como
node_modules/,dist/,.astro/etmp/. - Compile o site com
npm.cmd run build. - Implante do GitHub Actions para o GitHub Pages.
- Mantenha o desenvolvimento local em
http://localhost:4321/. - Use um caminho
basedo Astro apenas durante as compilações do GitHub Actions para URLs de projeto Pages, comohttps://USERNAME.github.io/REPOSITORY/.
Antes de Implantar
Verifique a prontidão com comandos leves:
git status
npm.cmd run build
Confirme que estes arquivos ou configurações existem:
package.jsonastro.config.mjs.gitignore.github/workflows/deploy.ymlsrc/public/
Para este projeto, astro.config.mjs deve suportar compilações locais e do GitHub Pages, por exemplo:
import { defineConfig } from "astro/config";
const isGithubPagesBuild = process.env.GITHUB_ACTIONS === "true";
export default defineConfig({
site: "https://USERNAME.github.io",
base: isGithubPagesBuild ? "/REPOSITORY" : "/",
});
Use auxiliares de URL em páginas/layouts Astro ao vincular a ativos públicos locais ou páginas internas:
const base = import.meta.env.BASE_URL;
const url = (path: string) => {
const normalizedBase = base.endsWith("/") ? base : `${base}/`;
const normalizedPath = path.replace(/^\/+/, "");
return `${normalizedBase}${normalizedPath}`;
};
Fluxo de Trabalho do GitHub Actions
Use um fluxo de trabalho Pages como este:
name: Deploy to GitHub Pages
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Build with Astro
uses: withastro/action@v6
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v5
Explique as ações de forma simples quando necessário:
actions/checkout@v7: baixa o repositório no executor do GitHub Actions.withastro/action@v6: instala dependências, compila o site Astro e prepara o artefato Pages.actions/deploy-pages@v5: publica o artefato compilado no GitHub Pages.
O sufixo @vN fixa uma versão principal da ação.
Repositório e Etapas de Commit
Oriente o usuário a commitar e enviar alterações prontas para implantação:
git status
git add .
git commit -m "Preparar implantação do site"
git push origin main
Se o Git relatar avisos de fim de linha, como LF will be replaced by CRLF, explique que este é um aviso de normalização de fim de linha do Windows e geralmente não bloqueia a implantação.
Se o Git relatar que nenhuma identidade de usuário foi configurada, configure a identidade do repositório ou global antes de commitar. Se a privacidade for importante, use o e-mail noreply do GitHub do usuário.
Configurações do GitHub Pages
Oriente o usuário no GitHub:
- Abra o repositório no GitHub.
- Vá para
Settings. - Vá para
Pages. - Em
Build and deployment, definaSourcecomoGitHub Actions. - Salve se o GitHub mostrar um botão de salvar.
- Vá para a aba
Actionse abra a execução de implantação mais recente. - Aguarde até que o fluxo de trabalho seja bem-sucedido.
- Abra a URL Pages mostrada pelo GitHub.
Para um site de projeto, a URL esperada é geralmente:
https://USERNAME.github.io/REPOSITORY/
Verificação
Após a implantação, verifique:
- A página inicial carrega.
- Os links de navegação funcionam.
- As imagens carregam.
- Arquivos para download, como o PDF do currículo, abrem corretamente.
- A URL do navegador inclui o caminho do repositório para Pages de projeto.
- Nenhum caminho quebrado como
/REPOSITORYprojects,/REPOSITORYprofile.jpgou/REPOSITORYfile.pdfaparece no HTML gerado.
Se o site implantado estiver quebrado, mas a pré-visualização local funcionar, inspecione o tratamento do caminho base primeiro.
Se o GitHub Actions falhar, inspecione a etapa com falha:
- Falha no checkout: problema de repositório ou permissão.
- Falha na instalação/compilação: problema de dependência, Astro ou código fonte.
- Falha na implantação: problema de fonte/permissão/configuração do GitHub Pages.
Critérios de Conclusão
Considere a tarefa de implantação concluída quando:
- A compilação local passa.
- As alterações no código fonte foram commitadas e enviadas.
- A fonte do GitHub Pages está definida como GitHub Actions.
- A execução de implantação do Actions é bem-sucedida.
- A URL pública do Pages carrega o site corretamente.