Deploy from GitHub Actions

Overview

You can automate Gram deployments using GitHub Actions by setting up a workflow that runs the Gram CLI in your CI/CD pipeline.

This allows you to deploy changes automatically whenever you push to your repository.

Prerequisites

Before setting up GitHub Actions deployment, ensure you have:

A Gram Producer key
A repository with your OpenAPI specification or toolset configuration

Setup

1. Add API Key to Repository Secrets

Go to your repository’s Settings > Secrets and variables > Actions
Click New repository secret
Name: GRAM_API_KEY
Value: Your Producer API key
Click Add secret

2. Create a deployment config

The deployment config will replace any existing Gram deployment in your project.

Config files can refer to local and remote files. Relative paths resolve from the config file’s directory.

Example:


// fixtures/gram.json
{
  "schema_version": "1.0.0",
  "type": "deployment",
  "sources": [
    {
      "type": "openapiv3",
      "location": "./petstore.yaml",
      "name": "My Petstore",
      "slug": "my-petstore"
    },
    {
      "type": "openapiv3",
      "location": "./symphony.json",
      "name": "Night at the Symphony",
      "slug": "symphony"
    },
    {
      "type": "openapiv3",
      "location": "https://raw.githubusercontent.com/speakeasy-api/gram/refs/heads/main/server/gen/http/openapi3.yaml",
      "name": "Gram Official API",
      "slug": "gram-official"
    }
  ]
}

3. Create GitHub Actions Workflow

Create .github/workflows/deploy.yml in your repository.

Force the deployment to be processed by passing a random value to --idempotency-key.


# .github/workflows/deploy.yml
name: Deploy to gram (staging)
 
on:
  pull_request:
    branches:
      - main
 
jobs:
  push-deployment:
    name: Push deployment to staging project
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      # Alternatively: `brew install speakeasy-api/homebrew-tap/gram`
      - name: Install CLI
        run: |
          curl -fsSL -o gram.zip https://github.com/speakeasy-api/gram/releases/download/0.2.0/gram_linux_amd64.zip
          unzip gram.zip gram
          chmod +x gram
          sudo mv gram /usr/local/bin/
 
      - name: Push to gram
        env:
          GRAM_API_KEY: ${{ secrets.GRAM_API_KEY }}
        run: |
          gram push --project staging --config ./fixtures/gram.json --idempotency-key="$(uuidgen)"

Workflow Customization

Deploy on Specific Branches

To deploy only from specific branches:


on:
  push:
    branches: [main, production]

Add Validation Step

Include validation before deployment:


- name: Validate OpenAPI Spec
  run: |
    # Add your validation commands here
    npm run validate-spec ./openapi.yaml
 
- name: Deploy to Gram
  if: success()
  env:
    GRAM_API_KEY: ${{ secrets.GRAM_API_KEY }}
  run: gram push --project default --config ./openapi.yaml --idempotency-key="$(uuidgen)"

Troubleshooting

Authentication Errors

If you encounter authentication errors:

Verify your GRAM_API_KEY secret is set correctly
Ensure you’re using a Producer key, not a Consumer key

Last updated on May 7, 2025