Best Practices

1. Use Preview Before Sync

Always use the preview action before syncing to verify the structure:

- name: Preview changes
  uses: Myastr0/mk-notes/preview
  with:
    input: './docs'
    format: 'plainText'

- name: Sync to Notion
  if: github.ref == 'refs/heads/main'
  uses: Myastr0/mk-notes/sync
  with:
    input: './docs'
    destination: ${{ secrets.NOTION_DOCS_PAGE_URL }}
    notion-api-key: ${{ secrets.NOTION_API_KEY }}

2. Secret Management

Proper secret management is crucial for secure GitHub Actions workflows:

• Never commit secrets: Use GitHub repository secrets for sensitive information

• NOTION_API_KEY - Your Notion integration secret token

• NOTION_DOCS_PAGE_URL - The URL of the Notion page where you want to sync your documentation

2. Use Clean Sync Carefully

The clean: 'true' option removes ALL existing content from the destination page. Use it only when:

• You're sure you want to replace all content
• The page is dedicated to mk-notes content
• You have backups of important content

3. Sync on Specific Paths

Only trigger syncs when documentation files change:

on:
  push:
    branches: [main]
    paths: ['docs/**', '*.md']

4. Use Different Pages for Different Branches

Consider using different Notion pages for different branches:

- name: Sync to Notion
  uses: Myastr0/mk-notes/sync
  with:
    input: './docs'
    destination: ${{ github.ref == 'refs/heads/main' && secrets.NOTION_MAIN_DOCS_PAGE_URL || secrets.NOTION_DEV_DOCS_PAGE_URL }}
    notion-api-key: ${{ secrets.NOTION_API_KEY }}

5. Conditional Workflows

Use conditional logic to control when syncs happen:

# Only sync on main branch pushes
if: github.ref == 'refs/heads/main'

# Only sync when specific files change
on:
  push:
    paths: ['docs/**', 'README.md']

# Manual sync with workflow_dispatch
on:
  workflow_dispatch:

6. Error Handling

Add proper error handling to your workflows:

- name: Sync to Notion
  uses: Myastr0/mk-notes/sync
  with:
    input: './docs'
    destination: ${{ secrets.NOTION_DOCS_PAGE_URL }}
    notion-api-key: ${{ secrets.NOTION_API_KEY }}
  continue-on-error: false

7. Artifact Management

Save preview outputs as artifacts for review:

- name: Upload preview
  uses: actions/upload-artifact@v4
  with:
    name: sync-preview-${{ github.sha }}
    path: ./preview.txt
    retention-days: 30

8. Environment-Specific Configuration

Use different configurations for different environments:

env:
  NOTION_PAGE_URL: ${{ github.ref == 'refs/heads/main' && secrets.NOTION_PROD_PAGE_URL || secrets.NOTION_DEV_PAGE_URL }}

9. Workflow Organization

Organize your workflows logically:

• Separate workflows for different purposes (preview, sync, cleanup)
• Use descriptive workflow names
• Add proper descriptions and documentation
• Use consistent naming conventions

10. Secret Management

Proper secret management is crucial for secure GitHub Actions workflows:

• Never commit secrets: Use GitHub repository secrets for sensitive information
• Use descriptive secret names: Make secret names clear and consistent
• Rotate keys regularly: Regularly update your Notion API keys
• Environment separation: Use different integrations for different environments when possible
• Monitor usage: Keep track of your Notion integration usage