DEV Community

Emanoel Carvalho
Emanoel Carvalho

Posted on

GitHub Stats Quebrados? Resolva de Vez com GitHub Actions!

#githubactions #programming #automation #webdev

Se você chegou até aqui, provavelmente já se deparou com aquele frustrante ícone de imagem quebrada no seu perfil do GitHub onde deveria estar aparecendo suas estatísticas lindamente renderizadas. Eu sei, é irritante!

Mas calma, tenho uma boa notícia: existe uma solução permanente, gratuita e muito mais poderosa do que simplesmente esperar o serviço voltar. Neste artigo, vou te mostrar como implementar um sistema automatizado que gera suas métricas do GitHub usando GitHub Actions, garantindo que seu perfil esteja sempre atualizado e funcionando perfeitamente.

📉 O Problema: Por Que o GitHub Readme Stats Caiu?

Antes de partirmos para a solução, é importante entender o que realmente aconteceu com o github-readme-stats, aquele serviço querido que todos usávamos.

A História Por Trás do Erro 503

O GitHub Readme Stats é um projeto open-source extremamente popular que gerava cards dinâmicos de estatísticas do GitHub. Durante muito tempo, ele funcionou perfeitamente hospedado na Vercel com um plano enterprise gratuito fornecido como patrocínio para projetos open-source.

Mas o que deu errado?

Em abril de 2024, a Vercel descontinuou esse patrocínio. O projeto foi rebaixado para o plano "Hobby" gratuito, que possui limites de uso bem mais restritos. Com milhões de desenvolvedores usando o serviço público, esses limites são ultrapassados rapidamente, resultando no temido erro:

503 SERVICE_UNAVAILABLE
DEPLOYMENT_PAUSED
"This Deployment is paused by the owner."
Enter fullscreen mode Exit fullscreen mode

Por Que Isso Não Vai Se Resolver Sozinho?

Muita gente pensa que é apenas uma "queda temporária", mas a verdade é mais complexa:

  1. Limites de recursos: O plano gratuito da Vercel não suporta o tráfego massivo gerado pelo uso global
  2. Custos insustentáveis: Manter o serviço funcionando exigiria que o mantenedor arcasse com custos significativos
  3. Problema estrutural: Não é um bug, mas sim uma incompatibilidade entre demanda e recursos disponíveis

O Impacto na Comunidade

  • Milhares de perfis do GitHub exibindo imagens quebradas
  • Perda da funcionalidade de showcasing de habilidades
  • Frustração generalizada entre desenvolvedores
  • Dezenas de issues duplicadas reportando o mesmo problema

A Solução Proposta: GitHub Actions + lowlighter/metrics

Depois de analisar as alternativas disponíveis, a solução mais robusta e confiável é migrar para o lowlighter/metrics executando via GitHub Actions. Vamos entender por quê.

Por Que Esta Solução é Superior?

1. Totalmente Gratuita e Independente

  • Roda na infraestrutura do próprio GitHub
  • Sem depender de serviços externos que podem cair
  • Zero custos de hospedagem

2. Extremamente Personalizável

  • Mais de 40 plugins disponíveis
  • Mais de 300 opções de configuração
  • Templates variados: classic, terminal, markdown, etc.

3. Mais Poderosa

Enquanto o GitHub Readme Stats oferece apenas cards básicos, o lowlighter/metrics fornece:

  • Análise de linguagens com detalhes avançados
  • Gráficos de linhas de código
  • Calendários isométricos de commits
  • Análise de hábitos de codificação
  • Integração com WakaTime, LeetCode e outras plataformas

4. Confiável e Estável

  • Execução controlada por você
  • Sem rate limits externos
  • SVG gerado e commitado no seu repositório
  • Sempre disponível, mesmo offline

🛠️ Tutorial Passo a Passo Completo

Agora vamos colocar a mão na massa! Siga este guia detalhado para implementar suas métricas automatizadas.

Pré-requisitos

Antes de começar, certifique-se de que você tem:

  • ✅ Uma conta no GitHub (Sim, eu sei, pode parecer besta essa confirmação rsrs)
  • ✅ Um repositório para seu perfil (geralmente seu-usuario/seu-usuario)
  • ✅ Conhecimento básico de Git e GitHub

Passo 1: Criar o Personal Access Token (PAT)

O token é necessário para que o GitHub Actions possa acessar seus dados de forma segura.

  1. Acesse as configurações de desenvolvedor:

  2. Gere um novo token:

    • Clique em "Generate new token" → "Generate new token (classic)"
    • Dê um nome descritivo, como METRICS_TOKEN

  3. Configure os escopos necessários:

Para funcionalidades básicas, selecione:

  • ✅ public_repo - para acessar repositórios públicos
  • ✅ read:user - para dados do usuário

Se você quiser métricas mais avançadas, adicione:

  • ✅ read:org - para métricas de organizações (se aplicável)
  • ✅ repo - para incluir repositórios privados
  1. Gere e copie o token:
    • Clique em "Generate token"
    • IMPORTANTE: Copie o token AGORA! Você não poderá vê-lo novamente
    • O formato será algo como: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Passo 2: Adicionar o Token como Secret no Repositório

Agora vamos armazenar o token de forma segura no seu repositório.

  1. Navegue até o repositório do seu perfil:

    • Geralmente é https://github.com/seu-usuario/seu-usuario

  2. Acesse as configurações de Secrets:

    • Clique em "Settings" (No menu superior)
    • No menu lateral: "Secrets and variables" → "Actions"

  3. Crie um novo secret:

    • Clique em "New repository secret"
    • Name: METRICS_TOKEN
    • Value: Cole o token que você copiou no Passo 1
    • Clique em "Add secret"

Pronto! Seu token está seguro e pronto para ser usado.

Passo 3: Criar o Arquivo de Workflow

Agora vamos criar a automação que vai gerar suas métricas.

  1. No seu repositório, crie a estrutura de pastas:

    • Crie a pasta .github/workflows/ na raiz do repositório
    • Se estiver usando a interface web, você pode fazer isso ao criar o arquivo

  2. Crie o arquivo metrics.yml:

    • Caminho completo: .github/workflows/metrics.yml

  3. Adicione o seguinte conteúdo:

name: GitHub Metrics

on:
  # Permite execução manual do workflow
  workflow_dispatch:

  # Executa automaticamente todo dia às 6h da manhã (UTC)
  schedule:
    - cron: "0 6 * * *"

jobs:
  metrics:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: lowlighter/metrics@latest
        with:
          # Token de autenticação (obrigatório)
          token: ${{ secrets.METRICS_TOKEN }}

          # Seu usuário do GitHub
          user: seu-usuario-aqui

          # Nome do arquivo que será gerado
          filename: assets/metrics.svg

          # Seções base a serem incluídas
          base: header, activity, community, repositories, metadata

          # Plugin de linguagens de programação
          plugin_languages: yes
          plugin_languages_sections: most-used, recently-used
          plugin_languages_details: bytes-size, percentage
          plugin_languages_limit: 8

          # Plugin de linhas de código
          plugin_lines: yes
Enter fullscreen mode Exit fullscreen mode

  1. ** IMPORTANTE: Substitua seu-usuario-aqui** pelo seu username do GitHub!

  2. Commit o arquivo:

    • Se estiver na interface web, clique em "Commit changes"
    • Se estiver localmente: git add .github/workflows/metrics.yml && git commit -m "feat: adiciona GitHub Metrics workflow" && git push

Passo 4: Entender a Configuração do Workflow

Vamos destrinchar cada parte do workflow para você entender exatamente o que está acontecendo.

Trigger Events (Eventos de Disparo) 

on:
  workflow_dispatch:
  schedule:
    - cron: "0 6 * * *"
Enter fullscreen mode Exit fullscreen mode
  • workflow_dispatch: Permite executar o workflow manualmente através da interface do GitHub
  • schedule: Agenda execuções automáticas
  • cron: "0 6 * * *": Sintaxe cron que significa:
    • 0 = minuto 0
    • 6 = hora 6 (UTC)
    • * * * = todos os dias, todos os meses, todos os dias da semana

Dica: Para converter para seu fuso horário local, use crontab.guru

Permissões 

permissions:
  contents: write
Enter fullscreen mode Exit fullscreen mode

Esta linha é crítica! Ela concede ao workflow permissão para fazer commit dos arquivos gerados de volta ao repositório. Sem isso, o workflow falhará.

Configurações Básicas 

token: ${{ secrets.METRICS_TOKEN }}
user: seu-usuario-aqui
filename: assets/metrics.svg
Enter fullscreen mode Exit fullscreen mode
  • token: Referência ao secret que criamos (nunca exponha o token diretamente!)
  • user: Seu username do GitHub
  • filename: Onde o SVG será salvo (cria a pasta automaticamente)

Base Sections (Seções Base) 

base: header, activity, community, repositories, metadata
Enter fullscreen mode Exit fullscreen mode

Define quais informações básicas serão exibidas:

  • header: Cabeçalho com seu nome e avatar
  • activity: Nível de atividade e contribuições
  • community: Pull requests, issues, reviews
  • repositories: Estatísticas dos seus repositórios
  • metadata: Informações sobre quando foi gerado

Plugin: Languages (Linguagens) 

plugin_languages: yes
plugin_languages_sections: most-used, recently-used
plugin_languages_details: bytes-size, percentage
plugin_languages_limit: 8
Enter fullscreen mode Exit fullscreen mode
  • most-used: Mostra suas linguagens mais utilizadas historicamente
  • recently-used: Linguagens usadas recentemente
  • bytes-size, percentage: Exibe o tamanho em bytes e percentual
  • limit: 8: Mostra no máximo 8 linguagens

Plugin: Lines (Linhas de Código) 

plugin_lines: yes
Enter fullscreen mode Exit fullscreen mode

Gera estatísticas sobre linhas de código adicionadas e removidas. Simples e direto!

Passo 5: Executar e Testar

Agora vamos rodar o workflow pela primeira vez!

  1. Navegue até a aba Actions do seu repositório:

    • URL: https://github.com/seu-usuario/seu-usuario/actions

  2. Encontre o workflow "GitHub Metrics":

    • Ele deve aparecer na lista de workflows disponíveis

  3. Execute manualmente:

    • Clique no workflow "GitHub Metrics"
    • Clique no botão "Run workflow" (à direita)
    • Mantenha a branch padrão selecionada
    • Clique em "Run workflow" (verde)

  4. Acompanhe a execução:

    • Aguarde alguns segundos e recarregue a página
    • Clique na execução que apareceu
    • Clique em "metrics" para ver os detalhes
    • Acompanhe o log em tempo real

  5. Verificar o resultado:

    • Se tudo correr bem, você verá um ✅ verde
    • O arquivo assets/metrics.svg será criado no seu repositório
    • Verifique acessando: https://media2.dev.to/dynamic/image/width=1000,height=420,fit=cover,gravity=auto,format=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fs8yjffjm1uwfulw9il5g.png

Passo 6: Adicionar o SVG ao README

Última etapa: vamos exibir suas métricas no README!

  1. Abra o arquivo README.md do seu repositório

  2. Adicione a imagem usando Markdown:

## 📊 Minhas Estatísticas do GitHub

![Metrics](./assets/metrics.svg)
Enter fullscreen mode Exit fullscreen mode

Ou, para garantir que sempre mostre a versão mais recente:

## 📊 Minhas Estatísticas do GitHub

![Metrics](https://raw.githubusercontent.com/gist/Ev357/17d9fc0cbccd58aea20b392de2d88eba/raw/aa5379c97b7f1bf89105f0960fafdb389cdbd70e/github-metrics.svg)
Enter fullscreen mode Exit fullscreen mode
  1. Commit e push das alterações: 
git add README.md
git commit -m "docs: adiciona métricas do GitHub ao README"
git push
Enter fullscreen mode Exit fullscreen mode
  1. Admire o resultado!

Acesse seu perfil e veja suas métricas lindamente renderizadas!

Customizações e Plugins Avançados

Agora que você tem o básico funcionando, que tal turbinar suas métricas? O lowlighter/metrics oferece uma infinidade de opções!

Plugins Populares para Experimentar

1. Calendário Isométrico de Commits 

plugin_isocalendar: yes
plugin_isocalendar_duration: half-year
Enter fullscreen mode Exit fullscreen mode

Cria um calendário 3D mostrando sua atividade de commits.

2. Hábitos de Codificação 

plugin_habits: yes
plugin_habits_charts: yes
plugin_habits_days: 14
plugin_habits_facts: yes
plugin_habits_from: 200
Enter fullscreen mode Exit fullscreen mode

Analisa seus padrões: horários preferidos, dias mais produtivos, etc.

3. Contribuições Notáveis 

plugin_notable: yes
plugin_notable_filter: stars:>50
Enter fullscreen mode Exit fullscreen mode

Destaca repositórios onde você contribuiu que têm mais de 50 stars.

4. Gráfico de Stargazers 

plugin_stargazers: yes
plugin_stargazers_charts: yes
plugin_stargazers_charts_type: chartist
Enter fullscreen mode Exit fullscreen mode

Mostra a evolução de stars nos seus repositórios.

5. Integração com WakaTime 

plugin_wakatime: yes
plugin_wakatime_token: ${{ secrets.WAKATIME_TOKEN }}
plugin_wakatime_days: 7
plugin_wakatime_sections: time, projects, languages
Enter fullscreen mode Exit fullscreen mode

Exibe estatísticas detalhadas de tempo de codificação do WakaTime.

Templates Visuais Diferentes

Você pode mudar completamente a aparência usando templates:

Terminal Style 

template: terminal
Enter fullscreen mode Exit fullscreen mode

Classic (padrão) 

template: classic
Enter fullscreen mode Exit fullscreen mode

Repository Style 

template: repository
Enter fullscreen mode Exit fullscreen mode

Temas Pré-definidos 

config_theme: dark
# Opções: default, dark, auto
Enter fullscreen mode Exit fullscreen mode

Ou use temas personalizados:

config_theme: github-dark
# Outras opções: github, monokai, solarized, etc.
Enter fullscreen mode Exit fullscreen mode

Exemplo de Configuração Avançada

Aqui está um exemplo completo com vários plugins:

name: GitHub Metrics Advanced

on:
  workflow_dispatch:
  schedule:
    - cron: "0 0 * * *"

jobs:
  metrics:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: lowlighter/metrics@latest
        with:
          token: ${{ secrets.METRICS_TOKEN }}
          user: seu-usuario
          filename: assets/metrics-advanced.svg

          # Configurações gerais
          base: header, activity, community, repositories, metadata
          config_timezone: America/Sao_Paulo
          config_theme: dark

          # Plugin de linguagens
          plugin_languages: yes
          plugin_languages_sections: most-used, recently-used
          plugin_languages_details: bytes-size, percentage
          plugin_languages_limit: 8
          plugin_languages_indepth: yes

          # Plugin de linhas de código
          plugin_lines: yes

          # Calendário isométrico
          plugin_isocalendar: yes
          plugin_isocalendar_duration: half-year

          # Hábitos
          plugin_habits: yes
          plugin_habits_charts: yes
          plugin_habits_days: 14
          plugin_habits_facts: yes

          # Contribuições notáveis
          plugin_notable: yes
          plugin_notable_filter: stars:>100

          # Stargazers
          plugin_stargazers: yes
          plugin_stargazers_charts: yes
Enter fullscreen mode Exit fullscreen mode

🔧 Troubleshooting: Problemas Comuns e Soluções

Encontrou algum problema? Vamos resolver! Aqui estão os erros mais comuns e como corrigi-los.

❌ Erro: "Resource not accessible by integration"

Causa: O workflow não tem permissão para fazer commit.

Solução:

  1. Adicione permissions: contents: write ao job
  2. Verifique se as Actions têm permissão de escrita:
    • Settings → Actions → General
    • Em "Workflow permissions", selecione "Read and write permissions"

❌ Erro: "Bad credentials" ou "401 Unauthorized"

Causa: Problema com o token de acesso.

Soluções:

  1. Verifique se o secret METRICS_TOKEN está configurado corretamente
  2. Certifique-se de que o token não expirou
  3. Confirme que o token tem os escopos necessários
  4. Gere um novo token se necessário

❌ Erro: Plugin não funciona ou exibe "Skipped"

Causa: O token não tem as permissões (scopes) necessárias para aquele plugin.

Solução:

  1. Verifique a documentação do plugin para ver quais scopes são necessários
  2. Crie um novo token com os scopes corretos
  3. Atualize o secret METRICS_TOKEN

❌ O SVG não aparece no README

Causas possíveis:

  1. Caminho incorreto no Markdown
  2. O arquivo ainda não foi gerado

Soluções:

  1. Verifique se o caminho está correto: ./assets/metrics.svg
  2. Ou use o caminho completo: https://upload.wikimedia.org/wikipedia/commons/1/14/Cryogenic_electron_microscopy_workflow.svg
  3. Certifique-se de que o workflow rodou com sucesso
  4. Aguarde alguns minutos para o cache do GitHub atualizar

❌ Workflow executou mas não gerou o arquivo

Causa: Permissões ou configuração incorreta.

Soluções:

  1. Verifique os logs do workflow para mensagens de erro específicas
  2. Confirme que permissions: contents: write está presente
  3. Verifique se o filename está correto
  4. Certifique-se de que a pasta de destino não está em .gitignore

Dica Profissional: Como Debugar

Para facilitar o debugging, adicione esta configuração ao workflow:

config_output: svg
debug: yes
Enter fullscreen mode Exit fullscreen mode

Isso gerará logs mais detalhados mostrando exatamente o que está acontecendo em cada etapa.

Ainda com Problemas?

  1. Consulte a documentação oficial: github.com/lowlighter/metrics
  2. Use o playground interativo: metrics.lecoq.io para testar configurações
  3. Verifique as issues: Procure por problemas similares nas issues do projeto
  4. Peça ajuda: Crie uma issue detalhando seu problema com logs e configurações

🎯 Conclusão e Próximos Passos

Parabéns! Você acabou de implementar uma solução profissional, confiável e totalmente automatizada para exibir suas estatísticas do GitHub.

Vantagens que Você Conquistou

✅ Independência total - Não depende mais de serviços externos

✅ Confiabilidade garantida - Suas métricas sempre estarão disponíveis

✅ Personalização infinita - Mais de 40 plugins ao seu dispor

✅ Gratuito para sempre - Sem custos de hospedagem

✅ Controle total - Você decide quando e como atualizar

✅ Profissionalismo - Um perfil que impressiona recrutadores

Sugestões de Próximos Passos

  1. Experimente diferentes plugins

    • Teste o plugin_habits para mostrar seus padrões de codificação
    • Adicione plugin_isocalendar para um visual impactante
    • Se usa WakaTime, integre com plugin_wakatime

  2. Crie múltiplas versões

    • Gere um SVG para modo claro e outro para modo escuro
    • Crie versões especializadas (só linguagens, só atividade, etc.)

  3. Otimize o agendamento

    • Ajuste o cron para atualizar em horários estratégicos
    • Considere executar semanalmente se diário for excessivo

  4. Compartilhe e inspire

    • Mostre seu perfil renovado nas redes sociais
    • Ajude outros devs compartilhando este artigo

  5. Explore a documentação

Uma Nota Final sobre Open Source ❤️

Tanto o github-readme-stats quanto o lowlighter/metrics são projetos open-source mantidos pela comunidade. Se você achar essas ferramentas úteis, considere:

  • ⭐ Dar uma estrela no repositório
  • 💬 Reportar bugs ou sugerir melhorias
  • 🤝 Contribuir com código ou documentação
  • ☕ Apoiar os mantenedores se possível

O open source só funciona porque pessoas dedicam seu tempo para criar ferramentas incríveis gratuitamente. Vamos retribuir sempre que possível!

📚 Recursos Adicionais

Gostou do artigo? Deixe um ❤️ e compartilhe com outros desenvolvedores que possam estar com o mesmo problema! Tem alguma dúvida ou sugestão? Comenta aqui embaixo!

Top comments (0)