Ouvrir Astrolabe à tes outils

Certains de tes outils appellent Astrolabe tout seuls : GitHub envoie un webhook, un pipeline déclare un déploiement, un assistant IA lit le catalogue. Ce sont des programmes, pas des personnes : ils ne passent jamais par une page de connexion.

Si un proxy de connexion protège ton Astrolabe (Cloudflare Access, oauth2-proxy, l'authentification unique de ton entreprise), il doit laisser passer ces adresses. Cette page les liste toutes, dit pourquoi chacune est appelée et ce qui la protège, et montre comment les ouvrir.

⚙️ Pourquoi c'est important

Un proxy de connexion répond à un programme comme à une personne : avec sa page de connexion. Beaucoup de proxys envoient cette page avec le statut 200. L'outil lit 200 et croit son appel livré ; Astrolabe ne l'a jamais reçu. Rien ne casse bruyamment : le journal des événements reste vide, le déploiement ne s'affiche pas, l'assistant ne se connecte jamais.

Ouvrir ces adresses n'ouvre rien d'autre. Chacune vérifie elle-même qui l'appelle, avec le secret, le jeton ou l'accès indiqué ci-dessous.

📋 Les adresses

Remplace astrolabe.acme.example par l'adresse de ton Astrolabe.

Webhooks

Chaque outil envoie ce qui vient de se passer au journal des événements et aux notifications. Sans son webhook, Astrolabe relit l'outil toutes les quelques minutes.

Méthode	Adresse	Appelée par	Ce qui la protège	Si elle est fermée
POST	/api/orion-events/github	GitHub	Le secret du webhook, dans l'en-tête X-Hub-Signature-256	Administration › Webhooks dit Aucun appel reçu depuis le démarrage d'Astrolabe. alors que GitHub affiche ses livraisons réussies
POST	/api/orion-events/gitlab	GitLab	Le secret du webhook, dans l'en-tête X-Gitlab-Token	Pareil, pour GitLab
POST	/api/orion-events/jira	Jira	Le secret du webhook, dans l'en-tête X-Hub-Signature	Pareil, pour Jira
POST	/api/orion-events/argocd	Argo CD	Le secret du webhook, dans l'en-tête X-Argocd-Token	Pareil, pour Argo CD
POST	/api/orion-events/sonarqube	SonarQube	Le secret du webhook, dans l'en-tête X-Sonar-Webhook-HMAC-SHA256	Pareil, pour SonarQube
POST	/api/orion-events/grafana	Grafana	Le secret du webhook, dans l'en-tête Authorization	Pareil, pour Grafana
POST	/api/orion-events/azure	Azure DevOps	Le secret du webhook, dans l'en-tête X-Azure-DevOps-Token ou Authorization	Pareil, pour Azure DevOps

Les secrets se posent dans Administration › Webhooks : Poser le secret du webhook.

Pipelines

Méthode	Adresse	Appelée par	Ce qui la protège	Si elle est fermée
POST	/api/release-manager/pipeline/projects/{project}/environments/{environment}	Ton pipeline (GitHub Actions, GitLab CI, Jenkins…), à la fin d'un déploiement	Le jeton de pipeline, dans l'en-tête Authorization: Bearer	Le pipeline reçoit une page HTML ou une redirection au lieu de JSON ; la version ne s'affiche jamais dans Déploiements

Le jeton se génère dans Administration › Plugins › Déploiements : Déclarer les déploiements depuis tes pipelines.

Assistants IA

L'assistant de tes utilisateurs (Claude, Cursor…) se connecte au serveur MCP d'Astrolabe. L'utilisateur l'approuve une fois dans son navigateur ; ensuite l'assistant appelle ces adresses tout seul.

Méthode	Adresse	Appelée par	Ce qui la protège	Si elle est fermée
POST	/api/mcp-actions/v1/astrolabe	L'assistant, pour lire le catalogue avec les droits de l'utilisateur	L'accès qu'Astrolabe a donné à l'assistant, dans l'en-tête Authorization: Bearer	L'assistant ne se connecte pas, ou dit que le serveur ne répond pas
GET	/.well-known/oauth-protected-resource/api/mcp-actions/v1/astrolabe	L'assistant, pour savoir qui donne l'accès au serveur	Rien à protéger : une description publique, sans donnée	L'assistant ne propose jamais l'approbation
GET	/.well-known/oauth-authorization-server/api/auth	L'assistant, pour savoir où demander son accès	Rien à protéger : une description publique, sans donnée	L'assistant ne propose jamais l'approbation
GET	/api/auth/.well-known/openid-configuration	Certains assistants, pour la même description	Rien à protéger : une description publique, sans donnée	Ces assistants ne proposent jamais l'approbation
POST	/api/auth/v1/token	L'assistant, pour changer l'approbation de l'utilisateur en accès, puis le renouveler	Le code d'approbation ou le jeton de renouvellement qu'Astrolabe lui a donné	L'utilisateur approuve l'assistant, puis l'assistant échoue à se connecter ; plus tard, la connexion tombe quand l'accès expire

Le serveur MCP est éteint tant qu'un administrateur ne l'allume pas : Allumer le serveur MCP.

Supervision

Seulement si ta supervision tourne hors de ton réseau.

Méthode	Adresse	Appelée par	Ce qui la protège	Si elle est fermée
GET	/.backstage/health/v1/readiness	Ta supervision	Rien à protéger : un état, sans donnée	Ta supervision lit la réponse du proxy : Astrolabe paraît en panne, ou toujours debout

Ce qui reste derrière ta connexion

Tout le reste. Les gens ouvrent Astrolabe dans leur navigateur, se connectent d'abord à ton proxy, puis à Astrolabe : la page de connexion, l'approbation d'un assistant et chaque écran passent par ton proxy comme d'habitude. N'ouvre rien de plus que les adresses ci-dessus.

🔧 Les laisser passer

Avec Cloudflare Access

1. Dans Cloudflare Zero Trust, ouvre Access › Applications et clique sur Add an application.

2. Choisis Self-hosted.

3. Ajoute une destination par ligne de ce tableau, sur le domaine de ton Astrolabe :

   Chemin
   api/orion-events
   api/release-manager/pipeline
   api/mcp-actions
   .well-known
   api/auth/.well-known
   api/auth/v1/token

   Ajoute aussi .backstage/health si ta supervision est hors de ton réseau.

4. Ajoute une règle avec l'action Bypass, et inclus Everyone.

5. Enregistre l'application.

L'application qui protège tout le domaine reste telle quelle : Cloudflare applique d'abord le chemin le plus précis. Cette étape n'a pas été vérifiée sur une instance.

Avec oauth2-proxy

Donne-lui les adresses à laisser passer, un --skip-auth-route par ligne :

--skip-auth-route='POST=^/api/orion-events/'
--skip-auth-route='POST=^/api/release-manager/pipeline/'
--skip-auth-route='^/api/mcp-actions/'
--skip-auth-route='GET=^/\.well-known/'
--skip-auth-route='GET=^/api/auth/\.well-known/'
--skip-auth-route='POST=^/api/auth/v1/token$'

Ajoute --skip-auth-route='GET=^/\.backstage/health/' si ta supervision est hors de ton réseau. Cette étape n'a pas été vérifiée sur une instance.

✅ Vérifier

Depuis une machine hors de ton réseau, sans te connecter à ton proxy :

curl -s -X POST https://astrolabe.acme.example/api/orion-events/github

Astrolabe répond lui-même, en JSON :

{"error":{"name":"AuthenticationError","message":"Missing credentials"}, …}

L'appel est refusé parce qu'il n'a pas de secret : c'est normal, il a atteint Astrolabe. Une page HTML, ou une redirection vers une page de connexion, veut dire que le proxy a répondu à sa place : reviens à Les laisser passer.

Fais ensuite un vrai appel depuis l'outil : pousse un commit, ou clique sur Redeliver sur la dernière livraison du webhook dans GitHub. Administration › Webhooks dit maintenant Dernier appel accepté le suivi d'une date.

🆘 Problèmes courants

Ce que tu vois	Que faire
GitHub affiche les livraisons réussies (200), et Administration › Webhooks dit Aucun appel reçu depuis le démarrage d'Astrolabe.	Ouvre la dernière livraison dans GitHub (Settings › Webhooks › Recent Deliveries) et lis le corps de la Response. Une page de connexion (par exemple Sign in ・ Cloudflare Access) veut dire que ton proxy a répondu : laisse passer l'adresse.
L'appel du pipeline répond en HTML, ou suit une redirection	Même cause : laisse passer l'adresse du pipeline, dans le tableau Pipelines.
L'assistant ouvre la page d'approbation, tu approuves, puis l'assistant dit qu'il ne peut pas se connecter	Une adresse du tableau Assistants IA est fermée dans ton proxy : ouvre-les toutes.
Le curl de Vérifier répond {"error":{"name":"AuthenticationError","message":"Missing credentials"}, …} mais Administration › Webhooks dit que la source signe avec un autre secret	L'adresse est ouverte ; le secret diffère. Voir Problèmes courants avec les webhooks.

Toujours bloqué ?

Écris à support@forgeit.fr avec l'adresse que l'outil appelle et le corps de la réponse qu'il affiche.