Formas alternativas de implantar no App Hosting

Na maioria das vezes, recomendamos o uso de lançamentos automáticos ou lançamentos acionados manualmente no console do Firebase. No entanto, talvez você precise de um fluxo de implantação mais personalizado. O 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 o App Hosting sem exigir uma conexão persistente com o GitHub.

Ao implantar da origem, o App Hosting faz upload do código-fonte para um bucket do Google Cloud Storage, executa o comando de build do framework no Cloud Build e implanta os artefatos compilados no Cloud Run e no 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 as pastas listados nele serão excluídos da implantação.

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

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

Como a CLI Firebase e o console do Firebase usam a mesma infraestrutura de back-end para armazenar e criar os 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 ou não implantando em um local específico (região) 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 integração inicial (primeira implantação em um local)

Quando a implantação de origem local é iniciada em um local de projeto pela primeira vez, o App Hosting precisa provisionar um bucket do GCS para armazenar seus arquivos e conceder ao agente de serviço do App Hosting acesso para acessá-los. Como essas são tarefas administrativas para envolvidos no projeto, elas exigem permissões de Proprietário do projeto ou de 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é-requisito 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 acesso de leitura (roles/storage.objectViewer) a App Hosting 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 o bucket é 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 papel forem inicializados para um local (por uma implantação inicial da CLI ou configuração do console), desenvolvedores, editores ou administradores do App Hosting 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 lançamento: permissões padrão do App Hosting (apphosting.builds.create e apphosting.rollouts.create)

Implantar da origem com a CLI Firebase

A CLI do Firebase 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 juntos com um único comando da CLI.

Pré-requisitos

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

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 do App Hosting para seu diretório local e solicita detalhes de configuração:
   • O ID do back-end para implantação
   • A região para implantação, se um novo back-end estiver sendo criado
   • O caminho para o diretório raiz do código do aplicativo
   • Seu ambiente de execução do Node.js preferido. Ao selecionar um ambiente de execução com controle de versão, as atualizações automáticas de imagens de base (ABIU, na sigla em inglês) aplicam automaticamente patches de segurança ao ambiente.
4. O App Hosting salva suas preferências de implantação em firebase.json, criando o arquivo no projeto local, se ele ainda não existir. Depois que a inicialização for concluída, execute firebase deploy para implantar o código-fonte.

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 ZIP)

O console do Firebase fornece 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 um lançamento manual em um back-end atual, incluindo back-ends implantados originalmente usando a CLI Firebase.

Formatos compatíveis

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. Selecione a origem: no assistente de criação de back-end, selecione Fazer upload de um ZIP durante a etapa "Como você quer importar seu app?".
2. Preparação para 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 sejam configurados e faz o upsert do bucket. A interface mostra um ícone de carregamento com mensagens de status dinâmicas: "Ativando API...", "Verificando permissões..." e "Preparando bucket...".
   • Tratamento de erros e proteções: se alguma etapa de preparação falhar (por exemplo, um não proprietário receber um 403 PERMISSION_DENIED devido a permissões insuficientes do IAM), a interface vai 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 botão final "Concluir e implantar" 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 de upload.

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

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

Opção B: criar um lançamento manual

1. Abrir caixa de diálogo: no painel App Hosting, clique em Criar lançamento.
2. Selecionar origem: selecione Fazer upload de um ZIP no seletor da caixa de diálogo. Se o back-end não tiver uma conexão com o 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 API...", "Verificando permissões..." e "Preparando bucket..."). Depois, arraste ou selecione o arquivo usando o uploader, especifique o diretório raiz do app e clique em Implantar para acionar o build e o lançamento.

Implantar com o Terraform

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

Se você não conhece o Terraform, consulte Começar a usar o Terraform e o Firebase. Se você já conhece o Terraform, comece com arquivos de configuração de amostra e outros recursos do App Hosting.

Configurar uma conexão do GitHub para CI/CD

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

Implantar usando ferramentas de IA

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