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.
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
-
Abrir a aplicação
Clique em
Aplicações na barra lateral esquerda, escolha
GitHub e clique em
Instalar (ver
Ligar Aplicações).
-
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.
-
Iniciar sessão no GitHub
Inicie sessão no GitHub e autorize a aplicação FeatValue.
-
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.
-
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.
-
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.
-
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.
-
Adicionar uma organização
Abra Definições › GitHub (página Ligar repositórios) e clique em Adicionar organização.
-
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.
-
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).
-
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.
-
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.
-
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.