Skip to content

ExFig Action

Actions

About

Export Figma assets (colors, icons, images, typography) using ExFig CLI
v3.1.3
Latest
By DesignPipe
Star (1)

Tags

 (2)
continuous-integrationutilities

ExFig Action

A GitHub Action for exporting Figma assets using ExFig CLI. Export colors, icons, images, and typography from Figma to your codebase with built-in caching.

Usage

- uses: DesignPipe/exfig-action@v2
  with:
    figma_token: ${{ secrets.FIGMA_TOKEN }}
    command: icons
    cache: true

Inputs

Input Description Required Default
figma_token Figma Personal Access Token Yes -
command ExFig command: colors, icons, images, typography, batch, fetch, download Yes -
config Path to exfig.pkl config file (comma-separated for batch) No exfig.pkl
filter Filter pattern for assets (e.g., icon/*) No -
version ExFig version to use No latest
cache Enable caching for incremental exports No false
cache_path Path to cache file No .exfig-cache.json
cache_key_prefix Prefix for cache key No exfig-cache
granular_cache Enable experimental granular caching No false
concurrent_downloads CDN download parallelism (number of concurrent downloads) No -
timeout API timeout in seconds No -
fail_fast Stop on first batch error No false
report Path to write JSON report file No -
rate_limit Figma API rate limit (requests/second) No 10
max_retries Maximum retries for failed API requests No 3
output_dir Output directory for exported assets No -
verbose Enable verbose logging No false
extra_args Additional CLI arguments to pass to ExFig (e.g., --force --dry-run) No -
slack_webhook Slack Incoming Webhook URL for notifications No -
slack_mention User/group to mention on failure (plain ID: U123, S456; or @channel) No -
slack_templates Path to custom Slack templates directory (overrides defaults) No -

Outputs

Output Description
assets_exported Number of assets exported
changed_files List of changed files (newline-separated)
cache_hit Whether cache was restored
exit_code ExFig command exit code (0 = success)
failed_count Number of failed configs in batch mode
duration Execution duration (e.g., "5s")
config_summary Summary of config files processed (batch command)
validated_count Number of configs validated from cache (no changes)
exported_configs Number of configs that exported new assets
error_category Error category code (RATE_LIMIT, TIMEOUT, AUTH, etc.)
error_message First error message from failed config (truncated)
report_json Raw JSON report content (from --report)

Examples

Basic Usage

Export icons with caching:

name: Export Figma Icons
on:
  workflow_dispatch:
  schedule:
    - cron: '0 0 * * *'  # Daily

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: DesignPipe/exfig-action@v2
        with:
          figma_token: ${{ secrets.FIGMA_TOKEN }}
          command: icons
          cache: true

      - name: Commit changes
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          git diff --staged --quiet || git commit -m "Update icons from Figma"
          git push

Export Multiple Asset Types

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Export colors
        uses: DesignPipe/exfig-action@v2
        with:
          figma_token: ${{ secrets.FIGMA_TOKEN }}
          command: colors
          cache: true
          cache_key_prefix: exfig-colors

      - name: Export icons
        uses: DesignPipe/exfig-action@v2
        with:
          figma_token: ${{ secrets.FIGMA_TOKEN }}
          command: icons
          cache: true
          cache_key_prefix: exfig-icons

      - name: Export typography
        uses: DesignPipe/exfig-action@v2
        with:
          figma_token: ${{ secrets.FIGMA_TOKEN }}
          command: typography
          cache: true
          cache_key_prefix: exfig-typography

Filter Specific Assets

- uses: DesignPipe/exfig-action@v2
  with:
    figma_token: ${{ secrets.FIGMA_TOKEN }}
    command: icons
    filter: 'navigation/*'
    cache: true

Pin ExFig Version

- uses: DesignPipe/exfig-action@v2
  with:
    figma_token: ${{ secrets.FIGMA_TOKEN }}
    command: icons
    version: 'v1.2.0'

Extra CLI Arguments

Pass additional flags directly to ExFig CLI:

- uses: DesignPipe/exfig-action@v2
  with:
    figma_token: ${{ secrets.FIGMA_TOKEN }}
    command: icons
    extra_args: '--force'

Batch with Report

Export multiple configs with a structured JSON report:

- uses: DesignPipe/exfig-action@v2
  id: exfig
  with:
    figma_token: ${{ secrets.FIGMA_TOKEN }}
    command: batch
    config: 'exfig-colors.pkl, exfig-icons.pkl'
    cache: true
    fail_fast: true
    report: 'exfig-report.json'

- name: Use report
  if: always()
  run: echo '${{ steps.exfig.outputs.report_json }}' | jq .

macOS Runner

jobs:
  export:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v6

      - uses: DesignPipe/exfig-action@v2
        with:
          figma_token: ${{ secrets.FIGMA_TOKEN }}
          command: icons

Caching

The action supports two levels of caching:

1. Binary Caching

The ExFig binary is automatically cached per OS and version to avoid re-downloading on every run.

2. Asset Caching

When cache: true, the action uses ExFig's built-in cache to enable incremental exports. Only changed assets are re-exported, significantly reducing Figma API calls and export time.

- uses: DesignPipe/exfig-action@v2
  with:
    figma_token: ${{ secrets.FIGMA_TOKEN }}
    command: icons
    cache: true
    cache_path: '.exfig-cache.json'  # Default
    cache_key_prefix: 'exfig-cache'   # Default

The cache is saved even on failure to support checkpoint resume for large exports.

Granular Cache (Experimental)

For better performance with large asset libraries:

- uses: DesignPipe/exfig-action@v2
  with:
    figma_token: ${{ secrets.FIGMA_TOKEN }}
    command: icons
    cache: true
    granular_cache: true

Supported Platforms

  • Ubuntu (Linux x64)
  • macOS (Universal binary: arm64 + x86_64)

Configuration

Create an exfig.pkl in your repository root:

amends "package://github.com/DesignPipe/exfig/releases/download/v3.0.0/exfig@3.0.0#/ExFig.pkl"

figma {
  fileId = "YOUR_FIGMA_FILE_KEY"
}

icons {
  new {
    figma { page = "Icons" }
    iOS { output = "Sources/Assets.xcassets/Icons" }
  }
}

colors {
  new {
    figma { page = "Colors" }
    iOS { output = "Sources/Assets.xcassets/Colors" }
  }
}

See ExFig documentation for full configuration options.

Slack Notifications

Send notifications to Slack when exports complete or fail:

- uses: DesignPipe/exfig-action@v2
  with:
    figma_token: ${{ secrets.FIGMA_TOKEN }}
    command: batch
    config: 'exfig/colors.pkl, exfig/icons.pkl'
    slack_webhook: ${{ secrets.SLACK_WEBHOOK }}
    slack_mention: 'U123456'  # Mention on failure only (auto-formatted)

Notification Types

Status Icon Description
Success ✅ Export completed successfully
Failure ❌ Export failed (mentions user if configured)
Cache hit 💨 No changes detected, all assets up to date

Message Contents

  • Command: Shows command and config files (e.g., batch (colors.pkl, icons.pkl))
  • Assets: Number of exported assets
  • Duration: Execution time
  • Repository: Link to GitHub Actions run

Custom Templates

Override default notification templates with your own Slack Block Kit JSON:

- uses: DesignPipe/exfig-action@v2
  with:
    figma_token: ${{ secrets.FIGMA_TOKEN }}
    command: icons
    slack_webhook: ${{ secrets.SLACK_WEBHOOK }}
    slack_templates: '.github/exfig-templates'

Create only the templates you want to override:

.github/exfig-templates/
├── success.json      # Override success message
├── failure.json      # Override failure message
└── cache-hit.json    # Override cache hit message

Templates support these placeholders:

Variable Description Example
{{ICON}} Status icon ✅, ❌, 💨
{{TITLE}} Main title "Export completed"
{{COMMAND}} Command with configs "batch (colors.pkl)"
{{ASSETS}} Assets count "140"
{{DURATION}} Execution time "5s"
{{REPO}} Repository name "org/repo"
{{RUN_URL}} Actions run URL "https://github.com/..."
{{SUBTITLE}} Context text "2 config(s) failed"
{{COLOR}} Attachment color "#36a64f"

Troubleshooting

Invalid Figma Token

Error: Request failed with status 403

Ensure your FIGMA_TOKEN secret has read access to the Figma file.

Rate Limiting

Error: Rate limit exceeded

Reduce rate_limit input or wait before retrying:

- uses: DesignPipe/exfig-action@v2
  with:
    figma_token: ${{ secrets.FIGMA_TOKEN }}
    command: icons
    rate_limit: 5
    max_retries: 6

Cache Not Working

Ensure caching is enabled and the cache path is accessible:

- uses: DesignPipe/exfig-action@v2
  with:
    figma_token: ${{ secrets.FIGMA_TOKEN }}
    command: icons
    cache: true
    verbose: true  # Enable verbose logging to debug

License

MIT License - see LICENSE for details.

Contributors (3)

@alexey1312@github-actions@claude

Resources

ExFig Action is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.

About

Export Figma assets (colors, icons, images, typography) using ExFig CLI
v3.1.3
Latest
By DesignPipe

Tags

 (2)
continuous-integrationutilities

Contributors (3)

@alexey1312@github-actions@claude

Resources

ExFig Action is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.