GitLab Pages
GitLab Pages turns files in your repository into a live website. Portfolios, documentation, school projects, and product landing pages all fit. A pipeline job copies the site files to GitLab, and a public web address appears.
Think of a shop window. You arrange the display inside the repository, and GitLab shows it to every passer-by on the internet.
What Pages Can Host
| Works With Pages | Needs a Server |
|---|---|
| HTML, CSS, and JavaScript files | PHP applications |
| Static site generators such as Hugo, Jekyll, and Eleventy | Apps that need a database |
| Documentation sites | Pages with server-side login |
| Single-page apps built with React or Vue | Back-end APIs |
How the Publishing Flow Works
Push site files
↓
Pipeline runs a job named "pages"
↓
Job saves the public/ folder as an artifact
↓
GitLab Pages publishes the folder
↓
https://username.gitlab.io/my-site
Create a Basic Site
Step 1: Add an index.html File
Create a folder named site with a file named index.html.
<h1>Welcome to My Site</h1> <p>Hosted on GitLab Pages.</p>
Step 2: Add the Pipeline File
Create .gitlab-ci.yml in the repository root.
pages:
stage: deploy
script:
- mkdir -p public
- cp -r site/* public/
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
The classic job name is pages, and the output folder is public. Recent GitLab versions add a dedicated pages keyword for custom job names. The classic form keeps working.
Step 3: Push and Wait
Commit both files and push to the default branch. Watch the job in Build → Pipelines. A green check means the site is live.
Find Your Site Address
Open Deploy → Pages. The page shows the live address.
| Project Location | Address Pattern |
|---|---|
| Personal namespace | https://username.gitlab.io/project-name |
| Group namespace | https://group-name.gitlab.io/project-name |
| Project named username.gitlab.io | https://username.gitlab.io |
Build with a Site Generator
A generator turns Markdown files into finished pages. The job installs the tool and writes the result into public.
pages:
stage: deploy
image: node:20
script:
- npm ci
- npm run build
- mv dist public
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
Change the build command and folder name to match your tool. Hugo writes to public by default, so the move step drops out.
Folder Layout
my-site/ ├── .gitlab-ci.yml ├── site/ │ ├── index.html │ ├── about.html │ ├── css/ │ │ └── style.css │ └── images/ └── README.md After the job runs: public/ ├── index.html ├── about.html ├── css/ └── images/
Control Who Sees the Site
Open Settings → General → Visibility, project features, permissions and find the Pages setting.
| Setting | Result |
|---|---|
| Everyone | Anyone on the internet opens the site |
| Only project members | Visitors must sign in and hold a role in the project |
Private access helps with internal documentation and drafts.
Add a Custom Domain
- Open Deploy → Pages.
- Select New domain.
- Type your domain name, such as www.example.com.
- Copy the DNS records that GitLab shows.
- Add those records at your domain provider.
- Select Verify after DNS changes spread.
GitLab can issue a free HTTPS certificate through Let's Encrypt for verified domains.
Fix Common Problems
| Problem | Check |
|---|---|
| Site shows 404 | The public folder needs an index.html file at the top level |
| Styles missing | Use relative paths such as css/style.css, not paths that start with a drive letter |
| Job does not run | Confirm the rules match the branch you pushed |
| Old content appears | Clear the browser cache and confirm the latest pipeline passed |
Good Habits
- Keep site content in Markdown and let a generator build the pages.
- Compress images before upload.
- Test changes on a feature branch before merging to the default branch.
- Add a privacy page when the site collects any visitor data.
