GitHub and GitLab Platform Essentials

Introduction and Context

Git provides distributed version control, but GitHub and GitLab provide the collaborative, administrative, and delivery platforms built around Git repositories. They help teams review code, manage work, document systems, control access, publish releases, and automate software delivery.

Although GitHub and GitLab use similar concepts, their terminology and feature organisation differ. GitHub commonly uses organizations, repositories, teams, issues, Projects, milestones, wikis, and releases. GitLab commonly uses groups, projects, members, issues, epics, milestones, iterations, wikis, releases, and issue boards. The word project therefore requires care: in GitHub it often refers to a planning board, whereas in GitLab a project is primarily the container for a repository and its development resources.

For a DevOps practitioner, platform administration is not merely a user-interface task. It is a governance activity involving identity, least privilege, traceability, collaboration, compliance, and automation.

Learning Objectives

After completing this chapter, learners should be able to:

1. Create and administer repositories and GitHub organizations or GitLab groups.
2. Select suitable visibility, membership, team, and permission settings.
3. Configure issues, labels, milestones, wikis, releases, and project boards.
4. Compare important GitHub and GitLab terminology and workflows.
5. Apply governance and security principles to collaborative repositories.
6. Design a practical platform structure for a small DevOps team.

1. The Platform Object Model

A useful way to understand either platform is as a hierarchy of resources:

Figure: A conceptual hierarchy of platform resources and collaboration functions.

At the top level, an organization or group provides shared identity and administration. Repositories or projects contain source code, history, configuration, and often automation. Teams and members receive access through roles. Collaboration resources describe work and its status, while policies regulate how changes are proposed, reviewed, merged, and released.

2. Repositories, Projects, Groups, and Organizations

Repositories and GitLab projects

A repository contains Git objects such as commits, trees, and references. On a hosting platform it also contains associated metadata: pull or merge requests, issues, discussions, actions or pipelines, settings, security reports, and release information.

GitLab calls its principal collaborative container a project. A GitLab project normally includes a repository, issues, merge requests, a wiki, CI/CD configuration, packages, and security features. A GitHub repository is the closest equivalent.

When creating a repository or project, the administrator should decide:

• Name and purpose: use a stable, descriptive name such as payments-api rather than a personal or temporary label.
• Visibility: public, private, or an organisation-managed intermediate option. Public repositories expose code and metadata to the internet; private repositories restrict access to authorised users.
• Initial content: README, licence, .gitignore, and default branch.
• Ownership: personal ownership is often unsuitable for production work; organisational ownership supports continuity.
• Protection: default branch rules, required reviews, status checks, signed commits where appropriate, and secret scanning.

A repository should have one clear purpose. Combining unrelated applications increases permission complexity, obscures ownership, and makes release and issue management difficult.

Organizations and groups

A GitHub organization is a shared namespace for repositories, members, teams, billing, policies, and security controls. A GitLab group is a shared namespace that can contain projects and nested subgroups. Groups are especially useful when several products share a department, platform, or lifecycle policy.

A sound namespace reflects responsibility rather than individual employment history. For example, a company might use:

• acme/platform for reusable infrastructure;
• acme/customer-products for customer-facing applications;
• acme/sandbox for experimental work.

The exact structure should remain simple. Excessive nesting can make ownership and permissions difficult to understand.

Forks, templates, and duplication

A fork is a server-side copy associated with an upstream repository, commonly used when contributors cannot directly write to the source repository. A template repository provides a starting structure for new repositories without implying that changes flow back to the template. A normal clone is only a local working copy and does not create platform-level collaboration relationships.

3. Identity, Teams, Roles, and Permissions

Authentication establishes who a user is; authorization determines what that user may do. Platforms may support passwords, single sign-on, multi-factor authentication, SSH keys, personal access tokens, and machine identities. Tokens should be narrowly scoped, time-limited, stored securely, and revoked when no longer required.

Teams and groups of users

GitHub teams are named collections of organization members. They can receive repository access, be requested for code review, and own areas of responsibility. GitLab groups and subgroups similarly allow membership and permissions to be managed centrally. A team such as backend-maintainers is more manageable than granting the same permission independently to twelve people.

Teams should represent stable responsibilities, not short-lived tasks. Typical teams include:

• maintainers or technical owners;
• developers;
• quality engineering;
• operations or site reliability engineering;
• security reviewers;
• release managers.

Role models

GitHub commonly distinguishes repository roles such as read, triage, write, maintain, and administer. Organization roles include members and owners. GitLab commonly uses roles including Guest, Reporter, Developer, Maintainer, and Owner, with exact capabilities depending on whether the scope is a project or group.

The principle of least privilege requires granting the minimum access necessary for a person or automation account to perform its task. A developer who submits code normally does not need organization-owner privileges. A CI job that publishes a package should not receive unrestricted repository administration.

Permission inheritance is convenient but can be dangerous. A user may receive access through direct membership, a team, a parent group, or an external collaboration arrangement. Administrators should document which path grants access and review exceptions.

4. Issues, Labels, and Milestones

An issue records a problem, task, enhancement, question, or operational action. A useful issue contains a concise title, context, expected outcome, acceptance criteria, evidence, priority, owner, and relevant links. Templates improve consistency for bug reports, feature requests, incidents, and maintenance work.

Issues should not become unstructured chat. Discussion belongs in comments, while decisions and deliverables should be recorded in durable issue fields or linked documentation.

Labels

Labels classify work. A practical controlled vocabulary might include:

• type: bug, feature, documentation, security;
• priority: P0, P1, P2;
• lifecycle: triage, in-progress, blocked, ready;
• area: api, database, pipeline.

Labels should have one meaning each. Avoid creating dozens of overlapping labels such as urgent, critical, and high-priority unless their definitions are documented. Colour is a visual aid, not a substitute for semantics.

Milestones

A milestone groups issues and pull or merge requests toward a target, such as Version 2.1 or 2026-Q2 migration. It normally has a title, description, due date, and completion status. A milestone is not necessarily a release: it represents planned work, whereas a release represents a published version or deliverable.

Milestones support scope conversations. If the planned work exceeds team capacity, the team can move issues to a later milestone rather than silently accepting an unrealistic commitment.

5. Wikis and Documentation

A wiki is a repository-associated documentation space, often suited to architecture notes, onboarding guides, operational procedures, and frequently changing reference material. Documentation that must change atomically with code—such as an API contract or configuration schema—may be better stored as versioned Markdown in the repository.

A useful documentation structure includes:

1. purpose and audience;
2. system overview;
3. setup and prerequisites;
4. development workflow;
5. deployment and rollback procedures;
6. troubleshooting and escalation;
7. ownership and review date.

Documentation should have an owner and review cycle. Obsolete runbooks create operational risk, especially during incidents. Never place passwords, private keys, production tokens, or personal data in a wiki or repository.

6. Releases, Tags, and Packages

A Git tag is a named reference to a commit. A release is a platform presentation of a version, commonly associated with a tag, release notes, and downloadable assets. GitHub releases and GitLab releases provide a human-readable record of what was delivered.

A disciplined release normally includes:

• an immutable or protected version tag;
• release notes describing changes and known limitations;
• links to issues or merge requests;
• build or test evidence;
• checksums or signatures for important binaries;
• rollback or support information.

Semantic Versioning is often used as MAJOR.MINOR.PATCH. Under the conventional interpretation, incompatible public API changes increase MAJOR, backward-compatible functionality increases MINOR, and backward-compatible fixes increase PATCH. The convention is useful only when the project defines what constitutes a public API and applies the rules consistently.

Tags are references; they are not automatically proof that the source was tested, signed, or approved. Release governance must connect the tag to the build pipeline and approval evidence.

7. Project Boards and Work Visualisation

A project board visualises work as cards or items in states such as Backlog, Ready, In Progress, Review, Blocked, and Done. GitHub Projects can organise issues and pull requests using table, board, and roadmap-style views. GitLab issue boards represent issues through lists, commonly driven by labels, milestones, or other workflow attributes.

Boards implement a workflow model. The model should be explicit:

• What qualifies an item for Ready?
• Who may move an item to Done?
• Does Blocked require a linked dependency?
• How are cancelled items represented?
• Is work-in-progress limited?

A board is not a substitute for prioritisation. It displays information; product owners and technical leaders still decide value, risk, and sequencing. Excessive columns produce administrative overhead. A small team often needs only four or five states.

8. Pull Requests, Merge Requests, and Governance

GitHub generally calls a proposed code change a pull request; GitLab calls it a merge request. Both support discussion, review, automated checks, and controlled integration into a target branch.

A professional review process commonly requires:

1. a branch with a focused change;
2. a descriptive title and explanation;
3. linked issue or requirement;
4. automated build, test, lint, and security checks;
5. review by an appropriate team;
6. resolution of requested changes;
7. merge according to branch policy.

Protected branches or rulesets can require reviews, successful status checks, linear history, signed commits, or restrictions on who may push. The correct policy depends on risk. A production infrastructure repository generally needs stronger controls than a personal learning repository.

Code review is both a quality mechanism and a knowledge-transfer mechanism. It should evaluate correctness, security, maintainability, tests, observability, and operational consequences—not merely formatting.

9. GitHub–GitLab Comparison

Features and names change over time, and some capabilities depend on plan or edition. Administrators should verify current vendor documentation before designing a governance policy. The enduring concepts are repository ownership, identity, review, automation, traceability, and controlled delivery.

10. Worked Application: Establishing a Service Repository

Consider an illustrative scenario. Northstar Logistics, a small company, is creating a shipment-tracking service with eight developers and two operations engineers.

Background and problem

The team initially stores code in a personal repository. Two developers have administrator rights, issues are used inconsistently, and releases are announced in chat. A departing developer still owns the repository, creating continuity and access risk.

Analysis

The service needs organisational ownership, separated development and operational responsibilities, auditable changes, and a visible delivery plan. It does not need a complex hierarchy or unrestricted access for every contributor.

Approach

1. Create a GitHub organization or GitLab group named northstar.
2. Transfer the repository into an application subgroup or create shipment-tracking as a new project.
3. Enable private visibility initially and document the decision.
4. Create teams: developers, operations, and security-reviewers.
5. Grant developers write/developer access, operations maintain access where justified, and security reviewers review access without administrative control.
6. Protect the default branch. Require at least one review and successful CI checks.
7. Create issue templates for defects, features, and incidents.
8. Define labels for type, priority, lifecycle, and service area.
9. Create a milestone for the first production release and a board with Backlog, Ready, In Progress, Review, and Done.
10. Store setup and rollback instructions in versioned documentation; use the wiki for broader operational guidance.
11. Publish a release only after the pipeline produces tested artifacts and the release owner approves the tag.
12. Schedule quarterly access reviews and immediately remove access when roles change.

Outcome

The repository has accountable ownership, the work queue is visible, and merges require evidence. The team can identify who may change production-sensitive files and can reconstruct the path from issue to code review, commit, build, and release.

Learning points

The important improvement is not a particular platform feature. It is the integration of ownership, access, workflow, evidence, and documentation. A board without policies would merely make disorder more visible; permissions without review rules would still permit unsafe changes.

11. Security, Ethics, and Governance

Repositories frequently contain intellectual property, infrastructure definitions, customer information, and credentials. Administrators should therefore:

• enable multi-factor authentication or central identity where available;
• prohibit secrets in source code and scan for accidental exposure;
• use secret stores and protected environment variables;
• limit token scopes and expiration periods;
• review audit logs and privileged actions;
• protect production branches and deployment environments;
• define retention, backup, and export procedures;
• respect licensing, copyright, privacy, and data-protection requirements;
• avoid placing personal or regulated data in issues, logs, or comments.

A leaked secret must be treated as compromised: revoke or rotate it, investigate use, remove it from future history where appropriate, and document the incident. Simply deleting the visible file does not necessarily remove the secret from Git history or platform caches.

AI-assisted coding tools introduce additional governance questions. Teams should define whether confidential code may be submitted to an AI service, how generated code is reviewed, how licences are assessed, and who is accountable for defects. AI output is not automatically secure, original, or compliant. Human review, automated testing, and repository policy remain necessary.

12. Challenges and Limitations

Platform features can create false confidence. A green pipeline does not prove that requirements are complete; it proves only that configured checks passed. A protected branch does not guarantee good architecture. Labels become unreliable when definitions are unclear. Boards become burdensome when every movement is treated as administrative reporting.

Vendor dependence is another limitation. Platform-specific issue metadata, automation syntax, permissions, and APIs can make migration expensive. Teams should retain local clones, document workflows, use portable Git practices where practical, and avoid unnecessary dependence on undocumented behaviour.

Availability and privacy must also be considered. A hosted service may experience outages or have regional data-residency constraints. Organisations should identify backup requirements and understand contractual, regulatory, and service-plan implications.

Best-Practice Checklist

Before opening a repository for active development, confirm that:

• ownership is organisational rather than personal where appropriate;
• visibility is intentional and documented;
• teams and roles follow least privilege;
• the default branch is protected;
• CI checks cover relevant build, test, and security requirements;
• issues have templates and a defined label vocabulary;
• milestones and boards reflect an agreed workflow;
• documentation has an owner and review date;
• releases are traceable to tested source and artefacts;
• secrets and personal data are excluded;
• access reviews and offboarding procedures exist.

Chapter Summary

GitHub and GitLab extend Git with hosted repositories or projects, organisational structures, identity management, permissions, planning, documentation, releases, and automation. Organizations and groups provide shared ownership; repositories and projects provide the primary code and collaboration container; teams and roles implement controlled access. Issues, labels, milestones, and boards make work visible, while wikis and repository documentation preserve knowledge. Tags identify source versions, and releases communicate tested deliverables. Pull or merge requests connect proposed changes to reviews and automated checks. Effective administration depends on least privilege, protected branches, traceability, secret management, documentation quality, and regular governance reviews. Platform features should serve a clearly designed engineering workflow rather than replace one.

Key Terms

Organization: A GitHub container for shared repositories, members, teams, policies, and administration.

Group: A GitLab container for projects, members, policies, and often nested subgroups.

Repository: A Git database containing project history and references, together with platform collaboration resources.

Project: In GitLab, the principal container for a repository and associated development features; in GitHub, commonly a planning workspace.

Fork: A server-side copy of a repository associated with an upstream source.

Template repository: A repository used as a starting structure for new repositories.

Team: A named collection of users managed together for access and collaboration.

Role: A defined set of permissions granted at a particular scope.

Least privilege: Giving each identity only the access required for its responsibilities.

Issue: A record of a task, defect, feature, question, or operational action.

Label: A controlled classification applied to issues or other work items.

Milestone: A collection of work associated with a target or delivery objective.

Wiki: A collaborative documentation space associated with a repository or project.

Tag: A named Git reference, often used to identify a version.

Release: A published version record with notes, evidence, and optional assets.

Pull request: GitHub’s proposal for reviewing and integrating changes.

Merge request: GitLab’s proposal for reviewing and integrating changes.

Protected branch: A branch governed by rules controlling pushes, reviews, or merging.

Project board: A visual representation of work states and workflow.

Continuous integration: Automated validation of changes through repeatable builds and tests.

Review Questions

Short Answer Questions

1. What is the difference between a Git repository and a GitHub organization?
2. Why should teams use role-based access instead of many individual permissions?
3. What purposes do labels and milestones serve?
4. Distinguish a Git tag from a platform release.
5. State two risks of storing secrets in a repository.

Long Answer Questions

1. Explain how an organization or group, repository or project, team, and permission role fit together in a platform governance model.
2. Compare GitHub and GitLab terminology and explain why the differences matter when administering both platforms.
3. Design an issue, label, milestone, and board structure for a small web application team.
4. Explain how protected branches, reviews, CI checks, and releases create traceability from requirement to delivery.
5. Discuss the advantages and limitations of using a wiki compared with versioned documentation in the repository.

Analytical / Application Questions

1. A developer requests organization-owner access because they need to merge pull requests. Analyse the request and propose a least-privilege alternative.
2. A team has 120 open issues, 35 labels, and a board with 12 columns. Recommend a simplification strategy and justify it using workflow and governance principles.
3. A production token is committed to a private repository and deleted in the next commit. Analyse the incident and specify the immediate and longer-term response.

Multiple Choice Questions with Answers

Question 1

Which GitHub resource is primarily used to group repositories, members, teams, and organisation-wide policies?

A. Organization

B. Issue label

C. Release tag

D. Wiki page

Correct Answer: A. Organization

Question 2

What is the closest GitLab equivalent to a GitHub repository as a collaborative code container?

A. Milestone

B. Project

C. Team

D. Issue board

Correct Answer: B. Project

Question 3

Which principle requires granting an identity only the access needed for its task?

A. Open contribution

B. Continuous delivery

C. Least privilege

D. Semantic versioning

Correct Answer: C. Least privilege

Question 4

Which item most directly classifies an issue as a bug, feature, or security task?

A. Label

B. Tag

C. Wiki

D. Fork

Correct Answer: A. Label

Question 5

What is the primary purpose of a protected default branch?

A. To prevent all repository cloning

B. To control changes through rules such as reviews and checks

C. To convert issues into releases

D. To store deployment secrets in source code

Correct Answer: B. To control changes through rules such as reviews and checks

Question 6

Which statement best distinguishes a tag from a release?

A. A tag is a Git reference; a release presents a published version and related information

B. A tag is an issue category; a release is a team

C. A tag is a permission role; a release is a branch

D. A tag exists only in GitLab; a release exists only in GitHub

Correct Answer: A. A tag is a Git reference; a release presents a published version and related information

Question 7

What is a suitable use of a project board?

A. Visualising work as it moves through agreed workflow states

B. Replacing all source-control history

C. Storing passwords for deployment

D. Granting every contributor administrator access

Correct Answer: A. Visualising work as it moves through agreed workflow states

Question 8

A GitHub pull request and a GitLab merge request both primarily support which activity?

A. Creating user accounts

B. Reviewing and integrating proposed code changes

C. Backing up an entire cloud platform

D. Changing a repository into a wiki

Correct Answer: B. Reviewing and integrating proposed code changes

Question 9

Which action is most appropriate immediately after a production secret is committed?

A. Only delete the latest visible copy

B. Rename the repository

C. Revoke or rotate the secret and investigate exposure

D. Add the secret to the wiki for reference

Correct Answer: C. Revoke or rotate the secret and investigate exposure

Question 10

Which resource is generally best for documentation that must change atomically with source code?

A. A private chat message

B. Versioned files in the repository

C. An untracked local text file

D. A colour-only issue label

Correct Answer: B. Versioned files in the repository