Configure GitHub for Dev.to Publishing

Configure GitHub for Dev.to Publishing

1. Prepare Your Dev.to Account

Generate a Dev.to API Key

• Go to your Dev.to account.
• Navigate to Settings > Account > Extensions > API Key.
• Generate a new API key and copy it.

2. Create a GitHub Repository

Create a New Repository

• Go to GitHub and create a new repository.
• Give it a meaningful name (e.g., blog).

Set Up the Repository Structure

• Clone the repository to your local machine:

  git clone https://github.com/<your-username>/<repository-name>.git
  cd <repository-name>

It's always a best practice to create a branch and work from it.

  git branch <branch-name> initial-build
  git checkout <branch-name>

• Create a folder named "articles" to store your Markdown files:

  mkdir articles

After creating the folder, the repository structure should look like this:

  .
  ├── articles
  ├── LICENSE
  └── README.md

3. Add Your Dev.to API Key to GitHub Secrets

Go to Repository Settings

• Navigate to "Settings" > "Secrets and variables" > "Actions" > "New repository secret".

Add a Secret

• Name the secret "DEVTO_TOKEN".
• Paste the "Dev.to" API key from the previous step.

4. Create a GitHub Actions Workflow

Create a Workflow File

• Set up the folder structure for GitHub Actions workflows:

  mkdir -p .github/workflows
  touch .github/workflows/markdown-lint.yml
  touch .github/workflows/devto-publisher.yml

  .
  ├── .github
  │   └── workflows
  │       ├── markdown-lint.yml
  │       └── devto-publisher.yml
  ├── articles
  ├── LICENSE
  └── README.md

Configure markdown-lint.yml

• Update the "markdown-lint.yml" file with the following contents:

  name: markdown-lint

  on:
    push:
      branches:
        - "**"
    pull_request:
      paths:
        - "**/*.md"

  jobs:
    markdown-lint:
      runs-on: ubuntu-latest
      steps:
        - name: Checkout code
          uses: actions/checkout@v4

        - name: Install markdownlint
          run: npm install -g markdownlint-cli@0.41.0

        - name: Run markdownlint
          env:
            CONFIG: |
              {
                "comment": "Default rules",
                "default": true,
                "whitespace": true,
                "line_length": false,
                "ul-start-left": true,
                "ul-indent": true,
                "no-inline-html": true,
                "no-bare-urls": true,
                "fenced-code-language": true,
                "first-line-h1": true,
                "no-duplicate-header": true,
                "no-emphasis-as-header": true,
                "single-h1": true
              }
          run: |
            CONFIG_FILE="$(mktemp)"
            echo "$CONFIG" > "$CONFIG_FILE"
            markdownlint '**/*.md' --ignore node_modules -c "$CONFIG_FILE"

Configure devto-publisher.yml

• Update the "devto-publisher.yml" file with the following contents:

  name: Dev.to Publisher

  on:
    push:
      branches:
        - "**"
      paths:
        - "articles/**/*.md"

  jobs:
    publish:
      runs-on: ubuntu-latest

      steps:
        - name: Checkout code
          uses: actions/checkout@v4

        - name: Set dry-run mode based on branch
          id: dry_run_check
          run: |
            if [[ "${{ github.ref_name }}" == "main" ]]; then
              echo "dry_run=false" >> $GITHUB_ENV
            else
              echo "dry_run=true" >> $GITHUB_ENV
            fi

        - name: Publish articles to Dev.to
          uses: sinedied/publish-devto@v2
          with:
            devto_key: ${{ secrets.DEVTO_TOKEN }}
            github_token: ${{ secrets.GITHUB_TOKEN }}
            files: "articles/**/*.md"
            branch: ${{ env.CURRENT_BRANCH }}
            conventional_commits: true
            dry_run: ${{ env.dry_run }}

Summary

• The "markdown-lint.yml" workflow ensures Markdown files are formatted correctly.
• The "devto-publisher.yml" workflow automates publishing Markdown articles located in the articles directory to your Dev.to account.

5. Push the branch to GitHub

• Execute

git add --all
git commit -m "feat: add GitHub Actions workflows for publishing to Dev.to" \
  -m "Configure automation with markdown linting and article publishing workflows."
git push origin <branch-name>

6. Create a Pull Request (PR)

Go to Your Repository in GitHub

• Visit your repository on GitHub.

Navigate to the "Pull Requests" Tab

• Click on the "Pull Requests" tab at the top of the repository page.

Click "New Pull Request"

• Select the "New Pull Request" button.

Select Branches

• Base branch: Choose the branch you want to merge into (e.g., main or production).
• Compare branch: Select the <branch-name> branch.

Review Changes

• Review the list of commits and the files changed to ensure they are correct.

Add a Title and Description

• Provide a concise and descriptive title (e.g., feat: Add GitHub Actions for Dev.to publishing).
• Add any necessary details in the description box (e.g., reasons for changes, references to issues, etc.).

Review and Approve the PR

• Self-Review or Request Reviews.

Merge the Pull Request

• Navigate to the PR you just created.
• Click "Merge Pull Request".
• Click "Confirm merge".

7. Test and Validate the Workflow

• You might to go have and forth to fix issues other than testing the workflow.

Comments

[JesúsB]

Hey,

Thank you so much for sharing this article—it’s really insightful!

Based on your suggestions, I tried applying this approach to my repository, but I’m encountering the following issue:

articles/00-test.md has error(s):
- Update failed: HTTPError: Response code 422 (Unprocessable Entity)

I was attempting to push some articles directly that I had prepared earlier. After running into this error, I simplified the process by trying a minimal example based on the template repository sinedied/publish-devto, but the issue persists.

Have you encountered anything similar? In my case, pull requests work fine because they run the dry mode without issues. However, once I merge to the main branch, the error appears regardless of whether the articles are marked as published: true or published: false.

I reviewed the debug logs in GitHub, and the messages are quite similar to what I shared above. Here’s an excerpt:

##[debug]Output result_summary:
##[debug]Found 3 article(s)
##[debug]articles/00-test.md has error(s):
##[debug]- Update failed: HTTPError: Response code 422 (Unprocessable Entity)
##[debug]articles/01-to-signal.md has error(s):
##[debug]- Update failed: HTTPError: Response code 422 (Unprocessable Entity)
##[debug]articles/17-testing-in-angular.md has error(s):
##[debug]- Update failed: HTTPError: Response code 422 (Unprocessable Entity)
##[debug]
##[debug][FAILED] [PUBLISHED] How Angular Routing Works                             
##[debug][FAILED] [DRAFT]     New in Angular Bridging RxJS and Signals with `toSig… 
##[debug][FAILED] [PUBLISHED] Testing in Angular: From Unit to Integration Testing  
##[debug]Node Action run completed with exit code 255
##[debug]Set output result_json = [
##[debug]  {
##[debug]    "title": "How Angular Routing Works",
##[debug]    "status": "[FAILED]",
##[debug]    "publishedStatus": "[PUBLISHED]",
##[debug]    "errors": [
##[debug]      "Update failed: HTTPError: Response code 422 (Unprocessable Entity)"
##[debug]    ]
##[debug]  },
##[debug]  {
##[debug]    "title": "New in Angular Bridging RxJS and Signals with `toSignal`! 🚀",
##[debug]    "status": "[FAILED]",
##[debug]    "publishedStatus": "[DRAFT]",
##[debug]    "errors": [
##[debug]      "Update failed: HTTPError: Response code 422 (Unprocessable Entity)"
##[debug]    ]
##[debug]  },
##[debug]  {
##[debug]    "title": "Testing in Angular: From Unit to Integration Testing",
##[debug]    "status": "[FAILED]",
##[debug]    "publishedStatus": "[PUBLISHED]",
##[debug]    "errors": [
##[debug]      "Update failed: HTTPError: Response code 422 (Unprocessable Entity)"
##[debug]    ]
##[debug]  }
##[debug]] 

If you have any insights on what could be causing this or how to resolve it, I’d really appreciate your help.

Thanks in advance!.

[John Ajera]

Troubleshooting 422 Unprocessable Entity Error on Dev.to

1. Check for Duplicate Articles

   • Ensure no similar article already exists on your dev.to account. If found, manually delete it.

2. Enable conventional_commits

   • Set conventional_commits = true. This ensures the GitHub Action automatically updates the article metadata with an id and date, required by the sinedied/publish-devto@v2 action in handling upload.

   Example metadata (updated by GitHub Action):
   

    ---
    id: 123456
    date: 2024-12-14
    ---
   

3. Troubleshooting Tips

   • The 422 error can be vague. Check logs for missing or invalid fields in your article's metadata. You can manually create an article with the same content to test.
   • Verify GitHub Action configuration and ensure API key permissions are correct.

[JesúsB]

Everything you suggested is accurate.
I have conventional_commits set to true, and there are no duplicate articles.

To troubleshoot further, I tried publishing a basic test article using the example from the repository to rule out issues with my other articles. However, I’m still encountering the 422 error, and the logs I’ve shared don’t provide any additional details.

I'd need to check whether is a potential permissions issue.

[John Ajera]

Here is my current config, check it out and see it helps.

github.com/jdevto/blog/blob/main/....

[JesúsB]

I've just found that the issue was related with the metadata.
I was not using properly the tags, by adding some of them with spaces and maybe more than 4 at some stage.

Thanks for the help!