Backstage är inte plattformen — det är dörren till den

BackstageUtvecklarportal (Backstage)En utvecklarportal är den interna webbplats där en organisations tjänster, team, ägarskap, dokumentation och självbetjäningsmallar samlas på ett ställe. Backstage, som Spotify öppnade som open source 2020, är det vanligaste ramverket att bygga en på.Läs mer i ordlistan → har stått i produktion sedan i våras. Katalogen är fylld, TechDocs renderar, varje team har en egen sida med ägarskap och länkar. Och när ett nytt team ska sätta upp sin första tjänst öppnar de… Slack. Samma fråga som förut: ”hur brukar vi göra?” Portalen visar vad som finns. Den kan fortfarande inte göra något åt det.

Det är den vanligaste besvikelsen med utvecklarportaler, och den beror sällan på verktyget. En utvecklarportal — developer portal på engelska — är dörren till den interna utvecklarplattformen. Den är inte plattformen. Finns det inget bakom dörren spelar det ingen roll hur snygg den är.

Tre saker en portal gör — och bara en av dem gör något

Skalar man bort pluginlistan gör en utvecklarportal tre saker:

• Katalogen svarar på ”vad finns, och vem äger det?”. System, tjänster, API:er, team. Det är portalens minsta värdefulla version, och den är värdefull — förutsatt att svaret stämmer.
• Dokumentationen svarar på ”hur fungerar det?”. TechDocs i Backstage renderar markdown från repot, vilket är rätt idé: dokumentationen bor hos koden, portalen visar den.
• Mallarna svarar på ”hur gör jag?”. Scaffoldern tar ett formulär och skapar repo, pipeline och grundstruktur. Det är den enda av de tre som faktiskt utför något — och den enda som gör att nästa team slipper öppna Slack.

De flesta bygger i den ordningen: katalog först, dokumentation sedan, mallar när det blir tid över. Det blir sällan tid över. Så portalen blir en katalog med en dokumentationsflik, och teamen fortsätter göra som de alltid gjort.

Där portaler dör

1. Katalogen som ruttnar. catalog-info.yaml skrevs en gång vid importen och rördes aldrig igen. Ägarskapet pekar på team som omorganiserades bort i höstas. En katalog som är fel är sämre än ingen katalog, för folk slutar lita på den. Lösningen är att filen bor i repot, att CI validerar den och att ägarskapet hämtas från samma ställe som CODEOWNERS.
2. Wiki med bättre tema. Sidorna flyttades från Confluence till TechDocs, men de ligger fortfarande i ett separat dokumentationsrepo som ingen ser i sin pull request. Då är de lika inaktuella som förut, bara i en annan font. Docs-as-code betyder en docs-mapp bredvid koden, byggd vid merge.
3. Mallen ingen underhåller. En scaffolder-mall som skapar ett repo som ligger ett halvår efter standarden gör mer skada än nytta: det nya teamet får en start som redan är fel. En mall är en produkt med en ägare och en livscykel — vi har skrivit om det i Sluta skriva wiki-sidor, börja bygga golden paths.
4. Fel mått. ”Antal registrerade komponenter” går alltid upp och säger ingenting. Måtten som säger något är hur många nya tjänster som skapades via mallen utan att någon tvingade fram det, och tiden från nytt repo till första deploy i produktion. Det är samma frivilliga adoption som avgör om plattformen bakom portalen fungerar.

Portalen är för människor. Repot är för alla.

Det finns ett skäl till att ordningen spelar roll som blivit tydligare det senaste året. En kodagentKodagentEn kodagent är ett AI-verktyg som inte bara föreslår kod utan själv utför uppgifter i ett repo: läser filer, kör kommandon och tester, ändrar kod och öppnar pull requests — styrt av en instruktion och de regler som finns i kodbasen.Läs mer i ordlistan → öppnar aldrig portalen. Den läser repot: catalog-info.yaml, docs-mappen, AGENTS.mdAGENTS.mdAGENTS.md är en kort fil i repots rot skriven för kodagenter, inte människor: hur projektet byggs, testas och körs, vilka konventioner som gäller och vad som inte får röras — det agenten behöver veta innan den ändrar något.Läs mer i ordlistan →, pipelinefilen. Om portalen är sanningen och repot en kopia får människor och agenter olika svar på samma fråga.

Vänd på det. Repot äger: ägarskap, dokumentation och mallar är filer under versionskontroll som CI kontrollerar. Portalen visar: den läser filerna och sätter ihop bilden. Då är portalen en vy över något som är sant oavsett om portalen finns — och en agent, en ny kollega och en incidentledare klockan tre på natten får samma svar. Vi skrev om den nya plattformsanvändaren i Er nästa plattformsanvändare är en agent.

Så börjar du

Ni behöver inte Backstage för att börja. Ni behöver veta vad dörren ska leda till:

1. Svara på ”vem äger den här tjänsten?” för allt som kör i produktion. Kan ni inte det är katalogen det första jobbet — och en fil per repo räcker för att börja, utan portal.
2. Välj den vanligaste resan, oftast ”ny backend-tjänst”, och bygg en mall som tar ett team från tomt repo till produktion utan att fråga någon. Det är portalens första riktiga funktion, och den fungerar från ett kommando lika bra som från ett formulär.
3. Flytta dokumentationen till repot och bygg den vid merge. Portalen visar, repot äger.
4. Sätt ett mått som inte är ”antal komponenter”: tid från nytt repo till första deploy, och andel nya tjänster som gick via mallen frivilligt.
5. Installera Backstage när ni har något att sätta bakom dörren. Då blir portalen det den ska vara: stället där en utvecklare ser vad som finns och kan göra något åt det.

Vårt korta svar

En utvecklarportal är dörren till plattformen, inte plattformen. Bygg det dörren ska leda till först — en mall som tar ett team till produktion — och låt repot vara sanningen som portalen visar.

En vacker dörr in i ett tomt rum imponerar exakt en gång.