markdown-confluence/publish GitHub Action
This GitHub Action wraps up an NPM CLI that allows you to publish your Markdown files to Confluence quickly and easily. By using this action in your workflows, you can automate the process of publishing documentation to Confluence, making it faster, more streamlined, and more efficient.
Usage
To use this GitHub Action in your repository, you'll need to create a workflow file (e.g., .github/workflows/publish.yml
) and configure the action as described below.
Basic example
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@v1
with:
confluenceBaseUrl: https://your-confluence-instance-url
confluenceParentId: 123456
atlassianUserName: ${{ secrets.ATLASSIAN_USERNAME }}
atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }}
Example using a config file
Create a .markdown-confluence.json
file in your repository with the following content:
{
"confluenceBaseUrl": "https://your-confluence-instance-url",
"confluenceParentId": "123456",
"atlassianUserName": "your-email@example.com",
"folderToPublish": "docs",
"contentRoot": "/docs"
}
Then configure the GitHub Action in your workflow file:
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@v1
with:
configFile: .markdown-confluence.json
atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }}
Input Options
This section provides an overview of all the input options available for the markdown-confluence/publish
GitHub Action and examples of how to use them in your workflows.
confluenceBaseUrl
The base URL of your Confluence instance, used for API calls and publishing content. This value should include the protocol (e.g., https://
) but not a trailing slash.
Example:
with:
confluenceBaseUrl: https://your-confluence-instance-url
confluenceParentId
The ID of the parent page in Confluence where the Markdown files will be published as child pages.
Example:
with:
confluenceParentId: 123456
atlassianUserName
Your Atlassian account's username, required for authentication when interacting with Confluence.
Example:
with:
atlassianUserName: ${{ secrets.ATLASSIAN_USERNAME }}
atlassianApiToken
An API token generated for your Atlassian account, used for authentication when making API calls to Confluence. This value should be stored as a repository secret.
Example:
with:
atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }}
folderToPublish
The folder you want to apply a default of "connie-publish: true" to. All Markdown files within this folder will be considered for publishing.
Example:
with:
folderToPublish: docs
contentRoot
The root path for published content on Confluence. This is used to tell the action where to look for Markdown files and content.
Example:
with:
contentRoot: /docs
configFile
A configuration file containing additional settings and customizations for the publishing process. You can use this option to keep your workflow file clean and maintain all configuration settings in a separate file.
Example:
with:
configFile: .markdown-confluence.json
Advanced Example
Here's an example of using all input options in a single workflow:
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@v1
with:
confluenceBaseUrl: https://your-confluence-instance-url
confluenceParentId: 123456
atlassianUserName: ${{ secrets.ATLASSIAN_USERNAME }}
atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }}
folderToPublish: docs
contentRoot: /docs
configFile: .markdown-confluence.json
Remember to create and configure the .markdown-confluence.json
file in your repository as needed.
Storing API token as a repository secret
To store your Atlassian API token as a repository secret, follow these steps:
- Go to your GitHub repository and click on the "Settings" tab.
- In the left sidebar, click on "Secrets".
- Click on the "New repository secret" button.
- Enter
ATLASSIAN_API_TOKEN
as the name and paste your API token as the value. - Click on the "Add secret" button.
Now you can reference the ATLASSIAN_API_TOKEN
secret in your GitHub Actions workflows using the syntax ${{ secrets.ATLASSIAN_API_TOKEN }}
.
Support
If you need help with using this action or encounter any issues, please open an issue in the GitHub repository.
License
This GitHub Action is released under the Apache 2.0 License.