GitHub-to-Qiita lets you integrate your Qiita articles with your GitHub repository. Setting up GitHub-to-Qiita and pushing your articles into your GitHub repository, they will be published to Qiita automatically.

Make your writing efficient and save your time with GitHub-to-Qiita! 😉

The setup is easy. You can setup a workflow by following the instructions below.

Navigate to the Qiita access token generation page.

Enter the following information, and click the Generate token button.

After generating your new access token, it should be going to appear on your screen. Then copy it.

Note that it can be shown only once. If you lose it, regenerate it again.

WARNING: The above screen shot shows a dummy access token, not a real access token. You should not take a screen shot including your access token, and must not share it with other people. Please be careful.

Navigate to the Actions secrets creation page, which is accessible at https://github.com/<USERNAME>/<REPONAME>/settings/secrets/actions/new.

Enter the following information, and click the Add secret button.

Create a file as .github/workflows/qiita.yml, and set your own workflow.

Here is a sample workflow.

# .github/workflows/qiita.yml

name: "GitHub to Qiita"

on:
  push:
    branches: [ main ]

jobs:
  qiita:
    runs-on: ubuntu-latest
    steps:
      - name: "Publish to Qiita"
        uses: noraworld/github-to-qiita@v1.0.0
        with:
          dir: "articles"
          qiita_access_token: ${{ secrets.QIITA_ACCESS_TOKEN }}
          mapping_filepath: "mapping.txt"
          strict: false

Replace a part of the above YAML code with the following.

WARNING: Please do not set the version to @main at the jobs.qiita.steps[*].uses section for a production use because the specification is subject to change, and the latest codes potentially contain bugs. It is highly recommended to set the latest tagged version, which can be accessible at the Tags page.

The strict mode determines whether your article will be published newly or not even if the corresponding article on Qiita is not found and your article file on your repository is MODIFIED (not ADDED). When the strict mode is on (jobs.qiita.steps[*].with.strict is set to true), your article won’t be published newly if the mapping file is incomplete, the corresponding article on Qiita is not found, and your article file is MODIFIED. Otherwise, your article will be published newly.

If your mapping information is not fully filled, it is recommended to set true because if false your article can be going to be published newly even if your articles exist on Qiita. But note that if your new article failed to publish to Qiita for some reason (The Qiita API is down or your article is invalid), your article will never be published as long as you don’t publish manually. Consider setting jobs.qiita.steps[*].with.strict to false to avoid it.

That’s all!

Your Markdown articles need to include a YAML header like this.

---
title: "Your awesome title"
topics: ["GitHubActions", "Ruby", "YAML"]
published: true
---

Your article starts here.

Note that your article file must start with ---.

Additional keys and values are acceptable. They are simply ignored.

Pushing your articles in the specific directory (articles directory in the sample workflow above) into the specific branch (main branch in the sample workflow above), it starts to work automatically. There is no need to do the further operation.

You can see whether your workflow succeeded at https://github.com/<USERNAME>/<REPONAME>/actions/workflows/qiita.yml.

The files and directories for a local development are as follow.

• .env
• mapping.txt
• articles/

These are ignored for Git (described in .gitignore), so you can create sample data and use them to test how it works.

WARNING: The published key in a YAML header in a sample article (files in articles/) should be always set to false, or your sample article will be exposed publicly!

---
title: "Test"
topics: ["Foo", "Bar", "Baz"]
published: false # <= IMPORTANT!!!
---

This is a test article.

You need to set the following environment variables for a local debug. Note that the environment variables in .env are loaded only when a development environment.

Here is a sample .env file.

ADDED_FILES="articles/test01.md"
MODIFIED_FILES="articles/test02.md"
MAPPING_FILEPATH="mapping.txt"
QIITA_ACCESS_TOKEN="7f6c7aec310ded84ae3acfe8f920cb1c7556c7d3" # THIS IS A SAMPLE!!
STRICT="true"

NOTE: It is highly recommended to use the Qiita access token that is different from one for a production use.

You can omit either ADDED_FILES or MODIFIED_FILES, but if both are omitted, it does nothing.

The old implementation has moved to noraworld/github-to-qiita-server, and it is no longer maintained.

All codes of this repository are available under the MIT license. See the LICENSE for more information.