Gitpod is an online platform that makes it easy to clone and run code from online code repositories like GitHub and Gitlab. It’s essentially VS Code in the browser, running on a temporary server called a workspace, which you can use for development.
This guide will cover how to use Gitpod to work on practice and required projects for the Backend Development and APIs, Quality Assurance, and other certifications later in the curriculum.
If you’d like to learn how to work on the projects locally, check out this article: How to Run the freeCodeCamp Backend Challenges Locally
Table of Contents
Frequently Asked Questions
Is Gitpod Free?
Yes, Gitpod has a generous free tier, and doesn’t require a credit card to start using their platform.
At the time of writing, Gitpod provides 500 credits per month, or approximately 50 hours of usage across all of your workspaces each month.
How Can I Check My Current Credit Usage?
To see your current credit usage across your different workspaces, visit this link: https://gitpod.io/usage
How Can I Check My Remaining Credits?
To see your remaining credits and your usage period, visit this link: https://gitpod.io/billing
How Long Will a Workspace Run?
If you’re actively working in a workspace, it will run for 8 hours.
By default, Gitpod will shut down workspaces that are inactive for 30 minutes.
You can read more about workspace statuses and timeouts here: https://www.gitpod.io/docs/configure/workspaces/workspace-lifecycle
How Can I Save My Workspaces?
Gitpod workspaces are meant to be temporary development environments, so workspaces that have been stopped for 14 days are automatically deleted.
But if you pin a workspace on the Gitpod workspaces dashboard, it will never be deleted.
Read this section of the guide to learn how to pin a workspace.
How Can I Share My Workspace To Get Help?
You can create a snapshot of your workspace to generate a sharable URL you can use on our forum or our Discord, for example.
However, your snapshot WILL include your .env file, with any secret values you have written. Before generating a snapshot, you should move the secrets from the .env file to your user variables, which are not shared in your snapshot.
Gitpod Basics
Start a New Workspace
The main way you’ll start a new workspace on Gitpod is to go to the first challenge of a practice or required certification project page and click on a link.
For example, if you want to use Gitpod to start working on the challenges for the Managing Packages with NPM practice project, go to the first challenge, How to Use package.json, the Core of Any Node.js Project or npm Package.
Then, click on the link that reads “our Gitpod starter project”:
A new tab will open and Gitpod will automatically start up a workspace with the boilerplate code you need for that project.
Alternatively, if you know which freeCodeCamp boilerplate repository you need for the project you’ll work on, you can open a URL with this format in your browser: https://gitpod.io/?autostart=true#<repository-url>
For example, to start a workspace with the boilerplate code you need for the required Timestamp Microservice certification project, you can open this link in your browser: https://gitpod.io/?autostart=true#https://github.com/freeCodeCamp/boilerplate-project-timestamp/
Stop a Workspace
To stop a workspace, first close the tab or window with the active workspace.
Next, go to the Gitpod workspaces dashboard here: https://gitpod.io/workspaces
Find your workspace in the list and click on the kebab button, or the three vertical dots, and then click “Stop”:
This will stop your workspace until you restart it, or it gets deleted.
Open an Existing Workspace
To open a workspace you’ve already created and continue developing, go to the Gitpod workspaces dashboard here: https://gitpod.io/workspaces
Next, find your Gitpod workspace and click on its name, which is usually freecodecamp-boilerplate-<autogenerated-key>.
Alternatively, you can click on the workspace’s kebab button / three vertical dots, then click “Start”:
Delete a Workspace
WARNING: If you delete a workspace without pushing your changes to your fork, your changes will be lost and cannot be recovered. Read this section of the guide about how to create a new repository and push your changes to it.
To delete a workspace, go to the Gitpod workspaces dashboard here: https://gitpod.io/workspaces
Then find your workspace, click on the kebab button / three vertical dots, and click “Delete”:
Pin a Workspace
Any workspaces that have been stopped for 14 days will be deleted automatically. But pinned workspaces will never be deleted, and Gitpod will save them indefinitely.
To pin a workspace, first go to the Gitpod dashboard here: https://gitpod.io/workspaces
Find your workspace in the list, click on the kebab button / the three vertical dots, and click “Pin”:
Developing on Gitpod
Open the terminal
When you start a new workspace or open an existing one, the terminal should open automatically. But if you close it accidentally, here’s how you can open the terminal again.
To open the terminal with keyboard shortcuts, press Ctrl + `. Note that this shortcut is a toggle, and you can open and close the terminal with the same shortcut.
To open the terminal through the GUI, click on the hamburger icon / three horizontal lines in the upper left corner of the screen. Then, click on “Terminal”, and “New Terminal”:
Open the Preview
Many of the projects include a client or frontend, which you can see in the preview pane or in a separate tab/window. But if you accidentally close the client preview, follow these steps to open it again.
First, make sure you’ve started your project by following the instructions in this portion of the guide: Start and Stop Projects
Then, open the terminal and click on “Ports”:
Then to open the client preview as a separate pane in VS Code, click the “Open Preview” button:
Or to open the client preview in a new tab, click on the link under “Addresses”, or the “Open Browser” button:
How to Save Your Changes on GitHub
Most of the projects on freeCodeCamp are practice projects, and are there to help you prepare for the required certification projects you need to complete to claim a certification. While you don’t need to save your progress or final solution for the practice projects like Managing Packages with NPM, we strongly recommend that you save your progress for required certification projects like Timestamp Microservice.
As mentioned earlier in the guide, pinned workspaces won’t get deleted automatically by Gitpod. That said, the best way to save your progress and final solution for required certification projects is to push your code to Github. But this requires some setup, like creating a new repository, or repo for short, adding your repo as a remote, and pushing your changes there.
You can follow along even if you don’t know anything about Git. But if you’d like to learn the basics before continuing, check out these resources:
- Git and GitHub Tutorial – Version Control for Beginners
- Learn Git by Building an SQL Reference Object
Also, while these directions are written with GitHub in mind, the process should be similar for other code repositories like GitLab and Bitbucket.
Create a New Repo on GitHub
Sign into Github and go to the homepage and click the button with the + symbol, and click “New repository” in the dropdown:
On the next page, give your repository a name that reflects the required certification project you’re working on, and make sure it’s set to “Public”:
Then click the “Create repository” button at the bottom of the page.
Update Your Permissions on Gitpod
Before you can push code to your new GitHub repo, you’ll need to update the your permissions on Gitpod.
First, go to the “Git Providers” dashboard here: https://gitpod.io/user/integrations
Next, click the kebab button / three vertical dots and click “Edit Permissions” in the dropdown:
Then in the popup window, enable the checkbox near “public_repo” and click the “Update Permissions” button:
Add Your Repo As a Remote
Open a terminal in the workspace for the required certification project you’re working on. If a process like the Express server is running, you can stop it with Ctrl + c.
In the terminal, enter in the following commands one-at-a-time:
git remote set-url origin https://github.com/<github-username>/<repository-name>.git
git branch -M main
git push -u origin main
Note that you should add your own GitHub username and the name of the repository you created earlier for the .git address in the first command. For example, if your GitHub username is camperbot and the repo you created earlier is named timestamp-microservice, the first command would be: git remote set-url origin https://github.com/camperbot/timestamp-microservice.git
After following these steps, you’ll push the initial boilerplate code to a branch called main in the repo you created. Once that’s done, you can start developing and pushing your changes to a new branch in your GitHub repo.
Push Your Changes to Your Repo
Again, this is just a quick guide to get you started. If you’d like to learn more about best practices while working with Git, check out the resources listed in this section.
Create and Checkout a New Branch
Generally it’s not good practice to push changes directly to the main branch. Instead, it’s better to create a new branch, develop there, and to merge those changes into main once everything looks good.
Create and checkout a new branch with the following command: git checkout -b <branch-name>
For example, if you want to create and checkout a new branch named feat/timestamp-solution, the command would be as follows: git checkout -b feat/timestamp-solution
Add Updated Files to the Staging Area
After making your changes in VS Code in your Gitpod workspace, you need to add them to the staging area.
You can add a single file or directory with the following command: git add <file-or-directory-name>
You can also add multiple files or directories and once: git add <file-or-directory-name-1> <file-or-directory-name-2>
Or to add all the updated files at once with the following command: git add .
Write a Commit Message
Now that your updated files have been added to the staging area, you need to write a commit message to save a snapshot of all the changes at once.
To write a commit message, use the following command: git commit -m "<commit-message>"
For example, if you want to write a commit message that reads feat: add UNIX timestamp endpoint and response, the command would be git commit -m "feat: add UNIX timestamp endpoint and response".
You can write any commit message you want, but a short, concise message that explain what changes you made and why are best.
Check out this tutorial for tips on how to write better Git commit messages: How to Write Better Git Commit Messages – A Step-By-Step Guide
Push Your Changes to Your GitHub Repo
Finally, you can push your changes up to your repo.
If this is the first time you’re pushing changes to your repo, you can set the upstream branch and push your changes with the following command: git push --set-upstream origin <branch-name>
For example, if your branch is named feat/timestamp-solution, the command would be as follows: git push --set-upstream origin feat/timestamp-solution
If this is not the first time you’re pushing changes to your branch and you’ve already set the upstream branch, you can use this command: git push
After this you’ll have a new branch in your GitHub repo with the name you gave it. Once you’re happy with all of your changes and you’ve finished developing your project, you can open a pull request on GitHub to merge the changes from your new branch into the main branch.