Skip to main content
This guide shows you how to promote your WireMock mock APIs across multiple environments using Git version control and CI/CD automation. You’ll set up a workflow where changes are recorded in a development environment, reviewed through pull requests, and automatically deployed to staging via GitHub Actions.

​
Prerequisites

Before you begin, ensure you have:
  • Completed the Running on Kubernetes guide
  • WireMock Runner deployed and running in your Kubernetes cluster
  • WireMock CLI installed and authenticated
  • A GitHub account and repository for version control
  • Git installed and configured locally
While this guide uses GitHub and GitHub Actions, the same principles apply to other Git platforms (GitLab, Bitbucket) and CI/CD tools (Jenkins, CircleCI, GitLab CI).

​
Initial setup

​
Set up development environment

If you have already completed the Recording Multiple APIs on Kubernetes guide, you can skip this step as you will already have a development environment.
Create a development environment to keep your experimental changes separate from production: 
wiremock environments create --profile development
This creates new mock APIs in WireMock Cloud with a [development] suffix and generates a wiremock-development.yaml profile file that overlays your base wiremock.yaml configuration. Note the base URLs from the output - you’ll use these to test your recorded endpoints in WireMock Cloud.

​
Set up staging environment

Create a staging environment that will serve as your pre-production testing ground: 
wiremock environments create --profile staging
This creates another set of mock APIs with a [staging] suffix and generates a wiremock-staging.yaml profile file. The staging environment will receive automated deployments from your CI/CD pipeline.

​
Initialize git repository

If you haven’t already, initialize Git in your project directory: 
cd kubernetes-runner-demo
git init
git add .
git commit -m "Initial commit: WireMock configuration"
Create a repository on GitHub and push your initial configuration: 
git remote add origin https://github.com/your-username/your-repo.git
git branch -M main
git push -u origin main
Your repository now contains:
  • .wiremock/wiremock.yaml - Base configuration with production mock APIs
  • .wiremock/wiremock-development.yaml - Development environment overrides
  • .wiremock/wiremock-staging.yaml - Staging environment overrides
  • .wiremock/*/stub-mappings.yaml - Stub mappings for each mock API

​
Create GitHub Actions workflow

Create a GitHub Actions workflow that automatically pushes changes to staging when code is merged to the main branch. Create the workflow file: 
mkdir -p .github/workflows
Create .github/workflows/deploy-staging.yml: 
name: Deploy to Staging

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install WireMock CLI
        run: npm install -g @wiremock/cli

      - name: Configure WireMock CLI
        env:
          WIREMOCK_API_TOKEN: ${{ secrets.WIREMOCK_API_TOKEN }}
        run: |
          wiremock config set api_token $WIREMOCK_API_TOKEN

      - name: Push to staging environment
        run: |
          wiremock push mock-api --all --profile staging

      - name: Confirm deployment
        run: |
          echo "✅ Successfully deployed mock APIs to staging environment"

​
Configure GitHub secrets

Add your WireMock Cloud API token as a GitHub secret:
  1. Go to your GitHub repository settings
  2. Navigate to Secrets and variables → Actions
  3. Click New repository secret
  4. Name: WIREMOCK_API_TOKEN
  5. Value: Your WireMock Cloud API token (find it at app.wiremock.cloud/account/security)
Commit and push the workflow: 
git add .github/workflows/deploy-staging.yml
git commit -m "Add CI/CD workflow for staging deployment"
git push origin main

​
Update APIs via the workflow

Now that your environments and CI/CD pipeline are configured, you can start making changes.

​
Sync development with the source project

Run the following to push all the configuration to the development environment in WireMock Cloud: 
wiremock push mock-api --all --profile development

​
Update APIs in development

Update the development APIs in Cloud via whatever means you wish e.g. manual editing in the UI, recording, scripting etc. See the recording on Kubernetes guide for details on recording multiple APIs simultaneously from within Kubernetes.

​
Pull your changes from development

Pull the updated stub mappings from your development environment into your local project: 
wiremock pull mock-api --all --profile development
This downloads the stub mappings from your development environment and overwrites the local stub files in your .wiremock directory.
When pulling with a profile, only the stub mappings and API definition files are updated - the wiremock.yaml configuration remains unchanged.
Review the changes to ensure they look correct: 
git diff .wiremock

​
Create a pull request

Create a new branch for your changes: 
git checkout -b feature/add-github-org-endpoints
Commit your changes: 
git add .wiremock
git commit -m "Add GitHub organization and repository endpoints"
git push origin feature/add-github-org-endpoints
Create a pull request on GitHub:
  1. Go to your repository on GitHub
  2. Click Pull requests → New pull request
  3. Select your feature branch
  4. Add a description explaining the changes
  5. Create the pull request

​
Merge and Deploy

When the pull request is approved, merge it into the main branch:
  1. Click Merge pull request on GitHub
  2. Confirm the merge
GitHub Actions will automatically:
  1. Detect the changes in the .wiremock directory
  2. Run the deployment workflow
  3. Push the updated mock APIs to the staging environment
  4. Report the deployment status

​
Verify the Deployment

Check the GitHub Actions workflow to ensure it completed successfully:
  1. Go to the Actions tab in your repository
  2. Click on the latest workflow run
  3. Verify all steps completed successfully
Test the deployed endpoints in staging: 
curl https://your-staging-api.wiremock.cloud/a-new-endpoint
The staging environment now has the same stub mappings as your development environment.

​
Troubleshooting

​
Workflow Fails with Authentication Error

If the GitHub Actions workflow fails with an authentication error:
  1. Verify the WIREMOCK_API_TOKEN secret is set correctly in GitHub
  2. Check that your API token hasn’t expired
  3. Generate a new token at app.wiremock.cloud/account/security

​
Stub Mappings Not Updated After Push

If stub mappings don’t appear in WireMock Cloud after pushing:
  1. Check the workflow logs for errors
  2. Verify the profile name matches your environment file
  3. Ensure the cloud_id values in your profile file are correct

​
Additional Resources