Building Pull Requests
Pull request builds are an essential part of Travis CI. Whenever a pull request is opened on GitHub, Travis CI builds it and updates the status icon on the pull request page.
You can identify if a pull request was built while it was considered draft by the contributor by looking at the
DRAFT tag in the web UI. Check how draft pull request events work on GitHub.
How Pull Requests are Built #
When a pull request is opened on GitHub, Travis CI receives a notification and runs a build. During the build, we update the status icon of the pull request to one of the following statuses:
- a warning that the build is still running.
- a notification that the build failed – the pull request should not be merged.
- a notification that the build succeeded – the pull request can be merged.
Travis CI builds a pull request when it is first opened, and whenever commits are added to the pull request. Rather than build the commits that have been pushed to the branch the pull request is from, we build the merge between the source branch and the upstream branch.
To only build on push events not on pull requests, disable Build on Pull Requests in your repository settings.
To only build pull requests targeting specific branches you can use the
branches: only: key, which will also restrict the branches that trigger builds.
Pull Requests and Security Restrictions #
The most important restriction for pull requests is about secure environment variables and encrypted data.
A pull request sent from a fork of the upstream repository (we call it an “external pull request”) could be manipulated to expose environment variables. The upstream repository’s maintainer would have no protection against this attack, as pull requests can be sent by anyone who forks the repository on GitHub.
Travis CI makes encrypted variables and data available only to pull requests coming from the same repository (“internal pull requests”). These are considered trustworthy, as only members with write access to the repository can send them.
Pull requests sent from forked repositories do not have access to encrypted variables or data even if these are defined in the fork source project unless certain repository settings in Travis CI aren’t set.
Repository settings - forks #
Repository security settings for forked repositories on Git are available starting March 1st, 2022.
For Git repositories, you may manage per repository how the environment variables and the custom SSH keys will be handled in Travis CI when a build triggered as an effect of filing a Pull Request from a forked repository. Two settings are available specifically for this purpose, allowing you to customize your security vs. collaboration setup.
- base repository - a Git repository, which is forked by someone else
- fork or forked repository - any Git repository forked from the base repository
- PR - Pull Request (e.g. in GitHub, BitBucket, GitLab) or Merge Request (in Assembla)
Please note: Repositories activated in Travis CI before March 1st, 2022 will have the
Share encrypted environment variables with forks (PRs)setting set to OFF. Please verify your collaboration model if necessary (especially for public repositories). The
Share SSH keys with forks (PRs)will be set to ON for private repositories not to break too many collaboration setups. Repository settings will be set by default to OFF for any repository activated in Travis CI after March 1st, 2022. For repositories activated in Travis CI after March 1st, 2022, you may want to consider changing the default settings depending on your collaboration model.
Share encrypted environment variables with forks (PRs) #
This setting determines if the base repository´s encrypted environment variables will be shared with the forked repository in a fork-to-base pull request (the fork repository merges changes into the base repository).
In the case of a base-to-base pull request (changes are merged from the base repository into itself), the encrypted environment variables will always be available. This allows collaborators to file Pull Requests using the repository encrypted environment variables and preserve existing checks configured, e.g. in GitHub.
In the case of a fork-to-fork pull request (changes are merged from the forked repository into itself), the encrypted environment variables from the base repository will never be available. Therefore, one needs to replace or bypass them directly in forked repository.
In the case of a fork-to-base pull request:
- If this setting is ON, the encrypted environment variables will be available to the forked repository, which means that builds in the forked repository will have access to the encrypted environment variables from the base repository. This may be a less secure approach yet allows for a collaboration using forks and Pull Requests (PRs).
- If this setting is OFF and the build relies on any encrypted environment variable, the PR from fork to base repository will fail. This secures your base repository encrypted environmental variables by putting a constraint on accessing them from forks.
Share SSH keys with forks (PRs) #
Please Note: The ‘Share SSH keys with forks (PRs)’ repository setting is applicable only for private repositories in the travis-ci.com environment.
This setting determines if the custom SSH keys from the base repository will be shared with the forked repository in a fork-to-base pull request (changes are merged from the fork repository into the base repository). In the case of a base-to-base pull request (changes are merged from the base repository into itself), the custom SSH keys will always be available.
In the case of a fork-to-fork pull request (changes are merged from the forked repository into itself), the custom SSH keys from the base repository will never be available.
In the case of a fork-to-base pull request:
- if this setting is ON, the custom SSH keys from the base repository will be available to the forked repository, which means that the build in the forked repository will be able to use the custom SSH keys from the base repository. Consider setting to ON if your collaboration model requires working with Pull Requests (PRs) from forked repositories or there are dependencies defined, which rely on SSH key from base repository.
- If this setting is OFF and the build is relying on custom SSH keys i.e. for fetching some additional dependencies, it will fail with a no access error.
If you have the settings regarding sharing secrets with forks disabled and your build relies on encrypted variables to run, for instance to run Selenium tests with BrowserStack or Sauce Labs, your build needs to take this into account. You won’t be able to run these tests for pull requests from external contributors.
To work around this, restrict these tests only to situations where the environment variables are available, or disable them for pull requests entirely, as shown in the following example:
script: - 'if [ "$TRAVIS_PULL_REQUEST" != "false" ]; then bash ./travis/run_on_pull_requests; fi' - 'if [ "$TRAVIS_PULL_REQUEST" = "false" ]; then bash ./travis/run_on_non_pull_requests; fi'
My Pull Request isn’t being built #
If a pull request isn’t built or doesn’t show up in Travis CI’s user interface, that usually means that it can’t be merged. We rely on the merge commit that GitHub transparently creates between the changes in the source branch and the upstream branch the pull request is sent against.
So when you create or update a pull request, and Travis CI doesn’t create a build for it, make sure the pull request is mergeable. If it isn’t, rebase it against the upstream branch and resolve any merge conflicts. When you push the fixes up to the pull request, Travis CI will happily build them.
Travis CI also currently doesn’t build pull requests when the upstream branch is updated, as this would lead to an excessive number of new builds.
If the pull request has already been merged you can’t rerun the job. You’ll get an error like:
The command "eval git fetch origin +refs/pull/994/merge: " failed
Restoring the branch of a merged pull request will not trigger a build, nor will pushing a new commit to a branch that has already been merged.
‘Double builds’ on pull requests #
If you see two build status icons on your GitHub pull request, it means there is one build for the branch, and one build for the pull request itself (actually the build for the merge of the head branch with the base branch specified in the pull request).
Build pushed branches and Build pushed pull requests control this behaviour.