X (Twitter) 予約投稿ツール

YAML で定義したポスト/スレッドを、X (Twitter) に対して指定時刻に投稿します。GitHub Actions の定期実行を想定しています。

スレッド投稿、画像（最大4件）、動画付き投稿、各画像への代替テキスト設定などにも対応します。

使い方

git clone https://github.com/burnworks/x-scheduled-posts
cd x-scheduled-posts
npm install

1. data/tweets.sample.yaml をコピーし data/tweets.yaml にリネームして内容を編集
2. GitHub リポジトリの Secrets に環境変数を設定
3. .github/workflows/scheduled-post.yml の cron を調整（必要に応じて / 初期値は15分毎実行）
4. GitHub Actions を有効化してスケジュール実行

ローカルで動作確認したい場合は .env を作成し（.env.example をコピーしてください）、API 利用に必要な環境変数を設定した上で、以下を実行します（投稿せずログだけ出します）。

DRY_RUN=true node src/index.js --file data/tweets.yaml

必要な環境変数

.env.example を参考に各値を正確に設定してください。

OAuth2 (推奨)

• X_CLIENT_ID
• X_CLIENT_SECRET
• X_ACCESS_TOKEN
• X_REFRESH_TOKEN ： （任意）あれば自動更新を試みます

OAuth1.0a (代替)

OAuth1.0a の利用が必要な場合は以下をすべて設定してください。OAuth1.0a と OAuth2 のどちらも設定されていた場合、OAuth1.0a を使用します。

• X_API_KEY
• X_API_KEY_SECRET
• X_ACCESS_TOKEN
• X_ACCESS_TOKEN_SECRET

その他

• DRY_RUN ： true or 1 を指定すると投稿せずログだけ出します。false や 0 を設定する、あるいはこの変数自体を省略すれば false 扱いとなります。
  ただし、DRY_RUN を実行する場合でも、API に関連する環境変数について正しいものが設定されている前提です。

YAML 仕様

最も基本的な例

単一のポストを指定日時で投稿したい場合は、以下のように tweets 配下に各ポストを配置します。

timezone: "Asia/Tokyo"

tweets:
  - number: 1
    schedule_at: "2026-02-02T13:00"
    text: |
      予約投稿のテストです。
      改行もそのまま反映されます。
      https://example.com
    images:
      - path: "../assets/images/one.png"
        alt: "画像の alt テキスト"
      - path: "../assets/images/two.jpg"

  - number: 2
    schedule_at: "2026-02-02T13:20"
    text: "投稿テキスト"

  - number: 3
    schedule_at: "2026-02-02T16:00"
    text: |
      予約投稿テキスト
      #hashtag
    images:
      - path: "../assets/images/three.png"
        alt: "画像の alt テキスト"

  - number: 4
    schedule_at: "2026-02-03T09:30"
    text: "予約投稿テキスト"
    video: "../assets/videos/demo.mp4"

スレッド投稿する例

スレッド投稿をしたい場合は、thread を使用してポストをネストします。

timezone: "Asia/Tokyo"

tweets:
  - number: 1
    schedule_at: "2026-02-02T13:00"
    text: |
      予約投稿のテストです。
      改行もそのまま反映されます。
      https://example.com
    images:
      - path: "../assets/images/one.png"
        alt: "画像の alt テキスト"
      - path: "../assets/images/two.jpg"
    thread:
      - number: 2
        schedule_at: "2026-02-02T13:20"
        text: "「number: 1」に対する返信として投稿されます。"
        thread:
          - number: 3
            text: |
              「number: 2」に対する返信として投稿されます。
              schedule_at を省略すると親の日時を継承します。
            images:
              - path: "../assets/images/three.png"
                alt: "画像の alt テキスト"

  - number: 4
    schedule_at: "2026-02-03T09:30"
    text: "別の予約投稿。"
    video: "../assets/videos/demo.mp4"

YAML作成時のルール

• number は一意（重複してはいけない / number を変えずに schedule_at や text だけ変えて再利用するような形での履歴上の重複も基本的には NG ですので注意してください）、かつ必須です。
• schedule_at は ISO 形式。タイムゾーンが無い場合は timezone を適用します。
• thread はネストで表現します。
  • 子要素の schedule_at は省略可能（親の値を継承）です。
  • 子要素に schedule_at を書く場合は親より前の時刻を指定することはできません。
• images は最大4つ（path と alt の組み合わせが4セット）記述可能。video とは同時指定不可です（画像や動画のパスは tweets.yaml からの相対パスで記述してください）。
• alt は各画像ごとに設定可能です。省略した場合、画像の ALT は未設定として投稿されます。
• 1つのポストごとに、text または images or video のいずれかが必須です（text は images or video のいずれかと併用可能）。

スレッド指定の考え方

• thread 配列は「親への返信（子ツイート）」として投稿されます。
• 兄弟（同じ親の直下）同士は独立です。順番に投稿したい場合は「子の中にさらに子」としてネストしてください。
• schedule_at を省略した子は、直近の親の日時を継承します。

ログ

• logs/tweet-log.jsonl に JSONL 形式で出力します。
• 投稿済み判定は state/post-history.json に記録されます。

GitHub Actions から logs/tweet-log.jsonl と state/post-history.json を push するため、リポジトリ設定の Actions > Workflow permissions を "Read and write" に設定してください。（ブランチ保護がある場合は Actions の push を許可してください）