In a couple of previous blog posts, I provided a writeup on the GitHub Projects Beta. I wrote two posts on automation within GitHub Projects (Adding Issues to GitHub Projects with GitHub Actions for a user profile and Adding Issues to GitHub Projects with GitHub Actions for an Organization profile). I’m pleased to say that the capabilities went Generally Available last week! As a result of the GA announcement and resulting changes, I need to post updates to my older samples.
In a couple of previous blog posts, I provided a writeup on the GitHub Projects Beta. I wrote two posts on automation within GitHub Projects (Adding Issues to GitHub Projects with GitHub Actions for a user profile and Adding Issues to GitHub Projects with GitHub Actions for an Organization profile). I’m pleased to say that the capabilities went Generally Available last week! As a result of the GA announcement and resulting changes, I need to post updates to my older samples.
The team have had an incredible cadence of releases, posting new updates on the GitHub changelog every few weeks. There have been plenty of feature updates, including -
- Visualise Projects as Tables or Boards
- Custom Fields
- Iterations
- Charts to visualise the progress within projects
- Updates to the Automations
- GraphQL ProjectsV2 API
It’s because of that last point that I’m writing this particular blog post. When looking over the samples in the prior blog posts, you’ll notice that it used the ProjectNext object. However, the GitHub Projects Team announced that the ProjectNext object will be deprecated in favour of the ProjectV2 object. As such, my previous GitHub Action workflows will need to be updated. But, fear not - as I’ve included them for you below!
The example below shows how to add a GitHub Issue to an existing project.
- The example uses the ProjectV2 object
- Due to the new schema, the nodes property needs to be updated. Notice that it is now split into
... on ProjectV2Fieldand... on ProjectV2SingleSelectField(compared with the simple flat nodes object in the previous blog posts). - The example still passes in a
GITHUB_TOKEN. I have set this at my CloudWithChris organisation level, so it can be used across all repositories in the organisation.- I generated a Personal Access Token (PAT) which has the
projectOAuth2 scope. This was also newly introduced as part of the recent GitHub projects updates (as seen in the team’s June update). This means we can generate a token which either has read, or write access to Projects. - Ideally, I would have used the
permissionsproperty in GitHub Actions to leverage the Automatic Token Authentication capabilities, eliminating the need for Personal Access Tokens altogether. Unfortunately, it doesn’t look like there are permissions for GitHub Projects v2 at the moment.
- I generated a Personal Access Token (PAT) which has the
name: Add issue to project
on:
issues:
types:
- opened
jobs:
track_issue:
runs-on: ubuntu-latest
steps:
- name: Get project data
env:
GITHUB_TOKEN: ${{ secrets.GH_TOKEN_PROJECT_ACCESS }}
ORGANIZATION: CloudWithChris
PROJECT_NUMBER: 5
run: |
gh api graphql -f query='
query($org: String!, $number: Int!) {
organization(login: $org){
projectV2(number: $number) {
id
fields(first:20) {
nodes {
... on ProjectV2Field {
id
name
}
... on ProjectV2SingleSelectField {
id
name
options {
id
name
}
}
}
}
}
}
}' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json
echo 'PROJECT_ID='$(jq '.data.organization.projectV2.id' project_data.json) >> $GITHUB_ENV
- name: Add issue to project
env:
GITHUB_TOKEN: ${{ secrets.GH_TOKEN_PROJECT_ACCESS }}
ISSUE_ID: ${{ github.event.issue.node_id }}
run: |
item_id="$( gh api graphql -f query='
mutation($project:ID!, $issue:ID!) {
addProjectV2ItemById(input: {projectId: $project, contentId: $issue}) {
item {
id
}
}
}' -f project=$PROJECT_ID -f issue=$ISSUE_ID --jq '.data.addProjectV2ItemById.projectV2Item.id')"
And the same for Pull Requests -
name: Add PR to project
on:
pull_request:
types:
- opened
jobs:
track_pr:
runs-on: ubuntu-latest
steps:
- name: Get project data
env:
GITHUB_TOKEN: ${{ secrets.GH_TOKEN_PROJECT_ACCESS }}
ORGANIZATION: CloudWithChris
PROJECT_NUMBER: 5
run: |
gh api graphql -f query='
query($org: String!, $number: Int!) {
organization(login: $org){
projectV2(number: $number) {
id
fields(first:20) {
nodes {
... on ProjectV2Field {
id
name
}
... on ProjectV2SingleSelectField {
id
name
options {
id
name
}
}
}
}
}
}
}' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json
echo 'PROJECT_ID='$(jq '.data.organization.projectV2.id' project_data.json) >> $GITHUB_ENV
- name: Add PR to project
env:
GITHUB_TOKEN: ${{ secrets.GH_TOKEN_PROJECT_ACCESS }}
PR_ID: ${{ github.event.pull_request.node_id }}
run: |
item_id="$( gh api graphql -f query='
mutation($project:ID!, $pr:ID!) {
addProjectV2ItemById(input: {projectId: $project, contentId: $pr}) {
item {
id
}
}
}' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectV2ItemById.projectV2Item.id')"
I’m a fan of GitHub Issues and GitHub Projects. Combined with GitHub Issues Forms, there is a great level of flexibility in how you can manage your issues in a way that makes sense for your own projects. And it sounds like there are some exciting things planned for the future of GitHub Projects.
Are you using GitHub Projects? Have any automation tips? Let me know - I’d love to hear more!
Related
I recently wrote a blog post about using GitHub Actions to automatically add a GitHub Issue to a GitHub project (Beta) when the issue is opened. I received a question from my colleague and maintainer of the promitor and KEDA Open Source (OSS) Projects, Tom Kerkhove on doing the same with a user-owned GitHub repository, rather than organisation-owned.
Blog
I’ve been following the GitHub Projects beta for a while now, and have been fortunate to be accepted as an early adopter. I’m a big fan of the direction, and the flexibility. One of the limitations I’ve noticed is that there’s currently no built-in way to automatically add an issue to a project board. It’s on the backlog, but not yet available. Fortunately, GitHub Actions has us sorted. I’ll walk you through a sample I put together to do exactly that.
Blog
Chris is the blogger, podcaster, host and producer of his content platform CloudWithChris.com. He uses GitHub to manage, develop, build and deploy it. In this session, Chris explores how GitHub is more than just a Git repository, and how he uses it for his own work: GitHub Issues / Projects to plan the content (Blog & Podcast) backlog GitHub repositories to version control the website’s source code (and recently open sourced the theme) GitHub Codespaces to make changes to the site from any device GitHub actions to build/deploy the site, and publish podcast mp3 files
Talk