Setup Script

A Mac with an administrator account. Homebrew asks for your password once.

The onboarding credentials: Bitbucket, VA Nexus and Sandbox DTR usernames and tokens, plus Jira and Jenkins tokens if you have them. The onboarding team may give you these as a credentials file.

30 to 60 minutes on a new Mac. Most of that is downloading, and the questions all come at the start. An Intel Mac can take much longer, because Homebrew no longer has prebuilt packages for Intel Macs and builds the command-line tools from source. The script warns you and asks before it does.

Rosetta. If Terminal is set to Open using Rosetta, Homebrew won’t install Apple Silicon tools and SDKMAN would pick Intel JDKs, so the script starts itself again as Apple Silicon code (arch -arm64), and tells you how to turn Rosetta off for Terminal. If it can’t, for example when you piped it into bash, it stops instead.

An Intel Mac. Homebrew stopped making prebuilt packages for Intel Macs in September 2026, so some tools may build from source, which can take hours; the script asks before it does that. Homebrew stops supporting Intel Macs in September 2027; see Intel Macs for what that means and how to install the tools yourself.

An Intel Homebrew. Migration Assistant can copy an old Intel Mac’s Homebrew into /usr/local. On Apple Silicon the script uses, and if needed installs, Homebrew in /opt/homebrew instead, and sets it up last in your login profile so new terminals find it first. If a line that runs later, say in ~/.zshrc, puts /usr/local/bin back in front, doctor points it out.

Disk space. The setup needs about 30 GB. With less, it warns and asks; under 10 GB the default answer is to stop.

The VA network. If coderepo.mobilehealth.va.gov isn’t reachable, it tells you to connect to the VPN. Without it, cloning, the token checks and the build fail, so run the script again once you’re connected.

A setup started by hand. If you already did part of the setup by following the docs, the script lists what it found and stops before changing anything, because working around a half-finished setup makes its output hard to follow. Signs of this include credential or Skaffold settings in your shell profile outside the script’s block, a ~/.m2/settings.xml for VA Nexus, the Jira or Jenkins CLI, or the git hooks. Finish the setup by hand with Development Environment Setup and the pages it links to, then run doctor to check it, and doctor --fix to repair what it finds (see Check Your Setup). Repositories you cloned yourself don’t count, and neither does anything from an earlier run of the script. To run the guided setup anyway, add --force.

Installs the PlantUML Integration, Google Cloud Code, Bitbucket Integration Pro and GitHub Copilot plugins.

Imports the VA_Mobile_CodeStyle code style and the VA_Mobile_Inspections inspections from mobile-framework (see IntelliJ Checkstyle & Inspection Profiles), makes the code style the default, and makes the inspections the default for projects you open from now on.

Sets GitHub Copilot to sign in through va.ghe.com (see GitHub Copilot Access and IDE Configuration (VA GHEC-US)).

Java and Maven. Each repository’s .sdkmanrc pins them, so upgrade never moves them to a newer version, and it doesn’t upgrade Homebrew’s JDK or Maven packages either.

New major versions of Skaffold, Kustomize and TruffleHog. Builds, deployments and the git hooks use them, so upgrade tells you when one is out. Check with the team, then upgrade it with the brew upgrade command it prints.

Apps that are running. Homebrew closes an app to upgrade it, which would end a Windows App session, for example. Quit the app and run upgrade again.

Apps that update themselves: OrbStack, Docker Desktop, IntelliJ IDEA (which also updates its plugins), Postman, iTerm2, Sublime Text and Citrix Workspace. Use their own update prompts. Upgrading OrbStack or Docker Desktop through Homebrew would stop your containers.

Caches and logs left behind by IntelliJ IDEA versions that aren’t installed and haven’t run for 30 days (yes; IntelliJ rebuilds them).

Settings of those IntelliJ versions, moved to the Trash rather than deleted. It keeps the settings that a newly upgraded IntelliJ will import the first time it starts, including Community Edition settings that the unified IntelliJ IDEA can import. An IntelliJ installed somewhere tidy doesn’t look, such as a custom Toolbox folder, still counts as in use while it keeps writing logs.

Docker images and build cache that nothing has used for 30 days, and unused anonymous volumes (yes; images are pulled or rebuilt when next needed). The size it shows is an upper bound, and leaves the volumes out, because Docker counts named volumes there too, which it doesn’t remove. With a Docker CLI older than 23, it leaves volumes alone, because its volume prune removes named volumes too.

JDK, Maven and Gradle versions that no repository’s .sdkmanrc pins, no IntelliJ project uses as its SDK, and JAVA_HOME or your shell profile doesn’t name. It reads the repositories in your workspace, following symlinks; pass --workspace if some are somewhere else. It skips this when it finds no repositories, rather than guess. SDKMAN may no longer offer an old version once it’s gone.

Maven SNAPSHOT folders in ~/.m2/repository that no build has used for 30 days (nothing in them has changed), except ones built only on this Mac (mvn install without a deploy), which Maven couldn’t download again. Others download again on the VPN, unless Nexus has removed them.

Homebrew’s downloads and old versions (brew cleanup -s, yes).

Your shell history. It warns you if the history sets token variables, so you can delete those lines yourself.

~/.m2/settings.xml, and the backups of it the script makes when it replaces that file. It lists the ones with passwords written into them, so you can replace each password with an ${env.VAR} reference (see Maven Configuration) or delete the backup yourself.

IntelliJ. Remove the token in IntelliJ’s git settings and in the Bitbucket plugin.

The tokens themselves. Removing local copies doesn’t stop a token from working, so forget ends by saying where to revoke each one: Bitbucket, VA Nexus, Sandbox DTR, Jira and Jenkins each have a page for it (see Creating Token Values). For the onboarding team’s tokens, it tells you to let them know instead.

The versions and endpoints are at the top of the script. When the team moves to a new JDK or Maven version, change them there and on Development Environment Setup, and everyone re-runs the script to catch up.

It contains copies of the settings.xml from Maven Configuration and the hook scripts from Modular Git Hooks (Pick-and-Choose). After you change either page or the script, run scripts/check-dev-setup-sync.sh. It prints a diff and fails if they no longer match.

The IntelliJ plugin IDs are in IDEA_PLUGINS at the top of the script. The script imports the code style and inspections from mobile-framework, and falls back to this site’s VA_Mobile_CodeStyle.xml and VA_Mobile_Inspections.xml attachments when it can’t reach mobile-framework, so copy those over when mobile-framework’s docs/appendices/ide files change.

upgrade leaves the apps in SELF_UPDATING_CASKS to their own updaters, and holds back new major versions of the tools in HOLD_MAJOR. Both lists are at the top of the script.

Bump VERSION in the script whenever you change it. doctor tells people when a newer version is published, and update installs it.

Before you open a pull request that changes the script, run scripts/test-dev-setup/run.sh on a Mac. It runs the script against a throwaway home folder with stand-in commands, so nothing on your Mac changes and nothing goes over the network. Apps and Homebrew tools come only from that sandbox too, so the results don’t depend on what your Mac has installed, and the prompts are answered on a pseudo-terminal, the way a person types them. It runs several scenarios at once and takes a few minutes; scripts/test-dev-setup/run.sh h runs a single scenario (the scenarios are listed in the script), and JOBS=1 runs them one at a time. Ctrl-C stops them all, and a scenario still running after ten minutes is stopped and counted as failed (SCENARIO_LIMIT changes that). The top of run.sh also lists settings for trying other setups, such as bash as the login shell, GNU tools first on PATH, or another locale.