¶ Publicando uma Aplicação PHP Laravel com GitHub e Painel ICP
Neste tutorial, você vai aprender como conectar um projeto Laravel que está no GitHub ao Painel ICP.
A ideia é simples:
Sempre que você fizer uma alteração no seu projeto e enviar para o GitHub, o ICP poderá buscar essa nova versão automaticamente e publicar no servidor.
Ao final deste guia, toda vez que você enviar alterações para o seu repositório no GitHub, o Painel ICP poderá realizar a atualização da aplicação automaticamente no servidor.
¶
O que você precisa antes de começar
Antes de iniciar, confirme que você já tem:
- Uma conta no GitHub;
- Um projeto Laravel salvo em um repositório GitHub;
- Uma aplicação PHP criada ou que será criada no ICP;
- Acesso de administrador ao repositório.
Essa etapa é importante porque o ICP precisa ter permissão para acessar os arquivos do seu projeto no GitHub.
¶ Baixando o Projeto de Exemplo PHP Laravel
O projeto de exemplo utilizado neste tutorial está disponível publicamente no GitHub e pode ser baixado de duas formas:
Opção 1: Download do arquivo ZIP
1. Acesse o repositório:
https://github.com/integratorhostbr/phplaravel
Clique no botão Code.
3. Clique em Download ZIP.
4. Extraia os arquivos em seu computador.
Opção 2: Clonar utilizando Git
Caso possua o Git instalado, execute:
git clone https://github.com/integratorhostbr/phplaravel.git
¶ Etapa 1: Criando um Token de Acesso no GitHub
O token funciona como uma “senha segura” que permite ao ICP acessar seu repositório.
Esse token será usado pelo ICP para se conectar ao GitHub. Sem ele, o painel não consegue acessar o projeto nem criar o webhook automaticamente.
Acesse o GitHub pelo url a seguir: https://github.com
¶ Abra as configurações da conta
- Clique na sua foto no canto superior direito;
- Entre em Settings;
3. No menu lateral esquerdo, vá até Developer settings;
4. Clique em Fine-grained tokens;
6. Defina um nome para o Token
No campo Token name, informe um nome que facilite a identificação da finalidade deste token no futuro.
7. Selecione o proprietário do recurso
No campo Resource owner, escolha a conta ou organização que é proprietária do repositório que será utilizado pelo ICP.
8. Configure a validade do Token
No campo Expiration, defina por quanto tempo o token permanecerá ativo.
Você pode escolher um período específico ou configurar uma validade maior para evitar interrupções futuras na integração entre o GitHub e o ICP.
Importante: quando o token expirar, o ICP perderá acesso ao repositório até que um novo token seja configurado.
9. Escolha os repositórios que poderão ser acessados
Na seção Repository access, selecione quais repositórios o ICP poderá utilizar.
Para maior segurança, recomenda-se selecionar apenas os repositórios que serão utilizados na integração, evitando conceder acesso desnecessário a outros projetos.
10. Configure as permissões do repositório
Na seção Permissions, clique em Add permissions para definir quais recursos o token poderá acessar.
As permissões determinam quais operações o ICP poderá executar dentro do GitHub
11. Habilite a permissão de Webhooks
Para que o ICP possa criar e gerenciar automaticamente os Webhooks do GitHub, é obrigatório habilitar a permissão:
Repository permissions → Webhooks → Read and Write
Sem essa permissão, o ICP não conseguirá configurar ou atualizar os Webhooks responsáveis por disparar os deploys automáticos após um git push.
12. Gere o Token
Após revisar todas as configurações e permissões, clique em Generate token.
O GitHub exibirá o token apenas uma única vez. Copie-o imediatamente e armazene-o em local seguro, pois não será possível visualizá-lo novamente posteriormente.
13. Copie e guarde o TOKEN em lugar seguro.
¶ Etapa 2: Configurando o GITHUB no PAINEL ICP
Após criar e copiar o token de acesso no GitHub, o próximo passo é cadastrar essa credencial no Painel ICP. Essa configuração permitirá que o ICP acesse seu repositório, realize os deploys automáticos e gerencie os Webhooks necessários para a integração.
- Acesse o menu Configurações
No menu lateral esquerdo do Painel ICP, clique em Configurações.
Nessa área ficam centralizadas todas as configurações globais da plataforma, incluindo integrações com serviços externos.
2. Abra a aba Integrações
Na parte superior da tela, clique na aba Integrações.
Essa seção é responsável por gerenciar as conexões entre o ICP e plataformas de terceiros, como GitHub, permitindo automatizar processos de deploy e atualização de aplicações.
3. Adicione uma nova credencial
Localize a seção GitHub e clique no botão:
+ Adicionar credencial
Uma janela será exibida solicitando os dados da integração.
Nesta etapa, você deverá informar os dados da sua conta GitHub e o token criado anteriormente, permitindo que o ICP estabeleça uma conexão segura com seus repositórios.
Após concluir o cadastro, a credencial ficará disponível para utilização em qualquer aplicação criada no painel, facilitando a configuração de deploys automatizados via GitHub.
4. Defina um nome para a credencial
No campo Nome da Credencial, informe um nome que facilite a identificação desta integração dentro do Painel ICP.
Esse nome será utilizado apenas para organização interna e ajudará a identificar rapidamente qual conta GitHub está vinculada à credencial.
5. Informe o usuário ou organização do GitHub
No campo Usuário GitHub, informe o nome da conta ou organização proprietária do repositório que será utilizado no deploy.
Esse valor deve ser exatamente o mesmo exibido na URL do repositório GitHub.
6. Informe o Token de acesso do GitHub
No campo Token GitHub, cole o Fine-Grained Personal Access Token criado anteriormente.
Esse token permitirá que o ICP acesse seus repositórios de forma segura, sem a necessidade de informar sua senha do GitHub.
7. Informe o repositório GitHub
No campo Repositório, informe a URL completa do projeto que será utilizado para os deploys automáticos.
O ICP utilizará esse endereço para localizar o código-fonte da aplicação.
8. Teste a conexão
Após preencher todas as informações, clique no botão Testar Conexão.
Nesse momento, o ICP realizará uma série de verificações para garantir que a integração está configurada corretamente.
Serão validados os seguintes itens:
Se o token informado é válido;
Se o usuário ou organização existe no GitHub;
Se o repositório informado pode ser acessado;
Se as permissões necessárias foram concedidas ao token;
Se o ICP possui autorização para criar e gerenciar Webhooks.
Se todas as verificações forem concluídas com sucesso, a integração estará pronta para ser utilizada na criação dos deploys automáticos.
¶ Etapa 3: Configurando o seu aplicativo PHP com LARAVEL usando o Painel ICP
1. Acesse o menu Aplicações → PHP
No menu lateral esquerdo do Painel ICP, localize a seção Aplicações e clique em PHP.
Nessa área são gerenciadas todas as aplicações PHP hospedadas no painel, incluindo projetos Laravel, CodeIgniter, WordPress e aplicações PHP personalizadas.
Aqui você poderá criar novas aplicações, acompanhar deploys, visualizar logs e gerenciar as configurações do ambiente.
2. Inicie a criação da aplicação
Após acessar a área de aplicações PHP, clique no botão Criar, localizado na parte superior da tela.
Esse botão abrirá o assistente de configuração da nova aplicação, onde serão definidos parâmetros como domínio, versão do PHP, origem do código-fonte, integração com GitHub e demais configurações necessárias para a publicação do projeto.
A partir das próximas etapas, você informará todos os dados necessários para que o ICP possa criar o ambiente e realizar os deploys automáticos da aplicação.
4. Selecione a versão do PHP
No campo Versão do PHP, escolha a versão que será utilizada para executar sua aplicação.
Para este exemplo, utilizaremos: PHP 8.5.2
É importante selecionar uma versão compatível com o seu projeto Laravel e com os pacotes instalados via Composer.
5. Informe o domínio principal
No campo Domínio Principal, informe o domínio ou subdomínio onde a aplicação ficará disponível para acesso.
Exemplo:
phplaravel.mkt-icp.integrator.hostApós a conclusão da instalação, os usuários poderão acessar a aplicação utilizando esse endereço.
6. Ative o SSL
Marque a opção: ✅ Ativar SSL
O SSL permite que a aplicação seja acessada através de HTTPS, garantindo criptografia e maior segurança na transmissão dos dados.
Além disso, o uso de HTTPS é recomendado para aplicações Laravel e pode ser necessário para diversas integrações externas.
7. Defina a origem dos arquivos do projeto
No campo Origem dos Arquivos, selecione: GitHub
Com essa opção, o ICP buscará automaticamente o código-fonte diretamente do repositório GitHub configurado anteriormente, eliminando a necessidade de enviar arquivos manualmente para o servidor.
8. Escolha o tipo de projeto PHP
No campo Tipo de Projeto PHP, selecione: Framework (/public)
Essa opção é recomendada para frameworks modernos como Laravel, Symfony e CodeIgniter 4, que utilizam uma pasta pública específica para exposição dos arquivos web.
Ao selecionar essa opção, o ICP ajustará automaticamente a configuração do servidor para direcionar os acessos corretamente.
9. Configure a raiz pública
No campo Raiz Pública, informe:
publicNo Laravel, todos os acessos da aplicação devem passar pela pasta public, onde está localizado o arquivo responsável por inicializar o framework:
public/index.phpEssa configuração garante que apenas os arquivos necessários sejam expostos publicamente, aumentando a segurança da aplicação.
Marque a opção: ✅ Executar Composer antes do deploy
10. Selecione a credencial GitHub
No campo Credencial GitHub, escolha a credencial cadastrada anteriormente.
Exemplo:
projeto-phpEssa credencial contém as informações de autenticação necessárias para que o ICP tenha acesso ao repositório e possa realizar os deploys automáticos.
11. Escolha o repositório
No campo Repositório, selecione o projeto Laravel que será publicado.
Exemplo:
integratorhostbr/phplaravelApós selecionar a credencial, o ICP consultará automaticamente sua conta GitHub e exibirá a lista de repositórios disponíveis para utilização.
12. Defina a branch e a pasta do projeto
No campo Branch, informe qual ramificação do GitHub será utilizada para os deploys.
Normalmente é utilizada uma das seguintes opções:
mainou
masterCaso seu projeto utilize outra branch para produção, informe o nome correspondente.
Se necessário, também é possível informar uma pasta específica dentro do repositório onde o projeto está localizado.
13.Confirme a criação da aplicação
Após revisar todas as configurações, clique em Confirmar.
O ICP iniciará o processo de criação do ambiente, configuração da aplicação e preparação da integração com o GitHub.
Ao final do processo, sua aplicação estará pronta para receber deploys automáticos diretamente do repositório GitHub.
O Painel ICP iniciará o processo de deploy
Ao finalizar acesse o domínio que foi definido no passo 5)
¶ Etapa 4: Configurando o Webhook do GitHub
Após criar a aplicação PHP/Laravel e conectar o repositório GitHub ao Painel ICP, o próximo passo é configurar o Webhook.
O Webhook é o mecanismo responsável por informar ao ICP sempre que uma alteração for enviada para o GitHub. Dessa forma, o painel consegue iniciar automaticamente um novo deploy sem necessidade de intervenção manual.
Na prática, o fluxo funciona da seguinte forma:
Desenvolvedor → Git Push → GitHub → Webhook → ICP → Deploy AutomáticoSempre que um novo commit for enviado para a branch configurada, o GitHub notificará o ICP, que iniciará automaticamente o processo de atualização da aplicação.
1. Acesse a configuração de Webhook
Na listagem de aplicações, localize a aplicação criada anteriormente e clique no ícone Webhook GitHub.
Esse recurso permite criar e gerenciar automaticamente a integração entre o repositório GitHub e o Painel ICP.
2. Ativar Webhook
Ative a opção:
✅ Ativar Webhook
Ao habilitar essa configuração, o ICP passará a aceitar notificações enviadas pelo GitHub.
Sem essa opção ativada, mesmo que o Webhook exista no GitHub, os deploys automáticos não serão executados.
3. Payload URL
Ao habilitar essa configuração, o ICP passará a aceitar notificações enviadas pelo GitHub.
Sem essa opção ativada, mesmo que o Webhook exista no GitHub, os deploys automáticos não serão executados.
4. Content Type
No campo Content Type, utilize o valor:
application/jsonEsse é o formato padrão utilizado pelo GitHub para enviar os dados dos eventos ao ICP.
O formato JSON permite que o painel interprete corretamente informações como:
- Repositório de origem;
- Branch atualizada;
- Autor do commit;
- Data e horário do evento;
- Identificador da nova versão enviada.
5. Criar o Webhook no GitHub
Após revisar as configurações, clique no botão: Criar no GitHub
O ICP utilizará a credencial configurada anteriormente para acessar o GitHub e criar automaticamente o Webhook no repositório selecionado.
Você não precisará acessar o GitHub manualmente para realizar essa configuração.
O Resultado será:
No seu GITHUB e criada a conexão do Webhook automaticamente, pode ser vista em:
¶ Etapa 5: Enviando alterações para o GitHub e acompanhando o Deploy Automático no ICP
Com a aplicação criada, o repositório conectado e o Webhook configurado, chegou o momento de testar todo o fluxo de integração entre o GitHub e o Painel ICP.
Nesta etapa, você enviará uma alteração para o repositório e acompanhará o processo de CI/CD sendo executado automaticamente.
O fluxo ocorrerá da seguinte forma:
Desenvolvimento → Git Push → GitHub → Webhook → ICP → Deploy Automático
- Realize o Push do projeto para o GitHub
Na sua IDE de desenvolvimento (IntelliJ IDEA, VS Code, Eclipse ou outra de sua preferência), faça uma alteração no projeto e envie-a para o GitHub.
O envio pode ser realizado através da interface gráfica da IDE ou utilizando os comandos Git.
Exemplo:
git add .
git commit -m "Atualização da aplicação"
git push origin mainAo executar o comando git push, os arquivos serão enviados para o repositório GitHub configurado anteriormente.
2) O GitHub receberá a atualização
Assim que o Push for concluído com sucesso, o GitHub registrará o novo commit na branch configurada.
Nesse momento, o Webhook criado anteriormente será acionado automaticamente.
O GitHub enviará uma notificação para o Painel ICP informando que existe uma nova versão do projeto disponível para publicação.
3) O ICP iniciará o processo de Deploy
Após receber a notificação do GitHub, o Painel ICP iniciará automaticamente o processo de atualização da aplicação.
Dependendo da configuração escolhida, o ICP poderá executar tarefas como:
- Atualização do código-fonte;
- Download da nova versão do projeto;
- Execução do Composer;
- Atualização das dependências;
- Reinicialização dos serviços necessários;
- Publicação da nova versão da aplicação.
Todo esse processo ocorre automaticamente, sem necessidade de acesso manual ao servidor.
4) Acompanhe o processo pelo Painel ICP
Retorne ao Painel ICP e acesse a aplicação criada.Na área de Deploys ou Histórico de Execuções, será possível acompanhar todas as etapas executadas pelo sistema em tempo real.
Você poderá visualizar informações como:
- Horário de início do deploy;
- Branch utilizada;
- Commit publicado;
- Logs de execução;
- Status da implantação;
- Possíveis erros ou alertas.
Ao final do processo, o status do deploy será exibido como:
✅ Concluído com sucesso
Sua aplicação já estará utilizando a nova versão enviada para o GitHub.
A partir desse momento, sempre que um novo git push for realizado na branch configurada, o ICP executará automaticamente todo o processo de CI/CD, mantendo sua aplicação sempre atualizada com o código mais recente.
Bom uso!