Publish from GitHub Actions
This page sets up three workflows for a repository whose build writes a static site to dist/:
| Workflow | Runs on | Changes the live site? |
|---|---|---|
| Preview | every pull request | No — it publishes a preview and comments its URL |
| Production | every push to main | Yes, after a reviewer approves the preview |
| Roll back | a button in the Actions tab | Yes |
The examples publish to the distribution d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 (acme-marketing, live at https://acme-marketing.edge.deca-dev.com). If you have not used the CLI before, read Install the CLI first.
1. Create two tokens
Create two personal access tokens in the workspace that holds the distribution, from the Access tokens page:
| Name | Permissions | Used by |
|---|---|---|
github-preview | Publish previews | the Preview workflow |
github-production | Publish and promote | the Production and Roll back workflows |
Two tokens keep a pull request from ever being able to change the live site. Give both an expiry (90 days is a good default) and note when to replace them.
2. Store them in GitHub
In the repository, open Settings → Secrets and variables → Actions:
- Variables tab: add
EDGE_DISTRIBUTION=d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38. - Secrets tab: add the
github-previewtoken asEDGE_TOKEN.
Then open Settings → Environments, create an environment named production, turn on Required reviewers, and add the github-production token to that environment as EDGE_TOKEN. Environment secrets override repository secrets of the same name, and they are only handed to a job after a reviewer approves it.
3. Publish a preview for every pull request
Create .github/workflows/edge-preview.yml:
name: Edge preview
on:
pull_request:
permissions:
contents: read
pull-requests: write # to comment the preview URL
concurrency:
group: edge-preview-${{ github.event.pull_request.number }}
cancel-in-progress: true
env:
EDGE_PROFILE: edge.deca-dev.com
EDGE_VERSION: 0.1.6
jobs:
preview:
# Pull requests from forks do not receive secrets.
if: github.event.pull_request.head.repo.full_name == github.repository
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
- name: Build
run: npm ci && npm run build
- name: Install edge
run: |
curl -fsSL https://cli.edge.deca-dev.com/install.sh | EDGE_INSTALL_DIR="$HOME/.local/bin" sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Publish preview
id: edge
env:
EDGE_TOKEN: ${{ secrets.EDGE_TOKEN }}
run: |
edge deploy dist --distribution "${{ vars.EDGE_DISTRIBUTION }}" \
--wait --timeout 10m --output json > deployment.json
echo "id=$(jq -r .id deployment.json)" >> "$GITHUB_OUTPUT"
echo "url=$(jq -r .preview_url deployment.json)" >> "$GITHUB_OUTPUT"
- name: Comment the preview URL
env:
GH_TOKEN: ${{ github.token }}
run: |
gh pr comment "${{ github.event.pull_request.number }}" \
--body "Edge preview: ${{ steps.edge.outputs.url }} (deployment \`${{ steps.edge.outputs.id }}\`)"What each part does:
EDGE_PROFILEpoints the CLI at this environment's API.EDGE_VERSIONpins the release so a new CLI version cannot change your workflow unannounced.edge deploypacksdist/as a.tar.gzwith your files at the archive root, uploads it, commits, and with--waitblocks until the deployment isready. If the deployment fails, the step fails with exit code8.--output jsonwrites the finished deployment to stdout, so the next lines can readidandpreview_urlwithjq.
This does not change the live site. Each push to the pull request publishes a new preview and adds a comment with its URL.
4. Promote from main after approval
Create .github/workflows/edge-production.yml. It publishes a preview of main, then waits for a reviewer in the production environment, then promotes that same deployment — the one the reviewer could open — rather than building again.
name: Edge production
on:
push:
branches: [main]
permissions:
contents: read
concurrency:
group: edge-production
cancel-in-progress: false
env:
EDGE_PROFILE: edge.deca-dev.com
EDGE_VERSION: 0.1.6
jobs:
preview:
runs-on: ubuntu-latest
timeout-minutes: 20
outputs:
id: ${{ steps.edge.outputs.id }}
url: ${{ steps.edge.outputs.url }}
steps:
- uses: actions/checkout@v4
- name: Build
run: npm ci && npm run build
- name: Install edge
run: |
curl -fsSL https://cli.edge.deca-dev.com/install.sh | EDGE_INSTALL_DIR="$HOME/.local/bin" sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Publish preview
id: edge
env:
EDGE_TOKEN: ${{ secrets.EDGE_TOKEN }}
run: |
edge deploy dist --distribution "${{ vars.EDGE_DISTRIBUTION }}" \
--wait --timeout 10m --output json > deployment.json
echo "id=$(jq -r .id deployment.json)" >> "$GITHUB_OUTPUT"
echo "url=$(jq -r .preview_url deployment.json)" >> "$GITHUB_OUTPUT"
echo "Preview: $(jq -r .preview_url deployment.json)" >> "$GITHUB_STEP_SUMMARY"
promote:
needs: preview
runs-on: ubuntu-latest
timeout-minutes: 15
environment:
name: production
url: https://acme-marketing.edge.deca-dev.com
steps:
- name: Install edge
run: |
curl -fsSL https://cli.edge.deca-dev.com/install.sh | EDGE_INSTALL_DIR="$HOME/.local/bin" sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Promote
env:
EDGE_TOKEN: ${{ secrets.EDGE_TOKEN }}
run: edge deployments promote "${{ needs.preview.outputs.id }}" --wait --timeout 10mAfter a push to main, the run pauses at promote with Waiting for review. The reviewer opens the preview URL from the run summary, then clicks Review deployments → Approve. Only then does the job receive the production token and change the live site. --wait holds the job until https://acme-marketing.edge.deca-dev.com serves the new deployment.
concurrency with cancel-in-progress: false queues runs instead of cancelling them, so two merges never promote out of order.
5. Roll back from the Actions tab
Create .github/workflows/edge-rollback.yml:
name: Edge roll back
on:
workflow_dispatch:
inputs:
to:
description: Deployment to restore (empty = the one before the live deployment)
required: false
permissions:
contents: read
concurrency:
group: edge-production
cancel-in-progress: false
env:
EDGE_PROFILE: edge.deca-dev.com
EDGE_VERSION: 0.1.6
jobs:
rollback:
runs-on: ubuntu-latest
timeout-minutes: 20
environment: production
steps:
- name: Install edge
run: |
curl -fsSL https://cli.edge.deca-dev.com/install.sh | EDGE_INSTALL_DIR="$HOME/.local/bin" sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Roll back
env:
EDGE_TOKEN: ${{ secrets.EDGE_TOKEN }}
TO: ${{ inputs.to }}
run: |
edge deployments rollback --distribution "${{ vars.EDGE_DISTRIBUTION }}" \
${TO:+--to "$TO"} --timeout 15mRun it from Actions → Edge roll back → Run workflow. It restores the earlier deployment as a new deployment, waits for its preview, and promotes it — this changes the live site. Nothing is deleted: the deployment you rolled away from can be promoted again. It shares the edge-production concurrency group, so it never races a promote.
When a step fails
The CLI exits with a code you can read in the step log. The common ones in a workflow:
| Exit | Cause | Fix |
|---|---|---|
3 | The token is expired, revoked, or for another environment | Create a new token and update the EDGE_TOKEN secret |
4 | The token lacks a scope, for example deployment.promote in the Preview workflow | Use the production token for that job |
5 | The distribution is not in the token's workspace | Check EDGE_DISTRIBUTION, and create the token in the distribution's workspace |
8 | The deployment failed while building its preview | Check that the build wrote dist/index.html; edge deployments get ID shows the error |
Errors are printed as one JSON line with a hint. The full list is in the CLI reference.
Next
- Use the CLI in CI — the same flow in any CI system
- Patch, promote, and roll back
- CLI reference