Formas alternativas de implantar no App Hosting

Na maioria das vezes, recomendamos o uso de implementações automáticas ou acionadas manualmente no console do Firebase. No entanto, talvez você precise de um fluxo de implantação mais personalizado. App Hosting tem várias opções de implantação personalizada.

Implantar a partir da origem

A implantação da origem permite enviar o código-fonte e a configuração do aplicativo diretamente para App Hosting sem exigir uma conexão persistente do GitHub.

Ao implantar a partir da origem, App Hosting faz upload do código-fonte para um Google Cloud Storage bucket, executa o comando de build da estrutura no Cloud Build, e implanta os artefatos compilados no Cloud Run e Cloud CDN. O mesmo processo de build é usado para implantações de origem local e do GitHub. Se um arquivo .gitignore estiver presente no projeto, os arquivos e pastas listados nele serão excluídos da implantação.

É possível implantar a partir de uma origem local usando a Firebase CLI ou o Firebase console.

Permissões do IAM e configuração da infraestrutura necessárias

Como a Firebase CLI e o console do Firebase usam a mesma infraestrutura de back-end para armazenar e criar arquivos de origem, os mesmos requisitos de permissão do IAM se aplicam aos dois métodos de implantação.

Os requisitos exatos dependem de você estar implantando ou não em um local (região) específico pela primeira vez. Para mais informações sobre permissões, consulte a visão geral do IAM do Firebase e as permissões específicas do Firebase App Hosting.

Permissões para a integração inicial (primeira implantação em um local)

Quando a implantação de origem local é iniciada em um local do projeto pela primeira vez, Hosting precisa provisionar um bucket do GCS para armazenar seus arquivos e conceder acesso ao agente de serviço do Hosting para acessá-los. Como essas são tarefas administrativas para envolvidos no projeto, elas exigem permissões de Proprietário do projeto ou administrador do IAM. Um usuário com um papel básico de editor ou leitor não pode realizar essa configuração inicial e será bloqueado.

As permissões de configuração de pré-requisitos incluem:

• Ativar a API Storage: serviceusage.services.enable
• Criar bucket de origem: storage.buckets.create e storage.buckets.list
• Configurar o agente de serviço: resourcemanager.projects.setIamPolicy para conceder Hosting acesso de leitura (roles/storage.objectViewer) para que ele possa buscar o código enviado durante os builds.

Para a implantação inicial, o bucket do GCS é criado com um ciclo de vida de 30 dias, após o qual é excluído. No entanto, é possível gerenciar esse período no console do Cloud em Cloud Storage -> Buckets -> Ciclo de vida -> Regras. Consulte gerenciar ciclos de vida de objetos.

Permissões para implantações subsequentes (depois que o local é inicializado)

Depois que o bucket de origem e as vinculações de papéis forem inicializados para um local (por uma implantação inicial da CLI ou configuração do console), desenvolvedores, editores ou App Hosting administradores poderão implantar atualizações. As permissões de administração para envolvidos no projeto não são necessárias para implantações de rotina.

As permissões de implantação ativa incluem:

• Verificar bucket: storage.buckets.list
• Fazer upload do arquivo de origem: storage.objects.create
• Acionar build e implementação: permissões padrão Hosting (apphosting.builds.create e apphosting.rollouts.create)

Implantar a partir da origem com a CLI Firebase

Firebase CLI v14.4.0 e versões mais recentes permite enviar o código-fonte e as configurações do app diretamente da máquina local para o Firebase. Isso é conveniente se você já gerencia outras implantações do Firebase (como regras de segurança ou funções) e quer implantar o app da Web e os serviços de back-end com um único comando da CLI.

Pré-requisitos

• Seus projetos precisam estar no plano Blaze.
• É necessário executar a versão 14.4.0 ou mais recente do firebase-tools.

Etapas da implantação

1. Execute firebase init apphosting no diretório do projeto local.
2. Quando solicitado, selecione Usar um projeto atual e escolha o projeto do Firebase de destino.
3. Selecione um back-end novo ou atual para implantar. Essa etapa configura as implantações de Hosting para o diretório local e solicita detalhes de configuração:
   • O ID do back-end a ser implantado
   • A região a ser implantada, se você estiver criando um novo back-end
   • O caminho para o diretório raiz do código do aplicativo
   • O ambiente de execução do Node.js de sua preferência. A seleção de um ambiente de execução com versão ativará as atualizações automáticas de imagens de base (ABIU) para aplicar patches de segurança automaticamente ao ambiente subjacente.
4. App Hosting salva as preferências de implantação em firebase.json, criando o arquivo no projeto local, se ele ainda não existir. Quando a inicialização for concluída, execute firebase deploy para implantar o código-fonte.

Observação: se você estiver ignorando prompts interativos (por exemplo, em scripts de CI/CD), poderá gerenciar as configurações de ABIU e de ambiente de execução usando a flag de linha de comando --runtime (por exemplo, --runtime nodejs22). Se você tiver implantações de origem local configuradas para vários back-ends (ou seja, há várias entradas backendId em firebase.json), firebase deploy será implantado em cada um desses back-ends. Para implantar em um back-end específico, use firebase deploy --only apphosting:backendId.

Exemplo de firebase.json

{
  "apphosting": [
    {
      "backendId": "my-backend",
      // rootDir specifies the directory containing the app to deploy, but the entire
      // parent directory of firebase.json will be zipped and uploaded to ensure that
      // dependencies outside of the app directory will be available at build time.
      "rootDir": "./my-app",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log",
        "functions"
      ]
    }
  ]
}

Implantar com o console do Firebase (upload de arquivo zip)

O Firebase console oferece uma interface gráfica para implantar aplicativos fazendo upload de um arquivo de origem compactado diretamente. Isso serve como uma alternativa ao fluxo de conexão do GitHub, para casos em que você prefere não usar o GitHub ou prefere uma configuração de CI/CD diferente.

Os uploads de arquivos podem ser realizados durante a criação inicial do back-end ou ao criar uma implementação manual em um back-end atual, incluindo back-ends originalmente implantados usando a Firebase CLI.

Formatos aceitos

O uploader do console valida e aceita nativamente dois formatos de arquivo compactado:

• .zip
• .tgz

Esses formatos são exibidos explicitamente no texto de descrição do uploader de arquivos.

Etapas da implantação

Opção A: durante a integração inicial do back-end

1. Selecionar origem: no assistente de criação de back-end, selecione Fazer upload de um arquivo zip durante a etapa "Como você quer importar seu app?".
2. Preparação da integração: clicar em "Próxima" aciona o fluxo de preparação em segundo plano, que ativa sequencialmente a API Storage, garante que os papéis corretos estejam configurados e insere o bucket. A interface mostra um indicador de carregamento com mensagens de status dinâmicas: "Ativando a API..." "Verificando permissões...", e "Preparando o bucket...".
   • Tratamento de erros e barreiras de proteção: se alguma etapa de preparação falhar (como um usuário que não é proprietário receber um erro 403 PERMISSION_DENIED devido a permissões insuficientes do IAM), a interface mostrará um aviso dedicado instruindo você a entrar em contato com um proprietário do projeto. A navegação do stepper é estritamente bloqueada, e o botão "Próxima" e o "Concluir e implantar" final permanecem desativados até que o problema seja resolvido.
3. Fazer upload de arquivos: quando a preparação for concluída, selecione ou arraste o arquivo para o componente do uploader de arquivos.

4. Configurar configurações: especifique o diretório raiz do app (o padrão é /).

   Observação: o valor inserido especifica o diretório que contém o app a ser implantado. Compacte e faça upload de todo o diretório raiz do projeto (incluindo dependências compartilhadas ou arquivos de configuração fora do diretório do app) para garantir que eles estejam disponíveis no tempo de build.

5. Clique em Concluir e implantar: o botão "Concluir" independente está desativado para uploads de arquivos zip porque o upload de um arquivo é uma ação única e precisa ser seguida imediatamente por uma implantação para garantir um back-end funcional.

Opção B: criar uma implementação manual

1. Abrir caixa de diálogo: no painel Hosting, clique em Criar implementação.
2. Selecionar origem: selecione Fazer upload de um arquivo zip no stepper da caixa de diálogo. Se o back-end não tiver uma conexão do GitHub, a opção "GitHub" será desativada.
3. Preparação e upload: a seleção aciona o mesmo fluxo de preparação em segundo plano ("Ativando a API...", "Verificando permissões..." e "Preparando o bucket..."). Quando a operação for concluída, arraste ou selecione o arquivo usando o uploader, especifique o diretório raiz do app e clique em Implantar para acionar o build e a implementação.

Implantar com o Terraform

Se você precisar de mais controle sobre o processo de build e o ambiente implantado, poderá implantar usando o Terraform. O Terraform permite definir e gerenciar seus App Hosting recursos usando arquivos de configuração declarativos e oferece a capacidade de implantar sua própria imagem de contêiner pré-criada diretamente em App Hosting em vez de depender de App Hosting para criar a partir do seu código fonte.

Se você não conhece o Terraform, consulte Introdução ao Terraform e ao Firebase. Se você já conhece o Terraform, pode começar com arquivos de configuração de amostra e outros App Hosting recursos.

Configurar uma conexão do GitHub para CI/CD

Você tem a opção de conectar um repositório do GitHub a qualquer momento na guia Implantação das configurações de um back-end no console Firebase. Isso permite implantar um protótipo de app em um ambiente local e fazer a transição para um pipeline de CI/CD automatizado quando estiver tudo pronto.

Implantar usando ferramentas de IA

Vamos desativar Firebase Studio em 22 de março de 2027. Embora seus App Hosting back-ends não sejam afetados, o botão Publicar em Firebase Studio será desativado. Para continuar publicando atualizações sem mudar o URL, migre seu projeto. Saiba como migrar.