If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/theforeman/foreman shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 38+ active contributors
• Distributed ownership (top contributor 11% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live theforeman/foreman repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/theforeman/foreman.

What it runs against: a local clone of theforeman/foreman — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in theforeman/foreman | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of theforeman/foreman. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/theforeman/foreman.git
#   cd foreman
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of theforeman/foreman and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "theforeman/foreman(\\.git)?\\b" \\
  && ok "origin remote is theforeman/foreman" \\
  || miss "origin remote is not theforeman/foreman (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f "app/assets/config/manifest.js" \\
  && ok "app/assets/config/manifest.js" \\
  || miss "missing critical file: app/assets/config/manifest.js"
test -f ".github/workflows/foreman.yml" \\
  && ok ".github/workflows/foreman.yml" \\
  || miss "missing critical file: .github/workflows/foreman.yml"
test -f "Rakefile" \\
  && ok "Rakefile" \\
  || miss "missing critical file: Rakefile"
test -f ".rubocop.yml" \\
  && ok ".rubocop.yml" \\
  || miss "missing critical file: .rubocop.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/theforeman/foreman"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Foreman is a comprehensive infrastructure lifecycle automation platform written in Ruby on Rails that provisions, configures, orchestrates, and monitors servers across on-premises and cloud environments. It integrates with Puppet, Ansible, Chef, and Salt via its smart proxy architecture to automate bare-metal and VM provisioning, configuration management, and server lifecycle management at scale (managing 10s to 1000s of servers). Monolithic Rails application: app/assets contains frontend (JavaScript, SCSS, HTML), app/ contains core Rails models/controllers/views, Procfile indicates multi-process setup (web server + background jobs). Frontend uses modern JavaScript stack (.babelrc.js, .eslintrc.js, .prettierrc) for component management. Multiple GitHub workflows indicate CI tests for Ruby, JavaScript, plugins, and container builds. Infrastructure code lives alongside UI code in single codebase.

Systems administrators and DevOps engineers who need to automate mixed infrastructure (bare-metal, VMs, multi-cloud) with unified provisioning, configuration management, and monitoring; enterprise operators managing large server fleets; contributors building infrastructure orchestration features or integrating new provisioning providers.

Highly mature, production-ready project deployed in many organizations (RDO, RHOS) with extensive plugin ecosystem. The codebase shows strong CI/CD setup (.github/workflows with container, foreman, js_tests, breaking tests), substantial test coverage (Coverage Status badge), and active development indicated by Changelog and multiple workflow triggers. This is not experimental—it's battle-tested infrastructure software.

Primary risk is monolithic Rails architecture (5.3M lines of Ruby) making large refactors complex; dependency management relies on Gemfile + npm (.npmrc present) requiring careful version coordination. The project's scale and lifecycle-critical nature means breaking changes to provisioning logic or API endpoints (RESTful API is core interface) can cascade widely. Community-driven with plugin ecosystem, so breaking changes require careful deprecation windows.

Active development shown by recent workflow additions (test-breaking.yaml, plugins_react_tests.yml) indicating focus on React components and backward-compatibility testing. Dependency management automated (dependabot.yml). The .packit.yaml suggests container/distribution integration work. Multiple workflow triggers (single_commit.yml, labeler.yml) indicate PR-heavy development culture with automated triage.

git clone https://github.com/theforeman/foreman.git
cd foreman
bundle install
npm install
rake db:create db:migrate
rake test

Note: Consult Procfile and Dockerfile for full environment setup (likely requires PostgreSQL and background job processor like Sidekiq).

Daily commands:

rake db:create db:seed
rails server

Background jobs likely require: rake jobs:work or similar (check Procfile for exact process list). See Dockerfile for full environment requirements.

• Gemfile — Defines all Ruby gem dependencies for the entire Rails application; any contributor touching backend code must understand the project's dependency landscape.
• app/assets/config/manifest.js — Sprockets manifest that bundles all frontend assets (JS, CSS); essential for understanding how the UI is compiled and served.
• .github/workflows/foreman.yml — Primary CI/CD pipeline that runs tests and builds artifacts; reveals testing strategy and deployment process.
• Rakefile — Task runner for common development operations (migrations, tests, asset compilation); entry point for understanding the build system.
• .rubocop.yml — Enforces code style and quality standards across the Ruby codebase; contributors must comply with these conventions.
• .eslintrc.js — JavaScript linting configuration that maintains frontend code quality; required reading for any JavaScript contributor.
• VERSION — Single source of truth for the application version; critical for release and versioning workflows.

Add a new Rails API endpoint

1. Create a new controller in app/controllers/ inheriting from ApplicationController (app/controllers/api_controller.rb (reference only; create new file following this pattern))
2. Add routes in config/routes.rb pointing to your new controller actions (config/routes.rb)
3. Write controller tests following the test/ directory structure (test/controllers/api_test.rb (reference only; create following this pattern))
4. Ensure code passes RuboCop linting defined in .rubocop.yml (.rubocop.yml)

Add a new React UI component

1. Create a new component file in app/assets/javascripts/react_app/components/ (app/assets/javascripts/react_app/components/YourComponent.jsx (reference; follow this path structure))
2. Write Jest/React Testing Library tests in tests subdirectory (.github/workflows/js_tests.yml (defines test runner))
3. Ensure component passes ESLint rules (.eslintrc.js)
4. Format code using Prettier (.prettierrc)
5. Import and use the component in parent pages/containers (app/assets/javascripts/react_app/pages/ (reference; integrate into existing pages))

Add a new backend dependency

1. Add the gem to the appropriate group in Gemfile (Gemfile)
2. Run bundle install to update Gemfile.lock (Gemfile (triggers Gemfile.lock update))
3. Verify tests still pass using the CI pipeline (.github/workflows/foreman.yml)
4. Update CHANGELOG.md with the dependency addition if user-facing (CHANGELOG)

Add a new frontend dependency or asset

1. Add package to package.json or use npm install --save (.npmrc (configuration; package.json is referenced implicitly))
2. Import the asset in the appropriate manifest or component file (app/assets/config/manifest.js)
3. Run Babel transpilation if modern JS syntax is used (.babelrc.js)
4. Verify linting passes and add tests (.eslintrc.js)

• Ruby on Rails — Rapid development of server-side business logic, ORM (Active Record), and RESTful conventions; ideal for a complex infrastructure management system
• React — Component-based UI for dynamic, interactive dashboards and real-time server state updates; separates frontend from backend via REST/API
• PostgreSQL (inferred) — Reliable relational database for storing server metadata, configurations, and audit trails with ACID guarantees
• Docker — Containerization for consistent deployments across on-premises and cloud environments; aligns with Foreman's multi-environment mission
• GitHub Actions — Native CI/CD tight integration with repository; automates testing, linting, and container builds on every commit

• Monolithic Rails app with React frontend rather than full microservices

  • Why: Simpler deployment, shared database transactions, and unified code review process for an open-source project
  • Consequence: Scaling individual features requires careful database optimization; tightly coupled data and presentation logic

• Sprockets asset pipeline for Rails + separate JS tooling (Babel, ESLint, npm)

  • Why: Compatibility with Rails conventions while supporting modern JavaScript/React; allows incremental modernization
  • Consequence: Dual asset management systems increase build complexity; some tooling coordination required

• REST API rather than GraphQL

  • Why: Simpler to understand and maintain for open-source contributors; fewer dependencies; stable Rails ecosystem patterns
  • Consequence: Over-fetching or under-fetching of data; less flexibility for UI to request exact fields

• GitHub-native CI (Actions) rather than external CI/CD platform

  • Why: Reduced external dependencies; native integration with repository events (PRs, pushes) and secrets management
  • Consequence: CI/CD logic lives in YAML; less ergonomic debugging compared to dedicated CI platforms

• Real-time WebSocket communication (uses polling/HTTP where needed)
• Kubernetes-native deployment (supports Docker and traditional VMs equally)
• Single sign-on (delegated to external auth plugins)
• Windows server provisioning and management (Linux-focused core)
• AI/ML-driven automation (orchestration only, not predictive/adaptive)
• Multi-tenancy at the core level (single-tenant per deployment)

1. Smart Proxy communication: Core functionality depends on external smart proxy processes (via foreman_smart_proxy gem integration)—tests may require proxy mocks or stubs. 2) Database schema complexity: Host/provisioning model involves heavy associations (organizations, locations, templates, facts) requiring careful migration testing. 3) Transifex integration (.tx/config present): Internationalization is baked in; changing UI strings requires Transifex workflow awareness. 4) Plugin dependency ordering: Plugin system (visible in plugins_react_tests.yml) can have subtle dependency resolution issues—test matrix may hide failures. 5) Background job serialization: Jobs likely use Delayed::Job or Sidekiq—changing host/provisioning model can break serialized job payloads mid-queue. 6) Rails version constraints: Monolith likely pinned to specific Rails major version (check Gemfile) making upgrades risky.

• Smart Proxy Architecture — Foreman's distributed provisioning relies on smart proxies handling DHCP, DNS, TFTP, and configuration management—understanding client/server split is essential for provisioning troubleshooting
• Provisioning Template Rendering — Foreman generates OS installation scripts (kickstart, cloud-init, etc.) by rendering templates with host facts and variables—this is the core automation mechanism
• Host Facts and Inventory Management — Foreman tracks discovered server hardware facts (CPU, RAM, network) and configuration facts (Puppet/Ansible reports) to drive provisioning decisions and monitoring rules
• Multi-tenancy via Organizations & Locations — Rails models likely use belongs_to :organization and belongs_to :location for multi-tenant isolation; required for enterprise deployments managing multiple sites
• RESTful API Versioning (v2 pattern) — app/controllers/api/v2/ indicates versioned API design for backward compatibility; critical since plugins and external tools depend on stable endpoints
• Rails Asset Pipeline with Modern JavaScript Tooling — .babelrc + .eslintrc + Webpack/npm alongside Rails indicate hybrid frontend architecture; understanding this dual-layer asset compilation is needed for UI changes
• Delayed Job / Background Job Processing — Procfile suggests multi-process setup with background workers; long-running provisioning tasks (OS install, Puppet runs) must be async to avoid request timeouts

• theforeman/smart-proxy — Companion repository implementing the smart proxy architecture that Foreman depends on for provisioning, DHCP, DNS, and configuration management integration
• theforeman/foreman-pxe — Provides PXE boot integration and provisioning template infrastructure that Foreman uses for bare-metal server deployment
• ansible/ansible — One of the four primary configuration management tools Foreman integrates with (alongside Puppet, Chef, Salt) via the plugin ecosystem
• theforeman/foreman_ansible — Official plugin adding Ansible-specific provisioning, configuration, and orchestration capabilities to Foreman core
• hashicorp/terraform — Common infrastructure-as-code companion in organizations using Foreman for VM/cloud orchestration across multiple providers

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for JavaScript linting and formatting validation

The repo has .eslintrc.js, .prettierrc, and .stylelintrc configuration files, plus a js_tests.yml workflow, but there's no dedicated pre-commit validation workflow for linting/formatting. This prevents style violations from entering PRs early. A new workflow would catch issues like incorrect Babel configuration, style inconsistencies in .svg and .png asset imports, and ESLint rule violations before review.

• [ ] Create .github/workflows/js-lint.yml that runs eslint on app/assets changes
• [ ] Add prettier --check validation for .js, .jsx, .css files
• [ ] Add stylelint validation for any .scss or style files in app/assets
• [ ] Configure workflow to block PRs if linting fails, similar to existing test gates
• [ ] Document in CONTRIBUTING.md how to run lint locally using the same config

Add unit tests for image asset manifest loading in app/assets/config/manifest.js

The manifest.js file handles asset configuration for a large number of OS icons (centos.png, debian.png, redhat.png, etc.) in app/assets/images/icons16x16/, but there are no visible tests validating that all referenced icons load correctly. Missing or misnamed icon files could silently break the UI. Adding tests would ensure icon paths are validated at build time.

• [ ] Create spec/javascript/assets/manifest.test.js to validate all icon files in app/assets/images/icons16x16/ exist
• [ ] Add test cases for stub icons in app/assets/images/icons16x16/stub/ directory
• [ ] Verify manifest.js correctly references all vendor logos (Ansible.png, Chef.png, Puppet.png, Salt.png)
• [ ] Add test to catch broken image references before deployment
• [ ] Integrate test into existing js_tests.yml workflow

Add Dependabot configuration for GitHub Actions workflow updates

The repo has .github/dependabot.yml for dependency management, but reviewing the structure, there's no explicit configuration section for keeping GitHub Actions (in .github/workflows/) up to date. Actions like container.yml, foreman.yml, and plugins_react_tests.yml may be using outdated action versions. Adding this prevents security vulnerabilities and ensures compatibility with latest GitHub features.

• [ ] Update .github/dependabot.yml to add a 'github-actions' entry with version-update-strategy set to 'auto'
• [ ] Set appropriate open-pull-requests-limit and reviewers for workflow PR reviews
• [ ] Test configuration by checking that Dependabot generates PRs for any outdated actions (e.g., actions/checkout@v3 → v4)
• [ ] Document in CONTRIBUTING.md how maintainers should handle Dependabot PRs for workflows
• [ ] Verify existing workflows in .github/workflows/*.yml are using pinned versions for reproducibility

• Add integration tests for Ansible provisioning template rendering: app/models/provisioning_template.rb exists but file list shows no test coverage detail; Ansible is listed as core integration point in README: Write test cases in test/models/provisioning_template_test.rb covering Ansible template variable substitution and host fact binding
• Document RESTful API endpoints for host provisioning lifecycle: README mentions RESTful API as core interface but no app/controllers/api/v2/ documentation visible in file list; users can't discover provisioning workflows: Add inline OpenAPI/Swagger comments to app/controllers/api/v2/hosts_controller.rb describing provision, power, reboot, rebuild endpoints
• Migrate legacy jQuery selectors to modern JavaScript in app/assets/javascripts/host_mgmt: .eslintrc.js and .prettierrc present indicating modern JS standards, but old jQuery code likely exists; improves maintainability for plugin developers: Find jQuery(document).ready blocks in app/assets/javascripts/, refactor to ES6 modules, ensure .github/workflows/js_tests.yml passes

• High · Container runs with root group permissions — Dockerfile, lines 13-16. The Dockerfile creates a foreman user with group ID 0 (root group) and sets directory permissions to g=u, allowing the container process to inherit root group privileges. This violates principle of least privilege and could allow privilege escalation if the foreman user is compromised. Fix: Create a dedicated non-root group (e.g., gid 1001) instead of using root group (gid 0). Change 'groupadd -r foreman -f -g 0' to 'groupadd -r foreman -f -g 1001' and update chown to use 1001:1001
• High · Incomplete Dockerfile environment configuration — Dockerfile, line 31 (BUNDLER_SKIPPED_GROUPS). The Dockerfile has an incomplete environment variable 'BUNDLER_SKIPPED_GROUPS' that is cut off mid-value. This could lead to unexpected behavior in dependency management and potentially missing security-critical groups in bundled gems. Fix: Complete the BUNDLER_SKIPPED_GROUPS environment variable with a proper value. Ensure all intended gem groups are correctly specified for production builds.
• Medium · Base image from external registry without pinned version — Dockerfile, line 2. The Dockerfile uses 'quay.io/centos/centos:stream9' without a specific version digest. This makes builds non-reproducible and vulnerable to supply chain attacks if the image tag is updated with vulnerable components. Fix: Pin the image to a specific digest: 'quay.io/centos/centos:stream9@sha256:...' instead of relying on the 'stream9' tag alone. Implement image scanning and regular updates in CI/CD pipeline.
• Medium · Missing dependency file analysis — Gemfile, package.json, package-lock.json (not provided). No Gemfile, package.json, or dependency lock files were provided in the analysis context. This prevents assessment of known vulnerable dependencies. The application uses Ruby gems, npm packages, and Node.js but dependency versions cannot be verified. Fix: Provide complete dependency files for analysis. Implement dependency scanning tools (e.g., Bundler Audit for Ruby, npm audit for Node.js). Enable Dependabot (already configured in .github/dependabot.yml) and act on its alerts promptly.
• Medium · Entrypoint script permissions and source — Dockerfile, lines 24-25. An entrypoint script is copied and made executable without verification of its contents or origin. If this script is world-writable or sourced from untrusted locations, it could be modified at runtime to execute malicious code. Fix: Ensure the entrypoint script has restrictive permissions (755 or 750). Add RUN chmod 750 /usr/bin/entrypoint.sh. Verify the script contents for injection vulnerabilities. Consider signing scripts if supply chain security is critical.
• Medium · Hardcoded example credentials in environment — Dockerfile, lines 4-5. Environment variables contain hardcoded example FQDNs and domains (foreman.example.com, example.com) that may be used as defaults. While marked as examples, the codebase should not rely on these for security decisions. Fix: Ensure these example values are never used in production. Implement configuration management that requires explicit production values. Document that these must be overridden for any real deployment.
• Low · Missing security headers configuration — Configuration files not fully visible. No visible configuration for HTTP security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) in the provided files. The application serves web content and should implement comprehensive security headers. Fix: Configure security headers in the Rails application (config/initializers or middleware). Implement: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security, etc.
• Low · Incomplete build configuration visibility — Dockerfile, from line 28 onwards. The Dockerfile builder stage is incomplete in the provided snippet. Full build, asset compilation, and dependency resolution steps are not visible, preventing comprehensive security analysis of the build process. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.