Integração com o GitHub

Com a integração com o GitHub vê pull requests, runs do GitHub Actions, ambientes e commits diretamente nas suas tarefas no FeatValue. Os seus clientes ficam a saber em palavras simples se a alteração está em andamento, em staging para testar ou já no ar.

Para que serve a integração com o GitHub

Empresas de software e agências web ouvem sempre a mesma pergunta: «Isto já está online?» Com a integração, o FeatValue responde-lhe na tarefa:

  • Branches, commits e pull requests com o ID da tarefa aparecem na tarefa certa.
  • Runs do GitHub Actions e deployments mostram se a alteração foi testada e a que ambiente chegou.
  • O FeatValue regista os passos importantes como comentários no histórico da tarefa.
  • Em cada projeto decide o que os seus clientes veem disso.
  • Volta a executar runs falhados diretamente a partir do FeatValue.

Para uma visão geral, veja a página sobre a integração com o GitHub.

Requisitos

  • uma conta FeatValue da sua empresa com pelo menos um cliente e um projeto (ver Criar projetos)
  • uma conta ou organização em github.com
  • o direito de instalar aplicações nesta conta ou organização. Nas organizações, são os owners. Os outros membros podem pedir a instalação, que um owner depois aprova no GitHub.

Ligar o GitHub

  1. Abrir a aplicação

    Clique em Aplicações na barra lateral esquerda, escolha GitHub e clique em Instalar (ver Ligar Aplicações).
  2. Ligar ao GitHub

    Clique em Ligar ao GitHub. Uma nota curta indica as permissões que a aplicação pede (ver Permissões da GitHub App). Clique em Continuar para o GitHub.
  3. Iniciar sessão no GitHub

    Inicie sessão no GitHub e autorize a aplicação FeatValue.
  4. Instalar a aplicação ou escolher organizações

    Se a aplicação ainda não estiver instalada em lado nenhum, o GitHub abre logo a instalação: escolha a sua conta ou uma organização, depois All repositories ou, em Only select repositories, os repositórios que o FeatValue pode ver, e clique em Install. Se a aplicação já estiver instalada em várias organizações, escolhe numa página de seleção as organizações que quer ligar. Depois regressa ao FeatValue.
Dê acesso apenas aos repositórios que pretende ligar a projetos do FeatValue. Pode alterar a seleção a qualquer momento no GitHub, na aplicação FeatValue: numa conta pessoal em Settings › Applications › Installed GitHub Apps, numa organização em Organization settings › Third-party Access › GitHub Apps.

Permissões da GitHub App

A aplicação FeatValue pede ao GitHub estas permissões:

  • Metadata: read: nomes e dados básicos dos repositórios com acesso
  • Contents: read: commits e comparações de branches
  • Pull requests: read: pull requests com título, estado e branch
  • Actions: read & write: ler runs do GitHub Actions, escrever apenas para reiniciar um run
  • Deployments: read: implementações e ambientes
A GitHub App pede acesso de leitura ao conteúdo do repositório (Contents: read) porque o GitHub só disponibiliza commits e comparações de branches com esta permissão. O FeatValue usa-a apenas para ler dados dos commits (mensagem, autor, data e hora) e comparações de branches, nunca o código-fonte, e não guarda nenhum ficheiro.

Ligar um repositório a um projeto

Cada repositório pertence a exatamente um projeto do FeatValue. Só os repositórios ligados chegam ao FeatValue.

  1. Abrir Ligar repositórios

    Abra Definições › Empresa › Integrações e apps e escolha GitHub (ver Apps ligadas). A página chama-se Ligar repositórios.
  2. Encontrar o repositório

    Os repositórios a que deu acesso à aplicação estão listados em Repositórios no GitHub. Com Pesquisar repositório reduz a lista.
  3. Escolher o projeto e ligar

    Ao lado do repositório, escolha o Projeto FeatValue e clique em Ligar. O FeatValue recupera os últimos dias. Não precisa de criar nenhum webhook, os eventos chegam através da aplicação FeatValue.

Todas as ligações aparecem em Repositórios ligados. A coluna Atualização mostra De imediato por webhook. Com Alterar escolhe outro projeto e com Desligar remove a ligação.

Várias organizações numa só ligação

Uma ligação do FeatValue pode usar a aplicação de todas as organizações e contas do GitHub em que está instalada e a que tem acesso ao ligar, por exemplo a sua própria organização e as organizações dos seus clientes. A lista da página Ligar repositórios está agrupada por organização.

  1. Adicionar uma organização

    Abra Definições › GitHub (página Ligar repositórios) e clique em Adicionar organização.
  2. Escolher a organização

    Escolha uma organização em que a aplicação já esteja instalada. Se não aparecer, clique em Instalar noutra organização e instale lá a aplicação no GitHub.
  3. Ligar repositórios

    Os repositórios da organização aparecem na lista. Ligue-os como descrito acima.

Várias empresas no FeatValue podem usar a mesma instalação, por exemplo a sua agência e o seu cliente com a sua própria conta FeatValue.

Usar corretamente o ID da tarefa

Cada tarefa no FeatValue tem um ID, por exemplo abc123-4. Encontra-o na tarefa. Coloque este ID num destes sítios:

Onde Exemplo
Nome do branch abc123-4-formulario-contacto
Mensagem de commit abc123-4 Tornar o telefone obrigatório
Título ou descrição do pull request Formulário de contacto: tornar o telefone obrigatório (abc123-4)
  • Maiúsculas e minúsculas não importam, e é permitido um # no início.
  • Se o ID estiver no nome do branch, contam apenas os commits que existem só neste branch. Os commits do branch predefinido que vêm junto ao criar o branch não aparecem na tarefa.
  • Os commits noutros branches só aparecem se o ID estiver na respetiva mensagem de commit.
  • O ID só é válido dentro do projeto ligado. O FeatValue nunca atribui repositórios ligados a outro projeto ou que não estejam ligados.
  • Runs do GitHub Actions e deployments pertencem à tarefa se correrem para um dos seus branches, commits ou pull requests.

O que aparece na tarefa

A tarefa mostra a secção Desenvolvimento com uma linha compacta, por exemplo: PR #12 mesclado · Workflow concluído · Publicado em Staging. Clique em Mostrar detalhes para expandir:

  • Workflows: os runs do GitHub Actions, por exemplo CI #57, com os respetivos jobs e estado
  • Ambientes dos seus deployments com um link para os abrir, por exemplo Staging e Production
  • Pull requests, Branches e Commits

O que aparece no projeto

No projeto, a secção Desenvolvimento mostra os ambientes com o último deployment e o último run no branch predefinido. Clique em Mostrar todas as execuções de workflow para ver a lista Últimas execuções de workflow. É também aqui que encontra as Definições do projeto.

O que veem os clientes?

No projeto, nas Definições da secção Desenvolvimento, escolha em O que veem os clientes?:

Definição O seu cliente vê
Nada nenhuma informação do GitHub
Estado simples uma frase sem termos técnicos: Em andamento, Publicado em Staging com o link teste aqui, ou No ar com o link ver agora
Detalhes as secções que marcar em Detalhes para clientes: commits, branches, pull requests, workflows, ambientes e comentários de histórico

Esta definição pode ser alterada pelas pessoas da sua empresa que podem editar o projeto. Como o seu cliente depois testa e aceita, explicamos em Revisão e aceitação.

Configurar os comentários de histórico

O FeatValue regista os passos importantes como comentários no histórico da tarefa. Em Comentários de histórico na tarefa escolhe, para cada projeto, que eventos criam um comentário:

  • Pull request integrado
  • Workflow concluído
  • Workflow com falha (com jobs com falha)
  • Implantado no ambiente

Os eventos desmarcados continuam a atualizar o estado na tarefa, mas deixam de criar um comentário. Se o seu cliente vê os comentários depende da definição em O que veem os clientes?.

Voltar a executar runs falhados Starter

Quando um run do GitHub Actions falha ou é cancelado, volta a executá-lo diretamente no FeatValue. Num run falhado, o GitHub repete apenas os jobs com falha; num run cancelado, o run inteiro. Esta função está disponível a partir do plano Starter (ver Planos).

  1. Permitir workflows

    No projeto, abra as Definições da secção Desenvolvimento. Em Executar workflows novamente a partir do FeatValue encontra os workflows para os quais o GitHub comunicou até agora um run falhado, por exemplo CI. Marque os workflows que devem aparecer no FeatValue e clique em Guardar.
  2. Também para clientes

    Se o seu cliente também deve poder voltar a executar os workflows selecionados, marque Os clientes também podem executar novamente os workflows selecionados.
  3. Voltar a executar

    Um run falhado de um workflow permitido aparece com o botão Executar novamente. Depois do clique, o FeatValue mostra Executado novamente, e acompanha o resto no run.

Segurança

  • Só repositórios autorizados e ligados: A aplicação FeatValue só vê os repositórios a que der acesso durante a instalação. O FeatValue só atribui IDs de tarefa nos repositórios que ligou a um projeto, e apenas dentro desse projeto.
  • Sem código-fonte: O FeatValue lê apenas dados dos commits e comparações de branches, nunca o código-fonte, e não guarda ficheiros do seu repositório. Para isso a aplicação pede Contents: read (ver Permissões da GitHub App).
  • Webhooks verificados: O GitHub assina cada entrega ao FeatValue. O FeatValue só aceita chamadas com uma assinatura válida.
  • Poucas permissões de escrita: A única coisa que a aplicação pode alterar é voltar a executar runs do GitHub Actions, e apenas para os workflows que permitiu.
  • Desligar a qualquer momento: Desligar remove uma ligação. Se desinstalar a aplicação no GitHub, o FeatValue desliga automaticamente os repositórios dessa organização.

Desligar e desinstalar a aplicação

Se desligar o GitHub no FeatValue, o FeatValue apenas apaga as ligações dos repositórios. O que já aparece nas tarefas mantém-se. A aplicação continua instalada no GitHub até a desinstalar lá:

  • Organização: No GitHub, abra Organization settings › Third-party Access › GitHub Apps, clique em Configure junto à aplicação FeatValue e, no fundo da página, em Uninstall.
  • Conta pessoal: Abra Settings › Applications › Installed GitHub Apps, clique em Configure junto à aplicação FeatValue e depois em Uninstall.

Depois da desinstalação, o FeatValue desliga automaticamente os repositórios dessa organização.

Resolução de problemas

O meu repositório não aparece na lista

O FeatValue só mostra os repositórios a que deu acesso à aplicação. No GitHub, abra Settings › Applications › Installed GitHub Apps, escolha a aplicação FeatValue e adicione o repositório em Repository access. Numa organização, encontra isto nas definições da organização.

A instalação aguarda aprovação

Se não for owner da organização, o GitHub envia o pedido de instalação aos owners. Assim que um owner o aprovar, ligue o GitHub outra vez no FeatValue.

Não aparece nada na tarefa

  • O repositório está ligado ao projeto a que a tarefa pertence?
  • O ID completo da tarefa está no nome do branch, na mensagem de commit ou no pull request?
  • Se uma entrega do GitHub se perder, o FeatValue recupera-a no prazo de 10 minutos.

Não é possível voltar a executar um run

Voltar a executar está disponível a partir do plano Starter. Além disso, o workflow tem de estar permitido nas definições do projeto, e o run tem de ter falhado ou sido cancelado. Se aparecer Não foi possível executar novamente, verifique no GitHub se a aplicação ainda está instalada e pode ver o repositório.

Falta uma organização na seleção

O FeatValue só mostra organizações em que a aplicação está instalada e a que a sua conta do GitHub tem acesso. Instale a aplicação com Instalar noutra organização ou peça a um owner da organização que o faça.

Your question has not been answered?

We will be happy to help you. You can send us an e-mail or arrange a video conference:

Privacy Policy • Impressum • Terms and Conditions