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

1. Go to your repository’s Settings > Secrets and variables > Actions
2. Click New repository secret
3. Name: GRAM_API_KEY
4. Value: Your Producer API key
5. 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:

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