---
title: "Getting Started as a Contributor"
description: "Set up your authoring environment step by step: sign in once, create a token, pull the dev container, preview the site locally, and open a pull request."
scfTrail:
  tags: ["getting-started", "contributing", "dev-container"]
  maintainers:
    - user: "tobias.mueller"
  steps:
    - style: "compass"
      id: "route"
      title: "Your Part and the Part That Runs Without You"
      trailContext: "Five things are yours: fork the repository, start the dev container, run hike, run patrol and open the pull request. The checks, the preview site and the merge run by themselves."
      imageSrc: "contributors/stackit/core/contribution-flow.svg"
      imageAlt: "Your part and the part that runs without you: fork, dev container, hike, patrol, pull request, then the automatic checks and the merge"

    - style: "hut"
      id: "before-you-start"
      title: "Two Installs and One Login Are All You Need"
      trailContext: "Contributing means writing content, not running an application. Three prerequisites, and only two of them touch your machine."
      center:
        text: "A STACKIT account to log in with. Docker Desktop or podman plus VS Code. One access token. Everything else, from Node to the test browser, already sits inside the prebuilt image."

    - role: sub
      id: "needs"
      title: "What you need, in detail"
      trailContext: "The three prerequisites and why you never need the application repository."
      assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#what-you-need-before-you-start"

    - role: sub
      id: "stackit-account"
      title: "No STACKIT account yet?"
      trailContext: "Create one first, then come back to the next step."
      assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#creating-a-stackit-account"

    - style: "hut"
      id: "sign-in"
      title: "One Login Puts You on the Team"
      trailContext: "One IDP login creates your Git user and queues you for the contributors team."
      center:
        text: "Log in once through the STACKIT IDP. That creates your Git user, and a pipeline adds you to the contributors team within 15 minutes. Nobody has to invite you."

    - role: sub
      id: "sign-in-howto"
      title: "Signing in, step by step"
      trailContext: "Which address to use and what helps when the wrong account is signed in."
      assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#sign-in-once-to-get-onboarded"

    - role: sub
      id: "your-name"
      title: "How your name appears"
      trailContext: "Your name is public here, and which name it is stays your choice."
      splitRatio: 40
      left:
        text: "Contributing here is public. Your name appears once you declare it in a short form. Until then the credit reads Name not public. Pseudonyms and initials work too."
      right:
        imageSrc: "contributors/stackit/core/contributor-consent.svg"
        imageAlt: "From your declaration to what a reader sees: you declare, three checks, a branch is prepared, it is merged, the daily mirror shows the released fields"

    - role: sub
      id: "your-name-details"
      title: "How your name appears, in detail"
      trailContext: "Where the name comes from, what you release and how to change it."
      assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#how-your-name-appears"

    - style: "stairs"
      id: "machine"
      title: "Prepare Your Machine"
      trailContext: "A container runtime and VS Code with the Dev Containers extension. Nothing else gets installed. Everything the site needs already sits in the prebuilt image."
      assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#prepare-your-machine"
      alternatives:
        - id: "mac-podman"
          label: "macOS with podman"
          assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#podman-two-settings-to-get-right"
          trailContext: "Point VS Code at podman and give the machine memory, otherwise the container never starts."
        - id: "windows"
          label: "Windows (WSL2)"
          assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#windows-clone-into-wsl2"
          trailContext: "A clone under /mnt/c looks fine and silently breaks hot reload."

    - style: "shield"
      id: "token"
      title: "One Token Opens the Repository and the Image"
      trailContext: "Repository read and write plus package read. The token is shown exactly once."
      splitRatio: 45
      left:
        text: "Create it on the Git instance under Settings, Applications. It is your password for the clone and for the image. It is shown exactly once, so save it in your password manager."
      right:
        imageSrc: "contributors/stackit/core/getting_started/token-scopes.png"
        imageAlt: "Access token with two permissions: repository read and write, package read"

    - role: sub
      id: "token-howto"
      title: "Creating the token, step by step"
      trailContext: "Which permissions, which dropdown setting and what helps with a 403."
      assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#create-an-access-token"

    - style: "gondola"
      id: "registry"
      title: "Log In on Your Own Machine, Not in the Container"
      trailContext: "Log in to the registry with your Git username and the token, then pull the image."
      splitRatio: 35
      left:
        text: "Log in with your Git username and the token as the password, then pull the image. Run this in a terminal on your computer. Inside the container there is no docker or podman."
      right:
        imageSrc: "contributors/stackit/core/getting_started/registry-login.png"
        imageAlt: "Terminal on your computer: docker login, then docker image pull of the scf-system image"

    - role: sub
      id: "registry-howto"
      title: "The registry login, step by step"
      trailContext: "Docker and podman, and why the login does not work inside the container."
      assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#log-in-to-the-registry"

    - style: "chairlift"
      id: "clone"
      title: "Your Fork Becomes the Content of the App"
      trailContext: "The shared repository is read-only, so everybody pushes to a fork, Framework Core included. Your clone becomes the content of the prebuilt app."
      splitRatio: 35
      left:
        text: "Fork the shared repository, clone your fork and add the shared one as upstream. Then open the folder in VS Code and choose Reopen in Container."
      right:
        imageSrc: "contributors/stackit/core/getting_started/clone-fork.png"
        imageAlt: "Terminal: git clone of your fork, cd scf-content, git remote add upstream"

    - role: sub
      id: "clone-howto"
      title: "Fork and clone, step by step"
      trailContext: "Where VS Code asks for the password and why new work always starts from upstream/main."
      assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#fork-clone-and-reopen-in-the-container"

    - style: "t-bar"
      id: "hike"
      title: "Every Save Shows Up in Your Browser"
      trailContext: "The site is forwarded to localhost:4321 with hot reload. Type help for the full tool belt."
      splitRatio: 40
      left:
        text: "Run hike in the container terminal. The real site opens on localhost:4321 with the components your readers see, and every save shows up within a second. Type help for the other tools."
      right:
        imageSrc: "contributors/stackit/core/getting_started/local-site.png"
        imageAlt: "The Cloud Framework running on localhost:4321"

    - role: sub
      id: "hike-howto"
      title: "hike and the tool belt"
      trailContext: "Every command in the container at a glance."
      assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#run-hike-and-open-the-site"

    - style: "crevasse"
      id: "traps"
      title: "Three Traps Cost Most First Days"
      trailContext: "The token is shown once, the registry login belongs on your host and /mnt/c breaks hot reload."
      center:
        text: "The token is shown only once. The registry login belongs on your own computer. On Windows, a clone under /mnt/c silently breaks hot reload."

    - role: sub
      id: "traps-howto"
      title: "The traps in detail"
      trailContext: "Every trap with its fix."
      assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#three-traps-worth-knowing"

    - style: "stairs"
      id: "studios"
      title: "The Studio Writes the Frontmatter for You"
      trailContext: "The SCF Studio emits frontmatter that already satisfies the pipeline rules."
      splitRatio: 52
      left:
        text: "Frontmatter is where most first pull requests fail. The SCF Studio writes it from a form, with a valid description, category and tags. It runs in your container and on the dev site."
      right:
        imageSrc: "contributors/stackit/core/getting_started/studio.png"
        imageAlt: "The SCF Studio: a form on the right, the climb from page to page on the left"

    - role: sub
      id: "studios-howto"
      title: "Working with the studios, in detail"
      trailContext: "Which branch to start from and which studios there are."
      assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#author-with-the-studios"

    - style: "chart"
      id: "patrol"
      title: "patrol Runs the Checks Before the Pipeline Does"
      trailContext: "patrol reproduces the pipeline locally: build, UI tests and a walkthrough of what you changed."
      splitRatio: 45
      left:
        text: "patrol runs locally what the pipeline runs: the build, the UI tests and a walkthrough of everything you changed. A few minutes here save a review round."
      right:
        imageSrc: "contributors/stackit/core/getting_started/patrol.png"
        imageAlt: "Terminal in the container: patrol"

    - role: sub
      id: "patrol-howto"
      title: "patrol in detail"
      trailContext: "What patrol checks and how long it takes."
      assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#run-patrol-before-the-pull-request"

    - style: "rocket"
      id: "pull-request"
      title: "Your Part Ends With the Pull Request"
      trailContext: "The pipeline validates your change and deploys a password-protected preview site for the review."
      splitRatio: 52
      left:
        text: "Push your branch to your fork and open the pull request. The pipeline checks it, builds a preview site for the review and merges on its own after approval when you tick the box."
      right:
        imageSrc: "contributors/stackit/core/contribution-gates.svg"
        imageAlt: "From access to a published page: guard, content checks, report, checklist gate, review, merge"

    - role: sub
      id: "pr-howto"
      title: "Opening the pull request, in detail"
      trailContext: "The checks, the preview site and the automatic merge."
      assetId: "advisory/assetcontainer/stackit/howto-contributor-setup#open-your-pull-request"

    - style: "summit"
      id: "youre-in"
      title: "You Are a Contributor"
      trailContext: "Your environment runs and your first change is on its way. Next comes the authoring craft."
      splitRatio: 38
      left:
        text: "Setup is a one-off; authoring is the part you will come back to. The onboarding journey walks through registering your contributor profile, the asset frontmatter schema, and chaining your assets into a trail of your own."
      right:
        trailId: "advisory/trails/stackit/scf-onboarding"

  presentations:
    - id: "setup-only"
      label: "Set up my environment (10 minutes)"
      description: "Everything up to a running local site, without the authoring and pull request part."
      default: true
      agenda: false
      launch: true
      preset: "focus"
      fullscreen: true
      steps:
        - id: "route"
          notes: "One picture for the whole route: five things are theirs, the rest runs without them. Then go through the setup."
        - id: "before-you-start"
          notes: "Open with the promise: contributing is writing content, not running an application. Two things get installed, everything else lives in the image."
        - id: "stackit-account"
          role: sub
          notes: "Only relevant for people without a STACKIT login. Ask the room quickly, and skip if everyone nods."
        - id: "sign-in"
          notes: "The key message: onboarding is self-service. One login, and a pipeline adds you to the team within 15 minutes. No invite, no ticket."
        - id: "sign-in-howto"
          role: sub
          notes: "Walk through it or let them follow along. Point at the box about the wrong account."
        - id: "your-name"
          role: sub
          notes: "Say it plainly: contributing here is public. Names come from their own profile and commit identity, both of which they control, pseudonyms included."
        - id: "machine"
          notes: "Docker Desktop or podman, plus VS Code with the Dev Containers extension. Stress what is NOT installed: no Node, no pnpm, no build tools. Pick the room's platform via the step's alternatives: macOS with podman or Windows with the WSL2 rule."
        - id: "token"
          notes: "Two scopes, repository read and write plus package read. Hammer the one-time display: save it before closing the dialog."
        - id: "token-howto"
          role: sub
          notes: "The dropdown above the permissions is the part people miss."
        - id: "registry"
          notes: "Login on your own machine, not in the container terminal. That is the mistake almost everyone makes once."
        - id: "registry-howto"
          role: sub
          notes: "Let them run the two commands now if they follow along."
        - id: "clone"
          notes: "Fork, clone, add upstream, then Reopen in Container. The first start takes a few minutes because it pulls the image."
        - id: "clone-howto"
          role: sub
          notes: "Show where VS Code asks for the password: at the top of the window, not in the terminal."
        - id: "hike"
          notes: "The payoff slide. hike gives them the real site on localhost:4321 with hot reload."
        - id: "hike-howto"
          role: sub
          notes: "The tool belt table is worth reading out: hike, summit, panorama, patrol, scout."
        - id: "traps"
          notes: "Close the setup with the three classics. If they remember only this slide, most support questions disappear."
    - id: "full-onboarding"
      label: "Full onboarding, including the first pull request"
      description: "The complete path from account to merged content, including authoring and the review process."
      steps:
        - id: "route"
          notes: "Show the whole route first: fork, container, hike, patrol, pull request. Everything below the line runs by itself."
        - id: "before-you-start"
          notes: "Set the frame: content repository only, prebuilt environment, three prerequisites. Everything after this is mechanical."
        - id: "needs"
          role: hidden
        - id: "stackit-account"
          role: sub
          notes: "Skip quickly if everyone already has a STACKIT login."
        - id: "sign-in"
          notes: "Self-service onboarding through the IDP, with the 15-minute team pipeline. Point out that the username is derived from the mail address."
        - id: "sign-in-howto"
          role: hidden
        - id: "your-name"
          role: sub
          notes: "Say it plainly: contributing here is public. Names come from their own profile and commit identity, both of which they control, pseudonyms included."
        - id: "your-name-details"
          role: hidden
        - id: "machine"
          notes: "Container runtime plus VS Code with Dev Containers. Switch the step to the macOS or Windows alternative when the room is platform-specific: podman needs the dockerPath setting, Windows needs the WSL2 clone rule."
        - id: "token"
          notes: "Walk the scopes, then the one-time warning. It is the password for both the clone and the registry login."
        - id: "token-howto"
          role: hidden
        - id: "registry"
          notes: "Emphasize: on the host, not in the container. Pulling up front is optional but makes the first start faster."
        - id: "registry-howto"
          role: hidden
        - id: "clone"
          notes: "Explain the mount model: your clone becomes the content of the prebuilt app. That is why no app repository access is needed."
        - id: "clone-howto"
          role: hidden
        - id: "hike"
          notes: "Demo this live if you can."
        - id: "hike-howto"
          role: hidden
        - id: "traps"
          notes: "Three traps: token shown once, login on the host, no /mnt/c on Windows."
        - id: "traps-howto"
          role: hidden
        - id: "studios"
          notes: "Frontmatter is where first pull requests fail. The Studio generates valid frontmatter, so use it instead of copying by hand."
        - id: "studios-howto"
          role: hidden
        - id: "patrol"
          notes: "patrol is the local copy of the pipeline gate. A few minutes here saves a review round later."
        - id: "patrol-howto"
          role: hidden
        - id: "pull-request"
          notes: "The reviewer sees the change rendered on a preview site, not just the diff. With the box ticked, the merge happens after approval and green checks."
        - id: "pr-howto"
          role: hidden
        - id: "youre-in"
          notes: "Hand off to the authoring journey: contributor profile, asset frontmatter, building your own trail. End on the invitation to ship something small first."
    - id: "what-it-involves"
      label: "What contributing involves (non-technical)"
      description: "The path from first login to a published contribution, without the machine setup. For briefings and decision-makers."
      steps:
        - id: "route"
          notes: "The one picture for a briefing: the contributor does five short things, the checks, the preview and the merge run automatically."
        - id: "before-you-start"
          notes: "The one message: contributing is writing content, not operating software. Everything technical ships in a ready-made image; nobody needs access to the application code."
        - id: "sign-in"
          notes: "Access is self-service: one login with the STACKIT account, and a pipeline adds the person to the contributor team within 15 minutes. No invites, no tickets."
        - id: "your-name"
          role: sub
          notes: "Contributions are public under a name the person controls in their own profile. Worth stating in any team briefing before the first change."
        - id: "studios"
          notes: "Nobody hand-writes configuration: the Studio generates valid files from a form. The technical setup exists for previewing, not as an entry barrier."
        - id: "pull-request"
          notes: "Work lands through a reviewed pull request: automated checks, a rendered preview site and a human review gate every change."
        - id: "youre-in"
          notes: "Close with where help lives: the tool belt inside the container, the how-to assets and Framework Core as the direct contact."
source_url: "https://framework.stackit.cloud/advisory/trails/stackit/getting-started-contributor/"
source_file: "docs/advisory/trails/stackit/getting-started-contributor.mdx"
---

## Steps

### 1. Your Part and the Part That Runs Without You

Stage: `compass`

Five things are yours: fork the repository, start the dev container, run hike, run patrol and open the pull request. The checks, the preview site and the merge run by themselves.

### 2. Two Installs and One Login Are All You Need

Stage: `hut`

Contributing means writing content, not running an application. Three prerequisites, and only two of them touch your machine.

### 3. What you need, in detail

The three prerequisites and why you never need the application repository.

Asset: [/advisory/assetcontainer/stackit/howto-contributor-setup/#what-you-need-before-you-start](/advisory/assetcontainer/stackit/howto-contributor-setup/#what-you-need-before-you-start) — source: [/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md](/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md), section `#what-you-need-before-you-start`

### 4. No STACKIT account yet?

Create one first, then come back to the next step.

Asset: [/advisory/assetcontainer/stackit/howto-contributor-setup/#creating-a-stackit-account](/advisory/assetcontainer/stackit/howto-contributor-setup/#creating-a-stackit-account) — source: [/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md](/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md), section `#creating-a-stackit-account`

### 5. One Login Puts You on the Team

Stage: `hut`

One IDP login creates your Git user and queues you for the contributors team.

### 6. Signing in, step by step

Which address to use and what helps when the wrong account is signed in.

Asset: [/advisory/assetcontainer/stackit/howto-contributor-setup/#sign-in-once-to-get-onboarded](/advisory/assetcontainer/stackit/howto-contributor-setup/#sign-in-once-to-get-onboarded) — source: [/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md](/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md), section `#sign-in-once-to-get-onboarded`

### 7. How your name appears

Your name is public here, and which name it is stays your choice.

### 8. How your name appears, in detail

Where the name comes from, what you release and how to change it.

Asset: [/advisory/assetcontainer/stackit/howto-contributor-setup/#how-your-name-appears](/advisory/assetcontainer/stackit/howto-contributor-setup/#how-your-name-appears) — source: [/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md](/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md), section `#how-your-name-appears`

### 9. Prepare Your Machine

Stage: `stairs`

A container runtime and VS Code with the Dev Containers extension. Nothing else gets installed. Everything the site needs already sits in the prebuilt image.

Asset: [/advisory/assetcontainer/stackit/howto-contributor-setup/#prepare-your-machine](/advisory/assetcontainer/stackit/howto-contributor-setup/#prepare-your-machine) — source: [/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md](/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md), section `#prepare-your-machine`

### 10. One Token Opens the Repository and the Image

Stage: `shield`

Repository read and write plus package read. The token is shown exactly once.

### 11. Creating the token, step by step

Which permissions, which dropdown setting and what helps with a 403.

Asset: [/advisory/assetcontainer/stackit/howto-contributor-setup/#create-an-access-token](/advisory/assetcontainer/stackit/howto-contributor-setup/#create-an-access-token) — source: [/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md](/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md), section `#create-an-access-token`

### 12. Log In on Your Own Machine, Not in the Container

Stage: `gondola`

Log in to the registry with your Git username and the token, then pull the image.

### 13. The registry login, step by step

Docker and podman, and why the login does not work inside the container.

Asset: [/advisory/assetcontainer/stackit/howto-contributor-setup/#log-in-to-the-registry](/advisory/assetcontainer/stackit/howto-contributor-setup/#log-in-to-the-registry) — source: [/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md](/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md), section `#log-in-to-the-registry`

### 14. Your Fork Becomes the Content of the App

Stage: `chairlift`

The shared repository is read-only, so everybody pushes to a fork, Framework Core included. Your clone becomes the content of the prebuilt app.

### 15. Fork and clone, step by step

Where VS Code asks for the password and why new work always starts from upstream/main.

Asset: [/advisory/assetcontainer/stackit/howto-contributor-setup/#fork-clone-and-reopen-in-the-container](/advisory/assetcontainer/stackit/howto-contributor-setup/#fork-clone-and-reopen-in-the-container) — source: [/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md](/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md), section `#fork-clone-and-reopen-in-the-container`

### 16. Every Save Shows Up in Your Browser

Stage: `t-bar`

The site is forwarded to localhost:4321 with hot reload. Type help for the full tool belt.

### 17. hike and the tool belt

Every command in the container at a glance.

Asset: [/advisory/assetcontainer/stackit/howto-contributor-setup/#run-hike-and-open-the-site](/advisory/assetcontainer/stackit/howto-contributor-setup/#run-hike-and-open-the-site) — source: [/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md](/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md), section `#run-hike-and-open-the-site`

### 18. Three Traps Cost Most First Days

Stage: `crevasse`

The token is shown once, the registry login belongs on your host and /mnt/c breaks hot reload.

### 19. The traps in detail

Every trap with its fix.

Asset: [/advisory/assetcontainer/stackit/howto-contributor-setup/#three-traps-worth-knowing](/advisory/assetcontainer/stackit/howto-contributor-setup/#three-traps-worth-knowing) — source: [/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md](/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md), section `#three-traps-worth-knowing`

### 20. The Studio Writes the Frontmatter for You

Stage: `stairs`

The SCF Studio emits frontmatter that already satisfies the pipeline rules.

### 21. Working with the studios, in detail

Which branch to start from and which studios there are.

Asset: [/advisory/assetcontainer/stackit/howto-contributor-setup/#author-with-the-studios](/advisory/assetcontainer/stackit/howto-contributor-setup/#author-with-the-studios) — source: [/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md](/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md), section `#author-with-the-studios`

### 22. patrol Runs the Checks Before the Pipeline Does

Stage: `chart`

patrol reproduces the pipeline locally: build, UI tests and a walkthrough of what you changed.

### 23. patrol in detail

What patrol checks and how long it takes.

Asset: [/advisory/assetcontainer/stackit/howto-contributor-setup/#run-patrol-before-the-pull-request](/advisory/assetcontainer/stackit/howto-contributor-setup/#run-patrol-before-the-pull-request) — source: [/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md](/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md), section `#run-patrol-before-the-pull-request`

### 24. Your Part Ends With the Pull Request

Stage: `rocket`

The pipeline validates your change and deploys a password-protected preview site for the review.

### 25. Opening the pull request, in detail

The checks, the preview site and the automatic merge.

Asset: [/advisory/assetcontainer/stackit/howto-contributor-setup/#open-your-pull-request](/advisory/assetcontainer/stackit/howto-contributor-setup/#open-your-pull-request) — source: [/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md](/raw/advisory/assetcontainer/stackit/howto-contributor-setup.md), section `#open-your-pull-request`

### 26. You Are a Contributor

Stage: `summit`

Your environment runs and your first change is on its way. Next comes the authoring craft.