Contents

A GitHub Actions workflow can publish the same Markdown article to Zenn and Qiita when you push to main. The key is to save the Qiita article ID in Git. Otherwise, subsequent runs may create duplicate articles.

Key Points#

  • Keep Zenn articles in articles/ and generated Qiita files in public/, with matching filenames.
  • Preserve Qiita article IDs so edits update existing articles.
  • Treat Zenn’s published: false as a setting that stops publication. It does not make existing Qiita articles private.
  • Commit files updated by the CLI after publication, and handle deletions explicitly.

Use Git as the Source of Truth#

Connect the repository to Zenn and place the required articles/ directory at the repository root. For example, generate public/github-actions-sync.md for Qiita from the source file articles/github-actions-sync.md.

Use matching filenames to link articles across the two platforms. No separate mapping file is needed, but take care when renaming source files. If the conversion process cannot find the previous Qiita file, it may fail to preserve the ID and create a separate article.

Edit the source files in articles/. Treat public/ as storage for generated content and persistent publication state, rather than a second place to write articles. Changes made directly on Qiita may be overwritten during the next sync.

Configure the Workflow#

Create a Qiita access token with article write permissions and save it as the repository secret QIITA_TOKEN. Grant the workflow contents: write permission so it can commit publication state. Repository rules must also allow that push.

Configure GitHub Actions as follows.

  • Trigger it on pushes to main that change articles/**, and on workflow_dispatch for manual runs.
  • Set cancel-in-progress: false in a single concurrency group to prevent publication jobs from running simultaneously.
  • Check out the repository and install a supported version of Node.js.
  • Install pinned versions of @qiita/qiita-cli and js-yaml. Prefer a committed lockfile and npm ci.

Run checkout, conversion, publication, and commit steps in that order. Check the CLI’s current requirements before choosing Node.js and action versions. Avoid treating versions from older examples as a fixed standard. Set the Qiita token as an environment variable for the publication step.

Convert the Front Matter#

Parse YAML with a library instead of replacing lines. Copy the Markdown body and generate Qiita front matter using the following mapping.

| Qiita field | Value | |---|---| | title | Zenn’s title | | tags | Up to five topic strings | | private | false | | id | Existing Qiita ID, or null | | updated_at | Existing value, or an empty string | | organization_url_name | Existing value, or null | | slide | false |

These values follow the CLI’s Markdown format, which differs from the API request format. In the implementation presented, using strings for tags and null for new article IDs and organizations resolved the Bad request error. Validate this format with the CLI version you pin.

For each source file being processed, read the existing public/<slug>.md before overwriting it. Preserve its ID and update timestamp. Raise an error if publication metadata is missing or invalid, so unfinished articles are not mistakenly considered ready to publish.

Save IDs After Publication#

After publication, the Qiita CLI writes article IDs back to local Markdown files. Because GitHub Actions runners are temporary environments, these changes must be saved to the repository before the next run.

After successful publication, commit the changed files in public/ and push to main. The implementation presented also preserves the CLI’s public/.remote/ cache. If publication succeeds but the commit fails, recover the published article IDs before rerunning. Otherwise, duplicate articles may be created.

In addition to serializing jobs, fetch the latest branch state before conversion. Serialization alone does not guarantee that a queued run will check out the bot’s latest commit. If the final push conflicts with concurrent changes, resolve the conflict without losing IDs. Pull locally before starting new edits. Restricting the trigger to articles/** prevents commits containing only generated files from rerunning this workflow.

Handle Drafts and Deletions#

Zenn and Qiita handle publication differently. Setting published: false can return a Zenn article to draft status, but it does not make an already published Qiita article private. The pipeline leaves that Qiita article unchanged.

There is an easy-to-miss implementation pitfall. Skipping conversion does not exclude existing public/ files from qiita publish --all. Explicitly list the articles to publish, and publish only those using a selection method supported by the pinned CLI version. Preserve saved IDs for skipped articles.

Deletion requires a separate procedure.

  • First, exclude the source article from Qiita publication. Otherwise, conversion may recreate it.
  • Delete the article on Qiita.
  • Delete the generated file and its corresponding remote cache, then commit.
  • Before publication, check shared Markdown, image URLs, and tags. Zenn-specific blocks and images with repository-relative paths must be converted or replaced.

Next Steps#

Publish one test article through the workflow, then edit it and rerun. Confirm that the same article ID is updated on Qiita before enabling sync for the remaining articles in the repository.

Source: https://zenn.dev/ot4ma_zenn/articles/20261025-sun-zenn_qiita_pipeline

Contents