How to Welcome First-Time Contributors to Your Repository Using GitHub Actions

- Alexis Gonzales

What is a Welcome Message Action?

A welcome message triggers a GitHub action to post a message whenever a new contributor opens their first issue or pull request in your repository (repo). Why do we want to consider using a welcome message? The one-worded answer that comes to mind is community. Community comes from my personal journey while contributing to open source with Amplify. Amplify’s goal was to create a welcoming environment for all open-source contributors.

Since contributors are from all over the world, creating a welcome message is an easy but impactful step towards fostering a sense of community for your repository. Prior to Amplify, I had no idea what GitHub Actions was or how to even implement this, so let’s break them down together!

What is GitHub Actions?

GitHub Actions is a platform that allows developers to integrate continuous integration and continuous delivery to automate their build, test, and deployment pipeline. GitHub Actions does more than devOps, it lets developers run workflows when events happen in your repository. Let's dive into running workflows in more detail!

What is a GitHub Marketplace

So far we have covered what GitHub Actions is, but how are actions created? We could build a welcome message but there is no need to! GitHub Marketplace has one that we can use! GitHub Marketplace is where you can discover, browse, and install free and paid tools, including GitHub Apps, OAuth Apps, and GitHub Actions.

How to create Welcome Message

In order to create our welcome message, we will need to use an action called “welcome-new-contributors”, to read the official documentation for this bot click here. To add the welcome bot, we will need to create a YAML file to configure the automated process.

Configure Permissions

The bot will need to have read and write access to the repo. This bot will act like a contributor on your repo. To accomplish adding your welcome bot as a contributor, follow the steps below:

Create a new GitHub account to be used as the bot’s account.
Go to your repository and give the bot’s account access to be a collaborator on your repository that you want the workflow to execute. Ensure the bot has permission to write on the project’s repository.

Next, create a new token on our bot’s GitHub account by going to Settings > Developer settings > Personal access tokens so the workflow action can use your bot account to comment on issues.

You did it! You have connected your welcome bot account to your project repo. Let’s create a Workflow.

How to Configure a Workflow YAML
What is a YAML?
The purpose of YAML is to create the road map of when we want our workflow to execute. Workflows are defined in the .github/workflows directory of the repository. Let’s review some definitions that way we understand the building blocks needed. There are more components when it comes to coding a YAML but we will focus on the terms that we will use to construct our YAML. For a more in-depth explanation of GitHub Actions head to the GitHub Docs here.

Configure YAML
In your project repository create the following directory “.github/workflows”. Within the workflow directory, create a “welcome_action.YAML” and then paste the code below.

YAML Template:

name: 'Welcome New Contributors'

on:
  issues:
    types: [opened]
  pull_request_target:
    types: [opened]

jobs:
  welcome-new-contributor:
    runs-on: ubuntu-latest
    steps:
      - name: 'Greet the contributor'
        uses: garg3133/welcome-new-contributors@v1.2
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-message: 'Hello there, thanks for opening your first issue. We welcome you to the community!'
          pr-message: 'Hello there, thanks for opening your first Pull Request. Someone will review it soon.'

Want to tag the contributor in the message?
Use @contributor_name anywhere in the message and it will be automatically replaced by the contributor's username.

Summary
If you made it all the way to the end of the article, you can be proud of yourself for creating a welcome message on the first PR and Issues opened by a contributor. I encourage you to use this welcome bot to create a sense of community while also increasing communication.