GitHub Actions

Add a workflow that runs on pull requests, fails on a real defect, and reports a result reviewers can trust.

The file is Git; the run is GitHub

GitHub Pull Requests opened a conversation. GitHub Code Review put comments on that conversation. This lesson adds a third voice: a GitHub runner that checks out the same Git commit and reports pass or fail on the pull request. GitHub Branch Protection can later require that report. It cannot invent the workflow.

# These are Git. None of them starts a GitHub Actions run.
git add README.md
git commit -m "Note"
git push origin main

Use a disposable GitHub repository you own. A repository from the reviewed pull request project is fine if you still control it. Do not add a workflow to a project you do not maintain.

A small workflow you can name

Put one file at .github/workflows/clone-url.yml. The name in the file is what reviewers read. The job id clone-url is what protection can require later. Keep both boring and exact.

name: Clone URL check

on:
  pull_request:
  push:
    branches: [main]

jobs:
  clone-url:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Refuse a Pages clone URL
        run: |
          set -e
          if grep -n 'github.io' README.md; then
            echo "README must not use a Pages host as a git clone URL"
            exit 1
          fi
          grep -E 'git clone (https://github.com/|git@github.com:)' README.md

# From a clone of a GitHub repository YOU own
git switch main
git pull origin main
git switch -c feature/actions-check

mkdir -p .github/workflows
# Write .github/workflows/clone-url.yml from the contract below.
# If README.md has no Clone heading, or still uses a Pages URL, keep that defect
# for the first pull request so the check fails on purpose.

git add .github/workflows/clone-url.yml README.md
git diff --cached
git commit -m "Add a Clone URL check and a README the check can fail"
git push -u origin feature/actions-check

# Same contract GitHub will run. Dirty files you have not committed do not count.
grep -n 'github.io' README.md && echo "would fail" || echo "no Pages host"
grep -E 'git clone (https://github.com/|git@github.com:)' README.md

Local grep is a preview. It is not the GitHub check. CI must fail and pass on the pull request, not only in your terminal.

Fail on a real defect

The first pull request should be red. Plant the same Pages clone URL GitHub Code Review already treated as a defect. If README already has a correct Git URL, change it to a .github.io host in this branch so the first run has something true to reject.

## Clone

git clone https://OWNER.github.io/sovrancode-reviewed-pr/

That host is a static site, not a Git remote. The workflow's grep 'github.io' should exit 1. If the first run is green, you did not give the check a defect. Stop and plant one; a badge that never failed is decoration.

Watch the check on the pull request

gh pr create --base main --title "Add a Clone URL check" --body "$(cat <<'EOF'
## Summary
Adds a GitHub Actions workflow that fails when README.md uses a Pages host as a git clone URL.

## How to verify
1. Wait for the Clone URL check on this pull request.
2. Confirm it fails while README.md still contains github.io.
3. After the follow-up push, confirm the same check passes.
EOF
)"

gh pr checks
gh run list

gh pr checks talks to GitHub. git log will not. Wait until the run finishes; a pending check is not a pass. Open the run on GitHub and read the step that grepped README. That log is the proof the runner saw the Pages URL.

Pass, then maybe require

# Stay on feature/actions-check. The first run must have been red.
# Edit README.md so git clone uses the GitHub Git URL, then:
git add README.md
git diff --cached
git commit -m "Use the GitHub Git URL in the Clone section"
git push
gh pr checks
gh run list

# Do not force-push. The failed run is evidence.

Stay on the same feature branch. Ordinary git push. GitHub starts a new run for the new commit. gh pr checks should turn green. Then merge if the pull request is otherwise ready.

Only after a green run: in the protection rule for main, you may require the clone-url check. Do that on a repository you own. Do not require two reviewers. Do not require a check whose name you have never seen in gh pr checks.

What not to invent

Guided practice: red, then green

1. 01
   Pick a repository you own

   Confirm git remote -v is your GitHub URL. Update local main.

2. 02
   Add the workflow and a defect

   On feature/actions-check, add .github/workflows/clone-url.yml. README must contain github.io in a clone command for the first run.

3. 03
   Open the pull request and wait

   gh pr create, then gh pr checks and gh run list. Record the failed run.

4. 04
   Fix and push

   Use the GitHub Git URL. git push without force. Wait until the same check is green.

5. 05
   Optional require

   If protection already exists, add required status check clone-url only after green. Merge the pull request. Confirm a run on main if push is in on.

Independent lab: a trusted check

1. On a GitHub repository you own, add .github/workflows/clone-url.yml with on: pull_request, job id clone-url, actions/checkout@v4, and a step that fails when README.md contains github.io and passes when a git clone line uses GitHub's Git host.
2. Open a pull request whose first commit still has the Pages defect. Show gh pr checks (or the Checks panel) failing. Do not merge yet.
3. Fix the Clone command on the same branch. git push without --force. Show the same check passing.
4. Optional: require clone-url on protected main only after that green run. Do not require two reviewers.
5. Write six lines: repository URL, pull request number, failed run id or timestamp, passing run id or timestamp, the check name as GitHub showed it, and one sentence that distinguishes a GitHub Actions run from git show. Do not add a workflow to a project you do not maintain.

Common Actions mistakes

Lesson review

You can add a GitHub Actions workflow that runs on pull requests, fails a real clone-URL defect, passes after an ordinary push, and reports on the pull request—not inside Git. Git Internals reads the commit the runner checked out, Git Recovery isolates when a regression entered history, and GitHub Security constrains workflow credentials. The team CI project stays planned.

• I know a workflow is a Git file GitHub runs; git commit does not start the runner.
• I can add .github/workflows/clone-url.yml with on: pull_request and actions/checkout@v4.
• I can gh run list and gh pr checks, and I have evidence of one red run and one green run.
• I require that check in protection only after it has passed, on a repository I own.