After reading this guide, you will be able to:

• Understand how the Baton SDK works
• Understand how to generate a c1z file
• Understand how to integrate the Baton SDK with GitHub
• Understand how to set up a GitHub scheduled flow

Let’s get started!

Before you start

Before you begin, make sure you have everything set up from the list below:

• GitHub account
• AWS account with admin access

Part one: Prepare your GitHub access token

The GitHub connector allows you to manage access rights for all users across all repositories. Setting up the connector is very simple, so let’s take a look at how to do it.

1. Create a new GitHub Personal Access Token with the following permissions:

   Area	Scope of access
   repo	All
   admin:org	All
   user	All

2. Save your Personal Access Token. You will need it later.

Part two: Create an AWS S3 bucket

1. As a next step, you need to create new AWS S3 bucket. This bucket will be used for storage of the exported file from Baton.

If you are not sure how to create an S3 bucket, check the official AWS guide on how to work with AWS S3.

2. Once your AWS S3 is created, copy these values:
   • ACCESS KEY ID
   • REGION
   • SECRET ACCESS KEY

Now your AWS S3 account is ready to receive files from Baton. In next steps we will connect it all together.

Part three: Create GitHub Actions secrets

Because we want to use GitHub Actions for pushing access changess to AWS S3, we need to create GitHub Actions secrets first.

1. Create a new GitHub repository

2. Inside your GitHub repository click Settings.

3. Select Secrets, then Actions.

4. Add New repository secrets:

   • AWS_ACCESS_KEY_ID
   • AWS_SECRET_ACCESS_KEY
   • BATON_TOKEN

5. At the end your GitHub should look like this:

Part four: Schedule your connector

As a practical example, we have prepared a use case where the script will run at a scheduled time every day and check for permission changes on your GitHub.

In our case, we want to check updates every day at 9AM. We will use a simple cron script to do this.

1. Create a GitHub Action file .github/workflows/github-schedule.yml inside your GitHub repository.
2. Paste the GitHub Action instructions to github-schedule.yml.

name: Baton GitHub Schedule

on:
  schedule:
    - cron: "0 9 * * *"
  workflow_dispatch:

jobs:
  schedule:
    name: Baton diff GitHub permissions
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: "./.github/scripts/schedule.sh"
        shell: "bash"
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_BUCKET: your_s3_bucket
          AWS_REGION: your_s3_bucket_region
          BATON_ORGS: your_github_org
          BATON_TOKEN: ${{ secrets.BATON_TOKEN }}

If you need help with cron format, check out crontabguru.

3. Paste the script below, which the GitHub Action will use, into a new file called .github/scripts/schedule.sh.

#!/bin/bash
set -xe

# You have to set these ENV variables to your CI/CD:
# BATON_TOKEN - your github access token
# BATON_ORGS - your github organization(s) separated by comma
# AWS_ACCESS_KEY_ID - your AWS access key
# AWS_SECRET_ACCESS_KEY - your AWS secret access key
# AWS_REGION - your AWS bucket region
# AWS_BUCKET - your AWS bucket name

# Set the output filenames
now=$(date +"%Y%m%d%H%M%S")
s3bucket="s3://$AWS_BUCKET"
c1zFile="$s3bucket/scheduled-sync.c1z"
csvFile="$s3bucket/sync-github-$now.csv"
xlsxFile="$s3bucket/sync-github-$now.xlsx"

# Pull the containers to ensure we have access
docker pull ghcr.io/conductorone/baton:latest
docker pull ghcr.io/conductorone/baton-github:latest

# Run sync to produce c1z
docker run -e BATON_ORGS -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_REGION ghcr.io/conductorone/baton-github:latest -f "$c1zFile"

# Run a diff
docker run -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_REGION ghcr.io/conductorone/baton:latest -f "$c1zFile" diff

4. Make github/scripts/schedule.sh executable:

chmod +x github/scripts/schedule.sh

About the c1z file:

Ac1z file contains all of the information that the connector has collected as part of a synchronization process. Using the c1z utility, you can browse the contents of the sync.c1z file that is the output of a connector, including export to a .csv or .xlsx file.

5. Commit and push your changes to your default branch.

6. At this point, the script will automatically run at the time you set in github-schedule.yml.

What’s next?

As you’ve seen, the Baton SDK is a powerful tool that can help you monitor GitHub rights changes. But that’s just one example of what Baton can do.

Check out our other tutorials to discover the full potential of Baton:

• Export GitHub access updates to a CSV file
• Get Splunk alerts when a new GitHub admin is added
• Diff access rights from two GitHub orgs