ChangeCast

Introduction

We built ChangeCast to help communicate project updates to users. Whether the project is an open source library or a paid website, users want to know about the hard work being done! Keeping a changelog is important, but the other half of the battle is making that changelog available to users.

ChangeCast uses your Github Releases to build a static site and widget that can be added to your application or project homepage. Check out the examples on our homepage or get started deploying your own ChangeCast below.

Getting Started

Step One: Deploy

Github Actions

Github Actions are the easiest way to deploy ChangeCast for your project.

Instructions

1. Add the ChangeCast Action

action "Build" {
  uses = "palmerhq/changecast@v1.0.0"
  env = {
    DEPLOY_URL = {DEPLOY_URL}
  }
  secrets = [
    "GITHUB_TOKEN",
  ]
}

Note that URL is necessary for SEO and Open Graph tags to work properly, but ChangeCast will build without it. You can skip this for your first deployment, and redeploy once you know the deployment URL.

2. Add a static deployment Action

In the example below we are using Netlify, but any static deployment action should work. Simply configure the action to deploy the ./changecast directory that is created by the ChangeCast Action.

action "Publish with Netlify" {
  needs = "Build"
  uses = "netlify/actions/cli@master"
  args = "deploy --dir=./changecast --prod"
  secrets = [
    "NETLIFY_AUTH_TOKEN",
    "NETLIFY_SITE_ID",
  ]
}

Note that you can generate a new NETLIFY_SITE_ID by installing the Netlify CLI and running netlify sites:create.

As a bonus you can also try the Chronicler Action to help you draft release notes from PR titles.

For a full working example of deploying ChangeCast using Github Actions, check out our main.workflow.

Netlify

Netlify is the next easiest way to deploy ChangeCast for your project.

Instructions

1. Deploy

You will be prompted for the following information:

Github repository url: Enter the url of a Github repository (e.g. https://github.com/facebook/react).
Github access token (optional for public repos): Generate and enter an access token with repo scope.

After deploying, you can assign a custom domain for your changelog using Netlify.

2. Add a Build Trigger

In order to rebuild whenever a Github release is published, we want to add a webhook for Github releases to Netlify. The steps to do so are:

In your Netlify site's "Build & deploy" settings, find the "Github Releases" build hook and copy the URL displayed.
Create a webhook in the Github repository (https://github.com/{owner}/{name}/settings/hooks/new).
Paste the URL from step 1 into the Github webhook's "Payload URL".
In the Github webhook under "Which events would you like to trigger this webhook?", select "Let me select individual events." and "Releases".

You're all set! Now your changelog page and widget will rebuild whenever a new release is published.

Step Two: Embed Widget

First, add the following script tag to your site header. DEPLOY_URL should be the deployment URL of your ChangeCast site.

<script src="{DEPLOY_URL}/widget.js" defer="true"></script>

Next, add the data-toggle-changecast attribute to any clickable elements that you want to toggle the ChangeCast widget.

<button data-toggle-changecast="true">What's new?</button>