Skip to main content

Automate using the Sync API

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 contents are zipped and sent to the Portal Generation Endpoint.

  2. The returned portal artifacts are downloaded, extracted, and 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.

  • Zip the repository contents.

  • Call APIMatic’s Portal Generation API.

  • Download and unzip the portal artifacts received in response.

  • 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

    steps:
       
    - uses: actions/checkout@v1
      name : checkout-repo
      id: checkout-repo  
      
    - name: Zip files
      run: zip -qq -r portal-input.zip .
      
    - name: Call build endpoint
      run: curl -X POST --url 'https://www.apimatic.io/api/portal' -H 'Authorization:X-Auth-Key ${{ secrets.API_KEY }}' -F 'file=@portal-input.zip' -o portal-output.zip
      
    - name: Extract generated Portal
      run: unzip -qq portal-output.zip -d static-portal
    
    - name: Deploy to Netlify
          uses: nwtgck/actions-netlify@v1.2
          with:
            publish-dir: './static-portal'
            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: 1
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