Homepage Account

Host Config on Github Pages

Use the tools you already know, with version control and automatic signing

Our suggested host for your config file is Github Pages. It has many benefits:

  • Familiar tools: Git and Github

  • Version control built-in

  • Access controls built-in

  • Branch protections to authorize who can deploy

  • Github Actions automate the signing process

Setup Repository

Create a repository to host your config file.

We suggest new dedicated repository used only for this and this guide section assumes that approach. Add your JSON config file as a file named config.json in the root. See detailed instructions below if needed.

Alternatively: you could host host from your existing repository for your iOS codebase. Skip this step if you prefer that route. See the config options in Setup Automatic Signing for how to set the path to your config file, and how to specify which branch should be deployed.

Github Pages is only available on private repos if you are a paid Github user.

If you are a free Github user, you can still use this approach with a public repository. As the config file is going to be on the public internet for customers to retrieve, you aren't exposing any additional data.

Detailed Instructions

Using the Github UI create a new repository:

Then add your config. You can use the web UI or the CLI:

```
git init
git add config.json
git commit -m "current config"
git branch -M main
git remote add origin git@github.com:CriticalMoments/sample_app_config.git
git push -u origin main
```

Add Custom Domain (optional, recommended)

Adding a custom domain will allow you to change to a different host at a later time, if you no longer want to use GitHub Pages as your host.

Detailed Instructions

In Github > Repo Settings > Github Pages > Custom Domain set domain you want to use:

In your DNS Provicer, setup CNAME:

This screenshot shows Cloudflare's DNS settings, your DNS provider may look different.

See Github's full instructions for details.

Enable “Enforce HTTPs” in Github Settings

You may need to wait a few minutes for Github to provision a certificate. As the config can control aspects of your app, you always want to serve it over HTTPS/TLS.

Setup Automatic Signing and Deployment

Github Actions can automatically sign and deploy your config file for you, each time you merge a change. This has the added benefit of checking for errors, and aborting the deployment if any issues are found.

Detailed Instructions

Add the Github Action config below to the location .github/workflows/cm_deploy_to_pages.yml in your repository.

You may want to change these config options in the file below:

  • branches: defaults to main. If you prefer a different production deployment branch, change this value.

  • JSON_CONFIG: defaults to config.json. If you put your json config somewhere else, specify it’s path from root and filename here

  • SIGNED_NAME: the name where the signed config will be hosted. Defaults to cmConfigSigned.cmconfig

.github/workflows/cm_deploy_to_pages.yml
# Sample workflow for building and deploying a criticalmoments.io config file to GitHub Pages (including signing)
name: Deploy Critical Moments config to Github Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      JSON_CONFIG: 'config.json'
      SIGNED_NAME: 'cmConfigSigned.cmconfig'
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Sign Config File
        run: |
          mkdir -p public && \
          status_code=$(curl -s -X POST --data-binary @${JSON_CONFIG} -w "%{response_code}" --header "Content-Type: application/json" https://criticalmoments.io/account/api/sign_config -o ./public/${SIGNED_NAME}) && \
          if [ $status_code != "200" ]; then echo "Error signing config: $status_code"; cat ./public/${SIGNED_NAME}; exit 1; fi
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Once your follow the detailed instructions above, check that the action was successful in Github's Actions UI.

Use your New Hosted Config

Your signed config should now be live at a URL such as: https://democonfig.criticalmoments.io/cmConfigSigned.cmconfig

You can use this URL for your app release in your app delegate like so:

// Add this before `CriticalMoments.sharedInstance().start()`
CriticalMoments.sharedInstance().setReleaseConfigUrl("YOUR_URL")

Setup Access Control and Branch Protections (optional, recommended)

Setup any access controls and branch protections you desire.

Since the Critical Moments config file can push messaging to your users in app, we suggest you require approvals before merging into the deployment branch (defaults to main branch), just as you would a any webpage.

Last updated