Als Contributor starten

PLAN

Dein Teil und der Teil, der ohne dich läuft

Fünf Dinge sind deine: das Repository forken, den Dev-Container starten, hike laufen lassen, patrol laufen lassen und den Pull Request öffnen. Die Prüfungen, die Vorschauseite und der Merge laufen von selbst.

BASE

Zwei Installationen und ein Login genügen

Ein STACKIT-Account zum Anmelden. Docker Desktop oder podman und VS Code. Ein Access-Token. Alles andere, von Node bis zum Testbrowser, steckt schon im vorgebauten Image.

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

BASE

Ein Login bringt dich ins Team

Melde dich einmal über die STACKIT IDP an. Dabei entsteht dein Git-User, und eine Pipeline nimmt dich innerhalb von 15 Minuten ins Contributors-Team auf. Niemand muss dich einladen.

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

Wie dein Name erscheint Dein Name ist hier öffentlich, welcher Name das ist entscheidest du.

Beitragen ist hier öffentlich. Dein Name erscheint, sobald du ihn in einem kurzen Formular freigibst. Bis dahin steht dort Name nicht öffentlich. Pseudonyme und Initialen gehen auch.

Von deiner Erklärung zu dem, was Leser sehen: du erklärst, drei Prüfungen, ein Branch wird vorbereitet, er wird gemergt, der tägliche Abgleich zeigt die freigegebenen Felder

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

STEP

Rechner vorbereiten

Guide

Contributor Setup: From Login to First Pull Request

STACKIT

Advisory contributors onboarding dev container setup

Open Source In 1 Trail

Set up your authoring environment: sign in once, create a token, pull the dev container, run the docs site locally, and open your first pull request.

Owner

STACKIT

Der souveräne europäische Cloud-Anbieter hinter dem Framework, mit IaaS und PaaS aus deutschen und österreichischen Rechenzentren und voller Unabhängigkeit.

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

Guide

Contributor Setup: From Login to First Pull Request

STACKIT

Advisory contributors onboarding dev container setup

Open Source In 1 Trail

Set up your authoring environment: sign in once, create a token, pull the dev container, run the docs site locally, and open your first pull request.

Owner

STACKIT

Der souveräne europäische Cloud-Anbieter hinter dem Framework, mit IaaS und PaaS aus deutschen und österreichischen Rechenzentren und voller Unabhängigkeit.

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

Guide

Contributor Setup: From Login to First Pull Request

STACKIT

Advisory contributors onboarding dev container setup

Open Source In 1 Trail

Set up your authoring environment: sign in once, create a token, pull the dev container, run the docs site locally, and open your first pull request.

Owner

STACKIT

Der souveräne europäische Cloud-Anbieter hinter dem Framework, mit IaaS und PaaS aus deutschen und österreichischen Rechenzentren und voller Unabhängigkeit.

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

SAFE

Ein Token öffnet Repository und Image

Du erstellst es auf der Git-Instanz unter Settings, Applications. Es ist dein Passwort für den Klon und für das Image. Es wird genau einmal angezeigt, also sichere es im Passwortmanager.

Access-Token mit zwei Berechtigungen: repository Read and Write, package Read

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

AUTO

Der Login gehört auf deinen Rechner, nicht in den Container

Melde dich mit deinem Git-Username und dem Token als Passwort an und ziehe das Image. Das läuft in einem Terminal auf deinem Rechner. Im Container gibt es weder docker noch podman.

Terminal auf deinem Rechner: docker login, danach docker image pull für das Image scf-system

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

LIFT

Dein Fork wird zum Inhalt der App

Forke das geteilte Repository, klone deinen Fork und hänge das geteilte als upstream an. Dann öffnest du den Ordner in VS Code und wählst Reopen in Container.

Terminal: git clone deines Forks, cd scf-content, git remote add upstream

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

LIFT

Jedes Speichern erscheint sofort im Browser

Starte hike im Container-Terminal. Die echte Seite öffnet sich auf localhost:4321, mit denselben Komponenten, die deine Leser sehen. Jedes Speichern erscheint innerhalb einer Sekunde. help zeigt die übrigen Werkzeuge.

Das Cloud Framework läuft auf localhost:4321

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

WARN

Drei Fallen kosten die meisten ersten Tage

Das Token wird nur einmal angezeigt. Der Registry-Login gehört auf deinen eigenen Rechner. Unter Windows bricht ein Klon unter /mnt/c still das Hot Reload.

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

STEP

Das Studio schreibt das Frontmatter für dich

Am Frontmatter scheitern die meisten ersten Pull Requests. Das SCF Studio schreibt es aus einem Formular, mit gültiger Beschreibung, Kategorie und Tags. Es läuft in deinem Container und auf der Dev-Seite.

Das SCF Studio: rechts ein Formular, links der Aufstieg von Seite zu Seite

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

OPS

patrol prüft, bevor die Pipeline prüft

patrol führt lokal aus, was die Pipeline ausführt: den Build, die UI-Tests und einen Durchlauf durch alles, was du geändert hast. Ein paar Minuten hier sparen eine Review-Runde.

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

LIVE

Dein Teil endet mit dem Pull Request

Pushe deinen Branch in deinen Fork und öffne den Pull Request. Die Pipeline prüft ihn, baut eine Vorschauseite für das Review und merged nach der Freigabe selbst, wenn du den Haken setzt.

Vom Zugang zur veröffentlichten Seite: Wächter, Prüfungen, Bericht, Checklisten-Gate, Review, Merge

Contributing to the STACKIT Cloud Framework means writing content, not running an application. The whole docs app ships as a prebuilt dev container image, and your clone of the content repository is mounted into it. This guide takes you from having nothing installed to an open pull request.

What You Need Before You Start

Three things, and only the first two touch your machine:

A STACKIT account. It is the identity you log in with, and it onboards you automatically.
A container runtime and an editor. Docker Desktop or podman, plus Visual Studio Code with the Dev Containers extension.
An access token from the Git instance, which you create in a later step and use as your password for both cloning and pulling the image.

You never need access to the application repository. Everything the site needs to build, Node, the docs app, the diagram toolchain and the test browser, is already inside the image.

Creating a STACKIT Account

If you do not have a STACKIT login yet, create one first at accounts.stackit.cloud , then come back to the next step.

Use a personal work address for it, in the form firstname.lastname@company.com. The Git instance builds your username from the part before the @. You cannot change that username later.

If the login works but the Git instance rejects you afterwards, your account is probably not in the STACKIT organization that hosts the instance. Contact Framework Core and we will sort it out.

Log in once via the STACKIT IDP at scf-content.git.onstackit.cloud . That single login does two things:

It creates your STACKIT Git user. Your username is the part of your mail address before the @, so with a personal address it reads firstname.lastname.
It queues you for the contributors team. A pipeline adds every IDP-authenticated user to the team every 15 minutes, so onboarding is self-service and nobody has to invite you.

How Your Name Appears

Contributing here is public. The site credits people by name in two places: the history timeline on every asset and trail, and the Maintainers block on the pages you are listed for. That is the point of the credit, and you decide which name it is.

Three separate sources feed it:

Swipe sideways to see the whole table

Where	Comes from	You change it in
History timeline	the author of your commits, shown as who and when	`git config user.name` in your clone
Maintainers credit	the Full name of your STACKIT Git profile, mirrored daily once you have declared it	your Git profile
The profile panel that opens on hover	your biography, website, address and contribution record	your Git profile, once you have declared them

Your commit messages never appear on the site. The timeline names the author and the date and nothing else, because a commit message is written for the repository rather than for a reader.

Nothing is shown until you release it yourself, your name included. You do that once, in a declaration: open an issue in the content repository with the Contributor declaration template and tick the details you want shown. Framework Core or your framework owner records the result in settings/contributor-members.json, which is the only place the site reads it from. You cannot edit that file yourself. That is deliberate.

Until your declaration is recorded there, the daily pipeline publishes nothing about you, so a maintainer credit without one reads as an anonymous contributor with no hover panel at all. Your commits still carry your name inside the repository, as they do in any repository, but the website does not repeat it. A detail you did not release is not merely hidden: it is never fetched from your profile and never written down anywhere. Writing role: true next to your name in an asset does nothing either. Only the person a field describes can release it. A content file is not that person.

Two details are worth knowing before you tick the boxes. Your address only appears if you also made it public in your Git profile, because the API hands out a no-reply placeholder otherwise, and that is not a contact. Your contribution record is matched through the address on your commits, so it counts the commits you author under your own account. To change or withdraw any of it later, comment on your own declaration issue.

A pseudonym, a short form or just your initials are all fine in either place. Emptying the Full name works too: after the next mirroring run the maintainers credit shows “Anonymous contributor”, it never falls back to your username. If you would rather not have your private address in the commit history, set a no-reply identity in the same breath:

git config user.name  "Your display name"
git config user.email "your-username@noreply.scf-content.git.onstackit.cloud"

Your address is never shown unless you ask for it: it appears only when a page lists it explicitly, or when you both made it public in your Git profile and the page opts in.

Prepare Your Machine

Install these two, in any order:

Docker Desktop or podman. Either works. With podman, do the two settings in the next section.
Visual Studio Code with the Dev Containers extension. The extension is what turns the prebuilt image into your working environment.

Nothing else gets installed. No Node, no pnpm, no build tools on your host.

Podman: Two Settings to Get Right

With Docker Desktop you skip this section.

Point VS Code at podman. Open the settings (Ctrl + ,, on the Mac ⌘ + ,), search for dev containers path, change Dev > Containers: Docker Path from docker to podman, then restart VS Code. Without it the extension looks for a docker binary that is not there and the container never starts.

Give the machine memory and disk. The build and the test suite run inside the podman machine and the default one is too small for them. Set it up with room from the start:

podman machine init --memory 8192 --cpus 4 --disk-size 60
podman machine start

If your machine already exists, adjust it afterwards:

podman machine stop
podman machine set --memory 8192 --cpus 4
podman machine start

Windows: Clone Into WSL2

On Windows, do all of this inside WSL2 and clone into the Linux file system, for example ~/projects/scf-content.

A clone under /mnt/c/... looks like it works: the container starts, the site builds, the page loads. But file change events do not cross the Windows to Linux boundary reliably, so hot reload never fires and your edits appear to have no effect until you restart the server.

Create an Access Token

On the Git instance, open Settings, then Applications, then Generate new token. Grant exactly these permissions:

Permission	Level	Needed for
`repository`	Read and Write	cloning the content repo, pushing branches
`package`	Read	pulling the prebuilt dev container image

Above the permission list sits a dropdown called Repository and Organization Access. Leave it on All (public, private and limited). On “Public only” the token cannot see the private content repository at all, and cloning as well as the registry login fail with a 403 even though every permission above is set correctly.

Log In to the Registry

Log in with your Git username and the token as the password, then pull the image:

docker login scf-content.git.onstackit.cloud
docker image pull scf-content.git.onstackit.cloud/scf-core/scf-system:latest

podman is a drop-in replacement here: podman login and podman image pull take exactly the same arguments.

Pulling the image up front is optional, VS Code pulls it for you on the first container start. Doing it manually just makes the first start faster and shows you early whether the login worked.

The image is multi-arch: the same pull gives Intel and Windows machines the amd64 variant and Apple Silicon Macs the native arm64 variant, automatically. When you pull a newer image later, follow it with Rebuild Container in VS Code, because a plain reopen keeps the cached old container running. Superseded image versions pile up as untagged leftovers, so run docker image prune (or podman image prune) on your machine now and then to clear them out.

Fork, Clone and Reopen in the Container

The content repository grants read access only, so your fork is the place you push to. Everybody works this way, Framework Core included. Open scf-core/scf-content and press Fork, then clone your copy with your Git username and the token as credentials:

git clone https://scf-content.git.onstackit.cloud/<your-username>/scf-content.git
cd scf-content
git remote add upstream https://scf-content.git.onstackit.cloud/scf-core/scf-content.git

The upstream remote is how you pull later changes from the shared repository into your fork.

One thing to know before you branch: your fork copies every branch this repository has on the day you fork it, half-finished ones included. Start new work from upstream/main and from nothing else, which is also why a fork that has fallen behind cannot get in your way. When you do want it up to date, your fork’s page shows a green banner with a button that does it in one click. On our instance that button still carries its untranslated label repo.sync_fork.button, so go by the green banner rather than by the wording. A branch you have kept for weeks wants main merged into it before you open the next pull request.

Open the folder in VS Code. It detects the dev container configuration and offers Reopen in Container, which is also available from the command palette. The first start pulls the image and takes a few minutes; every later start is quick.

Your clone is mounted into the prebuilt app as its content, which is why you can preview the complete site without ever touching the application repository.

Where Your Logins Are Stored

You enter the token twice because two different tools remember it in two different places, and knowing where saves you a confusing afternoon later:

Git asks once per Git host and then stores the login in your operating system’s credential store: the Keychain on macOS, the Credential Manager on Windows. Every later git fetch and git push against that host replays it silently.
Docker and podman keep their own store (for example ~/.config/containers/auth.json). The two do not share anything, which is why the registry login is its own step.

There is no git logout. When you rotate a token, or signed in with the wrong account, git keeps replaying the stored login and never asks again — the fix is to clear the stored entry so the next fetch or push prompts fresh (in the VS Code terminal that prompt appears as an input box at the top of the window, not in the terminal):

printf "protocol=https\nhost=scf-content.git.onstackit.cloud\n\n" | git credential reject

On Windows you can alternatively open the Credential Manager and remove the git:https://scf-content.git.onstackit.cloud entry there. To see which account macOS currently has stored for the host:

security find-internet-password -s scf-content.git.onstackit.cloud | grep acct

Your commit identity is a separate thing entirely: git config user.name and user.email decide how your commits are labelled, the stored login only decides who you authenticate as when pushing.

Run hike and Open the Site

In the container terminal, run:

hike

The same thing is available as the VS Code task 🥾 Hike, Start Dev Docs. The site is forwarded to http://localhost:4321 with hot reload, so every save shows up in the browser within a second.

Type help to see the full tool belt:

Swipe sideways to see the whole table

Command	What it does
`hike`	dev server with hot reload on `http://localhost:4321`
`summit`	full production build
`panorama`	serve the built site
`patrol`	build plus the complete UI test suite, the same gate as your PR
`scout`	how to update the dev container image

Three Traps Worth Knowing

Almost every failed setup comes down to one of these:

The access token is shown exactly once. Save it before you close the dialog.
The registry login belongs on your own machine. Inside the container there is no container runtime to log in with.
On Windows, a clone under /mnt/c silently breaks hot reload. Work inside WSL2 and clone into the Linux file system.
A token created with “Public only” access fails with 403, even though every permission looks right. Set the access dropdown to All when generating it.
After rotating a token, git still replays the old one from your credential store and never prompts again. Clear the stored entry as shown in “Where Your Logins Are Stored”.

Author With the Studios

Branch off upstream/main rather than off your own main, then write:

git fetch upstream
git switch -c content/short-description upstream/main

Your fork’s main falls behind the moment somebody else contributes, and a branch started on top of it drags that gap into your pull request. Fetching first costs a second and takes the question away entirely. When you do want the fork itself tidy, CONTRIBUTING has the commands for that.

For new pages, use the studios instead of copying frontmatter by hand:

SCF Studio, at http://localhost:4321/studio, writes a contributor profile, an asset, a trail or a framework page. It also loads an existing file and changes only what you edit, so everything you leave alone stays exactly as it was.
Diagram Studio, at http://localhost:4321/diagrambuilder, draws a diagram in the SCF design and saves it next to your page.

Both run on your local dev server, and the SCF Studio runs on the dev site as well. It writes frontmatter that already satisfies the pipeline’s rules: a real description in the rewarded 120 to 160 character window, a category from the allowed list and at most 10 tags.

For the authoring rules behind the generated files, see the asset integration guide and the trail setup guide.

Run patrol Before the Pull Request

patrol

patrol reproduces what the pipeline runs: the production build, the UI test suite, and a walkthrough of every asset, trail and profile your branch touched. It takes a few minutes and saves you a review round, because a green patrol almost always means a green pull request.

Open Your Pull Request

Push your branch to your fork and open a pull request against main of the shared repository. The description arrives prefilled with three confirmations you have to tick: that you hold the rights to what you contribute, that it carries nobody’s personal data and nothing confidential, and that every link points at an official source. A separate check reads them and stays red until all three are ticked, so keep the prefilled text in place rather than replacing it with your own.

On the files your pull request touches, the pipeline checks:

frontmatter, description present and a real summary (120 to 160 characters is rewarded, not enforced), valid category, at most 10 tags
reference links, a link standing on its own line must be a <LinkCard> or <LinkChip>, and their on-site targets must exist — see the asset integration guide
internal links, including anchors, relative links and locale mixing
wording, no obscene or derogatory language
file size, nothing above 1 MB
secrets, accidentally committed credentials are rejected
markup safety, no scripts, inline styles, event handlers or remote-loading resources in content pages
trail integrity, every trail step reference must still resolve

It then builds the full site, runs the UI tests and posts a report on your pull request. A temporary, password-protected preview site is optional: tick the preview box in the description and your pages go up within fifteen minutes of the checks turning green, follow every push, then disappear when the pull request closes. Nothing depends on it, patrol shows you the same result locally.

A Framework Core reviewer approves and merges. You can also tick the automatic-merge box, then the merge happens on its own within ten minutes of an approval landing on a green pull request. Either way your content goes live with the next site deployment.

Where to Go Next

Cloud Framework Contributor Profile Registration Guide Register your organization with a contributor profile so your assets and trails resolve to you, or use the shared open-contributors entry if no company stands behind the work. Seite öffnen

GOAL

Du bist Contributor

Das Einrichten machst du einmal, das Schreiben immer wieder. Die Onboarding-Journey führt durch das Anlegen deines Contributor-Profils, das Frontmatter-Schema für Assets und den Bau eines eigenen Trails.

STACKIT

Dein erster Beitrag: Profil, Asset, Trail

Drei Stationen zu deinem ersten Beitrag: ein Profil, das sagt, wer du bist, ein Asset mit deinem Wissen und ein Trail, der deine Assets verbindet.

Advisory getting-started contributing authoring

Trail Steps

Drei Stationen zu deinem ersten Beitrag
Eine Seite stellt dich vor
Wo deine Dateien liegen
Aus deinen Metadaten wird die Karte

+ 7 more steps

Als Contributor starten