Skip to main content

Automate API Portal Generation with Github Actions

You can automate the docs-as-code process using GitHub Actions, ensuring that any changes to your documentation are instantly deployed.

Workflow Overview​

Whenever a change is pushed to the GitHub repository:

  1. The repository is checked out and the APIMatic CLI is used to generate the Portal.

  2. The generated portal artifacts are deployed to a hosting service.

note

Take a look at the GitHub repository for a sample GitHub workflow.

Step 1: Fork the Sample Repository​

  1. Click Fork on the top-right corner of the sample GitHub repository.

  2. Choose an Owner, provide a Repository name, and optionally add a Description.

  3. Click Create Fork.

fork repository

The forked repository contains a workflow file, DeployStaticPortal.yml, located in .github/workflows/. This file defines the steps to build and deploy the API Portal.

Step 2: Configure the Workflow​

The workflow file, DeployStaticPortal.yml, executes the following steps:

  • Check out the repository.

  • Generate the portal using the @apimatic/cli npm package.

  • Deploy the portal to Netlify.

DeployStaticPortal.yml file​

name: Deploy Static Portal

on:
  workflow_dispatch:
  push:
    branches:
      - master

jobs:
  generate-portal:
    runs-on: ubuntu-latest

    env:
      PORTAL_DIR: ${{ github.workspace }}/static-portal

    steps:
      - uses: actions/checkout@v4
        name: Checkout repo
        id: checkout-repo

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      # Generate Portal with APImatic CLI
      - name: Generate Portal
        run: npx @apimatic/cli@1 portal generate --auth-key="${{ secrets.API_KEY }}" --destination=${{ env.PORTAL_DIR }}

      # Upload Portal Artifact
      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: static-portal
          path: ${{ env.PORTAL_DIR }}

      - name: Deploy to Netlify
        uses: nwtgck/actions-netlify@v3.0
        with:
          publish-dir: ${{ env.PORTAL_DIR }}
          production-branch: master
          github-token: ${{ secrets.GITHUB_TOKEN }}
          deploy-message: "Deploy from GitHub Actions"
          enable-pull-request-comment: false
          enable-commit-comment: true
          overwrites-pull-request-comment: true
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
        timeout-minutes: 2
note

You can deploy to other platforms such as Cloudflare Pages or Azure Static Web Apps.

Step 3: Set Up Repository Secrets​

Since GitHub doesn't copy secrets when forking repositories, you need to reconfigure them manually:

  1. Go to your forked GitHub repository.

  2. Navigate to Settings > Secrets > Actions.

  3. Click New repository secret and add the required credentials.

creating repo secret

Step 4: Trigger the Workflow​

  • The workflow runs automatically whenever a commit is pushed to the master branch.

  • You can also manually trigger the workflow from the GitHub Actions tab.

  • Once the workflow completes, the updated portal will be available on the deployed server.

testing the github action