title: GitHub Pages
---
summary: Deploys to GitHub Pages.
---
body:

* `ghpages://username/repository`
* `ghpages+https://username/repository`

A popular way to host websites for Open Source projects is [GitHub Pages :ext][github-pages].
It's a service provided by GitHub which allows one to host static websites for free.

[github-pages]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages

The way this deployment support works is that it makes and pushes a new commit,
containing the current Lektor output, to a specific branch in a specified GitHub repository.
Lektor supports using either SSH or HTTPS to push to GitHub.

Example:

```ini
[servers.ghpages]
target = ghpages://your-user/your-repository
```

## Credentials

This deployment method has two implementations: `ghpages` (also known as
`ghpages+ssh`) which uses SSH and `ghpages+https` which uses HTTPS.  They
use different methods for configuring the credentials.

For the SSH transport the same
rules apply as for the [rsync deployment method :ref](../rsync/).

For the HTTPS transport, there are three ways in which to provide credentials. In order of precedence (the first one found wins):
- By passing  `--username` and `--password` parameters to the `lektor deploy` command.
- By setting the  `$LEKTOR_DEPLOY_USERNAME` and `$LEKTOR_DEPLOY_PASSWORD` environment variables.
- In the _userinfo_ part of the target URL.  E.g. `target = ghpages+https://user:pw@owner/repo-name`.

! If you have 2-factor authentication set up and you're using HTTPS, instead of your normal password, you will need to use a [personal access token :ext](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/).


## Pushing To An Explicit Branch

You may explicitly specify which branch to push to by supplying a `?branch`
query parameter to target URL.

```ini
[servers.production]
target = ghpages://your-user/your-user.github.io?branch=main
```

If no branch is explicitly specified, then, when pushing to _owner_ or _organization_ sites
(where the repository name is of the form _owner_`.github.io`) the branch defaults to `master`.
For _project_ sites, the branch defaults to `gh-pages`.

! Around October 1, 2020, GitHub changed the default name of the default branch for newly created repositories from `master` to `main`.  If you are deploying to a _user_ or _organization_ GitHub pages site that was created since then, you will likely have to explicitly specify which branch to push to.

## CNAME Support

If you want to use a custom domain with GitHub pages (also known as a 
[CNAME :ext](https://en.wikipedia.org/wiki/CNAME)), provide the intended 
CNAME in the target URL using the `?cname` parameter:

```ini
[servers.production]
target = ghpages://your-user/your-repository?cname=www.example.com
```

Note that this will overwrite whatever custom domain you may have set on
GitHub with every deployment.

For more information about how CNAMEs work with GitHub, you can read about
the feature in the GitHub help center:
[Adding a CNAME file to your repository
:ext](https://help.github.com/articles/adding-a-cname-file-to-your-repository/).

## 404 Pages

Per convention, the file named `404.html` is used as a placeholder if a page
cannot be found.  You can create such a page by creating a `404.html/contents.lr`
file.


## Pushing Orphan Commits

By default, when publishing to GH pages, the current head of the GH pages branch is fetched, a regular commit (with that parent) is made,
and then the new commit is pushed back to GitHub. This keeps the entire history of the site's built output in the git repository.

Keeping that history is of marginal utility, and doing things this way incurs the network overhead involved in fetching the current head.

Adding a `?preserve_history=no` query parameter to the target URL will cause orphan commits to be _force-pushed_ to the GH pages branch.

```ini
[servers.production]
target = ghpages://your-user/your-repo?preserve_history=no
```

! Setting `preserve_history=no`, while it avoids the network overhead involved in fetching the current head, _discards any history_ of the site's built output that may be kept in the target repository.

## Automatic Deployments

If you want to use ghpages it's desirable to have this build automatically.
This is easy to accomplish with the help of Travis-CI.  For more information
see [Deploying with Travis-CI :ref](../travisci/).
---
template_var: 
