Agility V2 - 2026
🔐 Esta versão traz perfis de acesso por workspace, administrador definido por grupo do Keycloak, convites por e-mail e notificações.
📦 Sobre esta versão v1.1.0
🔖 Código-fonte: c8b3d012 (gerado a partir da versão 205821ef, de 03/11/2026)
🐳 Pacote do sistema: repositorio.cithyper.click/centralit/agility:v1.1.0
🗄️ Novas etapas de preparação do banco: 00082 a 00091
📈 Desde a v1.0.0: 222 alterações no código (commits) e 23 pedidos de junção de código (merge requests)
🤝 Funciona junto com: Tenancit v1.0.0, Keycloak e PostgreSQL 16
⚠️ Antes de atualizar, leia a seção "Atualizar da v1.0.0".
Se o grupo de administradores não for criado no Keycloak, ninguém será Administrador do Agility depois da atualização. Nesse caso, criar workspace e abrir as páginas de campos personalizados e de IA ficam bloqueados para todos.

- 👥 Perfis e matriz de permissões: agora existem quatro perfis prontos (Convidado, Membro limitado, Membro e Administrador), e você também pode criar perfis personalizados. Para cada perfil, dá para ligar ou desligar 22 ações diferentes. O perfil vale por workspace, ou seja, a mesma pessoa pode ter um perfil em um workspace e outro perfil em outro.
- 👑 Administrador do Agility: é um papel que vale para todo o ambiente do cliente (tenant). Quem estiver no grupo do Keycloak definido em AGILITY_ADMIN_GROUPS recebe esse papel automaticamente. Ele também pode ser dado ou retirado em Configurações › Pessoas.
- ✉️ Convites por e-mail: convide pessoas já definindo o perfil e os projetos de cada uma. O e-mail é enviado pela conta de e-mail do cliente (SMTP ou Microsoft Graph).
- 🗃️ Arquivar, duplicar e mover: agora você pode arquivar cards, projetos e workspaces, e também duplicar e mover cards e projetos.
- 🔔 Sino de notificações: acompanhe seus avisos pelo sino na tela.
- 🕵️ Histórico de mudanças de permissão (trilha de auditoria): o sistema registra quem alterou a matriz de permissões, um perfil, o perfil de uma pessoa ou quem é Administrador do Agility.
- 🧭 Telas mostram só o que você pode fazer: as Configurações e os menus exibem apenas as opções liberadas para o seu perfil. As Chaves de API saíram do menu da sua foto (avatar) e agora ficam em /settings/api.
- 🎨 Login com a cara do Agility: um visual opcional do Keycloak, com a identidade do Agility, para as telas de login e os e-mails (arquivos em deploy/keycloak/theme).

- 🔢 Códigos de Épico e Feature do portfólio: a partir do número 100, o código perdia o último algarismo (por exemplo, EPIC-178 virava EPIC-17) e o cadastro dava erro. Isso foi corrigido. Os códigos que já estavam gravados não mudam (atualização do banco 00088).

🛠️ Atualizar da v1.0.0 para a v1.1.0
(para a equipe técnica)
Os marcadores (<NAMESPACE>, <HOST_AGILITY>, <REALM>, <TENANT>, <URL_TENANCIT>) são os mesmos das notas da v1.0.0.
0️⃣ Fazer o backup
Faça um pg_dump (cópia de segurança) do banco de cada tenant.
🅰️ Keycloak: administradores e entrada no sistema
Faça tudo no realm <REALM>:
- Grupo de administradores: abra Groups → Create group e crie o grupo agility-admins (caminho /agility-admins).
- ⚠️ Antes, confira se o grupo já não existe com outras pessoas dentro e se ele não é um grupo padrão (default group). Todos que estiverem nele viram administradores no primeiro login.
- Adicione ao grupo as pessoas que vão administrar o Agility.
- Mapper de grupos no client agility: acesse Clients → agility → Client scopes → agility-dedicated → Configure a new mapper → Group Membership e preencha:
Campo | Valor |
|---|---|
Name | agility-groups |
Token Claim Name | groups |
Full group path | On |
Add to access token | On |
Add to ID token | On |
Add to userinfo | Off |
- Papéis de entrada: crie os cinco papéis de realm que ainda não existirem: agility-viewer, agility-commenter, agility-editor, agility-approver e agility-admin.
- O client agility do kit vem com Full scope allowed desligado. Por isso, mapeie os cinco papéis e o offline_access em Clients → agility → Client scopes → agility-dedicated → Scope. Sem esse mapeamento, os papéis não chegam ao token e só entra quem for convidado.
- Atribua um desses papéis a quem pode entrar sem convite, direto na pessoa ou em um grupo.
📘 Os detalhes de cada tela estão no guia docs/operators/keycloak-realm-do-agility.md, nos passos 4 e 10.
🅱️ Tenancit: conta para envio de e-mails
Os convites só funcionam se houver uma conta de envio de e-mail. Sem ela, a opção de convidar pessoas fica indisponível, mas o resto do Agility funciona normalmente.
Em <URL_TENANCIT>, abra Recursos → Nova definição e crie a definição do jeito de envio escolhido. A Key da definição precisa ser exatamente smtp ou msgraph.
Opção smtp
Key | Obrigatório | Segredo | Exemplo (Office 365) |
|---|---|---|---|
host | sim | não | smtp.office365.com |
port | sim | não | 587 |
security | sim | não | starttls (ou tls na porta 465) |
auth_method | sim | não | login (ou none, sem credencial) |
username | não | não | a caixa de e-mail remetente |
password | não | sim | a senha da caixa |
from_address | sim | não | a caixa de e-mail remetente |
from_name | não | não | Agility |
timeout_seconds | não | não | 15 |
Opção msgraph (Microsoft Graph, ⭐ recomendada para Office 365)
Key | Obrigatório | Segredo | O que é |
|---|---|---|---|
directory_id | sim | não | Directory (tenant) ID do app no Entra ID |
client_id | sim | não | Application (client) ID do app |
client_secret | sim | sim | o valor do segredo do app, não o Secret ID |
from_address | sim | não | a caixa de e-mail remetente |
from_name | não | não | Agility |
timeout_seconds | não | não | 15 |
Depois, no tenant <TENANT>, abra Recursos → Adicionar recursos, escolha a definição e use o alias agility.email. Cada tenant tem apenas uma conta de envio.
🌐 A rede do cluster precisa conseguir acessar:
- no smtp: smtp.office365.com:587;
- no msgraph: login.microsoftonline.com:443 e graph.microsoft.com:443.
🔑 Permissões necessárias:
- msgraph: o app precisa da permissão Mail.Send, restrita à caixa remetente no Exchange Online;
- smtp: a caixa precisa estar com o SMTP AUTH ligado.
📘 O passo a passo das duas opções está em deploy/tenancit/README.md, na seção "Resource agility.email".
🅲 Ajustar os arquivos de configuração (manifestos)
No arquivo agility.yaml:
- No ConfigMap agility, inclua:
AGILITY_ADMIN_GROUPS: "/agility-admins"- ⚠️ O caminho precisa começar com a barra (/), senão o sistema não inicia. Para mais de um grupo, separe por vírgula.
- O ConfigMap também aceita a variável AGILITY_LOGIN_ACCESS_ROLES, que é opcional. Se ficar vazia, vale a lista dos cinco papéis do passo A.3. Para que só entre quem for convidado, coloque nela um papel que ninguém tem.
- Troque v1.0.0 por v1.1.0 na imagem do Deployment, na imagem do Job e nos rótulos app.kubernetes.io/version.
🅳 Aplicar a atualização, nesta ordem
No kit, a rotina de preparação do banco (Job de migration) está no mesmo arquivo do sistema (Deployment). Se tudo for aplicado de uma vez, a v1.1.0 sobe antes de o banco estar pronto. Por isso, separe o arquivo antes:
- ✂️ Separe a rotina do banco: mova o último documento do agility.yaml, o que começa em # Source: agility/templates/migrate-job.yaml (Job agility-migrate), para um arquivo novo chamado agility-migrate.yaml.
- ⏸️ Pare a v1.0.0, para que o código antigo não rode com o banco já atualizado:
kubectl -n <NAMESPACE> scale deploy/agility --replicas=0- 🗑️ Apague a rotina da v1.0.0. O nome dela é sempre o mesmo, e o Kubernetes não troca a imagem de uma rotina que já existe:
kubectl -n <NAMESPACE> delete job agility-migrate --ignore-not-found- 🗄️ Rode a preparação do banco e espere terminar:
kubectl -n <NAMESPACE> apply -f agility-migrate.yaml
kubectl -n <NAMESPACE> wait --for=condition=complete job/agility-migrate --timeout=600s- 🚀 Suba a v1.1.0. Este comando também volta o sistema para 2 cópias funcionando (réplicas):
kubectl -n <NAMESPACE> apply -f agility.yaml🅴 Conferir se está tudo funcionando
- Rode os comandos abaixo:
kubectl -n <NAMESPACE> rollout status deploy/agility
curl -fsS https://<HOST_AGILITY>/readyz- Peça para uma pessoa do grupo /agility-admins fazer login. No banco do tenant, ela precisa aparecer no resultado de:
SELECT email, is_agility_admin FROM agility.users WHERE is_agility_admin;- Em Configurações › Pessoas, convide alguém. ✉️ Se não for possível convidar, revise o recurso agility.email do passo B.
🆕 Instalação nova da v1.1.0
Siga a implantação das notas da v1.0.0 usando a imagem v1.1.0, e faça também os passos A, B e C.1 desta página antes de aplicar os manifestos.
- 🚪 Os papéis do realm agora só liberam a entrada no sistema. Os papéis agility-viewer, agility-commenter, agility-editor, agility-approver e agility-admin não dão mais permissões:
- quem tem um deles entra como Membro no primeiro login;
- quem não tem nenhum só entra por convite;
- o que cada pessoa pode fazer agora é definido pelo perfil.
- 👤 Quem já tinha acesso a algum workspace passa a ser Membro (atualização do banco 00083).
- 👑 Ninguém começa como Administrador do Agility. O primeiro administrador vem do grupo do Keycloak (veja o passo A abaixo).
Primeira versão oficial do Agility! 🎉 Aqui você encontra tudo o que o sistema já oferece e o guia de instalação para a equipe técnica.
📦 Sobre esta versão
🗓️ 09/10/2026 · 🔖 código a7eac2b7 🐳 Pacote: repositorio.cithyper.click/centralit/agility:v1.0.0 🗄️ Banco de dados: etapas de preparação 00001 a 00081 🤝 Funciona junto com: Tenancit v1.0.0, Keycloak e PostgreSQL 16

- 📋 Projetos e trabalho: organize suas tarefas do jeito que preferir:
- Quadro Kanban: as tarefas aparecem em colunas (raias) coloridas, que você pode recolher para ver melhor o quadro;
- Lista: todas as tarefas em formato de lista;
- Sprint ativa: o que o time está fazendo no ciclo de trabalho atual;
- Backlog: a fila de tudo o que ainda precisa ser feito;
- Épicos e histórias: grandes objetivos (épicos) divididos em entregas menores (histórias);
- Bugs: registro e acompanhamento de erros;
- WBS: o projeto dividido em partes menores, como uma árvore;
- Gantt: o projeto em uma linha do tempo, mostrando o que acontece em cada período.
- 🗂️ Card (tarefa): ao abrir um card, um painel lateral mostra tudo sobre a tarefa: descrição, comentários, checklist, anexos, aprovação, código da tarefa (por exemplo, PROJ-1, PROJ-2) e campos personalizados criados pela sua empresa.
- 🏢 Agilidade em escala (SAFe): para empresas com muitos times trabalhando juntos. Inclui portfólio (conjunto de todas as iniciativas), ARTs (grupos de times que entregam juntos), times, requisitos, metas da organização e releases (entregas planejadas).
- 📊 Gestão: controle financeiro, acompanhamento de SLA e prazos (o tempo combinado para entregar), ordens de serviço (OS) de projeto, painéis com indicadores (dashboards), relatórios e uma visão geral de todos os projetos ágeis.
- 🔗 Centro de Aplicativos (integração com o GitLab): o GitLab é onde os desenvolvedores guardam o código. Agora ele conversa com o Agility:
- você pode conectar sua conta pessoal e também a conta do espaço de trabalho;
- é possível ligar projetos do GitLab aos projetos do Agility;
- quando o desenvolvedor salva uma alteração no código (commit) ou cria uma ramificação de trabalho (branch) usando o código do card, ela é ligada ao card automaticamente.
- Dentro do card, você tem:
- um painel com as informações do Git;
- a atividade do Git registrada no histórico da tarefa;
- botões para criar uma branch, um pedido de junção de código (merge request) e uma issue (registro de problema ou tarefa no GitLab);
- o status da tarefa atualizado conforme o andamento no Git;
- uma prévia dos links do GitLab, sem precisar abrir;
- o andamento das verificações automáticas do código (pipeline);
- as aprovações.
- 🔑 API: cada usuário pode gerar suas próprias chaves de acesso para integrar outros sistemas ao Agility. A documentação da API fica disponível no Swagger, uma página que mostra como usar cada recurso.
- 🤖 Inteligência Artificial: a IA ajuda a estimar o esforço das tarefas e funciona como assistente. A empresa escolhe qual provedor de IA quer usar.
- 🌐 Plataforma:
- Vários clientes no mesmo sistema (multi-tenant): cada cliente acessa o Agility pelo seu próprio endereço, gerenciado pelo Tenancit;
- Login seguro: a entrada no sistema é feita pelo Keycloak (padrão OIDC);
- Dados separados: cada cliente tem seu próprio banco de dados PostgreSQL, sem misturar informações.
O passo a passo usa os arquivos de configuração do kit agility-tenancit/k8s. Nos textos abaixo, troque os marcadores (entre < >) pelos valores do seu ambiente:
Marcador | Exemplo em homologação |
|---|---|
<NAMESPACE> | agility-hom |
<HOST_AGILITY> | agility-hom.centralit.com.br |
<URL_TENANCIT> | https://tenancit-hom.centralit.com.br |
<URL_KEYCLOAK> | https://auth-hom.centralit.com.br |
<REALM> | central-prd |
<TENANT> | agility-approval |
🔒 Atenção: senhas, client secrets e tokens nunca devem ser escritos neste texto nem enviados ao Git. Gere cada um na hora da instalação e guarde no cofre de senhas do time.
✅ Antes de começar, confira se você tem:
- o Tenancit funcionando, instalado conforme o arquivo k8s/tenancit/readme.md do kit;
- o endereço (DNS) com certificado de segurança para <HOST_AGILITY> e para o Tenancit;
- um PostgreSQL 16 que o cluster consiga acessar;
- a credencial de download das imagens (pull secret harbor-cithyper) do repositório Harbor repositorio.cithyper.click.
1️⃣ Criar o banco de dados
O administrador do banco (DBA) deve executar no PostgreSQL:
CREATE ROLE usr_agility LOGIN PASSWORD '<SENHA_DO_BANCO>' NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION;
CREATE DATABASE db_agility OWNER usr_agility;
\connect db_agility
CREATE SCHEMA agility AUTHORIZATION usr_agility;
ALTER DATABASE db_agility SET search_path = agility;
ALTER ROLE usr_agility IN DATABASE db_agility SET search_path = agility;
CREATE EXTENSION IF NOT EXISTS pg_trgm WITH SCHEMA agility;
CREATE EXTENSION IF NOT EXISTS unaccent WITH SCHEMA agility;🔍 Para conferir: rode SHOW search_path;. A resposta precisa ser agility, e as duas extensões (pg_trgm e unaccent) precisam aparecer no schema agility.
2️⃣ Cadastrar as definições de recurso no Tenancit
Acesse <URL_TENANCIT>, abra Recursos → Nova definição e crie as duas definições abaixo.
Definição postgres (Key e Nome: postgres)
Key | Tipo | Obrigatório | Segredo |
|---|---|---|---|
host | Texto | sim | não |
database | Texto | sim | não |
port | Texto | sim | não |
username | Texto | sim | não |
password | String | sim | sim |
sslmode | Texto | não | não |
Definição keycloak (Key e Nome: keycloak)
Key | Tipo | Obrigatório | Segredo |
|---|---|---|---|
issuer | Texto | sim | não |
client_id | Texto | sim | não |
audience | Texto | sim | não |
directory_client_id | Texto | sim | não |
client_secret | Texto | sim | sim |
directory_client_secret | Texto | sim | sim |
3️⃣ Criar o tenant (cliente) e ligar o banco de dados
- Acesse Tenants → Novo tenant e preencha Nome e slug com <TENANT>.
- Dentro do tenant, abra a aba Recursos → Adicionar recursos → postgres e use o alias agility.postgres. Preencha:
- host: o IP ou endereço do PostgreSQL;
- port: 5432;
- database: db_agility;
- username: usr_agility;
- password: <SENHA_DO_BANCO>;
- sslmode: disable, ou o modo que o banco exigir.
4️⃣ Configurar o login no Keycloak
Faça tudo no realm <REALM>. ⚠️ Ele nem sempre é o mesmo realm do Tenancit.
- Importe os arquivos client-agility-kc.json (client agility) e client-agility-directory-kc.json (client agility-directory).
- No client agility, troque os endereços pelos de <HOST_AGILITY>:
- Valid redirect URIs: https://<HOST_AGILITY>/v1/auth/callback;
- Valid post logout redirect URIs: https://<HOST_AGILITY>/*;
- Web origins: https://<HOST_AGILITY>.
- Apague os endereços de outros ambientes que vierem no arquivo.
- No client agility-directory, abra Service accounts roles → Assign role → realm-management e marque somente view-users e query-users.
- Na aba Credentials, copie o Client secret dos dois clients. Você vai usá-los no passo 5.
📘 Os detalhes de cada tela estão no guia docs/operators/keycloak-realm-do-agility.md. Ele foi criado na v1.1.0, mas também vale para a v1.0.0, exceto o grupo de administradores (passo 10 do guia).
5️⃣ Ligar o Keycloak e o endereço do sistema ao tenant
- No tenant, abra Recursos → Adicionar recursos → keycloak e use o alias agility.keycloak. Preencha:
- issuer: <URL_KEYCLOAK>/auth/realms/<REALM>. Tire o /auth se o seu Keycloak não usar esse prefixo;
- client_id: agility;
- audience: agility-api;
- directory_client_id: agility-directory;
- client_secret e directory_client_secret: os dois secrets copiados no passo 4.
- Na aba Domínios → adicionar, informe <HOST_AGILITY> sem o https://.
6️⃣ Criar a chave de acesso do Tenancit para o Agility
- Acesse Chaves de API → Nova chave.
- Crie uma chave com o nome do ambiente e validade de 365 dias.
- Copie o token (ele começa com tnc_…). Ele será usado no passo 7.
⏰ Anote a data de vencimento! Quando a chave vencer, o Agility deixa de encontrar os tenants e para de funcionar para os clientes.
7️⃣ Instalar no Kubernetes / OpenShift
- Crie a namespace <NAMESPACE> (o "espaço" do Agility dentro do cluster).
- Se a credencial de download das imagens ainda não existir na namespace, ajuste e aplique o arquivo secret-harbor.yaml (pull secret harbor-cithyper).
- Ajuste e aplique o arquivo secret-agility.yaml (Secret agility-secrets) com três chaves:
- TENANCIT_TOKEN: o token criado no passo 6;
- SESSION_COOKIE_KEY: 32 bytes em base64, gerados com openssl rand -base64 32;
- AGILITY_DIRECTORY_REF_KEY: outros 32 bytes em base64, diferentes da chave anterior. ⚠️ Se as duas forem iguais, o sistema não inicia.
- No arquivo agility.yaml, troque:
- namespace pelo valor de <NAMESPACE>, em todos os objetos;
- TENANCIT_URL, no ConfigMap e no Job, pelo endereço interno do Tenancit no cluster: http://tenancit.<namespace-do-tenancit>.svc.cluster.local:8080;
- TENANCIT_DATABASE_HOSTS, no ConfigMap e no Job, por <HOST_AGILITY>;
- AGILITY_OIDC_TRUSTED_ISSUER_ORIGINS por <URL_KEYCLOAK>, sem /auth e sem barra no final;
- AGILITY_FRAME_ANCESTORS pelo endereço do portal que exibe o Agility dentro de outra página (iframe), se houver.
- Aplique o agility.yaml. A rotina agility-migrate prepara o banco de dados (atualizações 00001 a 00081) e o sistema sobe com 2 cópias funcionando ao mesmo tempo (réplicas).
- ⏳ Até essa rotina terminar, o sistema pode reiniciar ou ficar fora do ar. Isso é normal.
- No arquivo route-agility.yaml, ajuste o host para <HOST_AGILITY> e aplique. Se o cluster não for OpenShift, use um Ingress no lugar da Route.
8️⃣ Conferir se está tudo funcionando
Rode os comandos abaixo, um de cada vez:
kubectl -n <NAMESPACE> wait --for=condition=complete job/agility-migrate --timeout=600s
kubectl -n <NAMESPACE> rollout status deploy/agility
curl -fsS https://<HOST_AGILITY>/readyzDepois, abra https://<HOST_AGILITY> no navegador e entre com uma conta do realm. 🎯 Se o login funcionar, a instalação está concluída!
- 🔁 A rotina de preparação do banco sempre tem o mesmo nome. Antes de instalar de novo, apague a rotina antiga: kubectl -n <NAMESPACE> delete job agility-migrate.
- ⚠️ As atualizações do banco de dados não podem ser desfeitas. Para voltar a uma versão anterior, é preciso restaurar o backup do banco. Por isso, sempre faça backup antes de atualizar.