npm package: @jonvisc/gh-to-confluence
Description: A CLI tool that automatically sets up a GitHub Action to publish markdown files from your repository's `docs` folder to a Confluence page.
Latest version: 0.2.0

# 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

```bash
npx gh-to-confluence
```

## Usage

1. **Run the setup command:**
   ```bash
   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:**
   ```bash
   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:

```yaml
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](https://id.atlassian.com/manage-profile/security/api-tokens)
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.