DOCSEARCHbyAlgolia
Submit Docs

Shipyard Documentation

website·Indexed 34 days ago

https://docs.shipyard.build

Shipyard is an Environment Management platform that creates ephemeral, on-demand environments. It integrates with GitHub, GitLab, and Bitbucket to keep environments up to date, supporting Docker Compose, private Docker registries, and multi-repo applications. The platform includes a CLI with a Model Context Protocol (MCP) server for AI assistant integration, as well as integrations for Datadog, Slack, JFrog, CircleCI, and GitHub Actions.

Tokens
11.8K
Snippets
54
Records
109
Agent score
63%

What's inside Shipyard

  1. Overview of Shipyard Ephemeral Environments

    Shipyard is an Environment Management platform that automatically creates ephemeral, full-stack, near-production copies of your application whenever a Pull Request (PR) is opened. These environments are independent, allowing for parallel testing and validation without relying on a single shared staging environment. To start deploying environments with Shipyard, you only need a Docker Compose file.

  2. Enable GitHub commit checks and PR comments for Shipyard

    Shipyard provides GitHub commit checks and Pull Request (PR) comments to notify developers of the status of their ephemeral environments directly within the GitHub UI.

  3. Get an environment by UUID

    Retrieve detailed information about a specific environment using its unique application UUID (app_uuid).
    curl -H 'x-api-token: ${YOUR_API_TOKEN}' "https://shipyard.build/api/v1/environment/${app_uuid}"

  4. Integrate Shipyard with Slack for build notifications

    To receive notifications about build success, failure, and failure reasons (including links to build details) in a Slack channel, you must authorize the Shipyard Slackbot integration.

    1. Navigate to the Settings page at the top of your main dashboard to access Organization Settings.
    2. Click the Add to Slack button.
    3. Complete the Slack OAuth flow to authorize Shipyard to communicate with your Slack workspace.

  5. Restart an individual service pod

    If a specific service is unhealthy or needs a reset, you can restart individual pods from the Services Overview tab within the Build Details page. Locate the pod name and click the ↻ (restart) button next to it.

  6. Connect Shipyard to GitLab namespaces and repositories

    To keep environments up to date via Git webhook events and enable automatic rebuilding on push, Shipyard integrates with GitLab. During the initial login process, you must select a namespace (either your personal user account or a group you belong to) to use for your projects. Once a namespace is selected, you can choose specific repositories located within that namespace or any of its subgroups.

  7. Retrieve the Shipyard API token

    To authenticate the CircleCI orb, you need a Shipyard API token. If the Shipyard API is enabled for your organization, you can find and copy the token from the Organization Settings page, accessed via the 'Settings' link at the top of the main dashboard.

  8. Deploy a full-stack application using Shipyard

    Shipyard creates on-demand ephemeral environments based on a docker-compose.yml configuration. To deploy an application:

    1. Fork a compatible repository (e.g., the React + Flask starter).
    2. In the Shipyard dashboard, click + Application.
    3. Select the forked GitHub repository and the target branch (e.g., main).
    4. Select the services to deploy (Shipyard automatically detects these from the docker-compose.yml file).
    5. Add any required environment variables or secrets.
    6. Click Create application to start the build process.

    Once the build is complete, a Visit button will appear on the dashboard providing a uniquely-generated URL to access the environment.

  9. Run E2E tests on Shipyard ephemeral environments using GitHub Actions

    Use the shipyard/shipyard-action to authenticate into Shipyard-deployed ephemeral environments via a bypass token. This action fetches necessary environment variables during a workflow, allowing E2E tests to run where OAuth authentication is normally required. On a successful run, the action exports SHIPYARD_ENVIRONMENT_ID, SHIPYARD_ENVIRONMENT_URL, and SHIPYARD_BYPASS_TOKEN for use in subsequent steps.
    on: [pull_request]

jobs:
  cypress-e2e-tests:
    runs-on: ubuntu-latest
    name: Collect the bypass token and URL for an authenticated ephemeral environment
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Integrate Shipyard
        uses: shipyard/shipyard-action@1.0.0
        env:
          SHIPYARD_API_TOKEN: ${{ secrets.SHIPYARD_API_TOKEN }}
      - name: Run the E2E tests against the ephemeral environment
        run: npm run test
        shell: bash
        env:
            CYPRESS_BASE_URL: $SHIPYARD_ENVIRONMENT_URL
            CYPRESS_BYPASS_TOKEN: $SHIPYARD_BYPASS_TOKEN

  10. Obtain and use the Shipyard API Token

    To use the Shipyard API, you must include your organization's API token in the x-api-token header of every request. You can find this token by navigating to the Settings menu at the top of your main dashboard and accessing the Organization Settings page.

  11. Handle secrets inheritance and overrides

    Shipyard uses an inheritance model for secrets:

    1. Base Environment: Secrets defined here are inherited by all child PR Environments by default.
    2. PR Environments: You can add new secrets or override inherited secrets from the Base Environment (e.g., for rotating API keys).

    Note: Any secrets added or updated in a PR Environment must be added to the Base Environment before merging the PR to ensure persistence.

  12. Add a new application to Shipyard

    To add an application to Shipyard, ensure you have a Docker Compose file with the necessary labels. From the main dashboard, click the + Application button. You must have an integrated version control system (GitHub, GitLab, or Bitbucket) to select the repository and branch for deployment. Multi-repo applications can be created by clicking the + Add repository button during the app creation process.