GitLab

Projects are where code, issues, CI/CD, and settings live together. This tab teaches you how to create a project, set it up for a team, and keep it maintainable.

• Create or import a project and understand its structure.
• Set visibility, default branch, and essential settings.
• Connect members with the right access level.
• Set up basic conventions: README, labels, templates.

Use this when you’re starting a new repo, onboarding to an existing project, or standardizing how your org uses GitLab.

• New team repo or a hackathon project.
• Migrating from another Git hosting platform.
• You need consistent issues/labels across repos.
• You want to protect important branches and tags.

In GitLab UI, Projects are a top-level concept. From a project, you’ll navigate to Code, Issues, CI/CD, Security, Deployments, and Settings.

• Related: Managing code (MRs, branches).
• Related: Planning work (issues, boards).
• Related: CI/CD (pipelines, runners).
• Related: Extending GitLab (webhooks, API).

A project is a container: repository + collaboration + automation. Most configuration happens in project settings, and many settings inherit from group policies.

• Group → Project: groups can enforce standards and permissions.
• Repo content drives code workflows (branches/MRs).
• Issues/Boards track work tied to commits and MRs.
• CI/CD runs based on repository files and settings.

Projects connect a few core objects so you can trace work end-to-end.

• Project: top-level workspace for one product/service.
• Group: collection of projects with shared members/settings.
• Visibility: private/internal/public access scope.
• Members & roles: Guest/Reporter/Developer/Maintainer/Owner (varies by context).
• Project settings: repository, merge requests, CI/CD, integrations.

Projects typically mature from ‘just a repo’ into a governed, automated delivery unit.

• New: repo created/imported, minimal settings.
• Collaborative: members, README, issues, conventions.
• Governed: protected branches, approvals, policies.
• Automated: pipelines, environments, security scans.
• Operational: monitoring, incident response, audit.

These are the project-level tasks that unlock a smooth workflow.

• Create/import a project and choose visibility.
• Set default branch and branch protection rules.
• Invite members and assign least-privilege roles.
• Define naming conventions for branches and tags.
• Add templates (issue/MR) for consistent collaboration.

GitLab uses role-based access at group and project levels. Start least-privilege and elevate only when needed.

• Guest: limited access (often issues and comments).
• Reporter: read access with more visibility into project content.
• Developer: push to non-protected branches; create MRs.
• Maintainer: manage project settings and protected branches (commonly).
• Owner (group): manage billing/policies; not always per-project.

Projects integrate with tools through built-in integrations, webhooks, and CI variables.

• Use webhooks for chatops or deployment notifications.
• Use project/group CI variables for secrets and environment config.
• Connect container/package registries where applicable.
• Standardize integrations at the group level when possible.

Planning in GitLab centers on Issues, Boards, Milestones, and Labels. This tab helps you track work from idea → delivery without losing context.

• Create issues with clear acceptance criteria.
• Use labels and boards to visualize flow.
• Group work into milestones/iterations.
• Link code changes back to planning items.

Use this when you need a lightweight backlog, sprint-like planning, or cross-team visibility without switching tools.

• Product/engineering teams managing a backlog.
• Bug triage and prioritization.
• Sprint planning using milestones/iterations.
• Tracking deliverables across multiple repos via groups.

Planning features live in project/group navigation (Issues, Boards, Milestones/Iterations, Epics where available). Connect planning to MRs and CI results.

• Related: Managing code (link MRs to issues).
• Related: CI/CD (pipeline status on MRs).
• Related: Projects (labels/templates conventions).
• Related: Monitoring (incident issues).

A useful flow is: capture work as issues → refine → move across a board → implement via MR → close with reference. Keep the issue as the single source of truth.

• Issue is the planning anchor (why/what).
• Labels capture type/priority/status quickly.
• Boards visualize status by label.
• Milestones/iterations group issues by timebox.
• Merge requests implement and close issues.

These objects are enough for a strong planning workflow.

• Issue: unit of work (feature, bug, task).
• Label: flexible tagging for status/type/priority.
• Board: visual view of issues by labels.
• Milestone/Iteration: time-box grouping.
• Epic (if enabled): high-level work spanning issues.
• Assignee/Weight: ownership and effort signal.

Keep states simple and enforce them via labels/board columns. Don’t over-model early.

• Backlog → Ready → Doing → Review → Done (example).
• Transitions happen when criteria are met (not by time).
• Use ‘Review’ when code is in MR and waiting on approval.
• Use ‘Done’ when merged + verified.

These are the planning moves that keep teams aligned.

• Write a strong issue: context, steps, acceptance criteria.
• Triage: label and prioritize quickly.
• Run a weekly refinement session.
• Move issues across the board as work progresses.
• Close issues automatically from MRs using keywords (where supported).

Most planning actions require basic project access. If you can’t move issues or edit labels, ask a Maintainer to adjust permissions.

• Creating issues: typically Developer/Reporter depending on config.
• Editing labels/boards: often Maintainer.
• Group-level boards: require group access.
• Confidential issues: visibility depends on role.
• Audit who can change priority labels in sensitive projects.

Planning data becomes powerful when it connects to code and incidents.

• Use issue links/relationships for dependencies.
• Connect chat or alerting tools to create incident issues.
• Use webhooks/API to sync status if you must—prefer native first.
• Export/report from milestones for progress updates.

Code management in GitLab revolves around branches, merge requests (MRs), reviews, and approvals. This tab shows how to deliver code safely with predictable quality checks.

• Create MRs that are easy to review.
• Use diffs, discussions, and approvals effectively.
• Keep branches protected and enforce quality gates.
• Trace changes to issues and releases.

Use this if you’ll collaborate on a repository: feature branches, code review, and release-ready merges.

• Developers creating feature/bugfix branches.
• Reviewers approving changes.
• Maintainers setting merge policies.
• Teams wanting consistent merge strategy.

Inside a project, you’ll use Repository (files/branches), Merge requests, and Settings for merge policies. Code workflows connect tightly to CI/CD and Planning.

• Related: CI/CD (pipeline checks).
• Related: Projects (protected branches/settings).
• Related: Planning work (issues that MRs close).
• Related: Secure (security results on MRs where enabled).

Treat every MR as a mini-proposal: why → what changed → how to verify. GitLab then layers automated checks (CI) and human checks (review/approval).

• Branch contains your changes.
• MR describes intent and is the review surface.
• Pipeline validates build/test/security (as configured).
• Approvals enforce review policy.
• Merge strategy integrates changes to target branch.

These are the building blocks of code collaboration in GitLab.

• Merge Request (MR): proposed change from source → target branch.
• Diff: file-by-file change view.
• Review discussion: threaded comments on diffs.
• Approval rules: who must approve.
• Protected branches: restrict who can push/merge.
• CODEOWNERS: define required reviewers by path (if used).

A typical MR moves from draft → ready → approved → merged. Use this lifecycle to reduce churn and avoid half-baked reviews.

• Draft: collecting initial feedback; not ready to merge.
• Ready: scope stable; requests formal review.
• Approved: required reviewers signed off.
• Merged: integrated to target branch.
• Closed: abandoned or superseded (with explanation).

These are the tasks that keep code review efficient and safe.

• Create a MR from a feature branch.
• Write a reviewable description (context + test plan).
• Respond to review comments with follow-up commits.
• Handle merge conflicts.
• Choose merge method (merge commit/squash/rebase) per team policy.

Permissions matter most for protected branches and merge policies.

• Developers: typically create branches + MRs.
• Maintainers: configure MR settings, approvals, protected branches.
• Who can merge may be restricted by policy.
• If you can’t push a branch: check branch protection or role.
• If you can’t approve: ensure you’re in the required approver group.

MRs become stronger when paired with automation and traceability.

• Require pipelines to pass before merge (recommended).
• Connect issues: use references or closing keywords.
• Use webhooks/chat integrations to notify on MR events.
• Link deployments/environments in Deploy tab if you release from GitLab.

GitLab CI/CD automates building, testing, and deploying your code using pipelines defined in a `.gitlab-ci.yml` file. This tab shows how to create a first pipeline and keep it maintainable.

• Create a pipeline that runs on every push/MR.
• Understand jobs, stages, and artifacts.
• Choose and manage runners.
• Use variables safely for configuration and secrets.

Use this when you want repeatable builds/tests, faster feedback in code review, or automated releases.

• Developers adding tests/build steps.
• DevOps/SRE managing runners and deployment jobs.
• Teams wanting consistent quality checks.
• Projects adopting templates/components for reuse.

CI/CD lives inside each project (Pipelines, Jobs, Schedules, Settings > CI/CD). It ties into code review and deployment environments.

• Related: Managing code (pipelines required for merge).
• Related: Deploying & releasing (environments).
• Related: Managing infrastructure (runners, Kubernetes).
• Related: Extending GitLab (API, triggers, webhooks).

A pipeline is a sequence of stages, each containing jobs. Jobs run on runners. The YAML file defines when jobs run and what they do.

• Event triggers pipeline (push, MR, schedule, manual).
• Pipeline runs stages in order (build → test → deploy).
• Jobs run on runners (shared or self-hosted).
• Artifacts/Reports flow between stages.
• Status feeds back into MR as a quality gate.

These terms appear constantly in CI/CD setup and troubleshooting.

• `.gitlab-ci.yml`: pipeline definition file.
• Pipeline: full run of configured jobs.
• Job: a unit of work executed by a runner.
• Stage: an ordered grouping of jobs.
• Runner: agent that executes jobs.
• Artifacts: files saved from jobs for later stages/download.
• Variables: key-value configuration (including secrets).

Pipelines and jobs move through predictable states you’ll see in the UI.

• Created/queued: waiting for a runner.
• Running: executing on a runner.
• Success: finished with exit code 0.
• Failed: job or script failed.
• Canceled/skipped: not executed due to rules or manual stop.

These are the core CI/CD setup tasks for most repos.

• Add a minimal pipeline with lint + test jobs.
• Select the right runner (shared vs specific).
• Cache dependencies to speed up builds.
• Store secrets in CI/CD variables.
• Use rules to control when jobs run (MR vs main vs tags).

CI/CD configuration is usually controlled by project Maintainers, especially runner and variable settings.

• Editing `.gitlab-ci.yml`: anyone who can push to the branch.
• CI/CD settings (variables, protected variables): often Maintainer.
• Runner registration: typically Maintainer/Admin depending on scope.
• Protected branches + protected variables work together for safety.
• If a job can’t access a variable, check variable protection scope.

CI/CD integrates with container registries, package registries, environments, and external deployment targets.

• Publish build artifacts to the Package/Container Registry (if used).
• Trigger downstream pipelines or external deploy tools.
• Send job notifications to chat tools via integrations/webhooks.
• Use API/trigger tokens for programmatic pipeline runs (with least privilege).

GitLab can help you find and fix vulnerabilities as part of development. This tab focuses on beginner-friendly security habits: scanning in CI and reviewing results alongside code changes.

• Add security scanning jobs where available.
• Triage findings and focus on real risk.
• Fix vulnerabilities with traceability (issues/MRs).
• Keep secrets and dependencies under control.

Use this when you want earlier security feedback (before release) and a clear process to handle findings.

• Teams adding security to CI pipelines.
• Developers owning dependency and code risk.
• Maintainers setting policies for merge gates.
• Anyone responding to vulnerability reports.

Security features often show up in project navigation and in MR widgets (depending on configuration and tier). They rely on CI/CD to run scans.

• Related: CI/CD (where scans execute).
• Related: Managing code (review security results in MRs).
• Related: Planning (create issues for findings).
• Related: Deploying (block releases if critical issues).

Security is a loop: scan → review findings → fix → verify → monitor. Keep scans close to the code and treat findings like normal work items.

• Run scans on MRs and on default branch.
• Triage findings (severity, confidence, exploitability).
• Create issues for accepted work; document exceptions.
• Fix via MR and re-run scans to verify.
• Track status over time (trends, recurring issues).

Security terminology varies, but these concepts recur in GitLab security docs.

• Vulnerability: a weakness with potential impact.
• Finding: a scan result that may be a vulnerability.
• Severity: impact level (high/critical etc.).
• Dependency scanning: checks libraries for known CVEs.
• SAST: checks source code patterns for issues (where supported).
• Secret detection: finds leaked credentials (where supported).

Treat security findings like tracked work with clear states.

• Detected: scan reports a finding.
• Triaged: validated or marked false positive.
• Planned: issue created with priority and owner.
• Fixed: code change merged and re-scanned.
• Accepted: risk accepted with rationale and review date (if used).

Beginner security work in GitLab is about adding feedback loops and acting on them.

• Enable at least one scan in CI (dependency scanning is a common start).
• Review scan output on MRs and prioritize critical items.
• Create issues for fixes and link them to MRs.
• Prevent secret leaks with scanning + good credential practices.
• Regularly update dependencies and base images.

Security settings and policies are often restricted; coordinate with a Maintainer or security owner.

• Who can change CI config affects scan coverage.
• Who can dismiss/resolve findings depends on configuration/tier.
• Protect security variables (tokens/keys) like production secrets.
• Keep audit trails for accepted risks/exceptions.

Security often integrates with external tooling, but keep it simple early on.

• Feed scan results into issues/boards for workflow.
• Notify security channels for critical findings.
• Use package/container scanning where you publish artifacts.
• If exporting to SIEM/ticketing, keep a single source of truth.

Deploying and releasing in GitLab typically uses CI/CD jobs, environments, and release tagging. This tab helps you ship safely with staging-first habits and clear verification.

• Define environments (staging/production) and deploy jobs.
• Gate deploys with rules and approvals.
• Use tags/releases for versioning.
• Make rollbacks possible and visible.

Use this when you want GitLab to drive releases: build artifacts, deploy to environments, and track what’s running where.

• Teams doing continuous delivery.
• Services needing staging and production parity.
• Release managers coordinating cutovers.
• Apps deploying to Kubernetes/VMs/cloud.

Deployment features live around CI/CD, Environments, and Releases (project-level). They depend on a solid pipeline and good secrets management.

• Related: CI/CD (deploy jobs).
• Related: Managing infrastructure (clusters, runners).
• Related: Monitoring (verify after deploy).
• Related: Secure (don’t ship critical vulns).

A safe release flow is: build → test → deploy to staging → verify → promote to production. GitLab tracks this through pipeline stages and environment history (where configured).

• Build artifacts once; deploy the same artifact to each env.
• Use rules to control which refs can deploy (main/tags).
• Use manual steps for production early on.
• Record release notes and version tags.
• Verify with monitoring/health checks post-deploy.

These objects help you manage releases without guessing.

• Environment: a target like staging/prod.
• Deployment: a record of a deploy job run.
• Release: versioned package of changes (often tied to tags).
• Tag: a named commit (v1.2.3).
• Rollback: reverting to a previous deployment/version.
• Feature flags: gradual rollout controls (if used).

Deployments have simple, auditable states you can standardize.

• Pending: pipeline waiting for manual approval.
• Deployed (staging): running for verification.
• Promoted: production deploy executed.
• Rolled back: reverted to a previous version.
• Verified: monitoring confirms stability (your team’s definition).

These tasks cover most beginner release setups.

• Add deploy jobs for staging and production.
• Restrict deploy jobs with rules and protected refs.
• Store environment credentials as protected variables.
• Create tags/releases for versioned deployments.
• Add a rollback plan/job (even if manual).

Deploys are high-risk operations. Keep them gated by role and by branch/tag protections.

• Only allow Maintainers (or a release group) to deploy to production.
• Use protected environments/variables if available in your setup.
• Lock production credentials to protected branches/tags.
• Use manual ‘play’ jobs initially for production.
• Audit who can create tags/releases if that controls production deploy.

Deployments frequently integrate with cloud platforms and registries.

• Push images to a container registry then deploy from that tag.
• Use Kubernetes contexts/secrets via CI variables.
• Notify Slack/Teams on deployment events via integrations/webhooks.
• Record deployment metadata for audit (commit SHA, tag, pipeline link).

Infrastructure work in GitLab often means Infrastructure as Code (IaC), runner infrastructure, and cloud/Kubernetes integration. This tab helps you manage infra changes with the same MR + CI discipline.

• Track infra changes like application code (MRs + review).
• Automate plan/apply steps safely in CI.
• Manage runner capacity and execution environments.
• Keep environment credentials secure and scoped.

Use this if your team manages Terraform/Ansible/Kubernetes manifests, or you need to run CI jobs in specific environments.

• Platform/DevOps/SRE teams.
• App teams owning their Kubernetes manifests.
• Anyone managing GitLab runners.
• Teams standardizing environment provisioning.

Infrastructure topics connect across CI/CD (runners, jobs), Deployments (environments), and Integrations (clusters/cloud).

• Related: CI/CD (runners, pipeline jobs).
• Related: Deploying (environments, Kubernetes).
• Related: Secure (secrets and compliance).
• Related: Monitoring (infra health after changes).

Treat infra changes as high-risk: propose in MR → run ‘plan’ → review → apply with approvals. Separate read-only checks from write operations.

• MR triggers ‘plan’ jobs (read-only).
• Review outputs (diffs, plans) as part of MR.
• Apply jobs are manual and restricted to protected refs.
• Use environment-specific variables and scopes.
• Audit changes via pipeline/job history.

Infra work commonly uses these concepts in GitLab.

• Runner tags: route jobs to correct executors.
• Protected variables: restrict secrets to protected refs.
• Environments: map deploy/apply jobs to targets.
• IaC ‘plan’ vs ‘apply’: preview vs change.
• Kubernetes contexts/namespaces: target isolation.

A stable infra delivery lifecycle reduces outages.

• Change proposed: MR created with plan output.
• Approved: platform owners sign off.
• Applied: manual apply executed from protected pipeline.
• Verified: health checks/monitoring confirm stability.
• Postmortem: for incidents, create an issue and capture actions.

These are the minimum infra tasks to automate safely.

• Create a pipeline stage for lint/validate of IaC.
• Add a ‘plan’ job that runs on MRs.
• Add an ‘apply’ job that is manual and protected.
• Set runner tags for special environments (Docker-in-Docker, privileged, etc.).
• Document escalation/rollback procedures.

Infra operations should be restricted. Use protected branches/tags, protected variables, and limited deploy rights where available.

• Keep apply jobs manual and only for Maintainers/platform team.
• Use separate credentials per environment (staging vs prod).
• Restrict production credentials to protected refs only.
• Use dedicated runners for privileged jobs.
• Review access to runner registration and admin settings regularly.

Infrastructure usually integrates with cloud providers and Kubernetes. Keep the connection secure and auditable.

• Store kubeconfig/cloud credentials as protected variables.
• Use short-lived credentials where possible.
• Tag runners so only certain jobs can reach prod networks.
• Send change notifications to ops channels via webhooks/integrations.

Monitoring closes the loop after you deploy: you need signals to confirm changes are healthy. This tab helps you set up a basic monitoring workflow that connects incidents to issues and fixes.

• Define what ‘healthy’ means (SLO-lite).
• Create an incident workflow using issues.
• Capture evidence and follow-up actions.
• Verify fixes after deployments.

Use this when your team operates services and needs a repeatable way to detect, respond, and learn from problems.

• On-call developers and SREs.
• Teams shipping frequently and needing quick rollback signals.
• Anyone doing incident reviews/postmortems.
• Projects with staging/production environments.

Monitoring and incident handling connect to Issues (for incidents), CI/CD (for deploy verification), and Projects (for templates and permissions).

• Related: Deploying (verify after deploy).
• Related: Planning (incident issues and follow-ups).
• Related: CI/CD (automated smoke checks).
• Related: Extending (integrate alerting tools via webhooks/API).

A simple operating loop is: detect → triage → mitigate → fix → learn. Use GitLab issues to record the incident and track follow-ups as normal work.

• Detect via alerts/dashboards (internal or external).
• Triage: identify severity and owner.
• Mitigate: rollback, feature-flag off, scale, etc.
• Fix via MR + deploy.
• Learn via post-incident review and action items.

You’ll see these concepts in monitoring and incident workflows.

• Incident: service disruption requiring response.
• Severity: classification of impact/urgency.
• Runbook: documented steps to diagnose/mitigate.
• Postmortem: review of what happened and how to improve.
• Smoke test: fast verification after deploy.
• Alert routing: who gets notified and when.

Define a minimal incident state model so everyone knows what’s next.

• Open: incident active; mitigation underway.
• Monitoring: mitigated, watching for recurrence.
• Resolved: service stable; root cause identified.
• Follow-up: action items tracked to completion.
• Closed: learnings documented and shared.

These are starter monitoring and incident tasks you can implement quickly.

• Create an incident issue template (severity, timeline, actions).
• Define owner/rotation for on-call response.
• Add post-deploy verification (manual checklist or CI job).
• Integrate alerts to create issues automatically (optional).
• Track follow-up tasks in milestones/boards.

Incident response needs fast collaboration. Ensure the on-call group has permissions to create/edit incident issues and trigger rollbacks/deploys as defined.

• Ensure responders can create/edit issues in the relevant project/group.
• Restrict production deploy/rollback triggers to a trusted group.
• Keep incident communication channels accessible.
• Use confidential issues for sensitive incidents if needed.

Monitoring often integrates with external tools; keep GitLab as the system of record for incident tasks.

• Use webhooks/API to create issues from alerts (PagerDuty, Opsgenie, etc.).
• Post deployment notifications to chat tools.
• Store runbooks in repo/ Wiki for versioned updates.
• Link dashboards/logs as evidence in issues.

Extending GitLab means integrating it with your tools and automating workflows via webhooks, APIs, and tokens. This tab helps you start safely with the minimum required access.

• Use personal/project/group access tokens correctly.
• Set up webhooks for events you care about.
• Call the GitLab API for simple automation.
• Build lightweight integrations without compromising security.

Use this when you need to connect GitLab to chat, CI tools, deployment systems, or internal portals, or when you want scripts to manage projects/issues/MRs.

• Engineers automating repetitive admin tasks.
• Teams integrating chat notifications.
• Platform teams building internal tooling.
• Anyone needing to sync data between systems.

Extension points are usually in project/group Settings (Integrations/Webhooks) and in profile settings (tokens).

• Related: Projects (integrations at project or group level).
• Related: CI/CD (pipeline triggers, variables).
• Related: Monitoring (alert → issue automation).
• Related: Security (token scopes, least privilege).

Extensions work by either receiving events (webhooks) or making requests (API). Keep integrations minimal: only the events and permissions you actually need.

• Choose the event source (project/group/system).
• Choose the delivery method (webhook to your service).
• Authenticate with the smallest possible token scope.
• Handle retries and signature validation (in your service).
• Log/audit actions and rotate credentials.

These are the core concepts when integrating with GitLab programmatically.

• Access token: credential to call the API (various types).
• Token scopes: what the token is allowed to do.
• Webhook: GitLab sends event payloads to your endpoint.
• Event types: push, merge request, issue, pipeline, release, etc.
• Rate limits: API usage constraints (varies by offering).

Treat integrations like production systems with lifecycle management.

• Prototype: minimal scope + test project.
• Production: least privilege, monitoring, alerting.
• Rotation: periodic token rotation and key management.
• Deprecation: remove unused webhooks and tokens.
• Audit: review access and logs regularly.

Starter automation that pays off quickly.

• Post MR/pipeline notifications to chat.
• Auto-create issues from external alerts.
• Sync project metadata to an internal dashboard.
• Trigger pipelines from external systems (release tools).
• Bulk-manage labels/members across projects via API.

Automation is only as safe as its credentials. Always prefer minimal scope and consider using project/group-level credentials when possible.

• Prefer project/group tokens for scoped automation (when available).
• Use Personal Access Tokens carefully; don’t embed in client apps.
• Limit scopes to read-only unless write access is required.
• Store tokens in secret stores or CI/CD variables (protected/masked).
• Rotate/revoke tokens immediately if leaked.

GitLab supports many integrations, but the core building blocks remain: webhooks + API + CI triggers.

• Start with one integration endpoint per purpose (chat, alerts, deploy).
• Use environment-specific endpoints (staging vs prod).
• Monitor failures (HTTP 4xx/5xx) from webhook delivery logs.
• Document integration ownership and contact points.