GitHub to Confluence Publisher

A CLI tool that automatically sets up a GitHub Action to publish markdown files from your repository's docs folder to a Confluence page.

Features

• 🚀 One-command setup - Automatically creates GitHub Actions workflow
• 📁 Folder-based publishing - Publishes all markdown files from the docs folder
• 🌿 Branch restrictions - Optionally restrict workflow to specific branches
• ⚙️ Configurable - Customize Confluence parent ID and error handling
• 🔒 Secure - Uses GitHub Secrets for authentication

Installation

npx gh-to-confluence

Usage

1. Run the setup command:

   npx gh-to-confluence

2. Follow the interactive prompts:

   • Choose whether to restrict the workflow to your current branch
   • Enter your Confluence Parent ID
   • Decide if processing should continue on error

3. Set up GitHub Secrets: Add these vars & secrets to your repository settings:

   • Variable: CONFLUENCE_BASE_URL - Your Confluence base URL (e.g., https://yourcompany.atlassian.net)
   • Secret: ATLASSIAN_USERNAME - Your Atlassian username
   • Secret: ATLASSIAN_API_TOKEN - Your Atlassian API token

4. Create your docs folder:

   mkdir docs
   # Add your markdown files to the docs folder

5. Push to trigger the workflow: The GitHub Action will automatically run when you push changes to your repository.

How it works

The tool creates a GitHub Actions workflow file at .github/workflows/publish.yml that:

• Triggers on push events (and optionally pull requests)
• Checks out your repository
• Uses the markdown-confluence/publish-action@v5 to publish content
• Publishes all markdown files from the docs folder to your specified Confluence parent page

Generated Workflow

The tool generates a workflow that looks like this:

name: Publish to Confluence
on: push

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Publish Markdown to Confluence
        uses: markdown-confluence/publish-action@v5
        continue-on-error: false
        with:
          confluenceBaseUrl: ${{ vars.CONFLUENCE_BASE_URL }}
          confluenceParentId: YOUR_PARENT_ID
          atlassianUserName: ${{ secrets.ATLASSIAN_USERNAME }}
          atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }}
          folderToPublish: docs

Requirements

• Node.js (for running the CLI tool)
• Git repository
• Confluence space access
• Atlassian API token

Configuration

GitHub Secrets

You need to set up these secrets in your GitHub repository:

1. Go to your repository settings
2. Navigate to "Secrets and variables" → "Actions"
3. Add the following vars & secrets:
   • CONFLUENCE_BASE_URL: Your Confluence base URL (e.g., https://yourcompany.atlassian.net)
   • ATLASSIAN_USERNAME: Your Atlassian account username
   • ATLASSIAN_API_TOKEN: Your Atlassian API token

Getting an Atlassian API Token

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a label and copy the token
4. Add it as ATLASSIAN_API_TOKEN in your GitHub repository secrets

Troubleshooting

Workflow already exists

If you see "GitHub publish action already exists", the tool detected an existing workflow file. You'll need to modify it manually or remove it first.

Authentication issues

Make sure your GitHub Secrets are correctly set up with valid Atlassian credentials.

Branch restrictions

If you chose to restrict the workflow to a specific branch, make sure you're pushing to that branch for the workflow to trigger.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.