jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 09:57:42 -05:00
Code Issues Projects Releases Wiki Activity

Migrate users from ProjectNext to ProjectV2 GraphQL API (#28352)

Browse Source 
Co-authored-by: Lukasz Warchol <lukewar@github.com>
Co-authored-by: Sarah Edwards <skedwards88@github.com>
This commit is contained in:
Steve Guntrip
2022-06-23 17:37:05 +01:00
committed by GitHub
parent 154e2b7e93
commit 1b441fca04
6 changed files with 395 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
content/authentication/keeping-your-account-and-data-secure/authorizing-oauth-apps.md
View File

@@ -67,7 +67,8 @@ When you want to use an {% data variables.product.prodname_oauth_app %} that int
| Organizations and teams | Organization and teams access allows apps to access and manage organization and team membership. |
| Personal user data | User data includes information found in your user profile, like your name, e-mail address, and location. |
| Repositories | Repository information includes the names of contributors, the branches you've created, and the actual files within your repository. Apps can request access for either public or private repositories on a user-wide level. |
| Repository delete | Apps can request to delete repositories that you administer, but they won't have access to your code. |
| Repository delete | Apps can request to delete repositories that you administer, but they won't have access to your code. |{% ifversion projects-oauth-scope %}
| Projects | Access to user and organization projects (beta). Apps can request either read/write or read only access. |{% endif %}
## Requesting updated permissions

4
content/developers/apps/building-oauth-apps/scopes-for-oauth-apps.md
View File

@@ -63,7 +63,9 @@ Name | Description
**`user`** | Grants read/write access to profile info only. Note that this scope includes `user:email` and `user:follow`.
&emsp;`read:user`| Grants access to read a user's profile data.
&emsp;`user:email`| Grants read access to a user's email addresses.
&emsp;`user:follow`| Grants access to follow or unfollow other users.
&emsp;`user:follow`| Grants access to follow or unfollow other users.{% ifversion projects-oauth-scope %}
**`project`** | Grants read/write access to user and organization projects (beta).
&emsp;`read:project`| Grants read only access to user and organization projects (beta).{% endif %}
**`delete_repo`** | Grants access to delete adminable repositories.
**`write:discussion`** | Allows read and write access for team discussions.
&emsp;`read:discussion` | Allows read access for team discussions.

170
content/issues/trying-out-the-new-projects-experience/automating-projects.md
View File

@@ -15,6 +15,8 @@ topics:
{% data reusables.projects.projects-beta %}
{% data reusables.projects.graphql-deprecation %}
## Introduction
You can add automation to help manage your project. Projects (beta) includes built-in workflows that you can configure through the UI. Additionally, you can write custom workflows with the GraphQL API and {% data variables.product.prodname_actions %}.
@@ -89,23 +91,32 @@ jobs:
gh api graphql -f query='
query($org: String!, $number: Int!) {
organization(login: $org){
projectNext(number: $number) {
projectV2(number: $number) {
id
fields(first:20) {
nodes {
id
name
settings
... 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.projectNext.id' project_data.json) >> $GITHUB_ENV
echo 'DATE_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $GITHUB_ENV
echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV
echo 'TODO_OPTION_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Status") |.settings | fromjson.options[] | select(.name=="Todo") |.id' project_data.json) >> $GITHUB_ENV
echo 'PROJECT_ID='$(jq '.data.organization.projectV2.id' project_data.json) >> $GITHUB_ENV
echo 'DATE_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $GITHUB_ENV
echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV
echo 'TODO_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .options[] | select(.name=="Todo") |.id' project_data.json) >> $GITHUB_ENV
- name: Add PR to project
env:
@@ -114,14 +125,14 @@ jobs:
run: |
item_id="$( gh api graphql -f query='
mutation($project:ID!, $pr:ID!) {
addProjectNextItem(input: {projectId: $project, contentId: $pr}) {
projectNextItem {
addProjectV2ItemById(input: {projectId: $project, contentId: $pr}) {
item {
id
}
}
}' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectNextItem.projectNextItem.id')"
echo 'ITEM_ID='$item_id >> $GITHUB_ENV
}' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectV2ItemById.item.id')"
echo 'ITEM_ID='$item_id >> $GITHUB_ENV
- name: Get date
run: echo "DATE=$(date +"%Y-%m-%d")" >> $GITHUB_ENV
@@ -137,34 +148,39 @@ jobs:
$status_field: ID!
$status_value: String!
$date_field: ID!
$date_value: String!
$date_value: Date!
) {
set_status: updateProjectNextItemField(input: {
set_status: updateProjectV2ItemFieldValue(input: {
projectId: $project
itemId: $item
fieldId: $status_field
value: $status_value
value: {
singleSelectOptionId: $status_value
}
}) {
projectNextItem {
projectV2Item {
id
}
}
set_date_posted: updateProjectNextItemField(input: {
set_date_posted: updateProjectV2ItemFieldValue(input: {
projectId: $project
itemId: $item
fieldId: $date_field
value: $date_value
value: {
date: $date_value
}
}) {
projectNextItem {
projectV2Item {
id
}
}
}' -f project=$PROJECT_ID -f item=$ITEM_ID -f status_field=$STATUS_FIELD_ID -f status_value={% raw %}${{ env.TODO_OPTION_ID }}{% endraw %} -f date_field=$DATE_FIELD_ID -f date_value=$DATE --silent
```
### Example workflow authenticating with a personal access token
1. Create a personal access token with `org:write` scope. For more information, see "[Creating a personal access token](/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
1. Create a personal access token with the `project` and `repo` scopes. For more information, see "[Creating a personal access token](/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
2. Save the personal access token as a secret in your repository or organization.
3. In the following workflow, replace `YOUR_TOKEN` with the name of the secret. Replace `YOUR_ORGANIZATION` with the name of your organization. For example, `octo-org`. Replace `YOUR_PROJECT_NUMBER` with your project number. To find the project number, look at the project URL. For example, `https://github.com/orgs/octo-org/projects/5` has a project number of 5.
@@ -187,23 +203,32 @@ jobs:
gh api graphql -f query='
query($org: String!, $number: Int!) {
organization(login: $org){
projectNext(number: $number) {
projectV2(number: $number) {
id
fields(first:20) {
nodes {
id
name
settings
... 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.projectNext.id' project_data.json) >> $GITHUB_ENV
echo 'DATE_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $GITHUB_ENV
echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV
echo 'TODO_OPTION_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Status") |.settings | fromjson.options[] | select(.name=="Todo") |.id' project_data.json) >> $GITHUB_ENV
echo 'PROJECT_ID='$(jq '.data.organization.projectV2.id' project_data.json) >> $GITHUB_ENV
echo 'DATE_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $GITHUB_ENV
echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV
echo 'TODO_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .options[] | select(.name=="Todo") |.id' project_data.json) >> $GITHUB_ENV
- name: Add PR to project
env:
@@ -212,14 +237,14 @@ jobs:
run: |
item_id="$( gh api graphql -f query='
mutation($project:ID!, $pr:ID!) {
addProjectNextItem(input: {projectId: $project, contentId: $pr}) {
projectNextItem {
addProjectV2ItemById(input: {projectId: $project, contentId: $pr}) {
item {
id
}
}
}' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectNextItem.projectNextItem.id')"
echo 'ITEM_ID='$item_id >> $GITHUB_ENV
}' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectV2ItemById.item.id')"
echo 'ITEM_ID='$item_id >> $GITHUB_ENV
- name: Get date
run: echo "DATE=$(date +"%Y-%m-%d")" >> $GITHUB_ENV
@@ -235,25 +260,29 @@ jobs:
$status_field: ID!
$status_value: String!
$date_field: ID!
$date_value: String!
$date_value: Date!
) {
set_status: updateProjectNextItemField(input: {
set_status: updateProjectV2ItemFieldValue(input: {
projectId: $project
itemId: $item
fieldId: $status_field
value: $status_value
value: {
singleSelectOptionId: $status_value
}
}) {
projectNextItem {
projectV2Item {
id
}
}
set_date_posted: updateProjectNextItemField(input: {
set_date_posted: updateProjectV2ItemFieldValue(input: {
projectId: $project
itemId: $item
fieldId: $date_field
value: $date_value
value: {
date: $date_value
}
}) {
projectNextItem {
projectV2Item {
id
}
}
@@ -352,23 +381,34 @@ Replace <code>YOUR_PROJECT_NUMBER</code> with your project number. To find the p
gh api graphql -f query='
query($org: String!, $number: Int!) {
organization(login: $org){
projectNext(number: $number) {
projectV2(number: $number) {
id
fields(first:20) {
nodes {
id
name
settings
... on ProjectV2Field {
id
name
}
... on ProjectV2SingleSelectField {
id
name
options {
id
name
}
}
}
}
}
}
}' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json
}' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json
```
</td>
<td>
Uses <a href="https://cli.github.com/manual/">{% data variables.product.prodname_cli %}</a> to query the API for the ID of the project and for the ID, name, and settings for the first 20 fields in the project. The response is stored in a file called <code>project_data.json</code>.
<p>Uses <a href="https://cli.github.com/manual/">{% data variables.product.prodname_cli %}</a> to query the API for the ID of the project and return the name and ID of the first 20 fields in the project. <code>fields</code> returns a union and the query uses inline fragments (<code>... on</code>) to return information about any <code>ProjectV2Field</code> and <code>ProjectV2SingleSelectField</code> fields.</p>
<p>The response is stored in a file called <code>project_data.json</code>.</p>
</td>
</tr>
@@ -376,18 +416,18 @@ Uses <a href="https://cli.github.com/manual/">{% data variables.product.prodname
<td>
```yaml
echo 'PROJECT_ID='$(jq '.data.organization.projectNext.id' project_data.json) >> $GITHUB_ENV
echo 'DATE_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $GITHUB_ENV
echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV
echo 'TODO_OPTION_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Status") |.settings | fromjson.options[] | select(.name=="Todo") |.id' project_data.json) >> $GITHUB_ENV
echo 'PROJECT_ID='$(jq '.data.organization.projectV2.id' project_data.json) >> $GITHUB_ENV
echo 'DATE_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $GITHUB_ENV
echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV
echo 'TODO_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .options[] | select(.name=="Todo") |.id' project_data.json) >> $GITHUB_ENV
```
</td>
<td>
Parses the response from the API query and stores the relevant IDs as environment variables. Modify this to get the ID for different fields or options. For example:
<ul>
<li>To get the ID of a field called <code>Team</code>, add <code>echo 'TEAM_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Team") | .id' project_data.json) >> $GITHUB_ENV</code>.</li>
<li>To get the ID of an option called <code>Octoteam</code> for the <code>Team</code> field, add <code>echo 'OCTOTEAM_OPTION_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Team") |.settings | fromjson.options[] | select(.name=="Octoteam") |.id' project_data.json) >> $GITHUB_ENV</code></li>
<li>To get the ID of a field called <code>Team</code>, add <code>echo 'TEAM_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Team") | .id' project_data.json) >> $GITHUB_ENV</code>.</li>
<li>To get the ID of an option called <code>Octoteam</code> for the <code>Team</code> single select field, add <code>echo 'OCTOTEAM_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Team") |.options[] | select(.name=="Octoteam") |.id' project_data.json) >> $GITHUB_ENV</code></li>
</ul>
<strong>Note: </strong>This workflow assumes that you have a project with a single select field called "Status" that includes an option called "Todo" and a date field called "Date posted". You must modify this section to match the fields that are present in your table.
</td>
@@ -425,12 +465,12 @@ Sets environment variables for this step. <code>GITHUB_TOKEN</code> is described
```yaml
item_id="$( gh api graphql -f query='
mutation($project:ID!, $pr:ID!) {
addProjectNextItem(input: {projectId: $project, contentId: $pr}) {
projectNextItem {
addProjectV2ItemById(input: {projectId: $project, contentId: $pr}) {
item {
id
}
}
}' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectNextItem.projectNextItem.id')"
}' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectV2ItemById.item.id')"
```
</td>
@@ -500,25 +540,29 @@ gh api graphql -f query='
$status_field: ID!
$status_value: String!
$date_field: ID!
$date_value: String!
$date_value: Date!
) {
set_status: updateProjectNextItemField(input: {
set_status: updateProjectV2ItemFieldValue(input: {
projectId: $project
itemId: $item
fieldId: $status_field
value: $status_value
value: {
singleSelectOptionId: $status_value
}
}) {
projectNextItem {
projectV2Item {
id
}
}
set_date_posted: updateProjectNextItemField(input: {
set_date_posted: updateProjectV2ItemFieldValue(input: {
projectId: $project
itemId: $item
fieldId: $date_field
value: $date_value
value: {
date: $date_value
}
}) {
projectNextItem {
projectV2Item {
id
}
}

385
content/issues/trying-out-the-new-projects-experience/using-the-api-to-manage-projects.md
View File

@@ -11,6 +11,8 @@ topics:
- Projects
---
{% data reusables.projects.graphql-deprecation %}
This article demonstrates how to use the GraphQL API to manage a project. For more information about how to use the API in a {% data variables.product.prodname_actions %} workflow, see "[Automating projects (beta)](/issues/trying-out-the-new-projects-experience/automating-projects)." For a full list of the available data types, see "[Reference](/graphql/reference)."
{% data reusables.projects.projects-beta %}
@@ -19,7 +21,7 @@ This article demonstrates how to use the GraphQL API to manage a project. For mo
{% curl %}
In all of the following cURL examples, replace `TOKEN` with a token that has the `read:org` scope (for queries) or `write:org` scope (for queries and mutations). The token can be a personal access token for a user or an installation access token for a {% data variables.product.prodname_github_app %}. For more information about creating a personal access token, see "[Creating a personal access token](/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token)." For more information about creating an installation access token for a {% data variables.product.prodname_github_app %}, see "[Authenticating with {% data variables.product.prodname_github_apps %}](/developers/apps/building-github-apps/authenticating-with-github-apps#authenticating-as-a-github-app)."
In all of the following cURL examples, replace `TOKEN` with a token that has the `read:project` scope (for queries) or `project` scope (for queries and mutations). The token can be a personal access token for a user or an installation access token for a {% data variables.product.prodname_github_app %}. For more information about creating a personal access token, see "[Creating a personal access token](/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token)." For more information about creating an installation access token for a {% data variables.product.prodname_github_app %}, see "[Authenticating with {% data variables.product.prodname_github_apps %}](/developers/apps/building-github-apps/authenticating-with-github-apps#authenticating-as-a-github-app)."
{% endcurl %}
@@ -27,7 +29,7 @@ In all of the following cURL examples, replace `TOKEN` with a token that has the
{% data reusables.cli.cli-learn-more %}
Before running {% data variables.product.prodname_cli %} commands, you must authenticate by running `gh auth login --scopes "write:org"`. If you only need to read, but not edit, projects, you can omit the `--scopes` argument. For more information on command line authentication, see "[gh auth login](https://cli.github.com/manual/gh_auth_login)."
Before running {% data variables.product.prodname_cli %} commands, you must authenticate by running `gh auth login --scopes "project"`. If you only need to read, but not edit, projects, you can provide the `read:project` scope instead of `project`. For more information on command line authentication, see "[gh auth login](https://cli.github.com/manual/gh_auth_login)."
{% endcli %}
@@ -43,7 +45,7 @@ my_num=5
gh api graphql -f query='
query($organization: String! $number: Int!){
organization(login: $organization){
projectNext(number: $number) {
projectV2(number: $number) {
id
}
}
@@ -69,7 +71,7 @@ You can find the node ID of an organization project if you know the organization
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"query{organization(login: \"<em>ORGANIZATION</em>\") {projectNext(number: <em>NUMBER</em>){id}}}"}'
--data '{"query":"query{organization(login: \"<em>ORGANIZATION</em>\") {projectV2(number: <em>NUMBER</em>){id}}}"}'
```
{% endcurl %}
@@ -78,7 +80,7 @@ curl --request POST \
gh api graphql -f query='
query{
organization(login: "<em>ORGANIZATION</em>"){
projectNext(number: <em>NUMBER</em>) {
projectV2(number: <em>NUMBER</em>) {
id
}
}
@@ -93,7 +95,7 @@ You can also find the node ID of all projects in your organization. The followin
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"{organization(login: \"<em>ORGANIZATION</em>\") {projectsNext(first: 20) {nodes {id title}}}}"}'
--data '{"query":"{organization(login: \"<em>ORGANIZATION</em>\") {projectsV2(first: 20) {nodes {id title}}}}"}'
```
{% endcurl %}
@@ -102,7 +104,7 @@ curl --request POST \
gh api graphql -f query='
query{
organization(login: "<em>ORGANIZATION</em>") {
projectsNext(first: 20) {
projectsV2(first: 20) {
nodes {
id
title
@@ -113,7 +115,7 @@ gh api graphql -f query='
```
{% endcli %}
### Finding the node ID of a user project
### Finding the node ID of a user project
To update your project through the API, you will need to know the node ID of the project.
@@ -124,7 +126,7 @@ You can find the node ID of a user project if you know the project number. Repla
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"query{user(login: \"<em>USER</em>\") {projectNext(number: <em>NUMBER</em>){id}}}"}'
--data '{"query":"query{user(login: \"<em>USER</em>\") {projectV2(number: <em>NUMBER</em>){id}}}"}'
```
{% endcurl %}
@@ -133,7 +135,7 @@ curl --request POST \
gh api graphql -f query='
query{
user(login: "<em>USER</em>"){
projectNext(number: <em>NUMBER</em>) {
projectV2(number: <em>NUMBER</em>) {
id
}
}
@@ -148,7 +150,7 @@ You can also find the node ID for all of your projects. The following example wi
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"{user(login: \"<em>USER</em>\") {projectsNext(first: 20) {nodes {id title}}}}"}'
--data '{"query":"{user(login: \"<em>USER</em>\") {projectsV2(first: 20) {nodes {id title}}}}"}'
```
{% endcurl %}
@@ -157,7 +159,7 @@ curl --request POST \
gh api graphql -f query='
query{
user(login: "<em>USER</em>") {
projectsNext(first: 20) {
projectsV2(first: 20) {
nodes {
id
title
@@ -172,14 +174,14 @@ gh api graphql -f query='
To update the value of a field, you will need to know the node ID of the field. Additionally, you will need to know the ID of the options for single select fields and the ID of the iterations for iteration fields.
The following example will return the ID, name, and settings for the first 20 fields in a project. Replace `PROJECT_ID` with the node ID of your project.
The following example will return the ID, name, settings, and configuration for the first 20 fields in a project. Replace `PROJECT_ID` with the node ID of your project.
{% curl %}
```shell
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"query{node(id: \"<em>PROJECT_ID</em>\") {... on ProjectNext {fields(first: 20) {nodes {id name settings}}}}}"}'
--data '{"query":"query{ node(id: \"<em>PROJECT_ID</em>\") { ... on ProjectV2 { fields(first: 20) { nodes { ... on ProjectV2Field { id name } ... on ProjectV2IterationField { id name configuration { iterations { startDate id }}} ... on ProjectV2SingleSelectField { id name options { id name }}}}}}}"}'
```
{% endcurl %}
@@ -187,18 +189,37 @@ curl --request POST \
```shell
gh api graphql -f query='
query{
node(id: "<em>PROJECT_ID</em>") {
... on ProjectNext {
fields(first: 20) {
nodes {
node(id: "<em>PROJECT_ID</em>") {
... on ProjectV2 {
fields(first: 20) {
nodes {
... on ProjectV2Field {
id
name
settings
}
... on ProjectV2IterationField {
id
name
configuration {
iterations {
startDate
id
}
}
}
... on ProjectV2SingleSelectField {
id
name
options {
id
name
}
}
}
}
}
}'
}
}'
```
{% endcli %}
@@ -211,24 +232,42 @@ The response will look similar to the following example:
"fields": {
"nodes": [
{
"id": "MDE2OlByb2plY3ROZXh0RmllbGQxMzE1OQ==",
"name": "Title",
"settings": "null"
"id": "PVTF_lADOANN5s84ACbL0zgBZrZY",
"name": "Title"
},
{
"id": "MDE2OlByb2plY3ROZXh0RmllbGQxMzE2MA==",
"name": "Assignees",
"settings": "null"
"id": "PVTF_lADOANN5s84ACbL0zgBZrZc",
"name": "Assignees"
},
{
"id": "MDE2OlByb2plY3ROZXh0RmllbGQxMzE2MQ==",
"id": "PVTSSF_lADOANN5s84ACbL0zgBZrZg",
"name": "Status",
"settings": "{\"options\":[{\"id\":\"f75ad846\",\"name\":\"Todo\",\"name_html\":\"Todo\"},{\"id\":\"47fc9ee4\",\"name\":\"In Progress\",\"name_html\":\"In Progress\"},{\"id\":\"98236657\",\"name\":\"Done\",\"name_html\":\"Done\"}]}"
"options": [
{
"id": "f75ad846",
"name": "Todo"
},
{
"id": "47fc9ee4",
"name": "In Progress"
},
{
"id": "98236657",
"name": "Done"
}
]
},
{
"id": "MDE2OlByb2plY3ROZXh0RmllbGQ3NTEwNw==",
"id": "PVTIF_lADOANN5s84ACbL0zgBah28",
"name": "Iteration",
"settings": "{\"configuration\":{\"duration\":7,\"start_day\":5,\"iterations\":[{\"id\":\"c4d8e84d\",\"title\":\"Iteration 2\",\"duration\":7,\"start_date\":\"2021-10-08\",\"title_html\":\"Iteration 2\"},{\"id\":\"fafa9c9f\",\"title\":\"Iteration 3\",\"duration\":7,\"start_date\":\"2021-10-15\",\"title_html\":\"Iteration 3\"}],\"completed_iterations\":[{\"id\":\"fa62c118\",\"title\":\"Iteration 1\",\"duration\":7,\"start_date\":\"2021-10-01\",\"title_html\":\"Iteration 1\"}]}}"
"configuration": {
"iterations": [
{
"startDate": "2022-05-29",
"id": "cfc16e4d"
}
]
}
}
]
}
@@ -237,26 +276,86 @@ The response will look similar to the following example:
}
```
Each field has an ID. Additionally, single select fields and iteration fields have a `settings` value. In the single select settings, you can find the ID of each option for the single select. In the iteration settings, you can find the duration of the iteration, the start day of the iteration (from 1 for Monday to 7 for Sunday), the list of incomplete iterations, and the list of completed iterations. For each iteration in the lists of iterations, you can find the ID, title, duration, and start date of the iteration.
Each field has an ID and name. Single select fields are returned as a `ProjectV2SingleSelectField` object and have an `options` field where you can find the ID of each option for the single select. Iteration fields are returned as a `ProjectV2IterationField` object and have a `configuration` field which includes an `iterations` field containing the ID and information about each iteration.
### Finding information about items in a project
You can query the API to find information about items in your project.
{% note %}
**Note**: The API will not return information about draft issues.
{% endnote %}
The following example will return the title and ID for the first 20 items in a project. For each item, it will also return the value and name for the first 8 fields in the project. If the item is an issue or pull request, it will return the login of the first 10 assignees. Replace `PROJECT_ID` with the node ID of your project.
If you just need the name and ID of a field, and do not need information about iterations or a single select field's options, you can make use of the `ProjectV2FieldCommon` object.
{% curl %}
```shell
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"query{node(id: \"<em>PROJECT_ID</em>\") {... on ProjectNext {items(first: 20) {nodes{title id fieldValues(first: 8) {nodes{value projectField{name}}} content{...on Issue {assignees(first: 10) {nodes{login}}} ...on PullRequest {assignees(first: 10) {nodes{login}}}}}}}}}"}'
--data '{"query":"query{ node(id: \"<em>PROJECT_ID</em>\") { ... on ProjectV2 { fields(first: 20) { nodes { ... on ProjectV2FieldCommon { id name }}}}}}"}'
```
{% endcurl %}
{% cli %}
```shell
gh api graphql -f query='
query{
node(id: "<em>PROJECT_ID</em>") {
... on ProjectV2 {
fields(first: 20) {
nodes {
... on ProjectV2FieldCommon {
id
name
}
}
}
}
}
}
```
{% endcli %}
The response when using the `ProjectV2FieldCommon` object will look similar to the following example:
```json
{
"data": {
"node": {
"fields": {
"nodes": [
{
"__typename": "ProjectV2Field",
"id": "PVTF_lADOANN5s84ACbL0zgBZrZY",
"name": "Title"
},
{
"__typename": "ProjectV2Field",
"id": "PVTF_lADOANN5s84ACbL0zgBZrZc",
"name": "Assignees"
},
{
"__typename": "ProjectV2SingleSelectField",
"id": "PVTSSF_lADOANN5s84ACbL0zgBZrZg",
"name": "Status"
},
{
"__typename": "ProjectV2IterationField",
"id": "PVTIF_lADOANN5s84ACbL0zgBah28",
"name": "Iteration"
}
]
}
}
}
}
```
### Finding information about items in a project
You can query the API to find information about items in your project.
The following example will return the first 20 issues, pull requests, and draft issues in a project. For issues and pull requests, it will also return title and the first 10 assignees. For draft issue, it will return the title and body. The example will also return the field name and value for any text, date, or single select fields in the first 8 fields of the project. Replace `PROJECT_ID` with the node ID of your project.
{% curl %}
```shell
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"query{ node(id: \"<em>PROJECT_ID</em>\") { ... on ProjectV2 { items(first: 20) { nodes{ id fieldValues(first: 8) { nodes{ ... on ProjectV2ItemFieldTextValue { text field { ... on ProjectV2FieldCommon { name }}} ... on ProjectV2ItemFieldDateValue { date field { ... on ProjectV2FieldCommon { name } } } ... on ProjectV2ItemFieldSingleSelectValue { name field { ... on ProjectV2FieldCommon { name }}}}} content{ ... on DraftIssue { title body } ...on Issue { title assignees(first: 10) { nodes{ login }}} ...on PullRequest { title assignees(first: 10) { nodes{ login }}}}}}}}}"}'
```
{% endcurl %}
@@ -265,31 +364,57 @@ curl --request POST \
gh api graphql -f query='
query{
node(id: "<em>PROJECT_ID</em>") {
... on ProjectNext {
items(first: 20) {
nodes{
title
id
fieldValues(first: 8) {
nodes{
value
projectField{
name
}
... on ProjectV2 {
items(first: 20) {
nodes{
id
fieldValues(first: 8) {
nodes{
... on ProjectV2ItemFieldTextValue {
text
field {
... on ProjectV2FieldCommon {
name
}
}
}
... on ProjectV2ItemFieldDateValue {
date
field {
... on ProjectV2FieldCommon {
name
}
}
}
... on ProjectV2ItemFieldSingleSelectValue {
name
field {
... on ProjectV2FieldCommon {
name
}
}
}
}
}
}
content{
...on Issue {
assignees(first: 10) {
nodes{
login
content{
... on DraftIssue {
title
body
}
...on Issue {
title
assignees(first: 10) {
nodes{
login
}
}
}
}
...on PullRequest {
assignees(first: 10) {
nodes{
login
...on PullRequest {
title
assignees(first: 10) {
nodes{
login
}
}
}
}
@@ -297,29 +422,19 @@ gh api graphql -f query='
}
}
}
}
}'
}'
```
{% endcli %}
A project may contain items that a user does not have permission to view. In this case, the response will include a redacted item.
A project may contain items that a user does not have permission to view. In this case, the item type will be returned as `REDACTED`.
```shell
{
"node": {
"title": "You can't see this item",
...
}
}
```
## Updating projects
## Updating projects
Use mutations to update projects. For more information, see "[About mutations]({% ifversion ghec %}/free-pro-team@latest{% endif %}/graphql/guides/forming-calls-with-graphql#about-mutations)."
{% note %}
**Note:** You cannot add and update an item in the same call. You must use `addProjectNextItem` to add the item and then use `updateProjectNextItemField` to update the item.
**Note:** You cannot add and update an item in the same call. You must use `addProjectV2ItemById` to add the item and then use `updateProjectV2ItemFieldValue` to update the item.
{% endnote %}
@@ -332,7 +447,7 @@ The following example will add an issue or pull request to your project. Replace
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"mutation {addProjectNextItem(input: {projectId: \"<em>PROJECT_ID</em>\" contentId: \"<em>CONTENT_ID</em>\"}) {projectNextItem {id}}}"}'
--data '{"query":"mutation {addProjectV2ItemById(input: {projectId: \"<em>PROJECT_ID</em>\" contentId: \"<em>CONTENT_ID</em>\"}) {item {id}}}"}'
```
{% endcurl %}
@@ -340,8 +455,8 @@ curl --request POST \
```shell
gh api graphql -f query='
mutation {
addProjectNextItem(input: {projectId: "<em>PROJECT_ID</em>" contentId: "<em>CONTENT_ID</em>"}) {
projectNextItem {
addProjectV2ItemById(input: {projectId: "<em>PROJECT_ID</em>" contentId: "<em>CONTENT_ID</em>"}) {
item {
id
}
}
@@ -354,9 +469,9 @@ The response will contain the node ID of the newly created item.
```json
{
"data": {
"addProjectNextItem": {
"projectNextItem": {
"id": "MDE1OlByb2plY3ROZXh0SXRlbTM0MjEz"
"addProjectV2ItemById": {
"item": {
"id": "PVTI_lADOANN5s84ACbL0zgBVd94"
}
}
}
@@ -365,16 +480,16 @@ The response will contain the node ID of the newly created item.
If you try to add an item that already exists, the existing item ID is returned instead.
### Updating a project's settings
### Adding a draft issue to a project
The following example will update your project's settings. Replace `PROJECT_ID` with the node ID of your project. Set `public` to `true` to make your project public on {% data variables.product.product_name %}. Modify `description` to make changes to your project's README.
The following example will add a draft issue to your project. Replace `PROJECT_ID` with the node ID of your project. Replace `TITLE` and `BODY` with the content you want for the new draft issue.
{% curl %}
```shell
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"mutation { updateProjectNext(input: { projectId: \"<em>PROJECT_ID</em>\", title: \"Project title\", public: false, description: \"# Project README\n\nA long description\", shortDescription: \"A short description\"}) { projectNext { id, title, description, shortDescription }}}"}'
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"mutation {addProjectV2DraftIssue(input: {projectId: "<em>PROJECT_ID</em>" title: "<em>TITLE</em>" body: "<em>BODY</em>"}) {item {id}}}"}'
```
{% endcurl %}
@@ -382,19 +497,59 @@ curl --request POST \
```shell
gh api graphql -f query='
mutation {
updateProjectNext(
addProjectV2DraftIssue(input: {projectId: "<em>PROJECT_ID</em>" title: "<em>TITLE</em>" body: "<em>BODY</em>"}) {
item {
id
}
}
}'
```
{% endcli %}
The response will contain the node ID of the newly created draft issue.
```json
{
"data": {
"addProjectV2ItemById": {
"item": {
"id": "PVTI_lADOANN5s84ACbL0zgBbxFc"
}
}
}
}
```
### Updating a project's settings
The following example will update your project's settings. Replace `PROJECT_ID` with the node ID of your project. Set `public` to `true` to make your project public on {% data variables.product.product_name %}. Modify `readme` to make changes to your project's README.
{% curl %}
```shell
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"mutation { updateProjectV2(input: { projectId: \"<em>PROJECT_ID</em>\", title: \"Project title\", public: false, readme: \"# Project README\n\nA long description\", shortDescription: \"A short description\"}) { projectV2 { id, title, readme, shortDescription }}}"}'
```
{% endcurl %}
{% cli %}
```shell
gh api graphql -f query='
mutation {
updateProjectV2(
input: {
projectId: "<em>PROJECT_ID</em>",
title: "Project title",
public: false,
description: "# Project README\n\nA long description",
readme: "# Project README\n\nA long description",
shortDescription: "A short description"
}
) {
projectNext {
projectV2 {
id
title
description
readme
shortDescription
}
}
@@ -402,16 +557,16 @@ gh api graphql -f query='
```
{% endcli %}
### Updating a custom text, number, or date field
### Updating a custom text, number, or date field
The following example will update the value of a date field for an item. Replace `PROJECT_ID` with the node ID of your project. Replace `ITEM_ID` with the node ID of the item you want to update. Replace `FIELD_ID` with the ID of the field that you want to update.
The following example will update the value of a text field for an item. Replace `PROJECT_ID` with the node ID of your project. Replace `ITEM_ID` with the node ID of the item you want to update. Replace `FIELD_ID` with the ID of the field that you want to update.
{% curl %}
```shell
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"mutation {updateProjectNextItemField(input: {projectId: \"<em>PROJECT_ID</em>\" itemId: \"<em>ITEM_ID</em>\" fieldId: \"<em>FIELD_ID</em>\" value: \"2021-5-11\"}) {projectNextItem {id}}}"}'
--data '{"query":"mutation {updateProjectV2ItemFieldValue( input: { projectId: "<em>PROJECT_ID</em>" itemId: "<em>ITEM_ID</em>" fieldId: "<em>FIELD_ID</em>" value: { text: "Updated text" }}) { projectV2Item { id }}}"}'
```
{% endcurl %}
@@ -419,15 +574,17 @@ curl --request POST \
```shell
gh api graphql -f query='
mutation {
updateProjectNextItemField(
updateProjectV2ItemFieldValue(
input: {
projectId: "<em>PROJECT_ID</em>"
itemId: "<em>ITEM_ID</em>"
fieldId: "<em>FIELD_ID</em>"
value: "2021-5-11"
value: {
text: "Updated text"
}
}
) {
projectNextItem {
projectV2Item {
id
}
}
@@ -437,7 +594,7 @@ gh api graphql -f query='
{% note %}
**Note:** You cannot use `updateProjectNextItemField` to change `Assignees`, `Labels`, `Milestone`, or `Repository` because these fields are properties of pull requests and issues, not of project items. Instead, you must use the [addAssigneesToAssignable]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#addassigneestoassignable), [removeAssigneesFromAssignable]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#removeassigneesfromassignable), [addLabelsToLabelable]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#addlabelstolabelable), [removeLabelsFromLabelable]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#removelabelsfromlabelable), [updateIssue]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#updateissue), [updatePullRequest]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#updatepullrequest), or [transferIssue]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#transferissue) mutations.
**Note:** You cannot use `updateProjectV2ItemFieldValue` to change `Assignees`, `Labels`, `Milestone`, or `Repository` because these fields are properties of pull requests and issues, not of project items. Instead, you must use the [addAssigneesToAssignable]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#addassigneestoassignable), [removeAssigneesFromAssignable]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#removeassigneesfromassignable), [addLabelsToLabelable]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#addlabelstolabelable), [removeLabelsFromLabelable]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#removelabelsfromlabelable), [updateIssue]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#updateissue), [updatePullRequest]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#updatepullrequest), or [transferIssue]({% ifversion ghec%}/free-pro-team@latest{% endif %}/graphql/reference/mutations#transferissue) mutations.
{% endnote %}
@@ -455,7 +612,7 @@ The following example will update the value of a single select field for an item
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"mutation {updateProjectNextItemField(input: {projectId: \"<em>PROJECT_ID</em>\" itemId: \"<em>ITEM_ID</em>\" fieldId: \"<em>FIELD_ID</em>\" value: \"<em>OPTION_ID</em>\"}) {projectNextItem {id}}}"}'
--data '{"query":"mutation {updateProjectV2ItemFieldValue( input: { projectId: "<em>PROJECT_ID</em>" itemId: "<em>ITEM_ID</em>" fieldId: "<em>FIELD_ID</em>" value: { singleSelectOptionId: "<em>OPTION_ID</em>" }}) { projectV2Item { id }}}"}'
```
{% endcurl %}
@@ -463,15 +620,17 @@ curl --request POST \
```shell
gh api graphql -f query='
mutation {
updateProjectNextItemField(
updateProjectV2ItemFieldValue(
input: {
projectId: "<em>PROJECT_ID</em>"
itemId: "<em>ITEM_ID</em>"
fieldId: "<em>FIELD_ID</em>"
value: "<em>OPTION_ID</em>"
value: {
singleSelectOptionId: "<em>OPTION_ID</em>"
}
}
) {
projectNextItem {
projectV2Item {
id
}
}
@@ -486,14 +645,14 @@ The following example will update the value of an iteration field for an item.
- `PROJECT_ID` - Replace this with the node ID of your project.
- `ITEM_ID` - Replace this with the node ID of the item you want to update.
- `FIELD_ID` - Replace this with the ID of the iteration field that you want to update.
- `ITERATION_ID` - Replace this with the ID of the desired iteration. This can be either an active iteration (from the `iterations` array) or a completed iteration (from the `completed_iterations` array).
- `ITERATION_ID` - Replace this with the ID of the desired iteration. This can be either an active or completed iteration.
{% curl %}
```shell
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"mutation {updateProjectNextItemField(input: {projectId: \"<em>PROJECT_ID</em>\" itemId: \"<em>ITEM_ID</em>\" fieldId: \"<em>FIELD_ID</em>\" value: \"<em>ITERATION_ID</em>\"}) {projectNextItem {id}}}"}'
--data '{"query":"mutation {updateProjectV2ItemFieldValue( input: { projectId: "<em>PROJECT_ID</em>" itemId: "<em>ITEM_ID</em>" fieldId: "<em>FIELD_ID</em>" value: { singleSelectOptionId: "<em>OPTION_ID</em>" }}) { projectV2Item { id }}}"}'
```
{% endcurl %}
@@ -501,15 +660,17 @@ curl --request POST \
```shell
gh api graphql -f query='
mutation {
updateProjectNextItemField(
updateProjectV2ItemFieldValue(
input: {
projectId: "<em>PROJECT_ID</em>"
itemId: "<em>ITEM_ID</em>"
fieldId: "<em>FIELD_ID</em>"
value: "<em>ITERATION_ID</em>"
value: {
iterationId: "<em>ITERATION_ID</em>"
}
}
) {
projectNextItem {
projectV2Item {
id
}
}
@@ -526,7 +687,7 @@ The following example will delete an item from a project. Replace `PROJECT_ID` w
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <em>TOKEN</em>' \
--data '{"query":"mutation {deleteProjectNextItem(input: {projectId: \"<em>PROJECT_ID</em>\" itemId: \"<em>ITEM_ID</em>\"}) {deletedItemId}}"}'
--data '{"query":"mutation {deleteProjectV2Item(input: {projectId: \"<em>PROJECT_ID</em>\" itemId: \"<em>ITEM_ID</em>\"}) {deletedItemId}}"}'
```
{% endcurl %}
@@ -534,7 +695,7 @@ curl --request POST \
```shell
gh api graphql -f query='
mutation {
deleteProjectNextItem(
deleteProjectV2Item(
input: {
projectId: "<em>PROJECT_ID</em>"
itemId: "<em>ITEM_ID</em>"

5
data/features/projects-oauth-scope.yml Normal file
View File

@@ -0,0 +1,5 @@
# Issue 7302
# ProjectV2 GraphQL API
versions:
fpt: '*'
ghec: '*'

5
data/reusables/projects/graphql-deprecation.md Normal file
View File

@@ -0,0 +1,5 @@
{% note %}
**Note:** We deprecated the `ProjectNext` GraphQL API on **2022-06-20**, and we will remove the `ProjectNext` GraphQL API on **2022-10-01**. For more information on migrating to the new `ProjectV2` GraphQL API, please see "[Projects GraphQL API now generally available](https://github.blog/changelog/)" in {% data variables.product.prodname_blog %}.
{% endnote %}