airgap-devkit-teams

Author: Nima Shafie

Forkable template for teams to add custom tools to the airgap-devkit ecosystem.

Fork this repo to create your team's tool image. Add your tools, profiles, and config — then wire it into any airgap-devkit-based team image as a submodule.

---

Quick Start

Step 1 — Fork this repo

Click Fork on GitHub. Name your fork something like my-company-devkit-teams.

Step 2 — Clone your fork

git clone git@github.com:your-org/my-company-devkit-teams.git
cd my-company-devkit-teams

Step 3 — Add your tools

cp -r tools/example-tool/ tools/my-new-tool/
# Edit tools/my-new-tool/devkit.json and tools/my-new-tool/setup.sh

Step 4 — Point airgap-devkit at your tools

airgap-devkit --tools ./tools

Or wire this fork as a submodule in a team image repo (see .github/FORK_INSTRUCTIONS.md for the full setup).

---

Adding a New Tool

1. Copy the example tool directory:

   cp -r tools/example-tool/ tools/<your-tool-name>/

2. Edit tools/<your-tool-name>/devkit.json:

   • Set "id" to match the directory name.
   • Set "name", "description", "version", and "source" (your team name).
   • Set "category" to one of: Toolchains, Build Tools, Languages, Developer Tools, Frameworks, Security, Testing, Custom.
   • Set "platform" to "windows", "linux", or "both".
   • Set "setup" to the path of your install script relative to devkit.json (e.g. "setup.sh").
   • Set "check_cmd" to a shell command that exits 0 when the tool is installed (e.g. "mytool --version").
   • Set "receipt_name" to the subdirectory name under the install prefix where INSTALL_RECEIPT.txt is written — defaults to "id" when omitted.

3. Edit tools/<your-tool-name>/setup.sh:

   • Fill in SECTION 1 (detect OS, set archive names).
   • Fill in SECTION 2 (detect admin vs. user install, set INSTALL_PREFIX).
   • Fill in SECTION 3 (extract/copy/build your tool into INSTALL_PREFIX).
   • Leave SECTION 4 (write receipt) unchanged.

4. Syntax-check your script:

   bash -n tools/<your-tool-name>/setup.sh && echo OK

5. Run a test install:

   bash tools/<your-tool-name>/setup.sh

6. Commit:

   git add tools/<your-tool-name>/
   git commit -m "feat: add <your-tool-name>"

devkit.json Field Reference

Field	Type	Required	Description
id	string	Yes	Unique ID — must match the directory name
name	string	Yes	Display name shown in the dashboard
version	string	Yes	Semver or date string
description	string	No	One-sentence description
category	string	Yes	Dashboard grouping (Developer Tools, Build Tools, Toolchains, etc.)
platform	string	Yes	"windows", "linux", or "both"
setup	string	Yes	Path to the install script relative to devkit.json (e.g. "setup.sh")
check_cmd	string	Yes	Shell command that exits 0 when the tool is installed (e.g. "mytool --version")
receipt_name	string	No	Subdirectory under the install prefix where INSTALL_RECEIPT.txt is written — defaults to id
check_cmd_windows	string	No	Overrides check_cmd on Windows
check_cmd_linux	string	No	Overrides check_cmd on Linux
estimate	string	No	Estimated install time shown in the UI (e.g. "~2min")
uses_prebuilt	bool	No	true if the tool installs from a prebuilt archive
sort_order	int	No	Controls display order in the dashboard (lower = first)
source	string	No	Team name — identifies the tool's origin fork
homepage	string	No	URL to the tool's homepage
license	string	No	License identifier (e.g. "MIT", "Apache-2.0")
github_repo	string	No	GitHub repository URL

---

Adding a New Profile

1. Copy the example profile:

   cp profiles/example-profile.json profiles/<your-profile-id>.json

2. Edit the new file:

   • Set "id" to match the filename (without .json).
   • Set "name" and "description".
   • List the tool IDs to install in "tool_ids".
   • Optionally set "color" to a CSS color name or hex value for the profile badge.

3. Reference the profile in devkit.config.json if it should be the default:

   { "default_profile": "<your-profile-id>" }

4. Commit:

   git add profiles/<your-profile-id>.json
   git commit -m "feat: add <your-profile-id> profile"

---

Using This Repo as a Submodule

The intended deployment model is a team image repo that pulls in this fork alongside the core devkit. See .github/FORK_INSTRUCTIONS.md for the complete setup.

In short — in your team image repo:

git submodule add git@github.com:your-org/my-company-devkit-teams.git tools/team/

Then run airgap-devkit with both tool paths:

airgap-devkit --tools ./tools/default/ --tools ./tools/team/

The "source" field in each devkit.json identifies which fork a tool came from, so tools from the upstream devkit and from your team fork are always distinguishable in the dashboard.

---

Repository Structure

airgap-devkit-teams/
+-- README.md                    <- you are here
+-- devkit.config.json           <- team-level devkit configuration
+-- .gitignore
|
+-- tools/
|   +-- example-tool/
|       +-- devkit.json          <- fully commented field reference
|       +-- setup.sh             <- install stub with marked sections
|
+-- profiles/
|   +-- example-profile.json    <- example install profile
|
+-- .github/
    +-- FORK_INSTRUCTIONS.md     <- full team image repo setup guide

---

License

Copyright (c) 2024-present Nima Shafie. All Rights Reserved.

Source-available. See LICENSE for permitted and restricted uses. Commercial licensing available — contact github.com/NimaShafie.