Contributing to BOA

Everything flows through the public omega8cc GitHub organisation. omega8cc is the effective upstream for the whole stack — the Ægir components (Hostmaster, Provision, Hosting, hosting_tasks_extra) and Drush are fully diverged forks, so never route a patch or an issue through a pre-fork queue (aegir-project drupal.org queues, drush-ops): it will only get redirected.

Where to file

Search the active queue (and the legacy ones) for a duplicate before filing. Reports that ignore the guidelines below are closed unread — that is stated policy, not a threat.

What a useful bug report contains

The boa info Gist is mandatory. Every bug report must link a Gist with the output of boa info, run as root on the affected box. The generator is _display_info() in aegir/tools/bin/boa (function at boa:2384, dispatched from the info) case at boa:3038, which calls _check_virt then _display_info). It emits:

• host/CPU/disk basics (dmidecode manufacturer, nproc, root-fs usage), plus a loud warning block on bare metal or unsupported virtualisation;
• component versions as terse tags — SKY, CSF, NGX, PHP, DBV, RDS, PXY, SSH, SSL, CRL, … (boa:2579+);
• effective config echo tags (_DBS, _DNS, _PHP-family, _XTR, …);
• the _XSY uptime/load/kernel/GRUB/RAM/disk report and the _XSE key-services uptime report;
• the tail of the upgrade history: tail --lines=5 /var/log/barracuda_log.txt.

Mode variants, from the _mOde branch (boa:2816-2825):

Beyond the Gist, include:

• the exact command sequence that triggered the problem, verbatim;
• virtualisation system and hosting provider (name + URL) — the same context _check_virt reports;
• whether a fresh install of the same release reproduces it (install/upgrade bugs usually do; this rules out config drift);
• for upgrade failures: re-run with _DEBUG_MODE=YES in /root/.barracuda.cnf first (default NO, lib/settings/barracuda.sh.cnf:338) — it switches on the PROC:/DEBUG tracing throughout the lib functions.

Where the logs are

Octopus runs do not write /var/backups/octopus-* equivalents — the Octopus side exports _LOG_INFO="" (lib/settings/octopus.sh.cnf:1142), so its output stays on the console (or wherever the chosen {output} mode sends it).

Gist etiquette

• Never paste logs or boa info output inline in the issue — the tool itself prints the instruction after every default run (boa:2827-2833): link a Gist, and name your hosting provider alongside it.
• _display_info() does not sanitise for you. The output carries the server hostname context, Octopus instance user names, kernel and full GRUB command line, partition layout, and the OS/virt fingerprint of every upgrade since install. Audit before posting; use a secret Gist when in doubt.
• One issue per bug. A Gist can hold multiple files — put boa info and the failing run's barracuda-upgrade-errors-*.log in the same Gist rather than opening two issues.

Pull requests

Target the repo's default branch — that is where all development lands:

Never target the release lines (5.x-lts, 5.x-pro, or any -base/-edge branch) — those are maintainer-managed promotion branches. A PR against a release line will be closed or retargeted, not merged.

Mechanics that get a PR merged instead of reworked:

• One logical change per PR, single-concern commits. Promotion to the -base branches is selective; a commit that mixes concerns cannot be cherry-picked cleanly and stalls.
• Match the house bash style in BOA.sh.txt/BARRACUDA.sh.txt/ OCTOPUS.sh.txt and lib/: two-space indent, _SNAKE_CASE script variables with a leading underscore, lowercase_with_underscores functions, quoted expansions, and the _msg output helper with INFO:/NOTE:/OOPS:/ ERROR:/FATAL ERROR: prefixes in main scripts and lib functions.
• Bump the fetch serial when you touch a fetched tool. Tools under aegir/tools/ are deployed to running fleets by _fetch_versioned() (BOA.sh.txt:1056): the stamp file is <name>.ctrl.<serial>.<tree>.<xsrl>.pid, and a box refetches only when its stamp no longer matches. Any change to such a tool must change the fNN serial at its call site in BOA.sh.txt in the same commit — old stamps are cleaned on refresh, so the serial only has to differ — otherwise deployed servers never pick the change up. Files under lib/ ride the release version serial instead and need no fNN bump.
• Keep fork PHP at the lowest supported floor. boa help still offers php-max installing PHP 5.6–8.5, and legacy servers run the Ægir backend under old PHP CLI. PHP for Provision/Hosting/Drush must not assume modern syntax (no ??, arrow functions, scalar type hints, match, …) unless the file is provably loaded only under a newer engine.
• Leave CHANGELOG.txt alone — it is the genuine release changelog, assembled by the maintainers at release time, not per-PR.

Security disclosure

Do not open a public issue for an exploitable bug. SKYNET keeps every enabled fleet current on a tight cadence (the version check runs in aegir/tools/system/owl.sh, the fetched-tool refresh in BOA.sh.txt _fetch_versioned, and the optional self-upgrade cron in aegir/tools/bin/autoupboa):

• a daily release check;
• frequent refresh of the key BOA tools;
• monitors and D7 core patching;
• a meta-installer refresh on a short interval;
• and where the optional self-upgrade cron is configured, servers pull each new tagged release automatically.

A public proof-of-concept is therefore live against every production server for the window between disclosure and the next tagged release reaching them.

Report privately to the maintainers (Omega8.cc) via the contact form at omega8.cc/contact — the same private ticket channel the maintainers direct support requests to elsewhere in the stack. There is no root-level SECURITY.md disclosure policy file in the repo; the contact form is the documented private path.

If supporting material is needed, use a secret Gist and share the link only in the private ticket. Public issues that turn out to be security-sensitive get pulled and you will be asked to refile privately.

What maintainers do with your contribution

Understanding the pipeline explains the review strictness. All of this is visible in the public branch history:

1. Triage happens in the omega8cc/boa queue; fork-repo work is routed from there.
2. Merge to 5.x-dev — the latest-untested line. Your change is now in the default branch every clone and doc link points at.
3. Promotion to 5.x-dev-base — the slower, non-breaking subset (Merge branch '5.x-dev' into 5.x-dev-base merges in the history); experimental work parks on 5.x-dev-edge instead.
4. Promotion into the release lines — 5.x-dev-base merges into 5.x-pro-base and 5.x-lts-base, which merge into the stable 5.x-pro / 5.x-lts.
5. Tagging — releases are tagged only on the stable lines (BOA-<X.Y.Z>-pro / BOA-<X.Y.Z>-lts in the tag list), with notes in releases/BOA-<X.Y.Z>-*.md and CHANGELOG.txt. A tag is a fleet trigger: SKYNET-enabled servers detect the new release on their daily check (aegir/tools/system/owl.sh) and, where the self-upgrade cron entries are configured, upgrade themselves (aegir/tools/bin/autoupboa).

Step 5 is why review is conservative: a merged change ends up executing as root on every production BOA server with no operator in the loop. Expect maintainers to rework, split, or defer contributions to fit that pipeline — and expect a serial-mechanics or style rework request to be about fleet safety, not taste.

Related

• Reference appendix — consolidated variable and command index, including the boa CLI verbs and the _DEBUG_MODE / logging-related /root/.barracuda.cnf settings referenced above.