IBM Project4i — User Guide

Project4i is a companion to the Code for IBM i extension: it never talks to your system directly, it builds on the connection you already trust. You need VS Code or IBM BOB, the Code for IBM i extension, and an active IBM i connection.

1. Install Project4i from the VS Code Marketplace or the Open VSX Registry.
2. Connect to your IBM i system through Code for IBM i.
3. Open the IBM Project4i view in the Activity Bar.
4. On a fresh system, run the Setup Wizard to bootstrap your IFS root, environments, and promotion pipeline. If your organization is already configured, you simply join it.

A Home / Welcome view guides your first steps and links to the main actions.

A project group is a logical bundle of source members drawn from any library — you are no longer tied to physical library boundaries. You can mix native QSYS source members and IFS stream files in the same project.

• Create a project from the Projects view (the + action).
• Add a member by right-clicking it in the Object Browser → Add to Project; a physical checkout copy is placed in the project's dev library.
• Collaborative lock — lock a member while you edit it. A lock icon shows who holds it; release your own lock, and project owners can force-unlock.
• Conflicts — a member added to more than one project is flagged In Conflict, which blocks promotion until you resolve it.
• Missing / orphaned members — a health check flags members that no longer exist on IBM i so you can remove them individually or in bulk.

In a Git project the source of truth is a Git repository hosted on the IFS of your own IBM i: you edit files locally, commit, branch and merge, and the promote engine then builds what reaches each environment from a commit. Nothing leaves your system, and nothing changes for projects that stay traditional.

• Chosen per project, at creation time. A project with no explicit mode is traditional — there is no migration and no conversion of existing data.
• Repository layout — one folder per source physical file (src/QRPGLESRC/PGM1.RPGLE), so members with the same name in different source files never collide.
• A merge never writes to production — at most it triggers a deploy to DEV. Pre-promote backup, authority policy, data-safety gate on *FILE objects, deploy register and rollback all still apply.
• Advisory lock — the member lock warns instead of blocking. There is deliberately no blocking level: on fixed-format sources (RPG III/IV, DDS) an automatic merge can move fields into the wrong columns, so the warning still earns its place.
• Development libraries — one per project by default, or one per developer so that people on different branches stop overwriting each other. A name longer than 10 characters is refused, never truncated.
• Environment checks — the Setup Health Check reports a missing git, a version that is too old, or a missing SSH client, with a severity that depends on whether you actually use Git Mode.
• Line length is verified before a commit, with the line number: IBM i truncates an over-long line without failing the command.

Git Mode is being finalised and is not yet enabled in the published release. Everything else on this page is available today.

Each project defines its own promotion pipeline — an ordered chain of environments such as DEV → TEST → PROD (the built-in seed is a 7-tier chain you can rename, reorder, add to, or trim).

• Every environment maps to a set of libraries: a source and object library (required), plus optional data, config, backup, journal libraries and an IFS path.
• Libraries are exposed to your compile templates as generic, type-based variables (for example &DEV_SRC_LIB, &PROD_OBJ_LIB), so one template works across every project.
• The environment definition also drives the JOBD library list used when commands run natively on IBM i.

Promote moves a member from one environment to the next, compiling it with the right command for its source type. Every promote takes an automatic pre-promote backup so you can roll back safely.

• Compile Map — customizable CL templates per source type (RPGLE, CLLE, DDS, SQL…) with variable substitution; prefix a template with ? to open a visual prompt for its parameters.
• Data-safe promote — when a target object already exists, CRTPF becomes CHGPF (data migrated by field name) and an existing SQL table is preserved, so production data is never lost.
• Rollback — restore a member's pre-promote backup after a promote. When no backup exists, Project4i offers a confirmed cleanup instead.
• Blocked cases — for data safety, rollback of physical/logical data files (PF/LF) is intentionally skipped.
• Approval — promotion can require maker-checker sign-off: request approval, then a different user approves or rejects before deploy.

A deployment package bundles several members into one named release that you deploy together as a single governed operation. Each project has an always-visible Deployment Packages folder.

• Create a package with a name, optional release notes, and an optional shared ticket ID; members are shown in build-dependency order.
• Deploy promotes the members in build tiers (files → display/print → programs → CL → service programs) and stops on the first failure.
• Promote All deploys the entire project sequentially, with Run / Skip / Run All / Cancel controls and auto-skipped conflicts.
• Rollback restores every member's pre-deploy backup in reverse build order.

Project4i can promote across multiple IBM i systems, not just the one you are connected to. A server catalog holds the connection details of your remote systems.

• Assign a remote server to a target environment to promote there over SSH / PASE, including the pre-promote backup and rollback.
• Source transfer between systems — when enabled, the source member is copied to the remote system before it is compiled there.
• Server passwords are stored encrypted and never kept in project files, on the IFS, or in logs.

Shared projects store their metadata and audit trail as files on the IBM i IFS, so a whole team can collaborate in real time. Set the IFS root once, then create or join shared projects and sync them at any time.

• Roles & permissions — Owner, Contributor, and Viewer, with granular per-contributor permissions (add, promote, run action, document, and more).
• Approval workflow — an optional maker-checker gate; the requester cannot approve their own change.
• Global catalog — for enterprise setups, an organization centrally publishes default environments, servers, workflow commands, variables, and the source inventory, pulled automatically when you connect.

Understand the blast radius of a change before you release it. Project4i scans the relationships between your IBM i objects — programs, files, service programs, modules, logical→physical files, data areas, data queues, message files, triggers, and binding directories — into an interactive graph.

• Scan in the foreground with a live monitor, or as a background batch job on the server that you can detach from and re-attach to later.
• Impact Analysis 360 answers two mirror questions about any object: Used by (who depends on me) and Uses (what I depend on), at the first level or transitively with a configurable depth.
• Navigate with an object finder, drill down through a breadcrumb trail, and switch to a Diagram view of the same sub-graph.
• Open the source of a related object read-only, and while editing a source you can Ctrl/Cmd+click a referenced program, file, or table to jump to its source.

Inventories tell Project4i where your source and objects live, and the search tools help you find members fast across libraries.

• Source Inventory — an org-wide catalog of source containers (library/file) with descriptions, shared with the team and used by templates, AI, and the impact-analysis perimeter picker.
• Object Inventory — the object libraries that define the scope of a dependency scan.
• Member Search — search by name, type, description, changed-after date, and even inside the source content, from a sidebar view or a full panel.
• Source Collections — save a search as a reusable, named collection and re-run it later.

Project4i includes an optional AI suite that helps you document and analyze your code. AI features are entirely optional and run through a pluggable backend.

• AI documentation — generate technical and functional documentation from your source members, previewed in VS Code and openable in Word.
• Change-impact analysis — describe an intended change and let the AI judge which members are affected, with confidence and reasoning.
• Bring Your Own LLM — run the AI on VS Code models (GitHub Copilot) by default, or point it at any external OpenAI-compatible endpoint. Your API key is stored securely and never written to project files, the IFS, or logs.

Day-to-day helpers keep the whole team aligned and let you tailor Project4i to your standards.

• Activity Log — a filterable, team-synced audit trail of every action (create, promote, package, approval, rename, error).
• Kanban board — a Dev → Promoted → In Test lifecycle board with automatic state transitions on promote.
• Workflow commands — customizable CL templates for promote, checkout, release, and IFS promote, seeded from your global defaults.
• Run Action — run a reusable custom CL command on any member straight from its context menu.

Everything lives inside VS Code and IBM BOB, styled with the Deep Space design.

• Projects TreeView — a sidebar that shows your projects, members, deployment packages, and documentation, grouped for a clear overview.
• Control Panel — a two-column settings panel for global defaults (developer info, environments, workflow commands, variables, inventories, AI backend).
• Project Properties — a per-project panel for environments, promote configuration, custom variables, and permissions.
• Full Dark / Light theming with custom icons and color-coded nodes.