In diesem Artikel wird veranschaulicht, wie du die GraphQL-API verwendest, um ein Projekt zu verwalten. Weitere Informationen zum Verwenden der API in einem GitHub Actions-Workflow findest du unter Automatisieren von Projects mithilfe von Aktionen. Eine vollständige Liste der verfügbaren Datentypen findest du unter Verweis.
Authentifizierung
Ersetze TOKEN
in allen folgenden curl
-Befehlsbeispielen durch ein Token, das den Bereich read:project
(für Abfragen) oder project
(für Abfragen und Mutationen) aufweisen. Das Token kann ein personal access token (classic) für einen Benutzer oder ein Installationszugriffstoken für eine GitHub App sein. Weitere Informationen zum Erstellen eines personal access token findest du unter Verwalten deiner persönlichen Zugriffstoken. Weitere Informationen zum Erstellen eines Installationszugriffstokens für eine GitHub App findest du unter Generieren eines Installationszugriffstokens für eine GitHub-App.
Bei Verwendung eines Installationszugriffstokens für eine GitHub Appbenötigen einige GraphQL-Mutationen zusätzliche Berechtigungen. Wenn Sie beispielsweise einen repositoryId
-Eingabeparameter angeben, ist bei Verwendung der createProjectV2
-Mutation auch die Contents
-Berechtigung für dieses Repository erforderlich, um das Projekt mit dem Ziel-Repository zu verknüpfen.
Weitere Informationen zur GitHub CLI findest du unter Informationen zur GitHub CLI.
Bevor du GitHub CLI-Befehle ausführen kannst, musst du dich authentifizieren, indem du gh auth login --scopes "project"
ausführst. Wenn du für Projekte nur Lese- aber keinen Schreibzugriff benötigst, kannst du den read:project
-Bereich anstelle von project
bereitstellen. Weitere Informationen zur Befehlszeilenauthentifizierung findest du unter gh auth login.
Verwenden von Variablen
In allen folgenden Beispielen kannst du Variablen verwenden, um deine Skripts zu vereinfachen. Verwende -F
zum Übergeben einer Variable, die eine Zahl, ein boolescher Wert oder NULL ist. Verwende für alle andere Variablen -f
. Beispiel:
my_org="octo-org"
my_num=5
gh api graphql -f query='
query($organization: String! $number: Int!){
organization(login: $organization){
projectV2(number: $number) {
id
}
}
}' -f organization=$my_org -F number=$my_num
Weitere Informationen findest du unter Erstellen von Aufrufen mit GraphQL.
Suchen nach Informationen zu Projekten
Verwende Abfragen, um Daten zu Projekten abzurufen. Weitere Informationen findest du unter Erstellen von Aufrufen mit GraphQL.
Suchen der Knoten-ID eines Organisationsprojekts
Um dein Projekt über die API zu aktualisieren, musst du die Knoten-ID des Projekts kennen.
Zum Suchen der Knoten-ID eines Organisationsprojekts benötigst du den Namen und die Projektnummer der Organisation. Ersetze ORGANIZATION
durch den Namen deiner Organisation. Beispiel: octo-org
. Ersetze NUMBER
durch die Projektnummer. Sieh dir die URL des Projekts an, um die Projektnummer zu finden. https://github.com/orgs/octo-org/projects/5
hat beispielsweise die Projektnummer 5.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"query{organization(login: \"ORGANIZATION\") {projectV2(number: NUMBER){id}}}"}'
gh api graphql -f query='
query{
organization(login: "ORGANIZATION"){
projectV2(number: NUMBER) {
id
}
}
}'
Du kannst auch nach den Knoten-IDs aller Projekte in deiner Organisation suchen. Im folgenden Beispiel werden die Knoten-IDs und Titel der ersten 20 Projekte in einer Organisation zurückgegeben. Ersetze ORGANIZATION
durch den Namen deiner Organisation. Beispiel: octo-org
.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"{organization(login: \"ORGANIZATION\") {projectsV2(first: 20) {nodes {id title}}}}"}'
gh api graphql -f query='
query{
organization(login: "ORGANIZATION") {
projectsV2(first: 20) {
nodes {
id
title
}
}
}
}'
Suchen der Knoten-ID eines Benutzerprojekts
Um dein Projekt über die API zu aktualisieren, musst du die Knoten-ID des Projekts kennen.
Zum Suchen der Knoten-ID eines Benutzerprojekts benötigst du die Projektnummer. Ersetze USER
durch deinen Benutzernamen. Beispiel: octocat
. Ersetze NUMBER
durch deine Projektnummer. Sieh dir die URL des Projekts an, um die Projektnummer zu finden. https://github.com/users/octocat/projects/5
hat beispielsweise die Projektnummer 5.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"query{user(login: \"USER\") {projectV2(number: NUMBER){id}}}"}'
gh api graphql -f query='
query{
user(login: "USER"){
projectV2(number: NUMBER) {
id
}
}
}'
Du kannst auch nach den Knoten-IDs für alle deine Projekte suchen. Im folgenden Beispiel werden die Knoten-IDs und Titel deiner ersten 20 Projekte zurückgegeben. Ersetze USER
durch deinen Benutzernamen. Beispiel: octocat
.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"{user(login: \"USER\") {projectsV2(first: 20) {nodes {id title}}}}"}'
gh api graphql -f query='
query{
user(login: "USER") {
projectsV2(first: 20) {
nodes {
id
title
}
}
}
}'
Suchen der Knoten-ID eines Felds
Um den Wert eines Felds zu aktualisieren, musst du die Knoten-ID des Felds kennen. Darüber hinaus musst du auch die ID der Optionen für einzelne Auswahlfelder und bei Iterationsfeldern auch die IDs der Iterationen kennen.
Im folgenden Beispiel werden die IDs, der Name, die Einstellungen und die Konfiguration für die ersten 20 Felder in einem Projekt zurückgegeben. Ersetze PROJECT_ID
durch die Knoten-ID deines Projekts.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"query{ node(id: \"PROJECT_ID\") { ... 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 }}}}}}}"}'
gh api graphql -f query='
query{
node(id: "PROJECT_ID") {
... 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
}
}
}
}
}
}
}'
Die Antwort entspricht etwa dem folgenden Beispiel:
{
"data": {
"node": {
"fields": {
"nodes": [
{
"id": "PVTF_lADOANN5s84ACbL0zgBZrZY",
"name": "Title"
},
{
"id": "PVTF_lADOANN5s84ACbL0zgBZrZc",
"name": "Assignees"
},
{
"id": "PVTSSF_lADOANN5s84ACbL0zgBZrZg",
"name": "Status",
"options": [
{
"id": "f75ad846",
"name": "Todo"
},
{
"id": "47fc9ee4",
"name": "In Progress"
},
{
"id": "98236657",
"name": "Done"
}
]
},
{
"id": "PVTIF_lADOANN5s84ACbL0zgBah28",
"name": "Iteration",
"configuration": {
"iterations": [
{
"startDate": "2022-05-29",
"id": "cfc16e4d"
}
]
}
}
]
}
}
}
}
Jedes Feld besitzt eine ID und einen Namen. Einzelne Auswahlfelder werden als ProjectV2SingleSelectField
-Objekt zurückgegeben und verfügen über ein options
-Feld, in dem die ID jeder Option für die einzelne Auswahl angegeben ist. Iterationsfelder werden als ProjectV2IterationField
-Objekt zurückgegeben und verfügen über ein configuration
-Feld, das wiederum ein iterations
-Feld enthält, das die ID und Informationen zu jeder Iteration enthält.
Wenn du nur den Namen und die ID eines Felds benötigst und keine Informationen zu Iterationen oder den Optionen eines einzelnen Auswahlfelds, kannst du das ProjectV2FieldCommon
-Objekt.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"query{ node(id: \"PROJECT_ID\") { ... on ProjectV2 { fields(first: 20) { nodes { ... on ProjectV2FieldCommon { id name }}}}}}"}'
gh api graphql -f query='
query{
node(id: "PROJECT_ID") {
... on ProjectV2 {
fields(first: 20) {
nodes {
... on ProjectV2FieldCommon {
id
name
}
}
}
}
}
}'
Die Antwort bei Verwendung des ProjectV2FieldCommon
-Objekts sieht in etwa wie das folgende Beispiel aus:
{
"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"
}
]
}
}
}
}
Suchen von Informationen zu Elementen in einem Projekt
Du kannst die API abfragen, um Informationen zu Elementen in deinem Projekt zu finden.
Im folgenden Beispiel werden die ersten 20 Issues, Pull Requests und Entwurfsissues in einem Projekt zurückgegeben. Bei Issues und Pull Requests werden auch Titel und die ersten 10 zugewiesenen Personen zurückgegeben. Bei Entwurfsissues wird der Titel und der Textkörper zurückgegeben. Im Beispiel wird auch der Feldname und der Wert für alle Text-, Datums- oder Einzelauswahlfelder in den ersten acht Feldern des Projekts zurückgegeben. Ersetze PROJECT_ID
durch die Knoten-ID deines Projekts.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"query{ node(id: \"PROJECT_ID\") { ... 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 }}}}}}}}}"}'
gh api graphql -f query='
query{
node(id: "PROJECT_ID") {
... 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
}
}
}
}
}
}
}
}
}'
Ein Projekt kann Elemente enthalten, für die Benutzer*innen nicht über die Berechtigung zum Anzeigen verfügen. In diesem Fall wird der Elementtyp als REDACTED
zurückgegeben.
Aktualisieren von Projekten
Du verwendest Mutationen, um Projekte zu aktualisieren. Weitere Informationen findest du unter Erstellen von Aufrufen mit GraphQL.
Hinweis: Du kannst ein Element nicht im selben Aufruf hinzufügen und aktualisieren. Du musst addProjectV2ItemById
verwenden, um das Element hinzuzufügen, und das Element anschließend mit updateProjectV2ItemFieldValue
aktualisieren.
Hinzufügen eines Elements zu einem Projekt
Im folgenden Beispiel wird deinem Projekt ein Issue oder Pull Request hinzugefügt. Ersetze PROJECT_ID
durch die Knoten-ID deines Projekts. Ersetze CONTENT_ID
durch die Knoten-ID des Issues oder Pull Requests, das bzw. den du hinzufügen möchtest.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"mutation {addProjectV2ItemById(input: {projectId: \"PROJECT_ID\" contentId: \"CONTENT_ID\"}) {item {id}}}"}'
gh api graphql -f query='
mutation {
addProjectV2ItemById(input: {projectId: "PROJECT_ID" contentId: "CONTENT_ID"}) {
item {
id
}
}
}'
Die Antwort enthält die Knoten-ID des neu erstellten Elements.
{
"data": {
"addProjectV2ItemById": {
"item": {
"id": "PVTI_lADOANN5s84ACbL0zgBVd94"
}
}
}
}
Wenn du versuchst, ein bereits vorhandenes Element hinzuzufügen, wird stattdessen die ID des vorhandenen Elements zurückgegeben.
Hinzufügen eines Entwurfsissues zu einem Projekt
Im folgenden Beispiel wird deinem Projekt ein Entwurfsissue hinzugefügt. Ersetze PROJECT_ID
durch die Knoten-ID deines Projekts. Ersetze TITLE
und BODY
durch den Inhalt, den du für das neue Entwurfsissue benötigst.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"mutation {addProjectV2DraftIssue(input: {projectId: \"PROJECT_ID\" title: \"TITLE\" body: \"BODY\"}) {projectItem {id}}}"}'
gh api graphql -f query='
mutation {
addProjectV2DraftIssue(input: {projectId: "PROJECT_ID" title: "TITLE" body: "BODY"}) {
projectItem {
id
}
}
}'
Die Antwort enthält die Knoten-ID des neu erstellten Entwurfsissues.
{
"data": {
"addProjectV2DraftIssue": {
"projectItem": {
"id": "PVTI_lADOANN5s84ACbL0zgBbxFc"
}
}
}
}
Aktualisieren der Einstellungen eines Projekts
Im folgenden Beispiel werden die Einstellungen deines Projekts aktualisiert. Ersetze PROJECT_ID
durch die Knoten-ID deines Projekts. Lege public
auf true
fest, um dein Projekt auf GitHub Enterprise Server öffentlich zu machen. Ändere readme
, um Änderungen an der README-Datei deines Projekts vorzunehmen.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"mutation { updateProjectV2(input: { projectId: \"PROJECT_ID\", title: \"Project title\", public: false, readme: \"# Project README\n\nA long description\", shortDescription: \"A short description\"}) { projectV2 { id, title, readme, shortDescription }}}"}'
gh api graphql -f query='
mutation {
updateProjectV2(
input: {
projectId: "PROJECT_ID",
title: "Project title",
public: false,
readme: "# Project README\n\nA long description",
shortDescription: "A short description"
}
) {
projectV2 {
id
title
readme
shortDescription
}
}
}'
Aktualisieren eines benutzerdefinierten Text-, Zahlen- oder Datumsfelds
Im folgenden Beispiel wird der Wert eines Textfelds für ein Element aktualisiert. Ersetze PROJECT_ID
durch die Knoten-ID deines Projekts. Ersetze ITEM_ID
durch die Knoten-ID des Elements, das du aktualisieren möchtest. Ersetze FIELD_ID
durch die ID des Felds, das du aktualisieren möchtest.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"mutation {updateProjectV2ItemFieldValue( input: { projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: { text: \"Updated text\" }}) { projectV2Item { id }}}"}'
gh api graphql -f query='
mutation {
updateProjectV2ItemFieldValue(
input: {
projectId: "PROJECT_ID"
itemId: "ITEM_ID"
fieldId: "FIELD_ID"
value: {
text: "Updated text"
}
}
) {
projectV2Item {
id
}
}
}'
Hinweis: Du kannst updateProjectV2ItemFieldValue
nicht verwenden, um Assignees
, Labels
, Milestone
oder Repository
zu ändern, da diese Felder Eigenschaften von Pull Requests und Issues sind, nicht von Projektelementen. Stattdessen kannst du die folgenden Mutationen verwenden:
Aktualisieren eines einzelnen Auswahlfelds
Im folgenden Beispiel wird der Wert eines einzelnen Auswahlfelds für ein Element aktualisiert.
- Ersetze
PROJECT_ID
durch die Knoten-ID deines Projekts. - Ersetze
ITEM_ID
durch die Knoten-ID des Elements, das du aktualisieren möchtest. - Ersetze
FIELD_ID
durch die ID des einzelnen Auswahlfelds, das du aktualisieren möchtest. - Ersetze
OPTION_ID
durch die ID der gewünschten Auswahloption.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"mutation {updateProjectV2ItemFieldValue( input: { projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: { singleSelectOptionId: \"OPTION_ID\" }}) { projectV2Item { id }}}"}'
gh api graphql -f query='
mutation {
updateProjectV2ItemFieldValue(
input: {
projectId: "PROJECT_ID"
itemId: "ITEM_ID"
fieldId: "FIELD_ID"
value: {
singleSelectOptionId: "OPTION_ID"
}
}
) {
projectV2Item {
id
}
}
}'
Aktualisieren eines Iterationsfelds
Im folgenden Beispiel wird der Wert eines Iterationsfelds für ein Element aktualisiert.
- Ersetze
PROJECT_ID
durch die Knoten-ID deines Projekts. - Ersetze
ITEM_ID
durch die Knoten-ID des Elements, das du aktualisieren möchtest. - Ersetze
FIELD_ID
durch die ID des Iterationsfelds, das du aktualisieren möchtest. - Ersetze
ITERATION_ID
durch die ID der gewünschten Iteration. Dies kann entweder eine aktive oder abgeschlossene Iteration sein.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"mutation {updateProjectV2ItemFieldValue( input: { projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: { iterationId: \"ITERATION_ID\" }}) { projectV2Item { id }}}"}'
gh api graphql -f query='
mutation {
updateProjectV2ItemFieldValue(
input: {
projectId: "PROJECT_ID"
itemId: "ITEM_ID"
fieldId: "FIELD_ID"
value: {
iterationId: "ITERATION_ID"
}
}
) {
projectV2Item {
id
}
}
}'
Löschen eines Elements aus einem Projekt
Im folgenden Beispiel wird ein Element aus einem Projekt gelöscht. Ersetze PROJECT_ID
durch die Knoten-ID deines Projekts. Ersetze ITEM_ID
durch die Knoten-ID des Elements, das du löschen möchtest.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"mutation {deleteProjectV2Item(input: {projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\"}) {deletedItemId}}"}'
gh api graphql -f query='
mutation {
deleteProjectV2Item(
input: {
projectId: "PROJECT_ID"
itemId: "ITEM_ID"
}
) {
deletedItemId
}
}'
Verwalten von Projekten
Erstellen von Projekten
Du kannst eine Mutation verwenden, um ein neues Projekt zu erstellen. Weitere Informationen findest du unter Erstellen von Aufrufen mit GraphQL.
Um ein neues Projekt über die API zu erstellen, musst du einen Namen für das Projekt und die Knoten-ID für einen GitHub Enterprise Server-Benutzer oder eine Organisation angeben, der bzw. die als Besitzer des Projekts fungieren soll.
Wenn du den Benutzernamen kennst, kannst du die Knoten-ID eines GitHub Enterprise Server-Benutzers oder einer Organisation ermitteln. Ersetze GITHUB_OWNER
durch den GitHub Enterprise Server-Benutzernamen des neuen Projektbesitzers.
curl --request GET \
--url https://api.github.com/users/GITHUB_OWNER \
--header 'Authorization: token TOKEN' \
--header 'Accept: application/vnd.github+json'
gh api -H "Accept: application/vnd.github+json" /users/GITHUB_OWNER
Um das Projekt zu erstellen, ersetze OWNER_ID
durch die Knoten-ID des neuen Projektbesitzers und PROJECT_NAME
durch einen Namen für das Projekt.
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token TOKEN' \
--data '{"query":"mutation {createProjectV2(input: {ownerId: \"OWNER_ID\" title: \"PROJECT_NAME\"}) {projectV2 {id}}}"}'
gh api graphql -f query='
mutation{
createProjectV2(
input: {
ownerId: "OWNER_ID",
title: "PROJECT_NAME"
}
){
projectV2 {
id
}
}
}'
Verwenden von Webhooks
Du kannst Webhooks verwenden, um Ereignisse zu abonnieren, die in deinem Projekt stattfinden. Beispielsweise kann GitHub Enterprise Server beim Bearbeiten eines Elements eine HTTP POST-Nutzlast an die konfigurierte URL des Webhooks senden, die Automatisierung auf deinem Server auslösen kann. Weitere Informationen zu Webhooks findest du unter „Informationen zu Webhooks“. Weitere Informationen zum projects_v2_item
-Webhookereignis findest du unter Webhook-Ereignisse und -Nutzlasten.