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.

• Try it
• Twitter API compatibility
• Setup
• Contribute
• How it works
  • The push event
  • The pull_request event
  • Advanced tweeting
• Motivation
• License

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

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 repository’s 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!
   jobs:
     preview:
       name: Preview
       runs-on: ubuntu-latest
       if: github.event_name == 'pull_request'
       steps:
         - uses: twitter-together/action@v2
           env:
             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     tweet:
       name: Tweet
       runs-on: ubuntu-latest
       if: github.event_name == 'push' && github.ref == 'refs/heads/main'
       steps:
         - name: checkout main
           uses: actions/checkout@v3
         - name: Tweet
           uses: twitter-together/action@v2
           env:
             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
             TWITTER_ACCESS_TOKEN: ${{ secrets.TWITTER_ACCESS_TOKEN }}
             TWITTER_ACCESS_TOKEN_SECRET: ${{ secrets.TWITTER_ACCESS_TOKEN_SECRET }}
             TWITTER_API_KEY: ${{ secrets.TWITTER_API_KEY }}
             TWITTER_API_SECRET_KEY: ${{ secrets.TWITTER_API_SECRET_KEY }}

3. After creating or updating .github/workflows/twitter-together.yml 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 greatly appreciate any documentation improvements to make things more clear, I am not a native English speaker myself.

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

Thanks goes to these wonderful people (emoji key):

Jason Etcovitch 🎨 📖 💻

Erons 📖

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

twitter-together is using two workflows

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

(Tweets can also be invoked locally by calling the script with the --file flag, which can be useful for development. E.g. TWITTER_ACCESS_TOKEN=... node lib/index.js --file tweets/hello-world.tweet)

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.

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.

Beyond tweeting out plain-text tweets, twitter-together also supports creating polls, replying to other tweets, retweeting or quote-retweeting other tweets, threading a chain of tweets, and adding images to tweets.

Polls can be included directly in the body of tweet like so:

What is your favorite color?

( ) Red
( ) Blue
( ) Green

All other advanced tweeting features are supporting through defining YAML frontmatter in the tweet file. Some frontmatter items can be combined together, where Twitter functionality supports it.

A poll can also be defined in frontmatter, rather than in the tweet body, like so:

---
poll:
  - Red
  - Blue
  - Green
---

What is your favorite color?

To reply to another tweet, include the reply frontmatter item with the tweet link that you wish to reply to:

---
reply: https://twitter.com/gr2m/status/1409601188362809349
---

@gr2m I love your work!

If you want to quote-retweet another tweet, include the retweet frontmatter item with the tweet link that you wish to quote-retweet. If you'd prefer to just retweet without quoting, don't provide a tweet body after the frontmatter.

---
retweet: https://twitter.com/gr2m/status/1409601188362809349
---

twitter-together is awesome!

To include media items with your tweet, include the media frontmatter item as an array with each item having a file property and an optional alt property. The file property should be the name of a file within the media directory of your repository (same level as the tweets directory).

(Note: Although alt text can be set in frontmatter, it is not yet actually passed to Twitter due to library limitations).

---
media:
  - file: cat.jpg
    alt: A cat
  - file: dog.jpg
    alt: A dog
---

Here are some cute animals!

To thread a chain of tweets, use --- to delimit each tweet in the file. You can optionally set threadDelimiter in the frontmatter to change the delimiter for the next tweet in the thread. Each tweet in a thread supports its own frontmatter.

---
media:
  - file: cat.jpg
    alt: A cat
  - file: dog.jpg
    alt: A dog
---

Here are some cute animals!

---
---
poll:
  - Cat
  - Dog
---

Which one is cuter?

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 Actions, 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.

MIT