In GitHub Pages, what are the two publishing sources for a site, and how does each one get files onto the live site?

## What "publishing source" means A GitHub Pages site is a directory of static files that GitHub serves at `https://<owner>.github.io/<repo>/` (or at a custom domain). The **publishing source** is the answer to one question: where does GitHub get that directory? A repository has exactly one publishing source at a time, set under **Settings → Pages → Build and deployment → Source**. Switching it is a settings change, not a code change. ## Source 1: deploy from a branch This is the original model and still the simplest. You choose a branch and one of two folders — the repository root `/` or `/docs`. Everything committed there is the site. Push to that branch and, within a minute or so, the live site changes. The important subtlety is that this path is not a plain file copy. GitHub runs the content through **Jekyll**, its built-in static site generator, on its own infrastructure. If the folder contains Jekyll sources (`_config.yml`, `_posts/`, Markdown with front matter), Jekyll renders them into HTML. If it contains an already-built site, Jekyll still processes it — which is where the classic breakage comes from, because Jekyll drops paths beginning with an underscore. Committing an empty `.nojekyll` file at the root of the publishing source turns that processing off and makes GitHub serve the files verbatim. A common variant is a dedicated `gh-pages` branch holding only build output, produced by a CI job or a tool that force-pushes the built directory. That keeps generated files out of `main`, at the cost of a branch whose history is machine-written. ## Source 2: GitHub Actions Here no branch is "the site". A workflow builds the site with whatever toolchain you want and hands the result to Pages through two first-party actions: ```yaml permissions: contents: read pages: write id-token: write jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm ci && npm run build - uses: actions/upload-pages-artifact@v3 with: path: ./dist deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages steps: - uses: actions/deploy-pages@v4 ``` `actions/upload-pages-artifact` packages the given directory into the specially-named artifact Pages expects; `actions/deploy-pages` creates the deployment from it. The permissions matter: `pages: write` lets the job create a Pages deployment, and `id-token: write` is required because the deploy action authenticates to the Pages service with an OIDC token rather than a stored credential. The deployment is attached to the `github-pages` environment, which is why environment protection rules and the deployment history in the repository UI apply to Pages too. ## Which one to pick Use **deploy from a branch** when the site genuinely is Jekyll, or when it is a handful of hand-written HTML files and you want zero moving parts. Use **GitHub Actions** for everything else. The Actions route wins on three practical grounds: - **Toolchain control.** Your Node, Ruby, Python or Go version is pinned in the workflow, not decided by GitHub's Jekyll environment, which supports only a fixed set of plugins. - **Any generator.** Hugo, Astro, MkDocs, Docusaurus, a Next.js static export — all produce a directory, and a directory is all `upload-pages-artifact` wants. - **Real CI before publish.** Link-checking, tests and linting run as ordinary steps, and a failing build simply never reaches the deploy job. With a branch source, whatever landed on the branch is live. The cost is that you now own a workflow: broken build, no new deploy, and the failure shows up in Actions rather than in the Pages panel. ## Things people get wrong The two sources are exclusive — you cannot have a branch source *and* an Actions deploy racing each other; setting one replaces the other. Pushing to `gh-pages` does nothing at all if the source is set to Actions. Conversely, a Pages deploy workflow that runs while the source is still "deploy from a branch" will fail or be ignored. And in both modes the result is the same kind of thing: a static directory. Choosing the Actions source does not give you server-side execution; it only changes who builds the files.