Suporte do Bouteiller

O Bouteiller é uma app gratuita para iPhone e iPad que permite acompanhar e controlar os seus servidores Jenkins: estado dos jobs, console log, lançamento e paragem de builds, aprovação dos inputs dos pipelines, widgets e Atalhos.

Requisitos

iPhone ou iPad com iOS 26 ou iPadOS 26 ou posterior.
Um servidor Jenkins na versão 2.580.1 LTS ou numa versão weekly 2.580 ou posterior. As versões mais antigas são recusadas ao adicionar o servidor, com uma mensagem explícita.
Não é necessário nenhum plugin no servidor: o Bouteiller usa apenas a API REST padrão do Jenkins. Se alguns plugins comuns estiverem instalados (Pipeline, Pipeline Stage View ou Pipeline Graph View, JUnit), a app mostra mais informação: stages dos pipelines, inputs pendentes, resultados de testes.
Uma conta de utilizador Jenkins e um token de API (ver abaixo). Não precisa de ser administrador: na app, vê e faz aquilo que a sua conta pode ver e fazer no Jenkins.
Acesso de rede do dispositivo ao servidor (direto ou através da VPN da sua organização).

Criar um token de API

O Bouteiller inicia sessão com o seu nome de utilizador Jenkins e um token de API, nunca com a sua palavra-passe.

Inicie sessão na interface web do Jenkins.
Abra a página Security (Segurança) das suas definições de utilizador: aceda a https://o-seu-jenkins/me/security (o formulário do servidor na app tem um botão Abrir a página do token que o faz por si) ou clique no seu nome no canto superior direito e depois em Security. A secção API Token encontra-se aí.
Na secção API Token, escolha Add new Token (Adicionar novo token), dê-lhe um nome (por exemplo, «Bouteiller iPhone») e gere-o.
Copie o token de imediato: o Jenkins só o mostra uma vez.
No Bouteiller, adicione um servidor e introduza o endereço do servidor, o seu nome de utilizador e o token. A app verifica a ligação e a versão do Jenkins antes de guardar.

Pode revogar o token a qualquer momento na mesma página do Jenkins; a app indicará então que as credenciais foram recusadas.

VPN e autoridades de certificação internas

Servidores acessíveis só por VPN

O Bouteiller não controla a sua VPN. Ao adicionar ou editar um servidor, ative Acessível só por VPN: quando o servidor não responder, a app sugere então que se ligue à VPN em vez de mostrar um erro genérico.

Sem a VPN, a app mostra os últimos dados conhecidos, com uma faixa «Offline» e a data desses dados. As ações (lançar, parar, aprovar…) ficam desativadas.
Assim que o servidor voltar a responder (VPN ligada, app de novo em primeiro plano), a faixa desaparece e os ecrãs são atualizados.
Uma ação nunca é colocada em espera para ser executada mais tarde: se o servidor estiver inacessível, é informado disso e pode tentar novamente depois de se ligar.

Certificados de uma autoridade interna

Se o seu servidor Jenkins usar um certificado emitido pela autoridade de certificação da sua organização, o iOS não confia nele por predefinição. Há duas opções:

Instalar a autoridade no dispositivo e confiar nela (perfil de configuração fornecido pelo seu departamento de informática e, depois, Definições › Geral › Informações › Definições de confiança de certificados). O Bouteiller funciona então como com qualquer certificado público.
Aprovar o certificado no Bouteiller: quando o certificado não é fidedigno, a app mostra os certificados enviados pelo servidor (assunto e impressão digital SHA-256) e permite aprovar um deles, apenas para esse servidor. A aprovação da autoridade de certificação raiz é sugerida por predefinição, porque se mantém válida quando o certificado do servidor é renovado. O nome do anfitrião e as datas de validade continuam a ser verificados.

Aprove apenas um certificado cuja impressão digital tenha confirmado com o seu departamento de informática. Caso contrário, qualquer pessoa capaz de intercetar a ligação poderia ler o seu token de API.

HTTP não encriptado

Espera-se HTTPS. O HTTP não encriptado só é aceite para um servidor da rede local, depois de o permitir explicitamente no formulário do servidor: o token de API é então enviado sem encriptação.

Notificações

Nesta versão, as notificações funcionam em modo local: a app verifica os seus jobs favoritos em segundo plano e apresenta uma notificação no dispositivo quando algo acontece. Nenhum servidor do programador está envolvido.

Configuração

Adicione o job aos seus favoritos.
Toque no sino do job favorito e escolha os eventos: build iniciado, sucesso, falha, instável, recuperado, cancelado, input pendente. A escolha predefinida («Notificar problemas») abrange falha, instável, recuperado e input pendente.
Permita as notificações quando o iOS o pedir. O estado do job nesse momento serve de referência: só são notificados os eventos posteriores.

Limites do modo local

O momento é decidido pelo iOS. As verificações em segundo plano são feitas quando o iOS o permite, muitas vezes a cada algumas dezenas de minutos, por vezes com menos frequência (bateria, utilização da app). Uma notificação pode, por isso, chegar bastante depois do evento.
Apenas favoritos. Só são verificados os jobs favoritos a que está subscrito.
Apenas o último build de cada favorito é visto: se vários builds tiverem decorrido entre duas verificações, só o resultado do último é notificado.
Acessibilidade do servidor. Nada pode ser verificado enquanto o servidor estiver inacessível (por exemplo, sem a VPN).
A atualização em segundo plano tem de estar ativada para o Bouteiller (Definições › Geral › Atualização em segundo plano). O modo de poupança de energia suspende-a e, em geral, o iOS não atualiza uma app que tenha forçado a sair a partir do seletor de apps até a voltar a abrir.
As ações das notificações (Relançar, Aprovar, Rejeitar) exigem que o dispositivo esteja desbloqueado e que o servidor esteja acessível; o resultado da ação é notificado. Um input com parâmetros abre a app para lhe responder.

A secção Notificações das definições da app indica se as notificações e a atualização em segundo plano estão permitidas e permite executar uma verificação de imediato.

Estão previstas para uma versão futura notificações push que funcionam também fora da VPN, através de um plugin Jenkins opcional.

Perguntas frequentes

O Bouteiller é uma app oficial do Jenkins?: Não. O Bouteiller é uma app independente, desenvolvida por um particular. Não é afiliada ao projeto Jenkins nem aprovada por ele.
Tenho de instalar um plugin no meu servidor?: Não. A app funciona com um servidor Jenkins sem qualquer plugin. Os jobs freestyle podem ser consultados, lançados, parados e relançados; os stages dos pipelines, os inputs e os resultados de testes são apresentados quando os plugins correspondentes estão instalados.
A app diz que a minha versão do Jenkins não é suportada.: O Bouteiller requer o Jenkins 2.580.1 LTS ou uma versão weekly 2.580 ou posterior. Fale com o seu administrador sobre uma atualização.
A app diz que as credenciais foram recusadas.: Verifique o nome de utilizador (o seu ID de utilizador Jenkins, não necessariamente o seu nome de apresentação) e o token de API. Se o servidor estiver atrás de um reverse proxy ou de um portal de autenticação única, confirme que o cabeçalho Authorization chega ao Jenkins.
O servidor está inacessível, mas funciona no Safari.: Verifique se introduziu o mesmo endereço que no Safari, incluindo o caminho (por exemplo, https://ci.exemplo.pt/jenkins). Se o Safari só funcionar com a VPN, ative a opção VPN do servidor. Se o certificado não for fidedigno, consulte autoridades de certificação internas.
Posso proteger as ações sensíveis?: Sim. Nas definições, pode exigir o Face ID, o Touch ID ou o código do dispositivo antes de parar um build e antes de aprovar ou rejeitar um input. A autenticação é tratada pelo iOS; a app nunca vê os dados biométricos.
Posso usar vários servidores?: Sim, tantos quantos quiser. O separador Favoritos mostra os jobs favoritos de todos os servidores.
Que widgets e atalhos estão disponíveis?: Widgets: estado de um job (ecrã principal e ecrã bloqueado), favoritos, builds com falha de um servidor, com um botão para lançar os jobs sem parâmetros. Atalhos e Siri: lançar um job, estado de um job, builds com falha, abrir um job. Um controlo na Central de controlo lança um job favorito. Os widgets mostram a hora da última atualização e indicam quando o servidor está inacessível.
Porque é que os widgets mostram dados antigos?: Os widgets são atualizados quando o iOS o permite e apenas enquanto o servidor estiver acessível. Caso contrário, mantêm o último estado conhecido, com a hora da última atualização e um indicador «inacessível».
Como apago os meus dados?: Apague o servidor na app: o respetivo token de API é removido do porta-chaves, juntamente com os favoritos, as subscrições de notificações e os dados em cache. A cache, por si só, pode ser limpa nas definições. Apagar a app remove os seus dados; como o iOS pode manter elementos do porta-chaves depois de uma app ser apagada, apague primeiro os seus servidores se quiser ter a certeza de que os tokens são eliminados, e revogue os tokens no Jenkins.
A app recolhe dados?: Não. Consulte a política de privacidade.

Contacto

Para uma questão, um problema ou uma sugestão, escreva para: nicolas.mannocci@gmail.com.

Para ajudar a resolver um problema, indique a versão da app (apresentada nas definições da app), o seu dispositivo e a versão do iOS, a sua versão do Jenkins e, se for o caso, se está envolvida uma VPN ou uma autoridade de certificação interna. Nunca envie o seu token de API.