Conectar o Jira com um token de API

Um token de API permite que o Planning Poker Web leia as issues do seu Jira e escreva de volta a estimativa aceita, sem passar por uma tela de login. Esta página explica como criar um, o que ele pode fazer e o que conferir quando algo não funciona. Vale para o Jira Cloud (um endereço como sua-equipe.atlassian.net). O Jira Data Center não é suportado.

Antes de começar

• Você precisa da permissão de gerenciar o planning poker na sua organização. Os donos já têm.
• A conta do Jira por trás do token precisa, em cada projeto que for usar, da permissão de navegar no projeto (para importar issues) e de editar issues (para escrever a estimativa de volta). Se você só importa e nunca devolve estimativas, navegar basta.
• Prefira uma conta compartilhada criada para isso, como planningpoker@sua-empresa.com, em vez da conta de uma pessoa. A estimativa aparece no histórico da issue com o nome dessa conta, e um token pessoal deixa de funcionar no dia em que a pessoa sai ou perde o acesso.

Passo 1: criar o token na Atlassian

1. Entre na Atlassian com a conta escolhida e abra id.atlassian.com → Segurança → Tokens de API.
2. Escolha Criar token de API. Use o comum, não o "Criar token de API com escopos": um token com escopos não funciona com esta conexão.
3. Dê um nome que você reconheça, como "Planning Poker Web", e escolha por quanto tempo ele deve valer.
4. Copie o token na hora. A Atlassian o mostra uma única vez. Se perder, crie outro.

Se a opção não aparecer, o administrador da sua Atlassian pode ter restringido quem cria tokens. Peça a ele para liberar na conta escolhida.

Passo 2: conectar no Planning Poker Web

1. Abra Configurações → Integrações, escolha Jira e depois Conectar, e selecione a opção Token de API.
2. Preencha os três campos:
   • Site do Jira: o endereço do seu Jira, por exemplo https://sua-equipe.atlassian.net. Só são aceitos endereços https://….atlassian.net.
   • E-mail da conta: o e-mail da conta da Atlassian que criou o token.
   • Token de API: o token que você copiou.
3. Escolha Testar. Se funcionar, você verá o nome da conta do Jira. O seu token é guardado criptografado e nunca é exibido de novo.
4. Na etapa Configurar, escolha se a estimativa aceita volta para o Jira e em qual campo. Veja Devolver estimativas.

Como funciona

Cada requisição sai dos nossos servidores para o seu Jira, assinada com o seu e-mail e o token. O token tem as mesmas permissões da conta que o criou, nem mais nem menos. O Planning Poker Web faz apenas isto:

• Lê os seus projetos e, de um projeto, os status, tipos de issue, épicos e sprints, para o diálogo de importação oferecer os filtros.
• Lê issues: a chave, o título e a descrição, para trazê-las para uma sala.
• Escreve um número em uma issue: a estimativa aceita, no campo que você escolheu.

Ele nunca cria nem apaga issues, nunca muda o status e nunca adiciona comentários. As sprints só são lidas se a conta puder abrir o quadro do projeto no Jira Software. Sem isso, o filtro de sprint fica simplesmente vazio.

Se não funcionar

• "O Jira rejeitou as credenciais": o e-mail ou o token está errado, o token foi revogado ou expirou. Crie um novo token e use Reconectar.
• "O Jira negou o acesso (403)": o Jira entendeu a chave, mas recusou o pedido. Confira, nesta ordem: se a conta realmente tem acesso ao Jira daquele site (abra o site logado com ela), se ela consegue navegar no projeto (e editar issues, para estimativas), se o administrador da Atlassian não limitou o acesso à API a certas redes, e se o token é do tipo comum, não o "com escopos". A explicação do próprio Jira, quando ele dá uma, aparece depois dos dois pontos.
• Seu projeto não aparece na lista: a conta não consegue navegar nele. Adicione a conta ao projeto, ou use uma conta que já faça parte dele.
• A estimativa não foi enviada, dizendo que o campo não está na tela: o campo precisa estar na tela de edição da issue naquele projeto. O Jira tem dois campos parecidos, Story points e Story point estimate; escolha o que o seu quadro mostra.
• "Use o endereço do seu Jira Cloud": o campo do site precisa ser parecido com https://sua-equipe.atlassian.net, sem nada depois.

Quando o token expira ou você quer parar

Os tokens da Atlassian não duram para sempre. Quando o seu expirar, crie um novo e use Reconectar; as suas configurações de estimativa são mantidas. Para parar a conexão, escolha Desconectar no Planning Poker Web e, se quiser, revogue o token em id.atlassian.com → Segurança → Tokens de API. Depois disso, nada consegue alcançar o seu Jira.