GitHub Pages Deployment
This page documents deployments using dpl v1 which currently is the default version. The next major version dpl v2 will be released soon, and we recommend starting to use it. Please see our blog post for details. dpl v2 documentation can be found here.
Deploying to GitHub Pages uses
git push --force
to overwrite the history on the target branch, so make sure you only deploy to a branch used for that specific purpose, such asgh-pages
. It is possible to disable this “force push” behavior by settingkeep_history
option totrue
.
Travis CI can deploy your static files to GitHub Pages after a successful build.
You will need to provide a personal access
token
and set the deployment provider details in .travis.yml
.
For a minimal configuration, add the following to your .travis.yml
:
deploy:
provider: pages
skip_cleanup: true
github_token: $GITHUB_TOKEN # Set in the settings page of your repository, as a secure variable
keep_history: true
on:
branch: main
Make sure you have
skip_cleanup
set totrue
, otherwise Travis CI will delete all the files created during the build, which will probably delete what you are trying to upload.
Setting the GitHub token #
You’ll need to generate a personal access
token
with the public_repo
or repo
scope (repo
is required for private
repositories). Since the token should be private,
you’ll want to pass it to Travis securely in your repository
settings
or via encrypted variables in
.travis.yml
.
Further configuration #
local_dir
: Directory to push to GitHub Pages, defaults to current directory. Can be specified as an absolute path or a relative path from the current directory.repo
: Repo slug, defaults to current repo. Note: The slug consists of username and repo name and is formatted likeuser/repo-name
.target_branch
: Branch to (force, see:keep_history
) pushlocal_dir
contents to, defaults togh-pages
.keep_history
: Optional, create incremental commit instead of doing push force, defaults tofalse
.fqdn
: Optional, sets a custom domain for your website, defaults to no custom domain support.project_name
: Defaults to value offqdn
or repo slug, used for metadata.email
: Optional, committer info, defaults todeploy@travis-ci.org
.name
: Optional, committer, defaults toDeployment Bot
.committer_from_gh
: Optional, defaults tofalse
. Allows you to use the token’s owner name and email for commit. Overridesemail
andname
options.allow_empty_commit
: Optional, defaults tofalse
. Enabled if onlykeep_history
istrue
.github_url
: Optional, the URL of the self-hosted GitHub enterprise, defaults togithub.com
.verbose
: Optional, be verbose about internal steps, defaults tofalse
.deployment_file
: Optional, defaults tofalse
, enables creation of deployment-info files.