Use metadata to reconcile go-github with GitHub's OpenAPI descriptions

.codecov.yml

@@ -3,5 +3,5 @@ ignore:
   - "github/github-accessors.go"
   # ignore experimental scrape package
   - "scrape"
-  # ignore update-urls
-  - "update-urls"
+  # ignore tools
+  - "tools"

.github/dependabot.yml

@@ -9,7 +9,7 @@ updates:
   schedule:
     interval: weekly
 - package-ecosystem: gomod
-  directory: update-urls
+  directory: tools
   schedule:
     interval: weekly
 - package-ecosystem: github-actions

.github/workflows/linter.yml

@@ -14,3 +14,6 @@ jobs:
         go-version: 1.x
         cache-dependency-path: "**/go.sum"
     - run: script/lint.sh
+      env:
+        CHECK_GITHUB_OPENAPI: 1
+        GITHUB_TOKEN: ${{ github.token }}

CONTRIBUTING.md

@@ -73,6 +73,16 @@ are more sensitive, emailed to <[email protected]>.
 [pull request]: https://help.github.com/articles/creating-a-pull-request
 [monitored by codecov.io]: https://codecov.io/gh/google/go-github
 
+## Metadata ##
+
+`metadata.yaml` contains metadata about go-github's code and GitHub's OpenAPI
+specification. We use this metadata to keep documentation links up to date and
+to keep tabs on coverage of the GitHub API.
+
+All exported methods on `*Service` structs need to have an entry in the
+"methods" section of `metadata.yaml` that maps it to the corresponding
+OpenAPI operation.
+
 ## Scripts ##
 
 The `script` directory has shell scripts that help with common development

github/actions_cache.go

@@ -217,7 +217,7 @@ func (s *ActionsService) GetTotalCacheUsageForOrg(ctx context.Context, org strin
 //
 // Permissions: You must authenticate using an access token with the "admin:enterprise" scope to use this endpoint.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-usage-for-an-enterprise
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/cache#get-github-actions-cache-usage-for-an-enterprise
 func (s *ActionsService) GetTotalCacheUsageForEnterprise(ctx context.Context, enterprise string) (*TotalCacheUsage, *Response, error) {
 	u := fmt.Sprintf("enterprises/%v/actions/cache/usage", enterprise)
 	req, err := s.client.NewRequest("GET", u, nil)

github/actions_required_workflows.go

@@ -67,7 +67,7 @@ type RepoRequiredWorkflows struct {
 
 // ListOrgRequiredWorkflows lists the RequiredWorkflows for an org.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/required-workflows?apiVersion=2022-11-28#list-required-workflows
+// GitHub API docs: https://docs.github.com/actions/using-workflows/required-workflows
 func (s *ActionsService) ListOrgRequiredWorkflows(ctx context.Context, org string, opts *ListOptions) (*OrgRequiredWorkflows, *Response, error) {
 	url := fmt.Sprintf("orgs/%v/actions/required_workflows", org)
 	u, err := addOptions(url, opts)
@@ -91,7 +91,7 @@ func (s *ActionsService) ListOrgRequiredWorkflows(ctx context.Context, org strin
 
 // CreateRequiredWorkflow creates the required workflow in an org.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/required-workflows?apiVersion=2022-11-28#create-a-required-workflow
+// GitHub API docs: https://docs.github.com/actions/using-workflows/required-workflows
 func (s *ActionsService) CreateRequiredWorkflow(ctx context.Context, org string, createRequiredWorkflowOptions *CreateUpdateRequiredWorkflowOptions) (*OrgRequiredWorkflow, *Response, error) {
 	url := fmt.Sprintf("orgs/%v/actions/required_workflows", org)
 	req, err := s.client.NewRequest("POST", url, createRequiredWorkflowOptions)
@@ -110,7 +110,7 @@ func (s *ActionsService) CreateRequiredWorkflow(ctx context.Context, org string,
 
 // GetRequiredWorkflowByID get the RequiredWorkflows for an org by its ID.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/required-workflows?apiVersion=2022-11-28#list-required-workflows
+// GitHub API docs: https://docs.github.com/actions/using-workflows/required-workflows
 func (s *ActionsService) GetRequiredWorkflowByID(ctx context.Context, owner string, requiredWorkflowID int64) (*OrgRequiredWorkflow, *Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/required_workflows/%v", owner, requiredWorkflowID)
 
@@ -130,7 +130,7 @@ func (s *ActionsService) GetRequiredWorkflowByID(ctx context.Context, owner stri
 
 // UpdateRequiredWorkflow updates a required workflow in an org.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/required-workflows?apiVersion=2022-11-28#update-a-required-workflow
+// GitHub API docs: https://docs.github.com/actions/using-workflows/required-workflows
 func (s *ActionsService) UpdateRequiredWorkflow(ctx context.Context, org string, requiredWorkflowID int64, updateRequiredWorkflowOptions *CreateUpdateRequiredWorkflowOptions) (*OrgRequiredWorkflow, *Response, error) {
 	url := fmt.Sprintf("orgs/%v/actions/required_workflows/%v", org, requiredWorkflowID)
 	req, err := s.client.NewRequest("PATCH", url, updateRequiredWorkflowOptions)
@@ -149,7 +149,7 @@ func (s *ActionsService) UpdateRequiredWorkflow(ctx context.Context, org string,
 
 // DeleteRequiredWorkflow deletes a required workflow in an org.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/required-workflows?apiVersion=2022-11-28#update-a-required-workflow
+// GitHub API docs: https://docs.github.com/actions/using-workflows/required-workflows
 func (s *ActionsService) DeleteRequiredWorkflow(ctx context.Context, org string, requiredWorkflowID int64) (*Response, error) {
 	url := fmt.Sprintf("orgs/%v/actions/required_workflows/%v", org, requiredWorkflowID)
 	req, err := s.client.NewRequest("DELETE", url, nil)
@@ -161,7 +161,7 @@ func (s *ActionsService) DeleteRequiredWorkflow(ctx context.Context, org string,
 
 // ListRequiredWorkflowSelectedRepos lists the Repositories selected for a workflow.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/required-workflows?apiVersion=2022-11-28#list-selected-repositories-for-a-required-workflow
+// GitHub API docs: https://docs.github.com/actions/using-workflows/required-workflows
 func (s *ActionsService) ListRequiredWorkflowSelectedRepos(ctx context.Context, org string, requiredWorkflowID int64, opts *ListOptions) (*RequiredWorkflowSelectedRepos, *Response, error) {
 	url := fmt.Sprintf("orgs/%v/actions/required_workflows/%v/repositories", org, requiredWorkflowID)
 	u, err := addOptions(url, opts)
@@ -184,7 +184,7 @@ func (s *ActionsService) ListRequiredWorkflowSelectedRepos(ctx context.Context,
 
 // SetRequiredWorkflowSelectedRepos sets the Repositories selected for a workflow.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/required-workflows?apiVersion=2022-11-28#sets-repositories-for-a-required-workflow
+// GitHub API docs: https://docs.github.com/actions/using-workflows/required-workflows
 func (s *ActionsService) SetRequiredWorkflowSelectedRepos(ctx context.Context, org string, requiredWorkflowID int64, ids SelectedRepoIDs) (*Response, error) {
 	type repoIDs struct {
 		SelectedIDs SelectedRepoIDs `json:"selected_repository_ids"`
@@ -200,7 +200,7 @@ func (s *ActionsService) SetRequiredWorkflowSelectedRepos(ctx context.Context, o
 
 // AddRepoToRequiredWorkflow adds the Repository to a required workflow.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/required-workflows?apiVersion=2022-11-28#add-a-repository-to-a-required-workflow
+// GitHub API docs: https://docs.github.com/actions/using-workflows/required-workflows
 func (s *ActionsService) AddRepoToRequiredWorkflow(ctx context.Context, org string, requiredWorkflowID, repoID int64) (*Response, error) {
 	url := fmt.Sprintf("orgs/%v/actions/required_workflows/%v/repositories/%v", org, requiredWorkflowID, repoID)
 	req, err := s.client.NewRequest("PUT", url, nil)
@@ -212,7 +212,7 @@ func (s *ActionsService) AddRepoToRequiredWorkflow(ctx context.Context, org stri
 
 // RemoveRepoFromRequiredWorkflow removes the Repository from a required workflow.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/required-workflows?apiVersion=2022-11-28#add-a-repository-to-a-required-workflow
+// GitHub API docs: https://docs.github.com/actions/using-workflows/required-workflows
 func (s *ActionsService) RemoveRepoFromRequiredWorkflow(ctx context.Context, org string, requiredWorkflowID, repoID int64) (*Response, error) {
 	url := fmt.Sprintf("orgs/%v/actions/required_workflows/%v/repositories/%v", org, requiredWorkflowID, repoID)
 	req, err := s.client.NewRequest("DELETE", url, nil)
@@ -224,7 +224,7 @@ func (s *ActionsService) RemoveRepoFromRequiredWorkflow(ctx context.Context, org
 
 // ListRepoRequiredWorkflows lists the RequiredWorkflows for a repo.
 //
-// Github API docs:https://docs.github.com/en/rest/actions/required-workflows?apiVersion=2022-11-28#list-repository-required-workflows
+// GitHub API docs: https://docs.github.com/actions/using-workflows/required-workflows
 func (s *ActionsService) ListRepoRequiredWorkflows(ctx context.Context, owner, repo string, opts *ListOptions) (*RepoRequiredWorkflows, *Response, error) {
 	url := fmt.Sprintf("repos/%v/%v/actions/required_workflows", owner, repo)
 	u, err := addOptions(url, opts)

github/actions_runner_groups.go

@@ -80,7 +80,7 @@ type ListOrgRunnerGroupOptions struct {
 
 // ListOrganizationRunnerGroups lists all self-hosted runner groups configured in an organization.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/self-hosted-runner-groups#list-self-hosted-runner-groups-for-an-organization
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/self-hosted-runner-groups#list-self-hosted-runner-groups-for-an-organization
 func (s *ActionsService) ListOrganizationRunnerGroups(ctx context.Context, org string, opts *ListOrgRunnerGroupOptions) (*RunnerGroups, *Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/runner-groups", org)
 	u, err := addOptions(u, opts)
@@ -104,7 +104,7 @@ func (s *ActionsService) ListOrganizationRunnerGroups(ctx context.Context, org s
 
 // GetOrganizationRunnerGroup gets a specific self-hosted runner group for an organization using its RunnerGroup ID.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/self-hosted-runner-groups#get-a-self-hosted-runner-group-for-an-organization
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/self-hosted-runner-groups#get-a-self-hosted-runner-group-for-an-organization
 func (s *ActionsService) GetOrganizationRunnerGroup(ctx context.Context, org string, groupID int64) (*RunnerGroup, *Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/runner-groups/%v", org, groupID)
 	req, err := s.client.NewRequest("GET", u, nil)
@@ -123,7 +123,7 @@ func (s *ActionsService) GetOrganizationRunnerGroup(ctx context.Context, org str
 
 // DeleteOrganizationRunnerGroup deletes a self-hosted runner group from an organization.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/self-hosted-runner-groups#delete-a-self-hosted-runner-group-from-an-organization
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/self-hosted-runner-groups#delete-a-self-hosted-runner-group-from-an-organization
 func (s *ActionsService) DeleteOrganizationRunnerGroup(ctx context.Context, org string, groupID int64) (*Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/runner-groups/%v", org, groupID)
 
@@ -137,7 +137,7 @@ func (s *ActionsService) DeleteOrganizationRunnerGroup(ctx context.Context, org
 
 // CreateOrganizationRunnerGroup creates a new self-hosted runner group for an organization.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/self-hosted-runner-groups#create-a-self-hosted-runner-group-for-an-organization
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/self-hosted-runner-groups#create-a-self-hosted-runner-group-for-an-organization
 func (s *ActionsService) CreateOrganizationRunnerGroup(ctx context.Context, org string, createReq CreateRunnerGroupRequest) (*RunnerGroup, *Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/runner-groups", org)
 	req, err := s.client.NewRequest("POST", u, createReq)
@@ -156,7 +156,7 @@ func (s *ActionsService) CreateOrganizationRunnerGroup(ctx context.Context, org
 
 // UpdateOrganizationRunnerGroup updates a self-hosted runner group for an organization.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/self-hosted-runner-groups#update-a-self-hosted-runner-group-for-an-organization
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/self-hosted-runner-groups#update-a-self-hosted-runner-group-for-an-organization
 func (s *ActionsService) UpdateOrganizationRunnerGroup(ctx context.Context, org string, groupID int64, updateReq UpdateRunnerGroupRequest) (*RunnerGroup, *Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/runner-groups/%v", org, groupID)
 	req, err := s.client.NewRequest("PATCH", u, updateReq)
@@ -175,7 +175,7 @@ func (s *ActionsService) UpdateOrganizationRunnerGroup(ctx context.Context, org
 
 // ListRepositoryAccessRunnerGroup lists the repositories with access to a self-hosted runner group configured in an organization.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/self-hosted-runner-groups#list-repository-access-to-a-self-hosted-runner-group-in-an-organization
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/self-hosted-runner-groups#list-repository-access-to-a-self-hosted-runner-group-in-an-organization
 func (s *ActionsService) ListRepositoryAccessRunnerGroup(ctx context.Context, org string, groupID int64, opts *ListOptions) (*ListRepositories, *Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/runner-groups/%v/repositories", org, groupID)
 	u, err := addOptions(u, opts)
@@ -200,7 +200,7 @@ func (s *ActionsService) ListRepositoryAccessRunnerGroup(ctx context.Context, or
 // SetRepositoryAccessRunnerGroup replaces the list of repositories that have access to a self-hosted runner group configured in an organization
 // with a new List of repositories.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/self-hosted-runner-groups#set-repository-access-for-a-self-hosted-runner-group-in-an-organization
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/self-hosted-runner-groups#set-repository-access-for-a-self-hosted-runner-group-in-an-organization
 func (s *ActionsService) SetRepositoryAccessRunnerGroup(ctx context.Context, org string, groupID int64, ids SetRepoAccessRunnerGroupRequest) (*Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/runner-groups/%v/repositories", org, groupID)
 
@@ -215,7 +215,7 @@ func (s *ActionsService) SetRepositoryAccessRunnerGroup(ctx context.Context, org
 // AddRepositoryAccessRunnerGroup adds a repository to the list of selected repositories that can access a self-hosted runner group.
 // The runner group must have visibility set to 'selected'.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/self-hosted-runner-groups#add-repository-access-to-a-self-hosted-runner-group-in-an-organization
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/self-hosted-runner-groups#add-repository-access-to-a-self-hosted-runner-group-in-an-organization
 func (s *ActionsService) AddRepositoryAccessRunnerGroup(ctx context.Context, org string, groupID, repoID int64) (*Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/runner-groups/%v/repositories/%v", org, groupID, repoID)
 
@@ -230,7 +230,7 @@ func (s *ActionsService) AddRepositoryAccessRunnerGroup(ctx context.Context, org
 // RemoveRepositoryAccessRunnerGroup removes a repository from the list of selected repositories that can access a self-hosted runner group.
 // The runner group must have visibility set to 'selected'.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/self-hosted-runner-groups#remove-repository-access-to-a-self-hosted-runner-group-in-an-organization
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/self-hosted-runner-groups#remove-repository-access-to-a-self-hosted-runner-group-in-an-organization
 func (s *ActionsService) RemoveRepositoryAccessRunnerGroup(ctx context.Context, org string, groupID, repoID int64) (*Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/runner-groups/%v/repositories/%v", org, groupID, repoID)
 
@@ -244,7 +244,7 @@ func (s *ActionsService) RemoveRepositoryAccessRunnerGroup(ctx context.Context,
 
 // ListRunnerGroupRunners lists self-hosted runners that are in a specific organization group.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/self-hosted-runner-groups#list-self-hosted-runners-in-a-group-for-an-organization
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/self-hosted-runner-groups#list-self-hosted-runners-in-a-group-for-an-organization
 func (s *ActionsService) ListRunnerGroupRunners(ctx context.Context, org string, groupID int64, opts *ListOptions) (*Runners, *Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/runner-groups/%v/runners", org, groupID)
 	u, err := addOptions(u, opts)
@@ -269,7 +269,7 @@ func (s *ActionsService) ListRunnerGroupRunners(ctx context.Context, org string,
 // SetRunnerGroupRunners replaces the list of self-hosted runners that are part of an organization runner group
 // with a new list of runners.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/self-hosted-runner-groups#set-self-hosted-runners-in-a-group-for-an-organization
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/self-hosted-runner-groups#set-self-hosted-runners-in-a-group-for-an-organization
 func (s *ActionsService) SetRunnerGroupRunners(ctx context.Context, org string, groupID int64, ids SetRunnerGroupRunnersRequest) (*Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/runner-groups/%v/runners", org, groupID)
 
@@ -283,7 +283,7 @@ func (s *ActionsService) SetRunnerGroupRunners(ctx context.Context, org string,
 
 // AddRunnerGroupRunners adds a self-hosted runner to a runner group configured in an organization.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/self-hosted-runner-groups#add-a-self-hosted-runner-to-a-group-for-an-organization
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/self-hosted-runner-groups#add-a-self-hosted-runner-to-a-group-for-an-organization
 func (s *ActionsService) AddRunnerGroupRunners(ctx context.Context, org string, groupID, runnerID int64) (*Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/runner-groups/%v/runners/%v", org, groupID, runnerID)
 
@@ -298,7 +298,7 @@ func (s *ActionsService) AddRunnerGroupRunners(ctx context.Context, org string,
 // RemoveRunnerGroupRunners removes a self-hosted runner from a group configured in an organization.
 // The runner is then returned to the default group.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/self-hosted-runner-groups#remove-a-self-hosted-runner-from-a-group-for-an-organization
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/self-hosted-runner-groups#remove-a-self-hosted-runner-from-a-group-for-an-organization
 func (s *ActionsService) RemoveRunnerGroupRunners(ctx context.Context, org string, groupID, runnerID int64) (*Response, error) {
 	u := fmt.Sprintf("orgs/%v/actions/runner-groups/%v/runners/%v", org, groupID, runnerID)
 

github/actions_variables.go

@@ -170,7 +170,7 @@ func (s *ActionsService) UpdateOrgVariable(ctx context.Context, org string, vari
 
 // UpdateEnvVariable updates an environment variable.
 //
-// GitHub API docs: https://docs.github.com/en/rest/actions/variables#create-an-environment-variable
+// GitHub API docs: https://docs.github.com/rest/actions/variables#update-an-environment-variable
 func (s *ActionsService) UpdateEnvVariable(ctx context.Context, repoID int, env string, variable *ActionsVariable) (*Response, error) {
 	url := fmt.Sprintf("repositories/%v/environments/%v/variables/%v", repoID, env, variable.Name)
 	return s.patchVariable(ctx, url, variable)