In 2016 GitHub released the first large-scale, public GraphQL API, proving to everyone that GraphQL is here to stay. Their API is robust and constantly evolving, and it provides developers the tools to “create integrations, retrieve data, and automate your workflows”.
Later on in 2018, Github came out with GitHub Actions — a tool to help developers do what they love most: automate things. With GitHub Actions you can automate your CI/CD and general project management using YAML files.
You can use GitHub’s GraphQL API in the GitHub Actions workflow files to create the automation of your dreams.
A Quick Overview of GraphQL
GraphQL was originally developed by Facebook as a way of cutting down response payload. With a REST get request, you get back everything that an entry has to offer. Let’s say we have a database of customers where a customer entry might look like the following:
"Customer" : {
"id" : "101010",
"first_name" : "Bjarne",
"last_name" : "Stroustrup",
"email" : "[email protected]",
"City" : "Austin",
"State" : "Texas",
...
}
Now let’s say we have the customer’s id and we just want their first name so we can print “Hello, Bjarne!”. Using a REST call will return all the fields for a customer when we only need a single field. This is where GraphQL comes in. With GraphQL you create a query specifying the fields you need and only those fields are returned.
Let’s look at a simple GraphQL query that calls on the GitHub GraphQL API:
query FindRepoID {
repository(owner:"YOUR_ORGANIZATION_NAME", name:"REPOSITORY_NAME") {
id
}
}
The query calls on the repository query with your organization name and the repository name, and returns the id of that repository.
Here is an example of a response of this query:
{
"data": {
"repository": {
"id": "R_ktHp3iGA",
}
}
}
The repository object has 119 fields, but we only asked for one and therefore only received one. Had we used a REST call we would have received all 119 fields.
The Basics of GitHub Actions
To create a workflow for a repository we need to create a workflow YAML file in the .github/workflows directory. If your project doesn’t have those directories, go ahead and create them.
Let’s look at a very basic workflow.yaml file:
name: My First Action ## name of our workflow
on: create ## branch or tag being created trigger
jobs: ## jobs to run when triggered
echo-branch-name: ## name of a job
runs-on: ubuntu-latest ## which machine the job runs on
steps: ## steps to run
- name: Step One ## name of a step
run: | ## commands to run
echo '${{ github.event.ref }}'
A workflow is triggered by events (you can see a list of events that trigger a workflow here). In this case our workflow is triggered by a branch or a tag being created in the workflow’s repository. Once the workflow is triggered, our jobs start running on the type of machine we chose. In this case we simply echo the name of the branch from the ${{ github.event }} variable.
Connecting Branches With Issues Using GitHub Actions and GitHub GraphQL API
First, let’s decide on a branch naming system. For this example we decide that for every Issue there is a branch with a name that starts with the Issue’s number. For example, an Issue numbered #42 will have a branch with a name that starts with #42, like “#42/awesome_branch”.
We’ll start off by getting the Issue number from the branch’s name.
name: New Branch Created
on:
create
jobs:
On-New-Branch:
runs-on: ubuntu-latest
steps:
- name: Get Issue Number
run: |
branch_name=`echo '${{ github.event.ref }}'`
issue_num=`echo ${branch_name#*#} | egrep -o '^[^/]+'`
For this example if a branch was created without an issue number at the start of its name we will ignore it and the workflow will not continue. To do so we’ll create output variables that the next job can use to determine if to execute or not.
name: New Branch Created
on:
create
jobs:
Check-Branch-Name:
runs-on: ubuntu-latest
outputs:
issue_num: ${{ steps.step1.outputs.issue_num }}
tracked: ${{ steps.step1.outputs.tracked }}
steps:
- name: Get Created Issue Number
id: step1
run: |
branch_name=`echo '${{ github.event.ref }}'`
issue_num=`echo ${branch_name#*#} | egrep -o '^[^/]+'`
re='^[0-9]+$'
if ! [[ $issue_num =~ $re ]] ; then
echo "::set-output name=tracked::false"
else
echo "::set-output name=tracked::true"
fi
echo "::set-output name=issue_num::$issue_num"
We check if issue_num is actually a number - if it is a number, we set an output variable named ‘tracked’ to be ‘true’, and if it is not a number we set it to be ‘false’. To use the issue number in the next steps, we also save it in an output variable named ‘issue_num’.
The next job created will need those outputs to run:
name: New Branch Created
on:
create
jobs:
Check-Branch-Name:
runs-on: ubuntu-latest
outputs:
issue_num: ${{ steps.step1.outputs.issue_num }}
tracked: ${{ steps.step1.outputs.tracked }}
steps:
- name: Get Created Issue Number
id: step1
run: |
branch_name=`echo '${{ github.event.ref }}'`
issue_num=`echo ${branch_name#*#} | egrep -o '^[^/]+'`
re='^[0-9]+$'
if ! [[ $issue_num =~ $re ]] ; then
echo "::set-output name=tracked::false"
else
echo "::set-output name=tracked::true"
fi
echo "::set-output name=issue_num::$issue_num"
Add-Linked-Issue-To-Project:
needs: Check-Branch-Name
if: needs.Check-Branch-Name.outputs.tracked == 'true'
env:
ISSUE_NUM: ${{ needs.Check-Branch-Name.outputs.issue_num}}
runs-on: ubuntu-latest
steps:
- name: Get Issue ${{ env.ISSUE_NUM }} Project Item ID
run: |
We specify the dependency on the first job with ‘needs’ and check if the job should execute using an if statement with the output variable ‘tracked’ from the previous job. We also make use of env variables here - environment variables are used to store information that you want to reference in your workflow. Env variables can be set for an entire workflow, for a specific job or for a specific step. To access the content of an env variable use ${{ env.NAME_OF_VARIABLE }}.
To make calls on the GraphQL API we need a GitHub authorization bearer token for our repository. To create one go through these steps , copy your generated token and save it under your repository’s settings as an Actions secret (repository Settings → Secrets → Actions → New repository secret). Name it PERSONAL_TOKEN to match the example. We’re also going to need our organization name and the repository’s name set as our workflow’s environment variables:
name: New Branch Created
on:
create
env:
GH_TOKEN: ${{ secrets.PERSONAL_TOKEN }}
ORGANIZATION: your-organization-name
REPO: the-repository-name
jobs:
Check-Branch-Name:
runs-on: ubuntu-latest
outputs:
issue_num: ${{ steps.step1.outputs.issue_num }}
tracked: ${{ steps.step1.outputs.tracked }}
steps:
- name: Get Created Issue Number
id: step1
run: |
branch_name=`echo '${{ github.event.ref }}'`
issue_num=`echo ${branch_name#*#} | egrep -o '^[^/]+'`
re='^[0-9]+$'
if ! [[ $issue_num =~ $re ]] ; then
echo "::set-output name=tracked::false"
else
echo "::set-output name=tracked::true"
fi
echo "::set-output name=issue_num::$issue_num"
Add-Linked-Issue-To-Project:
needs: Check-Branch-Name
if: needs.Check-Branch-Name.outputs.tracked == 'true'
env:
ISSUE_NUM: ${{ needs.Check-Branch-Name.outputs.issue_num}}
runs-on: ubuntu-latest
steps:
- name: Get Issue ${{ env.ISSUE_NUM }} ID and State
run: |
gh api graphql -f query='query FindIssueID {
repository(owner:"${{ env.ORGANIZATION }}",name:"${{ env.REPO }}") {
issue(number:${{ env.ISSUE_NUM }}) {
id,
state
}
}
}' > project_data.json
echo 'ISSUE_ID='
$(jq '.data.repository.issue.id' project_data.json)
>> $GITHUB_ENV
echo 'ISSUE_STATE='
$(jq '.data.repository.issue.state' project_data.json)
>> $GITHUB_ENV
We created a step called “Get Issue ${{ env.ISSUE_NUM }} ID and State”. In this step we run a GraphQL query and save its result into project_data.json. The query finds a repository by its organization name and repo name, then looks for an issue by its number and returns the issue’s id and state. We save the issue id and issue state from the result into env variables called ISSUE_ID and ISSUE_STATE for later use.
We use GitHub’s “gh api” to make an authenticated HTTP request to the GitHub API.
gh api <endpoint> [flags]
Our endpoint is the GraphQL API, and the flag -f adds a string parameter in key=value format so the key ‘query’ is set to be our raw GraphQL query FindIssueID.
name: New Branch Created
on:
create
env:
GH_TOKEN: ${{ secrets.PERSONAL_TOKEN }}
ORGANIZATION: your-organization-name
REPO: the-repository-name
jobs:
Check-Branch-Name:
runs-on: ubuntu-latest
outputs:
issue_num: ${{ steps.step1.outputs.issue_num }}
tracked: ${{ steps.step1.outputs.tracked }}
steps:
- name: Get Created Issue Number
id: step1
run: |
branch_name=`echo '${{ github.event.ref }}'`
issue_num=`echo ${branch_name#*#} | egrep -o '^[^/]+'`
re='^[0-9]+$'
if ! [[ $issue_num =~ $re ]] ; then
echo "::set-output name=tracked::false"
else
echo "::set-output name=tracked::true"
fi
echo "::set-output name=issue_num::$issue_num"
Add-Linked-Issue-To-Project:
needs: Check-Branch-Name
if: needs.Check-Branch-Name.outputs.tracked == 'true'
env:
ISSUE_NUM: ${{ needs.Check-Branch-Name.outputs.issue_num}}
runs-on: ubuntu-latest
steps:
- name: Get Issue ${{ env.ISSUE_NUM }} ID and State
run: |
gh api graphql -f query='query FindIssueID {
repository(owner:"${{ env.ORGANIZATION }}",name:"${{ env.REPO }}") {
issue(number:${{ env.ISSUE_NUM }}) {
id
state
}
}
}' > project_data.json
echo 'ISSUE_ID='
$(jq '.data.repository.issue.id' project_data.json)
>> $GITHUB_ENV
echo 'ISSUE_STATE='
$(jq '.data.repository.issue.state' project_data.json)
>> $GITHUB_ENV
- name: Reopen Issue
if: ${{ env.ISSUE_STATE }} == 'CLOSED'
run: |
gh api graphql -f query='
mutation {
reopenIssue(input: { issueId: ${{ env.ISSUE_ID }} } ){
issue {
title
state
}
}
}'
We added “Reopen Issue”, a Mutation query that runs if the issue state is closed.
We run this query in case we closed the issue in the past and want to reopen it once a branch for it exists, implying that the fix was not done.
We now have an easy-to-read, quick and simple Workflow file that uses GitHub Actions with GraphQL queries to reopen an issue by a branch being created for it. You can modify this basic example to your own needs — you can run a job when a PR is created, you can run a job when an issue is opened, you can run a job every time a commit is made to a branch or run a job on any event trigger you desire. You now have the tools to create your own automation.
More Advanced Examples
Here are some more advanced examples of using the GitHub GraphQL API with GitHub Actions:
- This workflow moves a newly created issue into a specific column in a project.
- This workflow connects branches to issues by branch name. When a branch is created for an issue, the issue will move to a specific column in a project. If the issue was closed prior to the creation of the branch, the issue will reopen.
- This workflow connects PRs to issues by branch name. When a PR is created/closed/merged the issue will move to a specific column in a project. Once an issue is moved to the ‘Done’ column the issue will be closed.
Not Convinced?
Not ready to embark on the GraphQL adventure? Looking for something out of the box to automate your workflows? Looking to mix it all up? Check out GitHub’s REST API and GitHub Marketplace. You can use the REST API instead of the GraphQL API, or you can integrate one of the apps or actions available in the GitHub Marketplace into your workflows. Whichever way you choose, automating your workflows will save you valuable time that you can now use for more coding! Woohoo!
Tips
Trying to use a Marketplace app or action but getting “Resource not accessible by integration” error? Most Marketplace apps and actions use the default “secrets.GITHUB_TOKEN”, but this token doesn’t come with read/write access to all scopes. For example, it doesn’t have write permissions for items in Projects. Set a personal access token like we did in the examples and use it instead of the GITHUB_TOKEN (make sure you give it the correct permissions).
If you’re using the GitHub GraphQL Documentation but having a hard time understanding and making queries work, take a look at the GitHub repository on Apollo GraphQL. The Documentation there is clear and they have an Explorer section where you can try out queries and see their responses.
Our goal here at liblab is to make the lives of developers easier, and that includes our own developers. If we can automate it and save time, we will — leaving our developers all the time they need to focus on the tasks that matter. If you’re looking to save time and automate your SDK creation, if you want flawless SDKs in multiple languages directly from your API, and if you care about making developers’ lives easier, check out what liblab has to offer and contact us to start your SDK journey.
