Conectar ao Git: guia do aplicativo

Para quem administra a organização no GitHub ou o grupo no GitLab. É feito uma vez e serve a toda a equipe.

O Versiona grava o script de carga no Git da sua empresa, com o nome de quem alterou. Para isso, cada pessoa precisa se conectar ao Git pela extensão. Há dois jeitos, e o recomendado é o aplicativo.

Nos dois jeitos, o token fica só no navegador de cada pessoa e vai só ao Git da sua empresa. A Cubotimize não recebe token, script nem dado nenhum, e a extensão não usa o "segredo" do aplicativo: ele não precisa ser gerado. Veja a política de privacidade.

GitHub: criar o GitHub App

Tem de ser um GitHub App, e não um OAuth App: o GitHub App só enxerga os repositórios em que for instalado. O OAuth App alcançaria todos os repositórios privados de cada pessoa.

1. Na organização, abra Settings, Developer settings, GitHub Apps, New GitHub App.
2. GitHub App name: um nome que a equipe reconheça, por exemplo "Versiona" seguido do nome da empresa.
3. Homepage URL e Callback URL: o GitHub exige os dois, e o login do Versiona não usa nenhum. Pode usar o endereço da própria organização no GitHub.
4. Marque Enable Device Flow. É o login por código, que o Versiona usa.
5. Deixe marcado Expire user authorization tokens. O token passa a valer 8 horas, e o Versiona renova sozinho, a partir da v1.13.0. Um token roubado deixa de valer para sempre.
6. Em Webhook, desmarque Active. O Versiona não usa, e marcado o GitHub exige um endereço.
7. Em Repository permissions, dê Contents: Read and write. O "Metadata: Read-only" entra sozinho. Todo o resto fica em "No access".
8. Em "Where can this GitHub App be installed?", deixe Only on this account.
9. Clique em Create GitHub App.

Conferir, copiar o Client ID e instalar

1. Em Optional features, a linha "User-to-server token expiration" deve mostrar o botão Opt-out. É sinal de que a validade de 8 horas está ligada. Se mostrar "Opt-in", clique nele.
2. Em General, copie o Client ID, que começa com Iv. Não é o "App ID", que é só número.
3. Não gere "client secret" nem "private key": o Versiona não usa nenhum dos dois. O aviso amarelo pedindo a chave pode ser ignorado.
4. Em Install App, instale na organização com Only select repositories, marcando só o repositório dos scripts.

A tela de instalação deve mostrar duas permissões e mais nenhuma: "Read access to metadata" e "Read and write access to code".

Na extensão

1. No cadastro do servidor, escolha GitHub e cole o Client ID em "Client ID do aplicativo".
2. Informe o endereço do repositório e salve.
3. Ao conectar, a extensão mostra um código. Cada pessoa digita esse código em github.com/login/device, com a própria conta, e autoriza.

Cada pessoa só alcança o que a conta dela já alcança: quem não tem permissão de escrita no repositório continua sem conseguir gravar.

GitLab: criar a Application

1. No grupo, abra Settings, Applications. Quem não administra o grupo tem o mesmo formulário em Edit profile, Applications, e o administrador da instância, na área de administração.
2. Redirect URI: o endereço que a extensão mostra no cadastro do servidor, em "Como conseguir o Application ID", com o botão de copiar. Para a extensão instalada pela Chrome Web Store, é:

   https://fhfhemfocaiigoakdnbafeoeibgemfag.chromiumapp.org/gitlab

3. Desmarque Confidential. A extensão não guarda segredo.
4. Marque só o escopo api.
5. Salve e copie o Application ID. O "Secret" não é usado.

Na extensão, escolha GitLab no cadastro do servidor e cole o Application ID. Cada pessoa entra com o próprio login do GitLab, e a extensão renova o acesso sozinha.

Quer também o versionamento automático de madrugada? Veja o guia da rotina noturna.

Sem aplicativo: token pessoal

Recomendação de segurança. O token pessoal é a opção de menor proteção: cada pessoa escolhe o alcance e a validade do seu, e ele fica valendo até vencer. Se for usar, crie um só para o Versiona, com apenas o repositório dos scripts, apenas a permissão de gravar nele e validade de 90 dias ou menos. Não reaproveite token de outro uso. A extensão mostra este mesmo aviso a quem escolhe o token.

Funciona, e serve para quem usa sozinho ou quer testar antes de envolver o administrador. Deixe o campo do aplicativo em branco no cadastro, e cada pessoa cria o seu token:

• GitHub: token "fine-grained", em Settings, Developer settings, Personal access tokens. Só o repositório dos scripts, com Contents de leitura e escrita, e uma data de validade.
• GitLab: em Edit profile, Access tokens, com o escopo api e uma data de validade. O papel no projeto precisa ser Developer.

• Copie o token direto para a extensão. Não cole em e-mail, chamado nem chat.
• Use sempre uma data de validade. A extensão avisa 15 dias antes de vencer.

O repositório

• Tem de ser privado. O Versiona se recusa a gravar em repositório público.
• Script de carga pode conter regra de negócio, nome de tabela e dado de conexão: controle quem tem acesso ao repositório.
• Um repositório pode guardar mais de um ambiente Qlik, cada um na sua pasta. A pasta é escolhida no cadastro do servidor.

Para o TI: distribuir por política (GPO)

O Versiona lê uma política do navegador, que o TI distribui por GPO, Intune ou registro. Com ela, ninguém precisa cadastrar servidor: a pessoa instala (ou recebe instalada) e só conecta ao Git com a própria conta. É também por onde a empresa impõe as regras de segurança.

• servidores: a lista de servidores Qlik e o repositório de cada um, já com o Application ID ou o Client ID. Servidor vindo da política não pode ser editado por quem usa, e vale como a confirmação do termo de responsabilidade pela organização.
• exigir_aplicativo: com true, ninguém conecta com token pessoal. Só pelo login do aplicativo.
• exigir_trava: com true, a extensão só conecta e só usa o token depois que a pessoa ativa o PIN ou a biometria, e a tela não oferece desativar. Serve o Windows Hello, uma chave de segurança ou o celular.
• itens_mestres: com true, todo servidor versiona também os itens mestres e as variáveis do app; com false, nenhum. Sem a chave, vale a escolha de cada servidor.

O exemplo abaixo é um arquivo .reg para o Chrome. Ele instala a extensão para todos, exige o aplicativo e cadastra um servidor. Troque os endereços, o Application ID e o projeto pelos seus. No Edge, o caminho começa com SOFTWARE\Policies\Microsoft\Edge no lugar de SOFTWARE\Policies\Google\Chrome.

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\ExtensionInstallForcelist]
"1"="fhfhemfocaiigoakdnbafeoeibgemfag;https://clients2.google.com/service/update2/crx"

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\3rdparty\extensions\fhfhemfocaiigoakdnbafeoeibgemfag\policy]
"exigir_aplicativo"=dword:00000001
"exigir_trava"=dword:00000001
"itens_mestres"=dword:00000001
"servidores"="[{\"nome\":\"Qlik\",\"hosts_qlik\":[\"qlik.example.com\"],\"provedor\":\"gitlab\",\"origem_git\":\"https://git.example.com\",\"application_id\":\"APPLICATION_ID\",\"projeto\":\"grupo/scripts-qlik\",\"rotina_noturna\":false}]"

• Em servidores, o valor é um texto com a lista em JSON. Os campos são os do cadastro: nome, hosts_qlik, provedor (gitlab ou github), origem_git (sempre com https://), application_id, projeto, branch, pasta, rotina_noturna e itens_mestres (true para versionar também os itens mestres e as variáveis).
• Se a empresa já usa a lista de instalação forçada, não reaproveite o número "1": use o próximo livre.
• Nenhum campo é segredo. Não ponha token nem senha na política: não existe campo para isso.
• Para conferir, abra chrome://policy (ou edge://policy) na máquina de quem usa: a política aparece na parte do Versiona CuboPlus.
• Na primeira vez em cada servidor Qlik, a pessoa ainda autoriza a extensão a ler aquele endereço. Isso o navegador pede a ela, e a política não substitui.

Proteger o token com PIN ou biometria (muito recomendado)

A partir da v1.17.0, o Versiona pode exigir o Windows Hello para usar o token do Git. Com isso ligado, o token só abre neste computador, depois de você confirmar com o PIN ou a biometria. Um programa malicioso que copie o perfil do navegador leva um token que não abre em lugar nenhum. Recomendamos muito ativar em todo computador com o Windows Hello configurado. Sem Windows Hello, servem uma chave de segurança (USB) ou o celular, a partir da v1.21.0. A chave de segurança ainda é experimental.

1. Clique no ícone do Versiona e abra Servidores.
2. No fim da tela, em "Exigir PIN ou biometria para usar o token", clique em Ativar.
3. Escolha onde a chave de acesso fica: Windows Hello (recomendado), Chave de segurança (USB) ou Celular.
4. No Windows Hello, a janela Segurança do Windows aparece dizendo "Isso será salvo em seu dispositivo Windows": é o Windows Hello, e a chave fica só neste computador. Se antes dela o navegador oferecer o Gerenciador de senhas do Google, escolha Salvar de outra forma e depois Windows Hello.
5. Confirme com o PIN ou a biometria. O Windows pede duas vezes na ativação: uma para criar a chave de acesso, outra para usá-la.

• No dia a dia, o PIN ou a biometria é pedido uma vez a cada vez que o navegador é aberto. Ao entrar no Qlik, o mascote pergunta, e um clique em "Desbloquear" basta.
• "Trancar agora", na mesma tela, tranca o token na hora, para quando você for se afastar do computador.
• Três lugares servem. O Windows Hello, que prende a chave a este computador; uma chave de segurança FIDO2 com PIN ou digital, que precisa estar conectada na hora de desbloquear; e o celular, com o Bluetooth ligado nos dois aparelhos.
• No celular, a chave precisa ir para o cofre nativo: o Gerenciador de senhas do Google no Android, ou as Senhas da Apple no iPhone. Cofre de senhas de outro fabricante não serve: a ativação é recusada, sem alterar nada. A chave acompanha a conta Google ou Apple, e a garantia passa a depender dela: use uma conta diferente da que está logada no navegador do computador. Com a mesma conta, a chave fica ao alcance do próprio navegador. Testado no Android; no iPhone, ainda não.
• A chave guardada na conta Google do navegador é recusada, e nada muda: ela mora no mesmo perfil que a proteção quer guardar.
• Não protege de tudo: um programa rodando na sua sessão depois do desbloqueio ainda alcança o token. Por isso as medidas do lado do Git, logo abaixo, continuam valendo.
• Perdeu o acesso ao Windows Hello, à chave de segurança ou ao celular? Use "Perdi o acesso: apagar as conexões e desativar", e conecte de novo ao Git.

O que precisa: o Windows Hello configurado neste computador (PIN, digital ou rosto), ou uma chave de segurança, ou o celular, e um Chrome atual. O Windows Hello foi testado no Chrome com o Windows 11; a chave de segurança e o celular ainda não. Se o computador não tiver o que o recurso precisa, a ativação é recusada, nada é alterado, e a tela diz o motivo.

Se o token for roubado: o que o seu Git consegue barrar

O token que o Versiona usa fica no navegador de cada pessoa. Desde a v1.12.0 ele vai para o disco criptografado, com uma chave criada naquele perfil do navegador e que não pode ser exportada. Isso tira o token do alcance do programa malicioso comum, que varre o navegador atrás de credenciais em texto.

Não é uma garantia: quem copiar o perfil inteiro do navegador, ou tiver um programa rodando na sessão da pessoa, ainda pode chegar ao token. O que impede um token roubado de funcionar em outro lugar é a configuração do Git, e ela depende do plano. As tabelas abaixo dizem o que cada plano oferece.

GitHub

GitLab

Consultado na documentação oficial em 6 de outubro de 2026: GitHub.com e GitHub Enterprise Cloud (sem número de versão), GitHub Enterprise Server 3.22, GitLab 19.5. Os planos mudam: confira o link de cada linha antes de decidir. "Não confirmado" quer dizer que a documentação lida não diz em qual plano o recurso existe.

O que fazer, por ordem de efeito

1. Restringir a rede. É a única medida que impede o token de funcionar em outro lugar. No GitLab instalado na empresa, deixe-o acessível só pela rede interna ou pela VPN: funciona em qualquer licença. No GitLab.com, a restrição por IP pede o plano Premium. No GitHub, a lista de IPs pede o Enterprise Cloud.
2. Exigir PIN ou biometria na extensão. É o que impede o token de abrir fora do computador da pessoa, em qualquer plano do Git. Veja como ativar.
3. Criptografar o disco do computador. No Windows Pro e Enterprise é o BitLocker; no Home, a "Criptografia do dispositivo". Protege o caso do notebook perdido ou roubado e do disco retirado da máquina: sem isso, quem tem o disco lê o perfil do navegador inteiro. Não protege de um programa rodando na sessão da pessoa. Quem liga costuma ser o TI, que também guarda a chave de recuperação.
4. Usar o aplicativo, e não o token pessoal. Com o GitHub App, o acesso alcança só os repositórios escolhidos na instalação. Com a validade ligada, o token dele vale 8 horas. Com a Application do GitLab, o token vale 2 horas.
5. Dar o alcance mínimo. Um repositório só para os scripts, e a pessoa só com o papel de que precisa para gravar nele.
6. Proteger a branch. Sem push forçado e sem apagar: um token roubado consegue gravar, mas não destrói o histórico. No GitHub, repositório privado protegido pede Pro ou Team.
7. Saber revogar. Suspeitou, revogue: a pessoa remove o aplicativo autorizado na própria conta, e conecta de novo pelo Versiona.

O que não barra um token já roubado: a verificação em duas etapas, que protege o login e não o token (o GitLab diz isso); a lista de IPs do próprio GitHub App, que vale para o aplicativo e não para o token da pessoa; e o login por certificado ou smart card do GitLab, que a documentação descreve para o acesso pela tela, e não pela API.

Se algo der errado

Dúvida, sugestão ou problema: [email protected]. Não mande token, senha nem script de carga por e-mail.

Instalar o Versiona CuboPlus