GitLab CI/CD Environments and Manual Deployments: Complete Beginner Guide

GitLab CI/CD Environments and Manual Deployments#

Learn how to use GitLab environments, deployment history, manual jobs, staging and production workflows, protected variables, protected branches, and safe production deployment patterns.

Table of contents#

• Quick answer
• What are GitLab environments?
• Environment types
• Basic environment example
• Manual deployment jobs
• Staging and production workflow
• Protected deployments
• Rollback and deployment history
• Common mistakes
• Best practices
• Related Melochip guides

Quick answer#

Environments#

Use environments to track where your application is deployed, such as development, staging, or production.

Manual jobs#

Use manual deployment jobs when a human should approve before deployment.

Protected deployment#

Protect production with protected branches, protected variables, and limited deploy permissions.

What are GitLab environments?#

GitLab environments represent deployment targets. For example, you can deploy the same application to development , staging , and production . GitLab can show deployment history, environment URL, and deployment status.

Common environment types#

Basic GitLab environment example#

You can add an environment to a deployment job using the environment keyword.

deploy_dev: stage: deploy script: - echo "Deploying to development" environment: name: development url: dev.example.com rules: - if: '$CI_COMMIT_BRANCH == "develop"'

This job deploys to the development environment and adds an environment URL in GitLab.

Manual deployment jobs#

Manual jobs are useful when you do not want deployment to happen automatically. Production deployment should usually require manual approval.

deploy_production: stage: deploy script: - echo "Deploying to production" environment: name: production url: example.com rules: - if: '$CI_COMMIT_BRANCH == "main"' when: manual - when: never

Staging and production workflow#

A practical deployment workflow can look like this:

stages: - test - deploy run_tests: stage: test script: - echo "Running tests" deploy_staging: stage: deploy script: - echo "Deploying to staging" environment: name: staging url: staging.example.com rules: - if: '$CI_COMMIT_BRANCH == "main"' deploy_production: stage: deploy script: - echo "Deploying to production" environment: name: production url: example.com rules: - if: '$CI_COMMIT_BRANCH == "main"' when: manual - when: never

In this example, staging deploys automatically after tests pass. Production waits for a manual approval.

Protected deployments and production safety#

For production, manual deployment alone is not enough. You should also protect branches, variables, and deploy permissions.

• Use protected branches such as main or release branches.
• Use protected variables for production credentials.
• Limit who can run production deployment jobs.
• Use separate variables for staging and production.
• Do not expose production credentials to feature branches.
• Review merge requests before production deployment.

Rollback and deployment history#

GitLab environments can help you track deployment history. A good deployment workflow should also support rollback or redeployment of a known good version.

Simple rollback idea:

rollback_production: stage: deploy script: - echo "Rolling back production to previous version" environment: name: production rules: - if: '$CI_COMMIT_BRANCH == "main"' when: manual - when: never

Common mistakes#

Best practices#

• Use clear environment names: development, qa, staging, production.
• Add environment URLs where possible.
• Use manual jobs for production deployment.
• Use protected variables for production secrets.
• Use protected branches for production release flow.
• Limit who can deploy to production.
• Separate staging and production credentials.
• Verify deployments after they complete.
• Keep rollback steps documented and tested.
• Review environment history after major releases.

Screenshot checklist#

You can add screenshots later from a safe test project:

1. GitLab Environments page showing development/staging/production.
2. Manual deploy button in a pipeline.
3. Deployment history for an environment.
4. CI/CD variables page with values hidden.
5. Protected branch settings.
6. Production deployment job log with secrets hidden.

• GitLab CI/CD Learning Path
• GitLab CI/CD Rules, Only, Except, and Workflow Explained
• GitLab CI/CD Variables and Secrets Explained
• GitLab CI/CD Deploy to Kubernetes
• GitLab CI/CD Multi-Stage Pipeline Examples
• Kubernetes Cluster Setup Guide

Official references#

• GitLab environments documentation
• GitLab job control documentation
• GitLab protected environments documentation

Conclusion#

GitLab environments and manual deployments help teams deploy safely and visibly. Environments show where your app is running, while manual jobs give humans control before sensitive deployments.

For production, combine manual jobs with protected branches, protected variables, limited deploy permissions, deployment history, and tested rollback plans.