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/opf/openproject 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 today
• 19 active contributors
• Distributed ownership (top contributor 20% 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 + OpenSSF Scorecard}

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

What it runs against: a local clone of opf/openproject — 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 opf/openproject | 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 dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of opf/openproject. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/opf/openproject.git
#   cd openproject
#
# 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 opf/openproject and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "opf/openproject(\\.git)?\\b" \\
  && ok "origin remote is opf/openproject" \\
  || miss "origin remote is not opf/openproject (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 dev >/dev/null 2>&1 \\
  && ok "default branch dev exists" \\
  || miss "default branch dev no longer exists"

# 4. Critical files exist
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f "Rakefile" \\
  && ok "Rakefile" \\
  || miss "missing critical file: Rakefile"
test -f ".github/workflows/test-core.yml" \\
  && ok ".github/workflows/test-core.yml" \\
  || miss "missing critical file: .github/workflows/test-core.yml"
test -f "app/assets" \\
  && ok "app/assets" \\
  || miss "missing critical file: app/assets"
test -f ".ruby-version" \\
  && ok ".ruby-version" \\
  || miss "missing critical file: .ruby-version"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/opf/openproject"
  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).

OpenProject is a web-based project management platform written primarily in Ruby on Rails with TypeScript/React frontend, offering work package tracking, Gantt charts, Agile/Scrum boards, time tracking, budgeting, and GitHub integration. It solves the problem of coordinating team efforts across projects by providing a unified interface for planning, execution, and reporting on collaborative work. Rails monoreith: backend API in app/controllers, app/models, app/services; frontend in TypeScript under frontend/src; migrations in db/migrate; extensive test suites parallel the source (spec/ directory). Configuration through .env.example, .editorconfig, ERB linting rules in .erb_linters/. GitHub Actions workflows orchestrate CI, release cycles, and downstream testing.

Project managers, Agile teams, and engineering leads who need self-hosted or cloud-based project management without vendor lock-in; also developers contributing to an open-source PM tool with complex scheduling and collaboration features.

Highly mature and production-ready: 36M+ lines of Ruby code, extensive GitHub Actions CI/CD pipelines (test-core.yml, docker releases, security scanning), established release management workflows with migration governance, and active commit history evidenced by multiple weekly workflows. This is a well-established open-source project with enterprise deployments.

Standard open source risks apply.

Active release management with merge-from-previous-release and release-into-dev workflows, ongoing frontend unit testing (test-frontend-unit.yml), i18n seeding across locales (seed-all-locales.yml), continuous security scanning (Brakeman, CodeQL), and Docker distribution pipelines. Crowdin integration for translation management is active.

Clone with git clone https://github.com/opf/openproject.git && cd openproject. Check .env.example for required variables (copy to .env.test.local for testing). Use bundle install for Ruby dependencies and likely npm install or yarn for TypeScript. Run docker-compose per Dockerfile, or consult DEVELOPMENT.md (inferred from README reference to installation guides).

Daily commands:

1. bundle install (Ruby gems). 2. npm install or yarn (TypeScript/React deps). 3. rails db:setup (migrate + seed). 4. rails server (Rails on :3000) + npm run dev (TS in parallel, or use Docker: docker-compose up). Check .env.example for DATABASE_URL, SECRET_KEY_BASE, RAILS_ENV=development.

• Gemfile — Defines all Ruby dependencies and gem versions; changes here ripple through the entire Rails application
• Rakefile — Entry point for all Rails tasks and build automation; defines database migrations, asset compilation, and testing workflows
• .github/workflows/test-core.yml — Core CI/CD pipeline that gates all commits; defines testing strategy and failure conditions for the entire project
• app/assets — Frontend asset pipeline for images, fonts, and styles; critical for UI rendering across all pages
• .ruby-version — Specifies the exact Ruby runtime version; mismatches here break the entire development environment
• Gemfile.modules — Modular gem configuration for plugins and extensions; enables OpenProject's extensible architecture
• .env.example — Template for all environment variables; developers must understand these to set up their first working instance

Add a New API Endpoint

1. Define the endpoint route using Rails routing conventions in config/routes.rb (config/routes.rb)
2. Create a new controller class inheriting from ApplicationController in app/controllers/ (app/controllers/)
3. Document the endpoint in OpenAPI spec referenced by .redocly.yaml (.redocly.yaml)
4. Add tests following Rails/RSpec conventions in spec/requests/ (spec/requests/)
5. Run linting with rubocop to ensure code style compliance (.rubocop.yml)

Add a New Frontend UI Tab

1. Create ERB template in app/views/ with OpenProject naming conventions (app/views/)
2. Add stylesheet assets in app/assets following the app/assets structure (app/assets/)
3. Lint your ERB template against rules in .erb_lint.yml (.erb_lint.yml)
4. Add integration tests in spec/features/ for the new UI component (spec/features/)
5. Update CHANGELOG.md with feature description for release notes (CHANGELOG.md)

Add a New Module/Plugin

1. Define gem dependency in Gemfile.modules under appropriate module section (Gemfile.modules)
2. Create module directory in modules/ following OpenProject plugin architecture (modules/)
3. Run bundle install and test using Rake tasks defined in Rakefile (Rakefile)
4. Verify CI passes for your module in .github/workflows/test-core.yml pipeline (.github/workflows/test-core.yml)

Set Up Local Development Environment

1. Copy .env.example to .env and configure environment variables for your setup (.env.example)
2. Install Ruby version specified in .ruby-version using rbenv or asdf (.ruby-version)
3. Run bundle install to install all gems from Gemfile and Gemfile.modules (Gemfile)
4. Start development services using Procfile.dev with foreman (Procfile.dev)
5. Run tests locally using rake test or specific test files in spec/ (Rakefile)

• Ruby on Rails — Mature web framework with strong conventions, integrated ORM (ActiveRecord), and built-in testing framework (RSpec) suitable for rapid web application development
• PostgreSQL — Production-grade relational database with ACID compliance and support for complex project management queries
• Redis — In-memory cache for session storage, job queues, and reducing database load on frequently accessed data like work packages
• Docker — Containerization enables consistent deployment across development, CI/CD, and production environments
• GitHub Actions — Native CI/CD integration with repository for automated testing, security scanning, and deployment workflows

• Modular monolith architecture (separate Gemfile.modules)

  • Why: Allows independent feature development without splitting into separate services initially
  • Consequence: Requires discipline to maintain module boundaries; coupling can increase as features grow

• Multiple CI/CD workflows (.github/workflows/) instead of single pipeline

  • Why: Enables parallel test execution and specialized scanning (security, linting, codeql) for faster feedback
  • Consequence: More complex to manage workflow dependencies; duplicate setup logic across files

• Rails monolithic app structure with asset pipeline

  • Why: Simplifies deployment and asset versioning for a centralized project management tool
  • Consequence: Harder to adopt modern frontend frameworks; less granular asset caching

• Custom ERB templates with linting (.erb_lint.yml) instead of component library

  • Why: Flexible template development without external dependencies
  • Consequence: Requires consistent style enforcement; harder to implement design systems

• Real-time collaborative editing (handled as separate Hocuspocus service)
• Mobile-first native apps (web-based only)
• Blockchain or decentralized features
• Cloud-agnostic multi-tenancy at kernel level (single-instance architecture)

1. Database setup: Migrations in release_migrations/ Dangerfile are gated; altering them requires special approval. 2. ERB linting: .erb_linters/ rules are strict; templates must follow conventions or CI fails. 3. Frontend/backend split: Changes to API contracts (frontend calls backend) need both TypeScript stubs and Rails controller updates; missing either breaks integration. 4. Environment config: .env.test.local.example shows test env differs from dev; DATABASE_URL, RAILS_ENV, and SECRET_KEY_BASE must be set. 5. Release branch workflow: Multiple Dangerfiles enforce commit message contracts (project_id_contract, user_references) to maintain traceability; casual commits may be rejected.

• Work Package (OpenProject domain model) — The core entity in OpenProject (analogous to Jira's Issue); all PM features (scheduling, time tracking, links, relations) pivot on work packages. Understanding the WP model is prerequisite to modifying any feature.
• Rails STI (Single Table Inheritance) — OpenProject likely uses STI for work package types (Task, Bug, Feature, etc.) stored in one table; you'll see this pattern in models/work_package*.rb and it affects querying and type safety.
• ERB linting (custom Danger rules) — OpenProject enforces ERB template quality via .erb_linters/erblint-github.rb; PRs fail linting before code review. Understanding Danger and ERB lint is mandatory for template changes.
• TypeScript React SPA with Rails API — Frontend is a separate TypeScript/React app calling Rails REST API (app/controllers/api/v3/); changes to either side need coordination. This decoupling allows independent frontend/backend iteration but requires API contract stability.
• Database schema versioning via Migrations & Release Workflows — OpenProject uses Rails migrations + special release_migrations dangerfile to gate schema changes; this prevents data loss in production. Migration changes require explicit review per .github/dangerfiles/release_migrations/.
• Gantt Chart scheduling and critical path analysis — Core PM feature in OpenProject (shown in file structure and README); involves dependency tracking, date calculation, and resource allocation. Modifying Gantt logic requires understanding precedence constraints and timeline recalculation.
• Multi-tenancy / Project scoping in Rails — OpenProject supports multiple projects in one instance; work packages, permissions, and views are project-scoped. Policy/permission checks are likely per-project; missing scoping causes security bugs.

• taiga-io/taiga-back — Similar Agile/Scrum PM tool written in Django; direct alternative in different ecosystem
• jira-server/jira — Canonical closed-source PM tool that OpenProject is often compared to; understanding Jira's design informs OpenProject's API and UX
• opf/openproject-docker — Official Docker images and compose configs for OpenProject; essential for containerized deployments
• opf/openproject-ce — Community Edition specific extensions and plugins; where optional PM features live
• plane-so/plane — Modern alternative PM tool written in React + Django; shows contemporary approaches to issues/projects that contrast with OpenProject's mature design

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 Action workflow for ERB linting validation in CI/CD pipeline

The repo contains .erb_lint.yml configuration and custom linters in .erb_linters/ directory, but there is no corresponding GitHub Actions workflow file for ERB linting (similar to existing eslint-core.yml, rubocop-core.yml, and brakeman-scan-core.yml workflows). This would ensure ERB template quality is validated on every PR, catching template issues early and maintaining consistency with other linting workflows.

• [ ] Review existing workflow patterns in .github/workflows/eslint-core.yml and rubocop-core.yml
• [ ] Create .github/workflows/erblint-core.yml that runs erb-lint against app/views and other ERB template directories
• [ ] Configure the workflow to fail on lint violations and report results on PRs
• [ ] Test the workflow by deliberately introducing ERB lint violations and verifying detection

Add integration tests for GitHub integration feature documented in README

The README prominently mentions GitHub integration for linking work packages to pull requests, but scanning the test-related workflows and config files reveals no dedicated test suite for this critical feature. Adding comprehensive integration tests would ensure this signature feature remains reliable across releases and prevent regressions.

• [ ] Create spec/integration/github_integration_spec.rb for testing work package ↔ PR linking
• [ ] Add fixtures in spec/fixtures/github/ for mocking GitHub API responses
• [ ] Write tests covering: authentication, PR linking, PR status sync, error handling for invalid/revoked tokens
• [ ] Integrate tests into test-core.yml workflow or create separate github-integration-test.yml workflow

Add OpenAPI documentation validation for endpoint authorization and permissions

The repo has .github/workflows/openapi.yaml and .redocly.yaml for OpenAPI spec linting, but there is no automated validation ensuring API endpoints document their required permissions (admin, project member, etc.). This would prevent documentation drift where endpoints gain permission requirements that aren't reflected in the spec, improving API clarity for integrators.

• [ ] Extend .redocly/plugins/rules/ with a new custom rule plugin (e.g., require-permissions-schema.js) that validates all endpoints have x-permissions or x-required-roles fields
• [ ] Update .redocly.yaml to enable and configure the new validation rule
• [ ] Add test cases in .redocly/plugins/rules/ testing the rule against valid and invalid endpoint specs
• [ ] Document the new permission schema requirement in the API contribution guide

• Add TypeScript unit tests for frontend/src/components/ files missing test files (grep for .test.ts/.spec.ts gaps). OpenProject has test coverage but some new components may lack tests; contributing tests improves reliability and teaches the component architecture.
• Document API contract changes: when modifying app/controllers/api/v3/*, update OpenAPI specs in .redocly.yaml and generate docs. Many endpoints likely have outdated OpenAPI definitions; fixing these helps API consumers and demonstrates API-first thinking.
• Improve ERB linting coverage: expand .erb_linters/erblint-github.rb with new rules (e.g., forbid inline styles, enforce data-testid attributes). This enforces team standards without code review churn and is a low-risk contribution.

OpenProject demonstrates a reasonable security posture with active CI/CD security scanning and dependency management. However, there are opportunities for improvement: (1) Review and restrict secrets/token files from version control, (2) Audit GitHub Actions workflows for proper secret handling and access controls, (3) Ensure security scan failures block deployments, (4) Implement stricter dependency management policies. The codebase is actively maintained with multiple security tools in place (Brakeman, CodeQL, Dependabot, RuboCop). The primary concerns are around configuration management and CI/CD security hardening rather than fundamental architectural issues.

• Medium · Public Security Token File — .openproject-token.pub. The file '.openproject-token.pub' exists in the repository root, indicating a public key file. While 'pub' suggests it's a public key, the presence of token files in version control can indicate improper secret management practices and potential exposure of authentication material. Fix: Ensure all authentication tokens and keys are excluded from version control. Add token files to .gitignore and use environment variables or secure secret management systems (e.g., HashiCorp Vault, AWS Secrets Manager) for token distribution.
• Medium · Environment Configuration Files in Version Control — .env.example, .env.test.local.example. Example environment files (.env.example, .env.test.local.example) are present in the repository. While these are templates, they may inadvertently contain hints about sensitive configuration variables or expose the application's configuration structure to potential attackers. Fix: Ensure actual .env files are in .gitignore. Keep example files minimal and sanitized. Document all environment variables without revealing sensitive defaults or structures that could aid attackers.
• Medium · GitHub Actions Workflow Security — .github/workflows/. Multiple GitHub Actions workflows are present (.github/workflows/). Without reviewing the content, workflows commonly have security risks including: exposed secrets in logs, insecure dependency handling, insufficient access controls, and vulnerable third-party actions. Fix: Audit all workflow files for: (1) Proper secret masking, (2) Pinning action versions with commit SHAs, (3) Using 'pull_request_target' carefully, (4) Implementing branch protection rules, (5) Regular review of third-party action security.
• Low · Brakeman and CodeQL Scanning in CI/CD — .github/workflows/brakeman-scan-core.yml, .github/workflows/codeql-scan-core.yml. While security scanning is enabled (brakeman-scan-core.yml, codeql-scan-core.yml), there is no visible evidence of whether scan failures block deployment or are merely informational. Fix: Configure workflows to fail the build on high/critical severity findings. Ensure scan results are reviewed before merging to default branch. Maintain updated scanning tool versions.
• Low · Dependency Management Workflow — .github/dependabot.yml. Dependabot configuration exists (.github/dependabot.yml), which is positive for keeping dependencies updated. However, automatic dependency updates without adequate testing can introduce vulnerabilities if updates are merged without thorough validation. Fix: Configure Dependabot to require status checks to pass before auto-merge. Implement comprehensive test coverage. Set up auto-merge only for patch updates of low-risk dependencies, and require manual review for minor/major version updates.
• Low · Missing SBOM Documentation — Root directory. No visible Software Bill of Materials (SBOM) or comprehensive dependency documentation in the provided file structure, which is important for vulnerability tracking and supply chain security. Fix: Generate and maintain an SBOM (using tools like CycloneDX or SPDX). Include dependency inventory in security documentation. Consider enabling GitHub's dependency graph and Dependabot alerts.

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.