GitHub Releases Uploading
This page documents deployments using the next major version dpl v2, which currently is in a beta release phase. Please see our blog post for details. The current default version is dpl v1. Check dpl v1 documentation here.
Be sure to read the v2 deployment overview.
- Status
- Known options
- Environment variables
- Securing secrets
- Authenticating with an OAuth token
- Authentication with a user name and password
- Regular releases
- Draft releases
- Setting the tag at deployment time
- Overwrite existing files on the release
- Deploying to GitHub Enterprise
- Uploading Multiple Files
- Troubleshooting Git Submodules
- Pull Requests
- See also
Travis CI can automatically upload assets to git tags on your GitHub repository.
For a minimal configuration, add the following to your .travis.yml
:
deploy:
provider: releases
token: <encrypted token>
file: <file>
edge: true # opt in to dpl v2
on:
tags: true
This configuration will use the given GitHub OAuth token to upload the specified file (relative to the working directory) on tagged builds.
Status #
Support for deployments to GitHub Releases is *stable**.
Known options #
Use the following options to further configure the deployment. Either token
or username
and password
are required.
token |
GitHub oauth token (needs public_repo or repo permission) — secret, type: string, alias: api_key |
username |
GitHub login name — type: string, alias: user |
password |
GitHub password — secret, type: string |
repo |
GitHub repo slug — type: string, default: repo slug |
file |
File or glob to release to GitHub — type: string or array of strings, default: * |
file_glob |
Interpret files as globs — type: boolean, default: true |
overwrite |
Overwrite files with the same name — type: boolean |
prerelease |
Identify the release as a prerelease — type: boolean |
release_number |
Release number (override automatic release detection) — type: string |
release_notes |
Content for the release notes — type: string, alias: body |
release_notes_file |
Path to a file containing the release notes — type: string, note: will be ignored if –release_notes is given |
draft |
Identify the release as a draft — type: boolean |
tag_name |
Git tag from which to create the release — type: string |
target_commitish |
Commitish value that determines where the Git tag is created from — type: string |
name |
Name for the release — type: string |
Shared options #
cleanup |
Clean up build artifacts from the Git working directory before the deployment — type: boolean |
run |
Commands to execute after the deployment finished successfully — type: string or array of strings |
Environment variables #
All options can be given as environment variables if prefixed with GITHUB_
or RELEASES_
.
For example, token
can be given as
GITHUB_TOKEN=<token>
orRELEASES_TOKEN=<token>
Securing secrets #
Secret option values should be given as either encrypted strings in your build
configuration (.travis.yml
file) or environment variables in your repository
settings.
Environment variables can be set on the settings page of your repository, or
using travis env set
:
travis env set GITHUB_TOKEN <token>
In order to encrypt option values when adding them to your .travis.yml
file
use travis encrypt
:
travis encrypt <token>
Or use --add
to directly add it to your .travis.yml
file. Note that this command has to be run in your repository’s root directory:
travis encrypt --add deploy.token <token>
Authenticating with an OAuth token #
The recommended way to authenticate is to use a GitHub OAuth token with
the public_repo
or repo
scope to upload assets.
The public_repo
and repo
scopes for GitHub oauth tokens grant write access
to all of a user’s (public) repositories. For security, it’s ideal for token
to have write access limited to only repositories where Travis deploys to
GitHub releases. The suggested workaround is to create a machine
user
— a GitHub account that is granted write access on a per repository basis.
Authentication with a user name and password #
You can also authenticate with your GitHub username and password using the
user
and password
options.
deploy:
provider: releases
user: <user>
password: <password>
# ⋮
Regular releases #
When the draft
option is not set to true
(see below), a regular release is
created.
Regular releases require tags. If you set on.tags: true
(as the initial
example in this document), this requirement is met.
Draft releases #
With
deploy:
provider: releases
# ⋮
draft: true
the resulting deployment is a draft release that only repository collaborators can see.
This gives you an opportunity to examine and edit the draft release.
Setting the tag at deployment time #
GitHub Releases needs the present commit to be tagged at the deployment time.
If you set on.tags: true
, the commit is guaranteed to have a tag. Depending
on the workflow, however, this is not desirable.
In such cases, it is possible to postpone setting the tag until you have all
the information you need. A natural place to do this is before_deploy
.
For example:
before_deploy:
# Set up git user name and tag this commit
- git config --local user.name "YOUR GIT USER NAME"
- git config --local user.email "YOUR GIT USER EMAIL"
- export TRAVIS_TAG=${TRAVIS_TAG:-$(date +'%Y%m%d%H%M%S')-$(git log --format=%h -1)}
- git tag $TRAVIS_TAG
deploy:
provider: releases
# ⋮
When tag is not set at deployment time #
If the tag is still not set at the time of deployment, the deployment provider attempts to match the current commit with a tag from remote, and if one is found, uses it.
This could be a problem if multiple tags are assigned to the current commit and the one you want is not matched.
In such a case, assign the tag you need (the method will depend on your use
case) to $TRAVIS_TAG
to get around the problem.
If the build commit does not match any tag at deployment time, GitHub creates one when the release is created.
The GitHub-generated tags are of the form untagged-*
, where *
is a random
hex string.
Notice that this tag is immediately available on GitHub, and thus will trigger a new Travis CI build, unless it is prevented by other means; for instance, by blocklisting
/^untagged/
.
Overwrite existing files on the release #
If you need to overwrite existing files, use the option overwrite
:
deploy:
provider: releases
# ⋮
overwrite: true
Deploying to GitHub Enterprise #
In order to upload assets to a GitHub Enterprise repository, override the
$OCTOKIT_API_ENDPOINT
environment variable with your GitHub Enterprise API
endpoint:
http(s)://"GITHUB ENTERPRISE HOSTNAME"/api/v3/
You can configure this in Repository Settings
or via your .travis.yml
:
env:
global:
- OCTOKIT_API_ENDPOINT=<endpoint>
Uploading Multiple Files #
You can upload multiple files using yml array notation. This example uploads two files.
deploy:
provider: releases
# ⋮
file:
- file-1
- file-2
The option file
by default takes a glob, so you can express the same as:
deploy:
provider: releases
# ⋮
file: {file-1,file-2}
Note that all paths in
file
are relative to the current working directory, not to$TRAVIS_BUILD_DIR
.
Troubleshooting Git Submodules #
GitHub Releases executes a number of git commands during deployment. For this reason, it is important that the working directory is set to the one for which the release will be created, which generally isn’t a problem, but if you clone another repository during the build or use submodules, it is worth double checking.
Pull Requests #
Note that pull request builds skip the deployment step altogether.