#### This Page

# GitHub Pages

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

A popular way to host websites for Open Source projects is the GitHub pages. It's a free service provided by GitHub which allows to host completely static websites through GitHub.

The way this is implemented in Lektor currently is that Lektor will force-push a website into a repository of choice. There are two ways to push it up: `ghpages` (which uses SSH) or `ghpages+https` (which uses HTTPS). The latter can also accept `username:password@` in the URL to hold the credentials in addition to accepting username and password from the command line or environment variables.

Example:

    [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 credentials. For the SSH transport the same rules apply as for the rsync deployment method. The HTTPS transport on the other hand accepts `--username` and `--password` which override the values in the URL.

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.

## Behavior

The way this deployment support works is that it commits a new commit into a temporary location and pushes it into the `gh-pages` or `master` branch depending on the name of the repository. If you push to `username.github.io` then it commits to `master`, otherwise to `gh-pages`. This is consistent with behavior for GitHub Pages.

## CNAME Support

If you want to use a custom domain with GitHub pages (also known as a CNAME), provide the intended CNAME in the target URL using the `?cname` parameter:

    [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.

## 404 Pages

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

## 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.

## Comments