使用PowerShell执行GitHub CLI GraphQL查询时遭遇方括号解析错误的问题排查

The root cause of your parse error is how you're passing the GraphQL query to the gh api command. Let's break this down and fix it:

Why the Error Happens #

When you use -F query="$graphQl" with gh api graphql, you're telling the GitHub CLI to treat your entire query as a GraphQL variable named query—not as the actual query document itself. GitHub's GraphQL API expects the query field in the request body to be the raw query string, not a variable. This mismatch causes the server to misparse your pattern value's square brackets as invalid GraphQL syntax.

In contrast, when you paste the query into the GraphQL Explorer, you're sending it directly as the query document, which is why it works there.

The Fix #

Replace the -F query="$graphQl" parameter with --raw "$graphQl" to send your query directly as the request body, just like the Explorer does:

# Replace this line:
# gh api --hostname "$Hostname" graphql -F query="$graphQl"

# With this:
gh api --hostname "$Hostname" graphql --raw "$graphQl"

Alternatively, you can pipe the query string directly to the command (this works well with PowerShell's here-strings):

$graphQl | gh api --hostname "$Hostname" graphql

Why This Works #

The --raw flag tells gh api to send the provided string as the exact request body for the GraphQL endpoint. This matches how the GraphQL Explorer sends queries, so your square brackets in the pattern value are treated as part of the string literal, not invalid syntax.

Bonus: Using Variables (Best Practice) #

If you want to follow GraphQL best practices and separate your query from variables (which makes maintenance easier), you can refactor your script like this:

1. Rewrite the GraphQL query to use variables:

mutation createBranchProtectionRule($repoId: ID!, $pattern: String!, $props: BranchProtectionRuleInput!) {
    createBranchProtectionRule(input: {
        repositoryId: $repoId
        pattern: $pattern
        allowsDeletions: $props.allowsDeletions
        allowsForcePushes: $props.allowsForcePushes
        blocksCreations: $props.blocksCreations
        dismissesStaleReviews: $props.dismissesStaleReviews
        isAdminEnforced: $props.isAdminEnforced
        requiredApprovingReviewCount: $props.requiredApprovingReviewCount
        requiresApprovingReviews: $props.requiresApprovingReviews
        requiresCodeOwnerReviews: $props.requiresCodeOwnerReviews
        requiresCommitSignatures: $props.requiresCommitSignatures
        requiresConversationResolution: $props.requiresConversationResolution
        requiresLinearHistory: $props.requiresLinearHistory
        requiresStatusChecks: $props.requiresStatusChecks
        requiresStrictStatusChecks: $props.requiresStrictStatusChecks
        restrictsPushes: $props.restrictsPushes
        restrictsReviewDismissals: $props.restrictsReviewDismissals
    }){
        branchProtectionRule {
            allowsDeletions
            allowsForcePushes
            creator { login }
            databaseId
            dismissesStaleReviews
            isAdminEnforced
            pattern
            repository { nameWithOwner }
            requiredApprovingReviewCount
            requiresApprovingReviews
            requiredStatusCheckContexts
            requiresCodeOwnerReviews
            requiresCommitSignatures
            requiresLinearHistory
            requiresStatusChecks
            requiresStrictStatusChecks
            restrictsPushes
            restrictsReviewDismissals
        }
        clientMutationId
    }
}

2. Pass variables via -F flags in PowerShell:

# Convert the Properties hashtable to JSON for the variable
$propsJson = $Properties | ConvertTo-Json -Compress

gh api --hostname "$Hostname" graphql `
    -F query="$graphQl" `
    -F repoId="$repoNodeId" `
    -F pattern="$BranchPattern" `
    -F props="$propsJson"

This approach keeps your query clean and avoids embedding dynamic values directly into the query string.

内容的提问来源于stack exchange，提问作者Emil