Skip to main content


You can use Shipyard's CircleCI orb to run jobs on ephemeral environments which were automatically deployed by Shipyard, authenticating into them via a bypass token. The orb connects with Shipyard during a workflow, fetching necessary environment variables in order to run E2E tests where authentication via OAuth is normally required.

How to use

In your CircleCI config, usually located in .circleci/, you can use the Shipyard Orb as per the following example:

  1. Use CircleCI version 2.1 at the top of your .circleci/config.yml file.
version: 2.1
  1. Add the orbs stanza below your version, invoking the orb:
shipyard: shipyard/shipyard@3.6.1
  1. Use Shipyard elements in your existing workflows and jobs.
  2. Opt-in to use of uncertified orbs on your organization’s Security settings page

Usage example

Collect the bypass token and URL for an authenticated ephemeral environment attached to this PR in order to run E2E tests on it. Please make sure that your SHIPYARD_API_TOKEN is included as an environment variable.

version: '2.1'
shipyard: shipyard/shipyard@1
name: cypress/browsers-chrome77
- checkout
- shipyard/fetch-shipyard-env
- run:
command: |
npm run test
name: Run the e2e tests on the ephemeral environment
- ephemeral-e2e-tests

The fetch-shipyard-env job can be configured using the following parameters:

Input nameDescriptionRequiredDefault ValueType
api-tokenShipyard API token used to fetch necessary environment variables from Shipyard.noSHIPYARD_API_TOKENenv_var_name
exit-if-not-pull-request# of minutes to wait for Shipyard environment before timing outno60integer
timeout-minutesGracefully exit CircleCI job if this job is not for a pull requestnofalseboolean
app-name 1Filter the environments by name of the application on the Shipyard appnostring

On successful run, the following environment variables are set, which can then be passed on to other actions in the same workflow.

Parameter NameDescription
SHIPYARD_ENVIRONMENT_IDID of the ephemeral environment
SHIPYARD_ENVIRONMENT_URLURL of the ephemeral environment
SHIPYARD_BYPASS_TOKEN 1Token to bypass authentication

1 Available in v3.5.1+


Shipyard's CircleCI Orb