Skip to content

Publish from GitHub Actions ​

This page sets up three workflows for a repository whose build writes a static site to dist/:

WorkflowRuns onChanges the live site?
Previewevery pull requestNo — it publishes a preview and comments its URL
Productionevery push to mainYes, after a reviewer approves the preview
Roll backa button in the Actions tabYes

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:

NamePermissionsUsed by
github-previewPublish previewsthe Preview workflow
github-productionPublish and promotethe 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-preview token as EDGE_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:

yaml
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_PROFILE points the CLI at this environment's API. EDGE_VERSION pins the release so a new CLI version cannot change your workflow unannounced.
  • edge deploy packs dist/ as a .tar.gz with your files at the archive root, uploads it, commits, and with --wait blocks until the deployment is ready. If the deployment fails, the step fails with exit code 8.
  • --output json writes the finished deployment to stdout, so the next lines can read id and preview_url with jq.

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.

yaml
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 10m

After 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:

yaml
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 15m

Run 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:

ExitCauseFix
3The token is expired, revoked, or for another environmentCreate a new token and update the EDGE_TOKEN secret
4The token lacks a scope, for example deployment.promote in the Preview workflowUse the production token for that job
5The distribution is not in the token's workspaceCheck EDGE_DISTRIBUTION, and create the token in the distribution's workspace
8The deployment failed while building its previewCheck 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 ​