How to use GitHub Actions to build and/or deploy an Observable Framework project #1030
-
|
The Getting Started Page provides a deploy.yml sample for a Yarn deployment of documentation website. Below Mike has posted samples for both yarn and npm deploy.yml files for the hello-framework starter. Mike's post on GitHub Pages deployments using deploy.yml avoids adding .nojekyll file. Pretty awesome! (We're fans of Cloudflare hosting too - looking forward to taking model.earth to Cloudflare Page as we integrate Observable with Chatbot UI.) If you don't use the Github Action setups using deploy.yml described in the posts below, here are several ways to create a site from the static files in your "dist" folder without adding deploy.yml: 1a.) Remove dist/ from the .gitignore file. The resulting URL includes "/dist" For the sample above, you'll see a 404 error if you don't include "/dist" in the URL. 2.) You can place the dist files in the root of a repo or in a "docs" folder ("docs" is the only subfolder GitHub Pages lists. Is there a way to tell GitHub Pages to point into the dist folder?). IMPORTANT: Add an empty .nojekyll file to the root directory (if you're not using deploy.yml), otherwise your Github Pages will be broken. Jekyll is the default page renderer for GH pages, and it ignores directories that begin with an underscore. Thanks Philippe Rivière! 3.) In Github, under Settings > Pages > Build and Deploy, choose "Deploy from branch: Source" and activate the static.yml file. Notes: If selecting GitHub Pages and "/docs" prevents the error: "docs:build" not found error in deploy.yml with the hello-framework site, BUT the site still has broken formatting and no navigation -- try adding an empty .nojekyll file to your docs folder. (You'll probably see raw code because the docs folder in the hello-observable repo contains src files.) When you choose "Deploy from branch", the source choice will disappear. Here's the more complex deploy.yml used for the documentation site from the bottom of the Getting Started page: Check out the deploy.yml examples from Mike below for running hello-framework on GitHub Pages and Cloudflare. |
Beta Was this translation helpful? Give feedback.
Replies: 2 comments 3 replies
-
|
I moved this to a discussion because it sounds like you’re asking how to use GitHub Actions to build and/or deploy an Observable Framework project. The deploy.yml we use is provided as reference, but it isn’t intended to work out of the box for all projects — there are quite a few ways in which are deploy.yml is tailored uniquely to the needs of building the Observable Framework documentation (which is itself an Observable Framework project). Here’s a smaller example of a GitHub Actions deploy workflow, setup to deploy on either (1) a daily schedule at 10:15 AM UTC, (2) on pushes to the main branch, and (3) manually. name: Deploy
on:
workflow_dispatch: {}
push:
branches: [main]
schedule:
- cron: "15 10 * * *"
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: yarn
- run: yarn --frozen-lockfile
- run: yarn build
- name: Deploy to Observable
run: yarn deploy -m "$(git log -1 --pretty=%s)"
env:
OBSERVABLE_TOKEN: ${{ secrets.OBSERVABLE_API_TOKEN }}The action above assumes Yarn. It also requires you to set the where The equivalent action with npm would look something like this: name: Deploy
on:
workflow_dispatch: {}
push:
branches: [main]
schedule:
- cron: "15 10 * * *"
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npm run build
- name: Deploy to Observable
run: npm run deploy -- -m "$(git log -1 --pretty=%s)"
env:
OBSERVABLE_TOKEN: ${{ secrets.OBSERVABLE_API_TOKEN }} |
Beta Was this translation helpful? Give feedback.
-
|
Thanks! Looking forward to implementing! When displaying the content of "dist" as static files in GitHub Pages, if you encounter formatting issues, add an empty .nojekyll file. These first two work only with .nojekyll file added: 1.) Dist files in the root of repo 2.) Dist files in the docs folder with Github Pages pointed into docs 3.) Works here (with /dist removed in .gitignore): Related quesiton: (Mike answers below) Does the Observable Framework main site repo have GitHub Pages pointed at its "docs" folder? Or is "Deploy from Branch" selected instead? (Both under Settings > Pages) |
Beta Was this translation helpful? Give feedback.
-
|
You may have to add an empty .nojekyll file to the root directory, because jekyll is the default page renderer for GH pages, and it ignores directories that begin with an underscore. |
Beta Was this translation helpful? Give feedback.
-
|
Brilliant! Adding the .nojekyll file worked for the "dist" pages copied into the root of a repo. AND it worked for the GitHub Pages pointed into "docs" too! (I had to run a deploy to refresh that one.) I've updated the posts above. Thanks! |
Beta Was this translation helpful? Give feedback.
-
|
We don’t use GitHub Pages for our documentation; we use Cloudflare Pages. If you want to deploy to GitHub Pages, you need something like this: - uses: actions/configure-pages@v3
- uses: actions/upload-pages-artifact@v1
with:
path: dist
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1You’ll also need some permissions: permissions:
contents: read
pages: write
id-token: writeSee:
If you use this approach you shouldn’t need the |
Beta Was this translation helpful? Give feedback.
I moved this to a discussion because it sounds like you’re asking how to use GitHub Actions to build and/or deploy an Observable Framework project. The deploy.yml we use is provided as reference, but it isn’t intended to work out of the box for all projects — there are quite a few ways in which are deploy.yml is tailored uniquely to the needs of building the Observable Framework documentation (which is itself an Observable Framework project).
Here’s a smaller example of a GitHub Actions deploy workflow, setup to deploy on either (1) a daily schedule at 10:15 AM UTC, (2) on pushes to the main branch, and (3) manually.