Skip to content

github-projects.md

Latest commit

 

History

History
213 lines (166 loc) · 5.82 KB

github-projects.md

File metadata and controls

213 lines (166 loc) · 5.82 KB

GitHub Projects Configuration

This document describes the GitHub Projects V2 setup for the Langstar repository.

Project Overview

Project Name: langstar Project Number: 4 Project ID: PVT_kwHOAAImgs4BGe4B Description: A project for governing LangStar issues Visibility: Public URL: https://github.com/users/codekiln/projects/4

Authentication

To access GitHub Projects V2 via the API, use the GITHUB_PROJECT_PAT environment variable (defined in .devcontainer/.env). This PAT has the necessary permissions to read and modify project data. This is not available in a github actions setting; it's only available locally.

IMPORTANT disambiguation between github credentials for projects vs for the repo

This project uses two different github credential environment variables because it's not possible to combine fine grained personal access tokens (which are advisable for AI coding to scope down permissions) with a token that allows read/write to GitHub Projects, AFAICT. As a result, we have a GITHUB_PAT which is a fine-grained project access token and a GH_PROJECT_PAT / GITHUB_PROJECT_PAT which has ONLY the permissions to read and write projects.

Using the PAT with GitHub CLI

export GH_TOKEN=$GITHUB_PROJECT_PAT
gh api graphql -f query='...'

Project Fields

The langstar project includes the following fields:

Field Name Data Type Field ID Description
Title TITLE PVTF_lAHOAAImgs4BGe4Bzg3g-NI Issue/PR title
Assignees ASSIGNEES PVTF_lAHOAAImgs4BGe4Bzg3g-NM Who is working on this
Status SINGLE_SELECT PVTSSF_lAHOAAImgs4BGe4Bzg3g-NQ Current work status
Labels LABELS PVTF_lAHOAAImgs4BGe4Bzg3g-NU Issue labels
Linked pull requests LINKED_PULL_REQUESTS PVTF_lAHOAAImgs4BGe4Bzg3g-NY Associated PRs
Milestone MILESTONE PVTF_lAHOAAImgs4BGe4Bzg3g-Nc Release milestone
Repository REPOSITORY PVTF_lAHOAAImgs4BGe4Bzg3g-Ng Source repository
Reviewers REVIEWERS PVTF_lAHOAAImgs4BGe4Bzg3g-Nk PR reviewers
Parent issue PARENT_ISSUE PVTF_lAHOAAImgs4BGe4Bzg3g-No Parent issue link
Sub-issues progress SUB_ISSUES_PROGRESS PVTF_lAHOAAImgs4BGe4Bzg3g-Ns Child issue tracking

Status Field Configuration

The Status field is the primary workflow field with three states:

Status Name Option ID Description
Todo f75ad846 This item hasn't been started
In Progress 47fc9ee4 This is actively being worked on
Done 98236657 This has been completed

Status Workflow

Issues should follow this progression:

  1. Todo - New issues start here
  2. In Progress - Move here when work begins
  3. Done - Move here when work is complete

Querying Project Data

Get All Projects for User

gh api graphql -f query='
query {
  user(login: "codekiln") {
    projectsV2(first: 10) {
      nodes {
        id
        number
        title
        shortDescription
        url
      }
    }
  }
}'

Get Project Fields and Status Options

gh api graphql -f query='
query {
  node(id: "PVT_kwHOAAImgs4BGe4B") {
    ... on ProjectV2 {
      id
      number
      title
      fields(first: 20) {
        nodes {
          ... on ProjectV2SingleSelectField {
            id
            name
            options {
              id
              name
              description
            }
          }
        }
      }
    }
  }
}'

Get Issue Project Status

gh issue view <issue-number> --json projectItems

Example output:

{
  "projectItems": [
    {
      "status": {
        "optionId": "f75ad846",
        "name": "Todo"
      },
      "title": "langstar"
    }
  ]
}

Modifying Project Items

Add Issue to Project

gh api graphql -f query='
mutation {
  addProjectV2ItemById(input: {
    projectId: "PVT_kwHOAAImgs4BGe4B"
    contentId: "<issue-node-id>"
  }) {
    item {
      id
    }
  }
}'

Update Item Status

gh api graphql -f query='
mutation {
  updateProjectV2ItemFieldValue(input: {
    projectId: "PVT_kwHOAAImgs4BGe4B"
    itemId: "<item-id>"
    fieldId: "PVTSSF_lAHOAAImgs4BGe4Bzg3g-NQ"
    value: {
      singleSelectOptionId: "47fc9ee4"
    }
  }) {
    projectV2Item {
      id
    }
  }
}'

Integration with Development Workflow

The GitHub project integrates with the issue-driven development workflow described in github-workflow.md. Project status updates are managed manually or via the Claude Code skill.

Manual Status Updates

Use the update-github-issue-project-status Claude skill to manually update project status:

Use the update-github-issue-project-status skill to set issue #42 to "in_progress"

The skill supports:

  • Single or batch issue updates (comma-separated)
  • All three status values: "todo", "in_progress", "done"
  • Automatic project item creation if needed

Native Automation Research

See Issue #38 for ongoing research into native GitHub Projects V2 automations that could provide automatic status updates without custom code

Troubleshooting

PAT Permissions

If you encounter "Resource not accessible" errors, ensure the PAT has these scopes:

  • project - Read/write access to projects
  • repo - Access to repository issues and PRs

GraphQL Node IDs

GitHub uses global node IDs for GraphQL queries. To get an issue's node ID:

gh issue view <issue-number> --json id

Related Documentation