Projects
Projects in Gitpod allow you to create standardized development environments across your organization. By defining consistent settings for repositories, runners, and environments, projects enable team members to create fully configured environments with just one click.
What are Projects?
A project in Gitpod serves as a blueprint for development environments, connecting a specific repository with predefined configurations. This ensures all team members work with the same standardized setup, eliminating “works on my machine” problems.
Projects provide several key benefits:
- One-click environment creation with consistent configuration
- Standardization of development environments across your organization
- Automatic secret and environment variable management
- Time savings by eliminating manual environment setup
- Team collaboration through shared project configurations
Prerequisites
Before creating a project, ensure you have:
- Organization administrator permissions
- At least one runner set up in your organization
Creating a Project
To create a new project:
- Navigate to your organization dashboard at https://app.gitpod.io
- If you have no existing projects, you’ll see the “No projects” screen
- Click Create project
No projects screen
- Enter the repository URL for your project
- Provide a descriptive project name
- Click Continue
Create project - Initial setup
- Configure your project settings:
- Select an Environment Class (determines the compute resources)
- Choose a Dev Container configuration or set up Automations
- Click Create project
Configure project settings
Project Configuration Options
Repository URL
The Git repository that will be cloned when an environment is created from this project.
Environment Class
Defines the compute resources (CPU, memory, storage) allocated to environments. Each runner can have multiple environment classes configured, but a project can currently only use one environment class.
Dev Container Configuration
Specifies how the development container should be configured, including:
- Base image
- Extensions
- Environment variables
- Port forwarding rules
Automations
Powerful tools that go beyond Dev Container configuration to define, automate, and share common workflows:
- Run services (long-running processes) and tasks (one-off actions)
- Automate database provisioning, test runs, or cloud authentication
- Define complex workflows in YAML configuration files
- Update via the Gitpod CLI
Managing Existing Projects
After creating a project, you can modify its configuration at any time:
- Navigate to your organization’s projects list
- Select the project you want to modify
- Use the settings panel to update configuration options including:
- Dev Container configuration
- Automations
- Secrets and environment variables
You can also activate projects (to share with your organization) or deactivate them when they’re no longer relevant.
Limitations and Troubleshooting
- Projects currently support only one environment class. If you need a project to run in different regions (on different runners), you must set up multiple projects
- Projects don’t yet have built-in support for multi-repo configurations, though they are supported through custom configurations
Next Steps
After creating a project, you can:
- Create an environment from your project
- Share the project with your team
- Configure additional automations
- Add project-specific secrets
For more detailed information on specific project features, refer to the Dev Container Configuration and Automations documentation.
Was this page helpful?