GraphQL queries and mutations
Resources
- Introduction to GraphQL, which I need every time I work with it
- GraphQL API docs for GitHub and GitLab
- GraphQL Explorer for GitHub and GitLab
GitHub projects, issues, and pull requests
Get UUID of a project board
Most users interact with their board via URL - GITHUB/orgs/ORGNAME/projects/NUMBER/ or GITHUB/users/USERNAME/projects/NUMBER/. Under the hood, each of them have a unique identifier to use with the API. This query takes the org/user name and board number, then returns the UUID only.
1
2
3
4
5
6
7
query getProjectV2Id($org: String!, $project: Int!) {
organization(login: $org) {
projectV2(number: $project) {
id
}
}
}
Count all items on a board
Returns the total number of non-archived items on a board - includes issues, pull requests, and notes.
1
2
3
4
5
6
7
8
9
query getTotalItemCount($org: String!, $project: Int!) {
organization(login: $org) {
projectV2(number: $project) {
items(first: 1) {
totalCount
}
}
}
}
List open pull requests in a repo
Pull requests have a lot more info associated with them than what’s returned by this query. (documentation)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
query listOpenPRs($repo: String!, $org: String!) {
repository(owner: $org, name: $repo) {
pullRequests(states: OPEN, first: 10) {
nodes {
id
title
url
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
List open issues in a repo
Issues have a lot more info associated with them than what’s returned by this query. (documentation)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
query listOpenIssues($repo: String!, $org: String!) {
repository(owner: $org, name: $repo) {
issues(states: OPEN, first: 10) {
nodes {
id
title
url
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
List all project cards associated to issues in a repo
This query returns the project cards associated with an issue in a repository. The relationship between issues and project boards is many-to-many, so an issue can be associated with multiple projects and a project can have multiple repositories in it. Much of this data is needed for other reports or to change the data with a mutation.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
query issuesInProject($org: String!, $repo: String!) {
organization(login: $org) {
repository(name: $repo) {
issues(first: 10) {
totalCount # total number of issues in that repo
nodes {
id # issue ID
number # issue number
title # issue title
projectItems(includeArchived: true, first: 10) {
edges {
node {
id # card ID
project {
title # project board title
id # project board ID
}
isArchived # whether the card is archived
status: fieldValueByName(name: "Status") {
... on ProjectV2ItemFieldSingleSelectValue {
name
}
} # custom field values, as many as needed
}
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
}
Add an issue or PR to a board
Use the id field from the issue or PR query above as the contentId variable. The projectId variable is the UUID for the project board.
1
2
3
4
5
mutation ($projectId: ID!, $contentId: ID!) {
addProjectV2ItemById(input: {projectId: $projectId, contentId: $contentId}) {
clientMutationId
}
}
Variables for issues
The contentId field is random, but starting with I_ denotes an issue and PR_ is a pull request.
1
2
3
4
5
6
7
{
"contentId": "I_kwDOENnY2c565dVz",
"org": "organization-name-or-user-name",
"project": 1,
"projectId": "PVT_kwDOAlIw4c4AAVtM",
"repo": "repo-name"
}
GitHub Enterprise admin stuff
Get enterprise ID
The enterprise ID is required for many queries and mutations. It is not the same as the enterprise slug, which is the URL-friendly name of the enterprise (e.g., my-enterprise in GITHUB/enterprises/my-enterprise).
1
2
3
4
5
query getEnterpriseId($slug: String!) {
enterprise(slug: $slug) {
id
}
}
Count organizations in an enterprise
Weirdly enough, it’s not easy for an enterprise admin to get a count of organizations in their enterprise. Many built-in reports and dashboards only show things the logged-in user can see, not the total. This gets a count of them all.
1
2
3
4
5
6
7
query countEnterpriseOrganizations($slug: String!) {
enterprise(slug: $slug) {
organizations{
totalCount
}
}
}
Get info about an organization
This query returns a little information about a specific organization and your relationship to it. (documentation for other info to query)
1
2
3
4
5
6
7
8
query getOrgInfo($org: String!) {
organization(login: $org) {
id
name
viewerIsAMember
viewerCanAdminister
}
}
List organizations in an enterprise
Same as above, but with a list of them all individually. The count here should match the total count from the query above. The id field is the UUID for it, stored in that orgId variable for other queries.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
query listEnterpriseOrganizations($slug: String!) {
enterprise(slug: $slug) {
organizations(first: 100, after: AFTER) {
edges {
node {
id
createdAt
login
email
viewerCanAdminister
viewerIsAMember
repositories {
totalCount
totalDiskUsage
}
}
cursor
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
Add enterprise owner to organization
This adds an enterprise owner to an organization role for a given enterprise, organization, and role.
1
2
3
4
5
6
7
8
9
10
11
mutation ($enterpriseId: ID!, $orgId: ID!, $orgRole: String!) {
updateEnterpriseOwnerOrganizationRole(
input: {
enterpriseId: $enterpriseId
organizationId: $orgId
organizationRole: $orgRole
}
) {
clientMutationId
}
}
Variables for enterprise admin
The enterpriseId and orgId fields seem random. O_ seems to be the convention for organizations. The orgRole field can be the name of any role a user may have within an organization.
1
2
3
4
5
6
7
{
"slug": "my-enterprise",
"enterpriseId": "MDEwOaoeuGVycHfpc2UxMTg=",
"org": "organization-name",
"orgId": "O_kgDOB5i9ew",
"orgRole": "owner"
}