Simulations from GitHub

A simulation from GitHub turns a repository into the source of truth: specs, static endpoints and configuration live as files, and every push deploys them. Nothing about the mock changes without a commit behind it, which is the whole point - mocks reviewed like code, with a URL per branch and per pull request.

From push to URL

Add one step to a workflow:

name: mockzilla

on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize, reopened, closed]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: mockzilla/actions@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

On every push the action verifies that the workflow really runs in your repository, using the standard GITHUB_TOKEN GitHub issues to the run - there is no Mockzilla key to create, and the token is used once against GitHub's API and never stored. Then it uploads the packed content, waits for the deployment, and prints the URL:

• https://{label}.api.mockz.io - the default branch
• https://{label}-pr{number}.api.mockz.io - a pull request
• https://{label}-{branch}.api.mockz.io - any other branch the workflow deploys

The label is the repository's name, or the one the host input asks for. When another simulation already holds it, a number goes after it: petstore-2.

A branch's host carries the branch name lowercased, with everything but letters and digits dropped: feature/checkout on petstore answers at https://petstore-featurecheckout.api.mockz.io. The run fails and says why when the branch name:

• has no letters or digits once the rest is dropped
• reads like a pull request, pr and digits
• makes the host longer than 63 characters
• gives a host already in use, by another live branch or another simulation

A pull request gets its URL posted as a comment on the PR, so reviewers click straight into the changed mock. Closing it tears that deployment down, as long as the workflow listens for closed pull requests.

No account required

The first push from a repository registers it: the simulation exists and answers before anyone has signed up. When you want to see it in the app - history, replays, usage - sign in with GitHub and your organization's simulations are there. The app shows a repository-sourced simulation read-only: its content changes through commits, not clicks, though access settings and environment variables stay editable in the app for values that should not live in a workflow file.

The repository layout

The portable action publishes a folder per service; the layout is the same one every simulation type shares:

services/
  petstore/
    openapi.yml        # the spec; any *.yml/yaml/json works
    config.yml         # optional: upstream, latency, errors, mount
    context.yml        # optional: values that shape generated data
    static/
      users/
        get/
          index.json   # GET /petstore/users, pinned by hand
app.yml                # optional: app-wide settings

The codegen action deploys a generated Go project from the repository instead, handlers included.

See Portable simulations for the folder format and Codegen simulations for the generated kind.

What the action accepts

Open by design

The action is a public repository, so what runs inside your CI is not a black box: read it at mockzilla/actions. The engine it deploys is the same open source mock server everything else here runs, and the layout it publishes matches the public template.

Start from the template: mockzilla/mockzilla-portable-template

The full input reference lives with the action, and on its docs page.

See GitHub Action.