GitHub Actions Is Not Only for CI/CD

GitHub Actions is a runtime environment offered by GitHub. The free tier of Actions offers 2,000 automation minutes a month and usage on an unlimited number of public and private repositories. The most common use case for Actions is for continuous integration (CI) and continuous deployment (CD) coverage. Yet, it has the potential to do so much more.

The Orbit Developer Relations team leverages GitHub Actions to provide an accessible path for using a suite of Orbit ready-to-connect integrations. This is done by offering GitHub Actions as one prong in a multi-pronged approach to give people from all backgrounds, whether developers or not, the ability to incorporate the integration helper libraries.

Furthermore, since GitHub Actions supports numerous programming languages, developers can contribute integration libraries in whatever language they prefer coding in, and users can run it without any need to be experienced in that language.

An approach centered on Actions is flexible, accommodating, and inclusive. Let's explore how we built it!

What Are Orbit Ready-to-Connect Integrations?

Orbit offers mission control for your community. With the Orbit platform you can understand your community and know your impact with each member across all the platforms your community lives on. There are several ways to add interactions from your community into Orbit. Namely, there are Plug & Play integrations incorporated via the UI of the Orbit app, low-code and no-code solutions with n8n, Zapier and Integromat, and an API to build your own solutions.

Credentials to the API are provided with every Orbit account, and with them, developers can connect any 3rd-party community platform to Orbit. As long as you can get the data out of the other platform, you can bring it into Orbit.

The ready-to-connect integrations function as helper libraries connecting popular 3rd-party platforms to the Orbit API. There are ready-to-connect integrations built for Stack Overflow, Reddit, YouTube, LinkedIn, Meetup, Circle, among many others.

Each ready-to-connect integration can be used as a package in an application or service you are building, and they also each include a CLI that can be used on your command line.

Take, for example, the Meetup integration, which is written in Ruby. The integration can be used as part of a separate Ruby application by including it in the Gemfile and requiring it:

{% c-block language="ruby" %}

# Gemfile

gem "meetup_orbit"

# app.rb

require "meetup_orbit"

{% c-block-end %}

The integration can also be run from the command line to fetch new event RSVPs:

{% c-block language="bash" %}

$ MEETUP_URLNAME=my_meetup_group ORBIT_API_KEY=your_api_key ORBIT_WORKSPACE_ID=my_orbit_workspace bundle exec meetup_orbit --check-rsvps

{% c-block-end %}

These are both conventional paths for building developer tooling; the options are standardized, whether a Ruby gem or an npm package. By offering developers a package to include in their own code and a CLI, you check off the list of two common ways people will come to use a tool.

In addition to these well-trodden paths, we wanted to offer a third approach. This last approach would leverage the CLI and make it accessible for developers from all language communities and individuals who are not developers and are not comfortable with running tooling on a command line. This approach is made possible with GitHub Actions.

From CLI to GitHub Actions Workflow

The CLI in each Orbit ready-to-connect integration is utilized as a part of an Actions strategy to open up the tooling to the broadest array of users. We take the CLI out of the command line and put it into the GitHub UI. Before we discuss how that works, we need to understand how Actions work by looking at the core of Actions -- the workflow.

Examining an Actions Workflow

GitHub Actions function by creating workflow files written in YAML. These workflows provide instructions on what to do inside the runtime environment. For example, a common use case is to write a testing suite on every push or pull request to a repository. This can be accomplished in Actions with the following YAML workflow:

{% c-block language="yaml" %}

name: CI

on:  
push:    
 branches: [ main ]  
pull_request:    
 branches: [ main ]
 
jobs:
test:    
 strategy:      
  matrix:        
   os: [ubuntu-latest, windows-latest, macos-latest]        
   ruby: [2.5, 2.6, 2.7, 3.0]    
 runs-on: ${{ matrix.os }}    
 steps:    
 - uses: actions/checkout@v2    
 - name: Set up Ruby      
   uses: ruby/setup-ruby@v1      
   with:        
    ruby-version: ${{ matrix.ruby }}    
 - name: Install dependencies      
    run: bundle install    
 - name: Run tests      
    run: bundle exec rake test      
    env:        
     CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

{% c-block-end %}

Let's break down the workflow above, as doing so will give a lot of insight into the mechanics of Actions.

The first parameter is a `name:`, this is how the workflow will be referred to throughout the repository and in the history of workflow runs. In our case, we call it `CI` as it contains instructions to run our CI testing.

The next set of instructions begin with `on:`. The `on`: key defines when and in what conditions to run the workflow. There is a lot of flexibility and customization possible in this section. The GitHub docs contain the full list of possibilities. These include only running it on a new release, on a pull request to specific branches, and on a timed schedule. The example in our workflow specifies that this action should run on every new push to and every new pull request against the `main` branch.

Lastly, the bulk of the action is contained in the `jobs:` key. There can be many jobs contained under this key. Each job is run in parallel by default unless specified otherwise.

Before defining the jobs to be run, we also define the `strategy` by which to run the jobs. In this case, we offer a `matrix` of runtime environments we want to test on Ubuntu, Windows, and macOS. We also define a `matrix` of Ruby versions we want to test against: 2.5, 2.6, 2.7, and 3.0. The action is run once for each combination of runtime environments and language versions.

Once we have created our strategy, then we define what the action will do with that strategy, which happens in the `steps:` key. There are three activities happening: set up a Ruby environment, install the dependencies and then run the test suite. In the last step, you will notice an additional key of `env:`. This one lets us define step-level environment variables. Those secrets are contained in the secrets section of our repository settings and referenced in the workflow using the `${{ secrets.SECRET_NAME }}` pattern. The workflow above contains the API token to send the CI results to Codecov.

Once this file is saved in your repository inside the `.github/workflows` file path it will immediately start working. Then, you can click on the `Actions` tab in GitHub and see the output of all the runs. Each line item in the output table can be clicked into to examine all the details of that particular run.

Now that we have an overview of how to use Actions in a CI context, we're ready to take a look at how we did the same for running Orbit ready-to-connect integrations.

A Workflow For More Than CI/CD

There are two things required to run any of the ready-to-connect integrations from within GitHub Actions. First, all the credentials for both Orbit and the 3rd-party platform need to be stored inside the GitHub repository secrets. Second, there needs to be a workflow created inside the `.github/workflows` folder path.

The Orbit DevRel team provides step-by-step instructions on how to save credentials inside the Secrets settings in the Orbit GitHub Actions Templates repository. Inside the templates repository is a subfolder for each integration that contains the specific instructions for that platform along with a complete Actions workflow to be copied and pasted into your own repository.

Let's continue the example of the Meetup integration. We discussed how to use it in your own Ruby code, or from the command line with the CLI. The Actions path provides a way to use it for both developers who do not work in Ruby, and for anyone else who is not a developer.

First, according to the instructions, we need to copy the provided Actions workflow to our own repository:

{% c-block language="yaml" %}

name: Check for New Meetup Interactions and Add to Orbit

on:  
schedule:    
 - cron: "0 0 */1 * *"  
workflow_dispatch:

jobs:  
comments-workflow:    
 runs-on: ubuntu-latest    
 steps:    
 - uses: actions/checkout@v2      
   with:        
    fetch-depth: 0        
    submodules: recursive    
 - name: Set up Ruby 2.7.2      
   uses: ruby/setup-ruby@v1      
   with:        
    ruby-version: 2.7.2    
 - name: Bundle Install      
   run: |        
    gem update --system 3.1.4 -N        
    gem install --no-document meetup_orbit    
 - name: Check for New Event RSVPs      
   run: |        
    meetup_orbit --check-rsvps      
   env:        
    MEETUP_URLNAME: ${{ secrets.MEETUP_URLNAME }}        
    ORBIT_API_KEY: ${{ secrets.ORBIT_API_KEY }}        
    ORBIT_WORKSPACE_ID: ${{ secrets.ORBIT_WORKSPACE_ID }}

{% c-block-end %}

The workflow above looks very similar to the CI example we showed early. There are two significant differences. One difference is in the `on:` key, and the other is in the work described inside the `steps:` key.

Unlike a traditional CI/CD workflow, we want to run our integrations on a timed schedule. Actions allow us to use a cron scheduler to define how often it runs. There is free tooling available to help form the cron syntax to define a frequency, or you can use the default provided in the workflow, which is once a day at midnight.

The workflow also adds an additional option for when to run it called `workflow_dispatch`. This is a unique option provided by GitHub that allows a repository owner to click into the `Actions` tab in the GitHub UI and manually run an action whenever they want.

All of our ready-to-connect integration workflows include a `workflow_dispatch` option to increase access to the workflow. There are times that you will want to trigger it to run even outside of the defined timed schedule.

The other difference is what is actually happening inside the workflow run. While in a CI workflow, you are running a testing suite. Here we are downloading from Rubygems the gem and then running the CLI from the gem with the credentials provided as secrets. This integration was written in Ruby, so it downloads and runs a Ruby gem, but it could have equally been written in Python, Node.js, Golang, or any other language and have done the same.

Once the workflow has been saved into your repository, and the credentials defined as Secrets, then it will start working by itself. For the Meetup integration, you will begin seeing new Meetup event RSVPs appear as activities in your Orbit workspace:

What's Next?

GitHub Actions opens an entirely new world of possibilities for creating automations for your work and for your communities. Is there a 3rd-party platform you would be interested in writing a ready-to-connect integration for and building an Actions automation? Reach out to the Orbit DevRel team by email or on Discord - we'd love to offer support!

There is a lot more to discover with GitHub Actions and the ready-to-connect integrations; consider continuing your journey with these resources:

• ‍GitHub Actions Documentation
• Orbit GitHub Actions Templates
• How Teams Are Leveling Up Their Orbit Workspaces with Community Integrations