Skip to content
gangway

Pull-request previews

  1. Create the GitHub App. Under Admin → GitHub, create one in a click through GitHub’s manifest flow, so no secret is copied by hand. Install it on your repositories.

    Admin → GitHub, not connected: a Create the GitHub App button and the webhook URL.Admin → GitHub, not connected: a Create the GitHub App button and the webhook URL.

  2. Connect a repository. Under Repositories, connect one. By default gangway gives you a workflow file to commit: it builds on GitHub Actions and hands gangway the image, authenticated by the run’s OIDC token. The alternative is to have gangway build from webhooks.

    Repositories, connecting one: the repository as owner/name, a name, and Cancel and Connect buttons.Repositories, connecting one: the repository as owner/name, a name, and Cancel and Connect buttons.

  3. Open a pull request. The preview’s URL arrives in a sticky comment and a GitHub Deployment, and the preview is torn down when the pull request closes.

Pull requests from forks wait until a maintainer comments /preview deploy.

A static site needs no image. Have the workflow build the site and send the built folder as a tarball instead, and gangway serves the files itself:

Terminal window
tar -czf - -C dist . | curl -fsS -X PUT \
  "$GANGWAY_API/v1/projects/$GANGWAY_PROJECT/pulls/$PR?sha=$SHA&wait=true" \
  -H "Authorization: Bearer $oidc" -H 'content-type: application/gzip' --data-binary @-

An agent can do step 2 for you: in Claude Code, /gangway:setup-pr-previews connects the repository, adds a Dockerfile if there is none, and opens a pull request with the workflow, whose own run is the first preview.

A repository can have its own domains for its previews, and a hostname for its production preview. See Domains.

To keep a branch such as main live at one address, rebuilt on every push, see Branch deploys.