Lançou uma nova versão do plugin no GitHub, mas os utilizadores continuam presos à antiga. Descarregar ZIPs manualmente, carregar através do painel de administração, verificar a compatibilidade: tarefas rotineiras que consomem tempo e geram erros.

O mecanismo padrão de atualizações do WordPress está ligado ao diretório oficial WordPress.org. Mas nem todos os plugins lá chegam: soluções personalizadas para clientes, ferramentas internas de equipa, forks de plugins populares com modificações. Estes precisam de um caminho diferente.

Felizmente, a entrega de atualizações diretamente a partir do GitHub foi resolvida há muito tempo. Abaixo estão dois métodos funcionais: simples (o plugin Git Updater, com alguns cliques) e avançado (uma classe PHP integrada para controlo total).

💡 Visão geral rápida:

• Instale o Git Updater: ele deteta os lançamentos do GitHub como atualizações normais do WordPress
• Para repositórios privados, configure um token de acesso nas definições do plugin
• Se está a escrever o seu próprio plugin e pretende incorporar atualizações automáticas no código: use a classe PHP integrada
• O repositório deve conter um cabeçalho de plugin válido e uma tag de versão

Método 1: Git Updater, atualizações em dois cliques

O Git Updater é um plugin gratuito que adiciona suporte para GitHub, Bitbucket, GitLab e Gitea ao ecrã padrão de atualizações do WordPress. Após a instalação, os plugins e temas do GitHub são atualizados no mesmo local que os normais: Painel → Atualizações.

O programador Andy Fragen mantém o projeto desde 2015. A página do Git Updater no GitHub tem mais de 400 estrelas e um repositório ativo com commits regulares. A base de conhecimento em git-updater.com cobre a instalação, configuração de tokens e utilização da API.

A instalação é simples: descarregue o ZIP a partir do lançamento no GitHub, carregue através de Plugins → Adicionar Novo → Carregar Plugin e ative. O plugin começa imediatamente a monitorizar os repositórios especificados nos cabeçalhos dos plugins e temas instalados.

Para repositórios privados, precisará de um token. Crie um Personal Access Token em GitHub Settings → Developer settings → Tokens (permissões: repo para privado; não é necessário token para público) e cole-o em Settings → Git Updater. Depois disso, o plugin consegue ver até repositórios fechados.

Um detalhe importante: o Git Updater procura tags no formato X.Y.Z (versionamento semântico) no repositório. Se não houver tags, a atualização não funcionará. Antes de lançar, defina sempre uma tag: git tag 1.2.0 && git push --tags.

Método 2: classe PHP integrada para programadores

Se é autor de um plugin e pretende incorporar o mecanismo de atualização automática diretamente no seu código (sem um plugin intermediário separado), a abordagem clássica com classe PHP continua a funcionar. É mais leve do que a classe original de Joachim Kudish e radishconcepts e utiliza hooks nativos do WordPress.

Adicione o seguinte código ao ficheiro principal do seu plugin ou a um ficheiro updater.php separado, incluído via require_once:

1
/**
2
 * Auto-update from GitHub releases.
3
 * Place in main plugin file or include via require_once.
4
 */
5
function myplugin_check_github_update($transient) {
6
    if (empty($transient->checked)) {
7
        return $transient;
8
    }
9
 
10
    $plugin_slug = 'my-plugin/my-plugin.php';
11
    $github_repo = 'username/my-plugin';
12
 
13
    $response = wp_remote_get(
14
        'https://api.github.com/repos/' . $github_repo . '/releases/latest',
15
        array(
16
            'headers' => array(
17
                'Accept' => 'application/vnd.github.v3+json',
18
                'User-Agent' => 'WordPress/' . get_bloginfo('version'),
19
            ),
20
        )
21
    );
22
 
23
    if (is_wp_error($response) || wp_remote_retrieve_response_code($response) !== 200) {
24
        return $transient;
25
    }
26
 
27
    $release = json_decode(wp_remote_retrieve_body($response));
28
 
29
    if (!isset($release->tag_name)) {
30
        return $transient;
31
    }
32
 
33
    $latest_version = ltrim($release->tag_name, 'v');
34
    $current_version = $transient->checked[$plugin_slug] ?? '0';
35
 
36
    if (version_compare($latest_version, $current_version, '>')) {
37
        $transient->response[$plugin_slug] = (object) array(
38
            'slug'        => dirname($plugin_slug),
39
            'new_version' => $latest_version,
40
            'url'         => 'https://github.com/' . $github_repo,
41
            'package'     => $release->zipball_url,
42
        );
43
    }
44
 
45
    return $transient;
46
}
47
add_filter('pre_set_site_transient_update_plugins', 'myplugin_check_github_update');

O código faz exatamente três coisas: consulta a API do GitHub para obter o último lançamento, compara a versão de tag_name com a versão atual do plugin e, se o GitHub tiver uma mais recente, regista a atualização no mecanismo padrão do WordPress. A versão do plugin é obtida a partir do cabeçalho padrão Version: X.Y.Z no ficheiro principal.

Nota: para repositórios públicos, não é necessário token, mas a API do GitHub sem token limita a frequência de pedidos a 60 por hora por IP. Para um plugin de produção com muitos utilizadores, adicione cache de resultados via set_transient() por 6 a 12 horas. Desta forma, não atingirá o limite sempre que alguém visitar a página de plugins.

Comparação das abordagens

Conclusão: se está a instalar o plugin de outra pessoa a partir do GitHub num site, use o Git Updater. Se é autor de um plugin e o distribui através do GitHub, incorpore as atualizações automáticas no código para que os utilizadores não tenham de instalar um plugin adicional.

Configurar o repositório para atualizações automáticas

Independentemente do método escolhido, o repositório do GitHub deve estar devidamente preparado. Três pontos obrigatórios:

• Cabeçalho do plugin. No ficheiro PHP principal, inclua o cabeçalho padrão do WordPress: Plugin Name, Version, Author e Plugin URI com um link para o repositório. O Git Updater lê Plugin URI e GitHub Plugin URI; especifique pelo menos um.

• Tags de versão. Acompanhe cada lançamento com uma tag: git tag 1.3.0 && git push origin 1.3.0. Sem tags, nem o Git Updater nem o pedido à API verão a nova versão.

• Ficheiro Readme. Adicione um README.md com uma descrição, changelog e link de instalação. O Git Updater exibe o conteúdo do readme no ecrã de informação do plugin, poupando tempo aos utilizadores que não precisam de visitar o GitHub para obter instruções.

Com o GitHub Actions, pode ir mais longe: ao fazer push de uma tag, construir automaticamente o ZIP, gerar um changelog a partir dos commits e criar um GitHub Release com o arquivo anexado. Um fluxo de trabalho pronto está disponível na documentação oficial do GitHub; adapte-o para o WordPress substituindo o passo de build pelo empacotamento do plugin.

O vídeo mostra o processo completo, desde a instalação do Git Updater até à primeira atualização automática do plugin. Recomendamos que o veja antes da configuração: 12 minutos de gravação de ecrã pouparão uma hora de experimentação.

⁉️🤔 Perguntas frequentes

O Git Updater funciona com plugins do diretório oficial WordPress.org?

Sim, mas não faz sentido. Os plugins do WordPress.org já recebem atualizações através do mecanismo padrão. O Git Updater é especificamente para plugins e temas que não estão no diretório: desenvolvimentos personalizados, forks, plugins em revisão.

O Git Updater pode ser usado num site de produção?

Sim, o projeto é estável e tem manutenção desde 2015. Antes de instalar, faça um backup completo (como com qualquer plugin novo). Num site de teste, verifique a atualização de pelo menos um plugin, certifique-se de que as tags no repositório estão definidas corretamente e que a atualização é aplicada sem erros.

E se a API do GitHub atingir o limite de pedidos?

Para repositórios públicos, o limite é de 60 pedidos por hora a partir de um IP. O Git Updater guarda as respostas em cache durante 12 horas, pelo que o problema raramente ocorre. Se ocorrer, crie um Personal Access Token gratuito (sem permissões adicionais) e adicione-o em Settings → Git Updater: o limite sobe imediatamente para 5000 pedidos por hora.

O que fazer se o plugin no GitHub usar dependências do Composer?

O Git Updater não executa composer install durante as atualizações. Se o seu plugin depende de pacotes do Composer, incorpore o autoloading através de um bundle (inclua a pasta vendor/ no ZIP de lançamento) ou adicione um script pós-atualização que verifique as dependências e avise o administrador se estiverem em falta.

Os plugins podem ser atualizados a partir de um repositório privado no GitHub gratuito?

Sim. As contas gratuitas do GitHub incluem repositórios privados ilimitados. Crie um Personal Access Token com permissão repo, adicione-o ao Git Updater e o plugin terá acesso aos seus repositórios privados.

Atualizações automáticas do GitHub: o que usar em 2026

Para o proprietário de um site, a resposta é clara: Git Updater. Gratuito, estável, não requer código.

Para um programador de plugins, a escolha depende do público. Se o seu produto é instalado por utilizadores comuns, incorpore a classe PHP de atualização automática diretamente no código do plugin. Um plugin intermediário extra na cadeia reduz a conversão de instalação. Se o produto for para um público técnico, o Git Updater como dependência é aceitável; basta mencioná-lo nas instruções.

Verifique já os seus plugins do GitHub: as tags estão definidas nos últimos lançamentos, o Plugin URI está preenchido no cabeçalho, o utilizador tem um caminho de atualização claro? Quinze minutos de configuração poupar-lhe-ão a si e aos seus utilizadores o trabalho manual com arquivos ZIP durante anos.