Awesome Open Source
Awesome Open Source

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, GitHubs 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

Twitter API compatibility

The Twitter Ads API we currently use is the v8 version.


  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 repositorys secrets settings.

  2. Create a .github/workflows/twitter-together.yml file with the content below. Make sure to replace 'main' if you changed your repository's default branch.

    on: [push, pull_request]
    name: Twitter, together!
        name: Preview
        runs-on: ubuntu-latest
        if: github.event_name == 'pull_request'
          - uses: gr2m/[email protected]
              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        name: Tweet
        runs-on: ubuntu-latest
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
          - name: checkout main
            uses: actions/[email protected]
          - name: Tweet
            uses: gr2m/[email protected]
              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
              TWITTER_API_KEY: ${{ secrets.TWITTER_API_KEY }}
  3. After creating or updating .github/workflows/twitter-together.yml in your repositorys 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, Id love to hear if you ran into any trouble. I greatly 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 script 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 GitHubs Actions, Apps and custom user interfaces backed by GitHubs REST & GraphQL APIs.

Ive plenty more ideas that Id like to build out. Please ping me on twitter if youd like to chat: @gr2m.



Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Javascript (1,118,848
Actions (55,378
Github (44,783
Twitter (21,453
Tweets (8,346
Github Actions (5,617