If your organisation has just made the call to replace ACS with VS Code and Aldon with GitHub, two things are true at the same time. The decision is sound — the tooling is better in every meaningful dimension. And the transition will be harder than whoever made the decision thinks it will be. What this guide does is get you from "we have been told to use these tools" to "our team is committing code and building programs with them" in a structured way, without breaking anything along the way.
This is not a vendor tutorial. This is written by someone who has watched several IBM i teams walk this path, and pays close attention to the places where they got stuck. Read it start to finish the first time. After that, keep it open as a reference while you work.
ACS and Aldon did their job for a long time. ACS gave you a green screen replacement that felt like a terminal. Aldon gave you a change management system that understood IBM i libraries, objects, and promotion paths. Both tools were built specifically for IBM i and fit the platform well.
What they did not do is integrate with the rest of the world. When the organisation decided to adopt GitHub for its .NET, Java, and web teams, the IBM i team stayed on an island. When the DevOps team built CI/CD pipelines that triggered from pull requests, IBM i releases still went through Aldon's promotion screens. When a new developer joined, they had to learn a toolset that nobody else in the industry uses.
The case for VS Code and GitHub is not that they are better editors than ACS or better change management than Aldon. The case is that they are the same tools every other developer in the organisation uses. That alignment — not any single feature — is the benefit.
The hardest part of this transition is not technical. It is the week three frustration when a senior RPG developer who has been writing clean code in SEU for twenty-five years suddenly cannot find a source member, cannot remember the Git command, and feels slower than the junior developer who joined last year. That frustration is real and it is temporary. What helps is acknowledging it openly. What hurts is pretending it is not happening. Give the team permission to struggle for a few weeks. Do not measure productivity during the transition — measure it six weeks in.
Before any tool is installed, the team needs to decide how it is going to work. There are two legitimate approaches, and the choice affects everything that follows.
Model 1 — Edit source members directly on the IBM i. Your RPGLE, CL, and DDS source stays in QRPGLESRC, QCLSRC, and so on, exactly where it has always been. VS Code connects to the IBM i over SSH, opens source members from member lists, and saves them back to the source physical files. Compilation happens on the IBM i the way it always has. Git, in this model, is not tightly integrated with your daily editing — it is a separate process where source members are periodically exported to a Git repository.
Model 2 — Local project files synced to the IBM i. Your source code is stored as streamfiles in a folder on your laptop. You edit locally, with all the features of VS Code and Git available inline. When you are ready to compile, VS Code deploys the files to your IFS home directory on the IBM i and runs the compile from there. The Git repository is the source of truth; the IBM i receives copies for compilation.
Start with Model 1 (source members). It is the smaller behavioural change. The team still thinks in QRPGLESRC and member lists, just with a better editor. You can ship real work within two weeks of installing VS Code.
Model 2 is more powerful and is where you want to end up. But it requires the team to simultaneously learn a new editor, a new workflow, a new source layout, and Git. That is too many changes at once for most teams.
A reasonable plan: eight to twelve weeks in Model 1 while the team gets comfortable with VS Code and Git basics, then a planned migration of a pilot application to Model 2.
The rest of this guide is written assuming Model 1 as the starting point. The Model 2 workflow differences are called out where they apply.
Go to code.visualstudio.com and download the installer for your operating system. Run it. On Windows, tick "Add to PATH" during installation — it is easy to miss. Launch VS Code once to confirm it opens.
VS Code is just an editor when you install it. Its power comes from extensions. You will install four of them before you do anything else.
Press Ctrl + Shift + X (Windows) or Cmd + Shift + X (Mac) to open the Extensions panel. In the search box at the top, type:
IBM i Development PackThe first result will be the pack maintained by the Code for IBM i team. Click Install. This single install gives you roughly a dozen extensions including the main "Code for IBM i" extension, RPGLE language tools, DB2 integration, debugger support, and the IBM i Project Explorer. Accept any prompts that appear.
After installation, restart VS Code. You should now see a new icon in the left sidebar that looks like an IBM i server — it appears below the standard icons for Explorer, Search, Source Control, and Debug.
If the IBM i icon does not appear after restart, the usual cause is that the extension pack did not fully install because VS Code is running in Restricted Mode on your workspace. Look at the bottom-left corner of VS Code. If it says "Restricted Mode", click it and choose "Trust". The extensions will then finish loading and the icon will appear.
VS Code connects to the IBM i over SSH, not over the 5250 or ODBC protocols that ACS used. Before you can connect, SSH has to be running on the IBM i. Log in with your usual 5250 session and check:
NETSTAT *CNNLook for any entry with local port 22 in the list. If you see port 22 in Listen state, SSH is running. If you do not, start it with:
STRTCPSVR SERVER(*SSHD)To check that it will start automatically the next time the system IPLs, work with the TCP/IP server auto-start list using CHGTCPSVR SVRSPCVAL(*SSHD) AUTOSTART(*YES). If SSH is completely unknown on your system, the 5733-SC1 licensed program product needs to be installed first — this is standard IBM shipping and your system administrator can confirm.
In a team setting, everyone generating their own SSH key and copying their public key to their IBM i user profile's .ssh/authorized_keys is a simple setup that works — until someone leaves the company and nobody knows which keys are authorised for which users. Before rolling this out to a team, decide whether keys will be managed centrally, whether you will use password authentication initially, or whether you have an identity management tool that handles SSH keys for the organisation.
Click the IBM i icon in the left sidebar. You will see a panel titled "IBM i" on the left with a button that says "Connect to an IBM i". Click it. A form appears at the top of the VS Code window asking for:
DEV-IBMi or PROD-IBMi. This is local to your VS Code only.Click Connect. Within a few seconds you should see the IBM i panel populate with sections for Objects, Libraries, IFS, and Database. If connection fails, the most common causes in order of likelihood are: SSH not running on the IBM i, a firewall blocking port 22, wrong password, and a user profile that is disabled or has password expired.
For the first month, password authentication is fine and simpler to reason about. Everyone on the team already has an IBM i user profile with a password. Get the team connecting and working first.
After the first month, switch the team to SSH key authentication. It is more secure, it means passwords do not get cached in connection dialogs, and it removes the small daily friction of re-entering a password. The Code for IBM i extension has built-in support for generating and deploying an SSH key — right-click on your connection and choose "Send SSH Key to Server".
With the connection live, you can now browse source physical files and edit members the same way you did in SEU or RDi — just in a better editor.
In the IBM i panel on the left, find the section labelled "User Library List". If it does not show the libraries you usually work with, right-click the section header and choose "Add Library to List". Add each library you need. This library list is connection-specific and persists between sessions.
The library list in VS Code works exactly like the library list in your 5250 session. It determines which library gets searched when you compile, which library unqualified object references resolve to, and the order of lookup.
In the IBM i panel, expand "Objects" and then expand a library, then a source physical file like QRPGLESRC. You will see the members inside. Click any member to open it in the editor.
The file opens with syntax highlighting, a minimap on the right, and all the standard VS Code editor features. Type your changes. Press Ctrl + S to save. The member is saved back to the IBM i immediately.
Source dates. If your shop uses source dates in column 1-6 of source members for change tracking, Code for IBM i handles this automatically but you need to enable it. Open the Code for IBM i settings (gear icon next to the connection) and ensure "Source Dates" is enabled. Without this setting, every line will appear as modified whenever you save, which is harmless but visually noisy and breaks change tracking for anyone still using tools that read source dates.
With a source member open, right-click anywhere in the editor and choose "Run Action on <member name>". A dropdown appears listing the available compile actions for this member type. For an RPGLE member, you will see options like CRTBNDRPG, CRTRPGMOD, or custom actions your team has defined.
Choose the appropriate action. The command runs on the IBM i and the output appears in a panel at the bottom of VS Code. If the compile fails, errors are shown inline in the editor — the line with the error gets a red squiggle, and hovering over it shows the error message. No more reading through spooled files.
The IFS section of the IBM i panel behaves like a file browser. You can navigate your home directory, create folders, edit streamfiles, and upload or download files by drag and drop. For IFS-based development (stored procedures in SQL files, Node.js code, shell scripts), this is where your work happens.
Before we connect GitHub to the workflow, there needs to be a shared understanding of what Git actually is. This is the single most important section of the guide. Teams that fail at Git fail because they never built the mental model — they kept running commands without understanding what those commands were doing.
When Aldon saw a change you made to a source member, it stored that change in its tracking system and promoted it when you asked it to. The mental model was: I edit the member, I check it in, it is saved somewhere else now.
Git does not work that way. With Git there are three separate places your code can be, and understanding these three places is the whole game:
1. Your working directory. The actual files on your laptop that you are editing right now. Changes here are invisible to Git until you tell Git about them.
2. The staging area (the "index"). A list of changes you have selected and are preparing to commit. You tell Git "these specific changes are the ones I want to save" before you actually save them.
3. The local repository. A database of permanent snapshots ("commits") on your laptop. Every commit is a point in time you can return to.
There is a fourth place — the remote repository (GitHub). But the first three exist entirely on your laptop. You can do useful work with Git without ever connecting to GitHub.
The basic cycle is: you edit files in the working directory, you stage the changes you want, you commit them to the local repository, and periodically you push commits from the local repository to the remote repository on GitHub so the rest of the team can see them.
Edit files → Stage changes (git add) → Commit to local repo (git commit) → Push to GitHub (git push)
And the reverse flow when picking up someone else's work: Pull from GitHub (git pull) → Files update in your working directory
A branch in Git is a lightweight pointer to a specific commit. Creating a branch takes milliseconds and uses almost no disk space. This is a fundamentally different model from what Aldon or Turnover gave you. In those systems, a branch was a heavy structural thing. In Git, a branch is nothing.
The standard workflow is: every piece of work happens on its own branch. When you start a new feature, bug fix, or change, you create a branch. You commit your work to that branch. When it is ready, you open a pull request, the team reviews it, and it gets merged into the main branch. Then the branch is deleted.
Working directly on the main branch — the equivalent of checking out from Aldon's production library and saving straight back to it — is possible in Git but it is the thing teams should make a rule against. Branches exist so that half-finished work can be saved, backed up to GitHub, and shared without it being taken as "this is ready".
A pull request is a GitHub feature, not a Git feature. It is a web page that shows the differences between your branch and the main branch, lets reviewers comment on specific lines, and provides the button that merges the change in when everyone approves.
Pull requests replace the Aldon approval workflow. Where you used to have a screen that listed pending promotions that needed approval, you now have a GitHub web page that shows the same thing — except it includes the actual code diff, line-by-line comments, automated checks, and a full audit trail of who said what and when.
Git is a separate tool from GitHub. Git is the version control system that runs locally on your machine. GitHub is a website that hosts Git repositories. You need Git installed on your laptop regardless of whether you use GitHub, GitLab, or anything else.
Download the Git installer from git-scm.com. On Windows, use the defaults for most options. One choice to pay attention to: when asked about line endings, choose "Checkout as-is, commit Unix-style line endings" — this prevents mixed line endings in code that will be deployed to the IBM i, where PASE is Unix-style.
Open a new command prompt (or terminal on Mac/Linux) and verify:
git --versionYou should see something like git version 2.44.0. If instead you see "command not found", close and reopen your terminal — Git added itself to the PATH and your existing terminal session does not know that yet.
Every commit you ever make in Git will have your name and email attached to it forever. This cannot be easily changed later. Set it correctly the first time:
git config --global user.name "Your Full Name"
git config --global user.email "your.work.email@company.com"Use your work email, not a personal one. Organisations that use GitHub Enterprise will require that the email on the commit match the email on your GitHub account — and that is validated on every push.
If your organisation uses GitHub Enterprise, your account will be provisioned by IT. Follow whatever onboarding process they have. If you are using GitHub.com, go to github.com and sign up. Use your work email.
In VS Code, press Ctrl + Shift + P to open the Command Palette and type:
GitHub: Sign InVS Code opens your browser, GitHub asks you to authorise the VS Code application, you click Authorise, and the browser redirects back to VS Code. You are now signed in. VS Code can now create repositories, clone existing ones, and push commits without being asked for credentials each time.
Many teams skip the VS Code GitHub sign-in and authenticate with a personal access token instead, usually because the organisation's SSO setup makes the browser flow unreliable. If that is your situation, generate a Personal Access Token on GitHub with repo scope, and VS Code will prompt you to paste it the first time you try to push. Store it somewhere safe because it will not be shown again.
For a team-level rollout, your senior developer or team lead will create the repository once, establish the folder structure, and everyone else will clone it. This section walks through both sides — the creator's first-time setup, and the subsequent clone that every team member will do.
Go to github.com (or your GitHub Enterprise URL), click the + in the top right, choose "New repository". Give it a descriptive name like order-management-ibmi. Set it to Private (almost always the right choice for business code). Check "Add a README file" so the repository is initialised with one commit.
Copy the repository URL (click the green "Code" button, copy the HTTPS URL). Open VS Code, press Ctrl + Shift + P, type "Git: Clone", paste the URL, and choose a folder to clone into. VS Code downloads the repository and asks if you want to open it. Say yes.
If you are in Model 1 (source members on the IBM i), you do not put source members in the Git repository directly. Instead you populate it with project metadata — the README, an actions.json file for Code for IBM i, and any documentation. The source members continue to live on the IBM i and will be exported to Git periodically (more on this below).
If you are in Model 2 (local project files), copy your source into the repository folder now. Organise it into subfolders: src/ for main programs, includes/ for copybooks, database/ for DDS or SQL definitions.
In VS Code, open the Source Control panel (the third icon in the left sidebar, or Ctrl + Shift + G). You will see your new files listed under "Changes". Click the + next to each to stage them (or the + next to "Changes" to stage everything). Type a commit message in the text box — "Initial project setup" is fine. Click the checkmark. Then click the three dots menu and choose Push.
Back on GitHub, go to the repository's Settings → Branches → Add rule. Require pull request reviews before merging to main. Require at least one approving review. This prevents anyone from pushing directly to main and enforces the review workflow from day one. Without this rule, the discipline breaks down within a month.
Once the repository exists on GitHub, every other team member needs to clone it to their own laptop. This is a one-time step per project:
Git: ClonePaste the repository URL (get it from the repo's main page), choose a folder location on your laptop, and VS Code clones it. This is your local copy of the repository. You now have everything — the full history, every branch, every file — on your machine.
This is the daily workflow. Read it, then come back to it every morning for the first two weeks until it is reflexive.
Open VS Code with your project. Before doing anything else, open the Source Control panel and click the three dots menu → Pull. This downloads any changes your teammates have pushed to GitHub since you last worked. If there are changes, you will see them flow into your files. If there are conflicts with changes you had in progress, VS Code will flag them — but if you followed the workflow yesterday and left in a clean state, this will just pull cleanly.
Any work you do today goes on a branch, not on main. Look at the bottom-left of the VS Code window. You will see something like "main" — that is the current branch. Click it. A menu appears at the top. Choose "Create new branch". Name it something meaningful, like fix/customer-inquiry-missing-trim or feature/new-pricing-api. Use hyphens, not spaces. Prefix with the type of change (fix, feature, chore).
The branch name is now shown at the bottom-left. You are working on it.
If you are in Model 1, open source members from the IBM i panel and edit them the usual way. If you are in Model 2, open files from the local folder.
Right-click the member and "Run Action" to compile. Fix any errors. Test in your test library.
When you have a small logical unit of change that works — even if the whole feature is not done — commit it. A good commit is one that, if you had to roll it back, you would roll back a coherent set of changes together. Do not wait until the end of the day to commit once with a huge batch of unrelated changes.
In the Source Control panel, stage your changes (+ icon), write a commit message, and click the checkmark. The commit is saved to your local repository. It has not been sent to GitHub yet.
A commit message is a note to your future self and your teammates. Good: Fix null pointer in customer inquiry when address line 2 is blank. Bad: fix bug. Good: Add audit trail to order update endpoint. Bad: updates.
Use the imperative mood — "Fix X", "Add Y", "Remove Z". It reads correctly when you review commit history later and think of each commit as an action that changed the state of the codebase.
After a few commits — or at the end of the day, whichever comes first — push your branch to GitHub. In Source Control, three dots menu → Push. Your commits are now visible on GitHub. If your laptop dies overnight, your work is safe.
Go to the repository on GitHub. You will see a yellow banner at the top saying "Your branch was recently pushed" with a button "Compare & pull request". Click it.
Fill in:
Click Create Pull Request. The reviewer gets notified. They will comment on specific lines, request changes, or approve. When approved, the pull request is merged into main. Your branch gets deleted. The cycle ends.
This is the specific question where most IBM i teams get stuck. You have RPGLE members in QRPGLESRC on the IBM i. You have a Git repository on your laptop. How do the two connect?
There are three legitimate approaches, and your team lead needs to pick one and stick with it.
The simplest approach and a reasonable way to start. Source members stay on the IBM i. Periodically — daily, weekly, or when a change is ready for review — a member is exported to the Git repository as a text file, committed, and pushed.
The export can be manual (use the Code for IBM i extension to download a member, save it as a file in the repo) or scripted (a CL program that iterates through a source file and writes members out to the IFS, followed by a Git commit from the IFS).
This approach preserves the SEU/PDM mental model. It works fine for smaller teams and smaller codebases. Its main weakness is that Git is not the source of truth — the IBM i is — so the Git history can drift from actual IBM i state if exports are not disciplined.
Source members are converted to streamfiles in the IFS (one file per member, with a sensible extension like .rpgle or .clle). A Git repository is created in the IFS folder containing those files. The IBM i's own installed Git (PASE) runs commits from the IFS. Compilation reads from the IFS streamfile, not from QRPGLESRC.
This is how many modernised IBM i shops end up. It works well but it is a significant change — compilation commands, build scripts, and developer habits all shift.
Source files live on the developer's laptop in a Git repository. Code for IBM i's "Deploy" feature copies them to the IFS on the IBM i when you are ready to compile. Compilation reads from the IFS location. The laptop's Git repo is the source of truth; the IBM i only sees the current state of files for compilation.
This is the most modern approach and the one with the best Git experience. It is also the biggest behavioural change. Save this for Model 2 adoption.
Pick Approach A as the team's first Git workflow. It is the most conservative change — nothing about compilation, source member layout, or the IBM i side moves. Get the team comfortable with Git the tool. After six to eight weeks, evaluate whether to progress to B or C.
Almost every team member will hit these in their first month. Each has a calm, clean recovery. Print this section and pin it.
Usually caused by: you switched branches and your editor is now showing the other branch's version of the files.
Check the bottom-left of VS Code. What branch does it say? Is it the branch you were working on? If not, switch back to your branch (click the branch name, pick the right one). Your changes are still there on the branch where you made them.
If that does not resolve it: open the Source Control panel. If you see changes there, your work is safe — you just need to stage and commit them. If the panel is empty, run git stash list in the terminal — you may have stashed them by accident.
That is a merge conflict. It means the same lines were changed both in your local copy and in the version on GitHub. Git does not know which to keep, so it is asking you to decide.
Open the conflicted file. You will see blocks like this:
<<<<<<< HEAD
your version of the lines
=======
the version from GitHub
>>>>>>> mainVS Code shows buttons above each conflict block: "Accept Current Change", "Accept Incoming Change", "Accept Both". Read both versions carefully, pick the right resolution, and the markers are removed. Save the file. Stage it. Commit. The merge completes.
If you are not sure what to do and you are panicking, run git merge --abort in the terminal. This undoes the pull entirely and puts you back where you were before. You can try again or ask a teammate for help.
You were on main, not on a feature branch, and you committed a bunch of changes. Now you want them on a feature branch and main to be clean.
In the terminal, from the folder of your project:
git branch feature/my-work
git reset --hard HEAD~1
git checkout feature/my-workLine 1 creates a new branch pointing at your current commit. Line 2 rewinds main by one commit (the commit is not lost — it is still on the branch you just created). Line 3 switches you to the new branch. You are now in the right place.
If there are more than one commit to move, change HEAD~1 to HEAD~2, HEAD~3, etc. — the number of commits to rewind.
Never run git reset --hard if you have commits that are only on your local machine and not pushed anywhere. The reset will delete them permanently. The safe rule: if you are not sure, do not run any command with --hard or --force in it. Ask someone first. These are the two flags that cause 90% of "Git ate my work" situations.
This is what I would have any IBM i developer do in their first month of VS Code and Git, in order.
Install VS Code, install the IBM i Development Pack, connect to the IBM i, and work entirely in source members. Do not touch Git this week. The goal is to become comfortable enough with the editor that switching from SEU does not slow you down. Focus on learning keyboard shortcuts — Ctrl+P to open a file by name, Ctrl+Shift+F for project-wide search, F12 to go to definition.
Clone your team's main Git repository. Browse it. Read the code. Look at the history. Open a few pull requests on GitHub (even merged ones from months ago) and read the conversations. Do not push anything yet. The goal is to build the mental model of what a repository looks like without the pressure of making changes to it.
Pick a tiny, low-risk change — a typo in a comment, a small refactor, a README update. Create a branch. Make the change. Commit. Push. Open a pull request. Get it reviewed and merged. Do this two or three times with similarly small changes. The goal is to exercise the whole workflow with something that cannot break anything, so that when you do it for real work you are not also learning the tooling.
Pick up an actual bug or small feature. Use the full workflow — branch, edit, compile, commit, pull request, review, merge. Do it without looking at this guide if you can.
After four weeks, every team member should be able to do the daily workflow without thinking about it. Expertise will keep developing for another six months, but the basics will be reflexive.
Once the team is comfortable with the tools, the conversations that become possible are big ones. Automated testing. Continuous integration. Deployment pipelines that promote changes from test to production without manual steps. Code reviews that are actually thorough because the diff view makes it easy. New developer onboarding that takes days instead of months because everything is in Git and documented in the same place as the code.
None of this is free and none of it is automatic. But it all becomes reachable once the team is past the initial learning curve — which is the curve this guide is designed to shorten.
Good luck.