GitHub Sync

Sync vals from Val Town to GitHub and back

Using a fork of this val, you can specify a list of your own vals to export to a GitHub repo. Log in to the web app rendered by this val to manually click the Export button, which will read the contents of your vals and commit those vals as files to your GitHub repo.

If you set up your repo to use the webhook in this val, any changes pushed to the GitHub repo will be synced back to the vals in your list.

1. Fork this val
2. Create a new repo on GitHub for syncing your vals to (it can be public or private as long as you use the appropriate token scope)
3. Add a webhook to your repo that points to your val's /webhook route, e.g. https://jxnblk-githubsync.web.val.run/webhook
4. Create a Secret for your webhook
5. In your Val Town Settings, add that same secret as GHSYNC_WEBHOOK_SECRET
6. On GitHub, create a new GitHub OAuth app
   • Use your val's web URL for the Homepage URL
   • Set your val's /auth route as the Authorization callback URL, e.g. https://jxnblk-githubsync.web.val.run/auth
   • Copy your new OAuth app's Client ID and add that as the GHSYNC_CLIENT_ID env var in Val Town
   • Create and copy a Client Secret and add that as the GHSYNC_CLIENT_SECRET env var in Val Town
7. On GitHub, create a new personal access token
   • Ensure the token has read access to Contents for your repo
   • Copy the access token and add that as the GHSYNC_GITHUB_TOKEN env var in Val Town
8. In your val, edit the config in the val to point to your repo's owner and repo
9. Edit the valNames list to include the name of the vals you'd like to sync to the repo
10. In your val's Settings, ensure that under Permissions, Vals has Read & Write access
11. Open your val's web URL in a new tab and click Log in with GitHub
12. You should see a page listing your vals to be exported and the GitHub repo to sync to (if not, see below)
13. Click the Export button to sync your vals to the GitHub repo. This can take a moment and you'll need to wait for the browser request to complete.
14. Once your vals are in the GitHub repo, edit them on GitHub or push changes to ensure that the webhook is working. You can check the Requests and Logs tabs for your val to debug any errors

• This val is synced to GitHub: gitHubSyncDemoVal
• This is the GitHub repo: jxnblk/valtown-github-sync

• If after logging in, you see a How to use GitHub Sync page, ensure that the config.owner in your val matches your GitHub username
• If the webhook doesn't work, ensure you have the webhook properly configured in the GitHub repo and that the GHSYNC_WEBHOOK_SECRET env var in Val Town matches the value in your GitHub repo.

The following list are ideas for how to improve this val. Feel free to implement some of these ideas. I would consider accepting pull requests for these features.

• Check timestamps on Val Town and GitHub to prevent syncing when an older version would overwrite a newer one
• Add an authenticated webhook to sync from Val Town to GitHub (e.g. a Cron val could trigger export to keep vals synced)
• A "No-UI" version of this will only webhooks (authentication would need to be considered)