build a CI/CD pipeline from scratch to understand every moving part. Here's what I built, and the three ways it broke.
The goal
A static site that checks itself on every push and deploys automatically when I merge to master.
The flow:
edit on development → push → CI checks → merge to master → CD deploys
- CI is automatic checks on every change.
- CD is automatic shipping after the checks pass.
The pipeline
name: CI/CD
on:
push:
branches: [master, development]
pull_request:
branches: [master]
permissions:
contents: read
pages: write
id-token: write
jobs:
ci:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Validate HTML
run: npx --yes htmlhint index.html
deploy:
needs: ci
if: github.ref == 'refs/heads/master' && github.event_name == 'push'
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v4
- uses: actions/configure-pages@v5
- uses: actions/upload-pages-artifact@v3
with:
path: .
- id: deployment
uses: actions/deploy-pages@v4
Two jobs:
-
ciruns htmlhint onindex.html. -
deployonly runs ifcipassed (needs) and only on a push tomaster(if).
What broke
1. CI failed: exit code 1
My index.html was missing a doctype, a <title>, and lang on the <html> tag. htmlhint caught it and turned the run red.
The log also showed warnings about Node 20 and ubuntu-latest. Those weren't the problem. The lesson: warnings aren't errors. Find the red step.
2. Merge conflict
When I merged development into master from the command line, git stopped:
CONFLICT (content): Merge conflict in index.html
Both branches had a different index.html. I opened the file, kept the version I wanted, deleted the conflict markers, then:
git add index.html
git commit -m "resolve merge conflict"
git push origin master
3. Deploy failed: Pages not enabled
ci passed but deploy died at configure-pages with "Get Pages site failed."
The fix was a repo setting: Settings → Pages → Source → GitHub Actions. Then I re-ran the failed job.
What I learned
- A pull request is the gate. It's where checks run before
masterchanges. - Read the failing step's log, not the summary.
- A pipeline is mostly reading logs and fixing config.



Top comments (0)