Skip to content
🐦 A GitHub action to tweet from a repository
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

twitter together logo

Twitter, together!

Build Status Coverage

For Open Source or event maintainers that share a project twitter account, twitter-together is a GitHub Action that utilizes text files to publish tweets from a GitHub repository. Rather than tweeting directly, GitHub’s pull request review process encourages more collaboration, Twitter activity and editorial contributions by enabling everyone to submit tweet drafts to a project.

Screencast demonstrating twitter-together

Try it

You can submit a tweet to this repository to see the magic happen. Please follow the instructions at tweets/ and mention your own twitter username to the tweet. This repository is setup to tweet from


  1. Create a twitter app with your shared twitter account and store the credentials as TWITTER_API_KEY, TWITTER_API_SECRET_KEY, TWITTER_ACCESS_TOKEN and TWITTER_ACCESS_TOKEN_SECRET in your repository’s secrets settings.

  2. Create a .github/main.workflow file or amend your existing one with the content below

    workflow "Tweet on push to default branch" {
      on = "push"
      resolves = ["Tweet"]
    action "Tweet" {
      uses = "gr2m/twitter-together@master"
    # "push" event won’t work on forks, hence the 2nd workflow with "pull_request"
    workflow "Preview and validate tweets on pull requests" {
      on = "pull_request"
      resolves = ["Preview"]
    action "Preview" {
      uses = "gr2m/twitter-together@master"
      secrets = ["GITHUB_TOKEN"]
  3. After creating or updating .github/main.workflow in your repository’s default branch, a pull request will be created with further instructions.

Happy collaborative tweeting!


All contributions welcome!

Especially if you try twitter-together for the first time, I’d love to hear if you ran into any trouble. I greately appreciate any documentation improvements to make things more clear, I am not a native English speaker myself.

See for more information on how to contribute. You can also just say thanks 😊

Thanks to all contributors 💐

Thanks goes to these wonderful people (emoji key):

Jason Etcovitch
Jason Etcovitch

🎨 📖 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

How it works

twitter-together is using two workflows

  1. push event to publish new tweets
  2. pull_request event to validate and preview new tweets

The push event

When triggered by the push event, the script looks for added *.tweet files in the tweets/ folder or subfolders. If there are any, a tweet for each added tweet file is published.

If there is no tweets/ subfolder, the scripts opens a pull request creating the folder with further instructions.

The pull_request event

For the pull_request event, the script handles only opened and synchronize actions. It looks for new *.tweet files in the tweets/ folder or subfolders. If there are any, the length of each tweet is validated. If one is too long, a failed check run with an explanation is created. If all tweets are valid, a check run with a preview of all tweets is created.


I think we can make Open Source more inclusive to people with more diverse interests by making it easier to contribute other things than code and documentation. I see a particularly big opportunity to be more welcoming towards editorial contributions by creating tools using GitHub’s Acions, Apps and custom user interfaces backed by GitHub’s REST & GraphQL APIs.

I’ve plenty more ideas that I’d like to build out. Please ping me on twitter if you’d like to chat: @gr2m.



You can’t perform that action at this time.