The Set up tab

This page is for whoever makes Foreman ready on a project, on the first day and again when a step breaks: how the Set up tab works, what each step checks, what its Test it button does and where the keys go. /foreman:init opens the tab for you; later it is the last tab of the dashboard (foreman dashboard), or foreman setup on its own.

How the tab works

The dashboard’s Set up tab walks through making Foreman ready on the project: one step per screen the first time, then a checklist grouped by area, with what each step needs, a Test it button that runs that step’s doctor checks, and what is wrong and what to do when one fails. Opening the tab runs nothing: each step shows its last result and how long ago it was tested. Test it runs the checks in the background, one step at a time, and the step reads Checking… until they answer, so a slow project check such as npm test never holds up the run. Checks that take over 15 minutes are stopped; foreman doctor in a terminal shows which one hangs. While a required step is missing, Set up is the first tab, with a done/total count. On a project with no foreman.config.json yet, its first step is a form: the project’s name, where the stories come from (story files or Jira), the check command with a button that runs it once, and the CI jobs to wait for. Save writes the same config foreman init write --answers writes for those answers. The check command runs only on a dashboard that listens on this computer, stops after 3 minutes, and its output is shown with secrets blanked and never stored. On a project that already has a config, This project lets you switch the story source and, with sfdx-project.json, the Salesforce pack. Areas that are off show one line saying why, with Turn on. The Set up tab picks up changes to foreman.config.json without a restart.

The areas, in order, are The project, Claude, GitHub, Where stories come from, Notifications, Salesforce and Running in the cloud. Each step carries a pill: Done, Needs you (a required key or config value is missing, and the line names it), Broken (a check failed at error level) or Optional. A warning shows but never stops a step being done, and a step that does not apply to the project (the Jira steps on a markdown project, say) is left out. Each step also says why it matters and lists what you do, in order, with the exact clicks where there are any.

Test it runs the step’s own doctor checks, plus any check whose last result counts against the step (a missing RESEND_API_KEY is found by the env check under Project keys but counts against Notifications). The checks run in a child process of their own, foreman setup steps --step <id>, so a slow one never holds the dashboard, which may be running inside the supervisor. One step’s checks run at a time, across steps: a Test it on another step waits. The results are cached per machine in <stateDir>/setup-checks.json, each with the time it was checked, and the step shows that time and how long ago. A step allows one try at a time, 5 a minute and 30 an hour, key tests counting against the key’s step; past that the button says how long to wait. A check still running after 15 minutes is killed with its whole process group, nothing is recorded, and the tab says to run foreman doctor in a terminal. Closing the dashboard ends a check still running.

From a terminal, foreman setup steps runs every check and prints one status word per step (--json prints each step with its results; --step <id> runs that step’s checks only and keeps the others’ cached results), and foreman setup next walks the steps in order and stops at the first that needs you or is broken, printing its why, its guide and a fix line per failing result. “All set: every step is done.” when none is waiting. Every check is on Doctor checks.

Keys

Each key a step needs has its own card, so you never edit an env file by hand. Paste the key into its password field and save it. The card then shows the file it is saved in, with only the last four characters. You can test the key with its service, replace it or remove it (Foreman asks first). For the dashboard token, Foreman can make one for you. Keys go into .env.foreman, or for an adapter’s own keys the env file, always at mode 600. If git does not ignore that file, Foreman adds it to .gitignore, and the card offers the same fix. A key set in the environment shows as set outside Foreman, and you can only test it. Keys can be changed only on a dashboard that listens on this computer. A key’s value never comes back to the page.

Foreman’s own keys are JIRA_CLIENT_ID, JIRA_CLIENT_SECRET, RESEND_API_KEY, RESEND_FROM_EMAIL, FOREMAN_NOTIFY_EMAIL, FOREMAN_DASHBOARD_TOKEN, GEARSET_API_TOKEN, ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN. They live in .env.foreman at the project root (foremanEnvFile in the config), which no story workspace gets. Every other key an adapter or pack asks for lives in the project’s env file (envFile, .env.local by default), which is linked into every slot so the builder and tester can use it. A key’s value is read from the environment first, then its file. The masked view shows the last four characters for a value of 24 characters or more, and just “set” for a shorter one.

Before a save, the value’s shape is checked, never its worth: no spaces, at most 4096 characters, a Console key starting with the Console key prefix, a subscription token with the token prefix, a Resend key re_, a GitHub token ghp_ or github_pat_, a Jira app ID or secret of 20 or more letters, digits, _ or -, an email address for the two addresses, and 32 characters or more for the dashboard token, the one key Foreman makes itself (32 random bytes). Test it asks the service: Anthropic lists its models with the key; Resend lists your domains (a send-only key counts as working); Gearset lists the pipelines, and says when the Reporting API is not on for the token’s team; the subscription token asks Claude one short question, which uses a few tokens; a GitHub token runs the cloud doctor’s check; the addresses and the Jira keys are only checked for shape. Each service gets 10 seconds to answer.

Every write goes through a temp file and a rename, leaves the file at mode 600 and keeps its other lines and comments. A save is refused, writing nothing, when git does not ignore the file (the card offers Add to .gitignore), when git already tracks it (remove it from the index first with git rm --cached <file>), or when the file is a link to one git could commit. One writer at a time holds the lock <stateDir>/locks/keys.json and waits up to 5 seconds for another. The same cards are the foreman keys command: list (not set, set outside Foreman, or masked with its file), set NAME (reads the value hidden; a value on the command line is refused, because it would stay in your shell history), remove NAME, test NAME and migrate, which moves Foreman’s own keys out of the env file into .env.foreman and leaves the rest of the file as it was. Each takes --project <path>.

This project

The first step, and the one with a form. On a project with no config it asks the project’s name, where the stories come from (story files in this repository, or Jira), the story folder (a folder inside the project, where Foreman adds an example story when it has none) or the Jira site and JQL filter, the check command (Run it runs it once; the run is killed after 3 minutes with everything it started, its last 40 lines, at most 4000 characters, are shown with secrets blanked, and nothing is stored) and the CI jobs that must pass before a merge, read from .github/workflows. Save foreman.config.json writes the file and the files that go with it. When the file is there but does not load, the same form shows under its errors and its save replaces the file.

On a project with a config, the step shows What Foreman uses: the Story source (Markdown files, Jira, or Salesforce Cases on a project with the pack) and, with sfdx-project.json, the Salesforce pack (Off or On, with the sandbox’s alias and org ID when turning it on). A switch to Jira saves a starter filter (labels = foreman AND statusCategory != Done ORDER BY Rank) for the Jira steps to narrow; a switch to Salesforce Cases saves a starter filter of the open Cases of Type Foreman in the first sandbox of salesforce.orgs; turning the pack on adds the salesforce block with that one sandbox as build org and the stage qa, and the pack’s ship steps; turning it off removes them and puts Foreman’s own ship steps back. The pack cannot be turned off while the stories come from Cases. Every change ends with a reminder to commit the file.

Its checks are config (the file loads and validates, traits included) and local settings (a local setting that is invalid is ignored and named). Project-wide checks with no step of their own land here too: merged code tested, role agents (a role that names an agent Foreman cannot find), the three learning checks and a pack that fails to load. Test it runs them all.

Claude Code

Foreman runs its agents in Claude Code, through the plugin. The step’s guide: install Claude Code and open a new terminal, install the plugin, and turn workflows on (they need a paid plan or the API; on Pro, in /config). Its checks are claude on PATH (claude --version), plugin installed and enabled and plugin fresh (from claude plugin list: the plugin is installed for this project, turned on, and the installed copy is the one the sessions load), and workflows, which always warns because the doctor cannot detect it. Three more land here: story session scope (what story sessions load: a session.mcpServers entry that .mcp.json does not define is an error), agent models (the newest story session’s agents ran on the models their roles are set to) and review engine <name> for a reviewer set to run through another CLI. No keys.

Claude sign-in

The agents need a Claude sign-in. The screen has two key cards, Console API key (ANTHROPIC_API_KEY, pay per use, needed to sell Foreman or run it for others) and Subscription (CLAUDE_CODE_OAUTH_TOKEN, for your own projects: run claude setup-token and paste the token it prints), a third card, Already signed in on this computer, when Claude Code is signed in there with claude auth login, and a line that says which one is in use and why: the key when it is set, with a note that the token is set too but the key wins; the token; the login on this computer; or, after the platform credits ran out or the key hit its usage limit, your subscription since a time, with Use the API key again to switch back. Neither key is required: with none saved, the line says to press Test it to see whether this computer is signed in. Its one check is claude sign-in, described on Install.

GitHub

Foreman pushes each story to a branch, opens a pull request and merges it through the GitHub CLI. The guide: push the project to GitHub so git has the remote (origin unless remote says otherwise), run gh auth login for the account that can push, and turn on branch protection for the base branch (GitHub › Settings › Branches › Add branch protection rule). Its checks are git remote, gh signed in and branch protection, which warns rather than fails: when protection is off, when the repository’s plan does not allow it, or when it cannot be checked. No keys. Release safety says what protection buys.

Tools and checks

The project’s own checks, and the tools its adapters need, must work on this machine. The guide: install each tool the doctor names, open a new terminal, and make each check in foreman.config.json that runs always pass here. Its named check is tools (command -v for every tool the configured adapters, ship steps and pack need), and the doctor ties these to the same step: check: <run> for each check with when: "always", docker compose when env.adapter is docker, vercel story previews when the project has a vercel.json or a Vercel deploy step, background service (installed, running, and pointing at a Node and a Foreman that exist), macOS privacy prompts (always ok; on a Mac with the service installed it explains why macOS asks on behalf of node and says to answer Don’t Allow), stray processes, machine load (a warning when the load is over twice the cores during a run, naming the five busiest processes), story sessions (two sessions in one slot folder) and last interrupt (who stopped the run with a signal in the last 7 days). Test it on this step runs the project’s checks, so it can take as long as your test suite. No keys.

Project keys

Some adapters need keys of their own, read by name only from the env file or the environment. The step is optional when the project asks for none. Its cards are one per key the configured adapters and pack ask for that no other step explains, plus FOREMAN_DASHBOARD_TOKEN, the token that guards a dashboard reached from another machine, with Make one for me. Its checks are env variables (every name the adapters, ship steps and pack need is in the env file, .env.foreman or the environment; a missing one says which file it belongs in), foreman keys file (.env.foreman is ignored by git, which the doctor fixes itself by adding the line, and readable by its owner only, else chmod 600) and foreman keys placement (none of Foreman’s own keys is left in the env file, where agents can read it; the fix is foreman keys migrate).

Jira

A project whose stories come from Jira gets three Jira screens, in order. The first takes the Jira app’s two keys and has a Copy button for the callback address the app needs. The second signs in: Sign in to Jira opens Atlassian in a new tab, the page notices when you approve, and you pick the site when the sign-in reaches more than one. The third picks the project, fills in the JQL filter and shows the first issues it finds as you edit it, suggests which status to move an issue to for each story event (or “Leave where it is”), and takes the owner label. Save writes them to foreman.config.json and reminds you to commit it.

Jira app

Foreman signs in to Jira Cloud through an OAuth app of your own, made once per project, at developer.atlassian.com under My apps. The guide walks the app’s Permissions (the Jira API with the scopes Foreman needs; offline_access gives it a refresh token), Authorization (the callback address, which the Copy button holds) and Settings (the client ID and secret). Its two key cards are JIRA_CLIENT_ID and JIRA_CLIENT_SECRET, both required, and its check is jira app keys.

Jira sign-in

Foreman reads and moves your issues as you, through a sign-in kept on this machine at ~/.config/foreman/jira-<site>.json. Besides Test it the step has Sign in to Jira, the same as foreman jira login; on a machine with no browser, foreman jira login --paste. The page asks the sign-in’s state every 2 seconds while it waits. Its checks are jira signed in (the token file is there) and jira sign-in age (renewed in the last 80 days; Atlassian retires a refresh token left unused for 90).

Jira site and filter

Foreman picks its stories from your site with a JQL filter. Its two config inputs are stories.site (the host only, such as acme.atlassian.net) and stories.jql. The screen’s preview asks Jira once typing rests, shows about how many issues match and the first ten, and offers one move per story event from the project’s real statuses. Its check is jira JQL (the filter runs, with the approximate count); jira options runs only when the stories block is wrong, and jira transitions only when the map has names (a warning when a name is not offered by an issue the filter finds, never an error). See Stories from Jira.

Notifications

The Notifications screen lets you choose email through Resend or no email, takes the Resend key, the sender and your address, and has a Send a test email button that shows whether it arrived or what to fix; with notifications off in Settings, the test goes to the outbox only.

The step is optional while notify.adapter is unset or none. Its inputs are the choice notify.adapter (none or email-resend), RESEND_API_KEY (required for email), RESEND_FROM_EMAIL (required for email unless notify.from is set, an address on a domain verified at Resend) and FOREMAN_NOTIFY_EMAIL (optional; empty means your git email). It has no doctor check of its own: a missing Resend key is found by the env check under Project keys and counts against this step, and Test it runs that check again. Send a test email answers in plain words: sent (check spam too), the outbox only (notifications off, or no email chosen), the key refused or inactive, the sender’s domain not verified, Resend sending only to your own address until a domain is verified, too many emails, or Resend unreachable. Each message names where to fix it. See Notifications.

Salesforce

The five Salesforce steps appear when pack is salesforce; the Gearset step only when salesforce.release is gearset. The Salesforce pack is a preview: its release paths pass their own tests, but no story has yet shipped through them on a live org. The full set-up is on Salesforce set-up.

Salesforce CLI

The pack deploys and tests through the Salesforce CLI and a few of its plugins. The guide: install sf, then the plugins the doctor names (such as sfdx-git-delta and the code analyzer), and set SF_DISABLE_TELEMETRY=true in the env file. Its checks are salesforce tools (each at its minimum version), salesforce plugin (the salesforce-development plugin, which Foreman turns off for its own runs) and salesforce telemetry. No keys.

Salesforce environments

Foreman needs to know your sandboxes: which build stories, which take releases, and the production branch it must never merge into. Its config inputs are salesforce.orgs and salesforce.stages; the guide also names salesforce.productionBranch and how to turn the Gearset path on (set salesforce.release to gearset, give the last stage a sandbox and a branch of its own, and set the production branch). Its checks are salesforce layout (where each step runs, with no sf and no git), salesforce test level, salesforce production branch, salesforce workflows (a workflow that deploys a Foreman branch to an org off the list is refused) and salesforce CONFIRM_PROD (that variable must be set nowhere).

Salesforce org sign-in

On a Salesforce project, the Salesforce org sign-in screen starts with Foreman’s key: make it there, or upload a key and certificate you already have, then download the certificate. The key stays on your computer and never comes back to the page. Below it, numbered steps with the exact clicks walk you through making the app Foreman signs in with in each sandbox. Each org in salesforce.orgs then gets its own row: give the username and the app’s consumer key and press Connect. Foreman shows the org ID it found, offers to save it when it differs from the config, and signs a production org out again at once, because it never connects to production. Steps you do only in Salesforce, such as turning on source tracking, show whether their doctor check passes once you press Test it.

Besides Test it the step has Make the key and Connect an org. Connect signs the org in to Foreman’s own sf home, so story sessions see only the sandboxes in salesforce.orgs, never your other orgs; sf can take up to 2 minutes. The guide’s steps are the External Client App in each sandbox’s Setup: OAuth with the JWT Bearer flow and the certificate you downloaded, the policies (Admin approved users are pre-authorized, and the profile or permission set of the user Foreman signs in as), the consumer key (Foreman does not need the secret), and, once, source tracking turned on in the production org, which you open yourself. Its named check is salesforce sf isolation; the doctor also ties salesforce org <alias> (<roles>) for each org, salesforce source tracking <alias> for each build sandbox, salesforce baseline <alias>, salesforce agentforce and, when the stories are Cases, the three salesforce stories checks to this step. FOREMAN_SF_HOME, if you set it, must be an absolute path.

Salesforce skills

The pack’s agents use the pinned Salesforce skills, installed in the project. Besides Test it the step has Install the skills, the same as foreman sf skills; commit skills-lock.json, .agents/skills and .claude/skills afterwards. Its checks are salesforce skills lock and salesforce skills named.

Gearset

The Gearset path is built but not yet proven on a live pipeline, so treat it as experimental. On a Salesforce project that releases through Gearset, the Gearset screen takes GEARSET_API_TOKEN on its key card, then reads your Gearset pipelines. Pick the one that promotes this repo and press Save: Foreman writes it to foreman.config.json as salesforce.gearset.pipelineId and from then on looks only in that pipeline (without one, it looks through every pipeline the token sees). A table shows each of the pipeline’s environments beside the org in salesforce.orgs with the same org ID and the stage on that org, and flags an environment no org matches, Gearset’s production environment (Foreman never promotes there), and any stage no environment deploys to. Each stage then shows whether its environment’s CI job is on and whether it runs Apex tests. Gearset’s API cannot show a CI job’s test level, so when no recent deploy shows it either, you check the CI job in Gearset and confirm it on the screen; Foreman remembers that as your confirmation, apart from what it checked, and checks again after Gearset’s next deploy.

The token comes from Gearset under My account › Team security › Access token management. Its checks are salesforce gearset token, salesforce gearset branch (ship.merge.keepBranch must be on), salesforce gearset merge method, salesforce gearset environments, salesforce gearset ci job and salesforce gearset ci tests.

Cloud runner

Foreman can build with your laptop off: in GitHub Actions, one story per scheduled job, or in a container that runs all the time. The step is always optional. Its screen asks which, and shows the guide entries for that choice. For GitHub Actions: Keep the run state on a branch (writes "state": { "store": "branch" }), Write the workflow (.github/workflows/foreman.yml, to commit and push; it runs every 30 minutes, cloud.actions.cron), then paste a GitHub token and press Set the secrets: Foreman checks the token, then sets FOREMAN_GH_TOKEN, your Claude sign-in and each name in cloud.envVars as the repository’s Actions secrets with gh, from the keys saved on the other steps. The token is never saved. For a container: paste the token and press Write the runner file, which writes .env.runner (mode 600, kept out of git) with the repository, the token, your Claude sign-in, the dashboard token and the project’s keys, and shows the docker run line; copy the file to your server and open its dashboard through an SSH tunnel to port 4317. Its checks run only when their files exist: cloud workflow (the state is on a branch and the workflow is the one this Foreman writes), cloud secrets (GitHub has every secret the workflow reads) and cloud runner file (a plain file, ignored and untracked by git, readable by its owner only). See Run in the cloud.