octokit / openapi

GitHub's official OpenAPI spec with Octokit extensions

openapi

GitHub's official OpenAPI spec with Octokit extensions

Amends operations from GitHub's official OpenAPI specification with an x-octokit extension that includes the following keys

• changes: see change files in changes/

Download

Download from https://unpkg.com/browse/@octokit/openapi/generated/

Node Usage

const { schemas } = require("@octokit/openapi");
const version = schemas["api.github.com"].info.version;
const paths = Object.keys(schemas["api.github.com"].paths).sort();

GitHub Actions usage

1. Install Octokit Release Notifier app
2. Create a new workflow file:

name: Update OpenAPI
on:
  repository_dispatch:
    types: [octokit/openapi release]

jobs:
  published:
    runs-on: ubuntu-latest
    steps:
      - run: "echo: 'new release: ${{ github.event.release.tag_name }}'"

Contributing

See CONTRIBUTING.md

License

MIT

openapi's Issues

Why doesn't the org repo endpoint have an `has_downloads` field?

Switch to the OpenAPI 3.1 definitions

Describe the need

GitHub started publishing OpenAPI 3.1 schemas, which now include definitions for webhooks.

It would be nice to have them published in this repo.
See also, octokit/webhooks#470

This would be blocked by #321

In the mean time, we could have a separate repo which contains only the webhook spec, until we can find a replacement
I have created a PoC in my repo: https://github.com/wolfy1339/openapi-webhooks and I will be more than happy to transfer it over to the Octokit org

SDK Version

N/A

API Version

N/A

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

Add deprecation for operationId change: `code-scanning/list-alerts-instances` -> `code-scanning/list-alert-instances`

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Location: package.json
Error type: The renovate configuration file contains some invalid settings
Message: Invalid configuration option: author, Invalid configuration option: files, Invalid configuration option: keywords, Invalid configuration option: license, Invalid configuration option: main, Invalid configuration option: name, Invalid configuration option: packageRules[0].@octokit/core, Invalid configuration option: packageRules[0].prettier, Invalid configuration option: packageRules[0].semantic-release, Invalid configuration option: packageRules[0].semantic-release-plugin-update-version-in-files, Invalid configuration option: publishConfig, Invalid configuration option: release, Invalid configuration option: renovate, Invalid configuration option: scripts, Invalid configuration option: version

The user type should be an enum.

I expect there are very few values for this property, but it's really unclear what they are or could be aside from "User", which is only given as an example.

Given OpenAPI supports enums, it would make a lot of sense to provide all possible values for this field, or at the very least properly document it to explain what its role and purpose is (or whether it's irrelevant, which doesn't seem to be the case assuming at least one of the other values is Org this could be useful for some interactions).

Not possible to run 'build' script with node v12

What's wrong?
Trying to run npm run build with node 12 fails

What did you expect?
To get an advice / constraint that the minimum version to run this script is node 14

Email visibility is unclear and ill-documented.

Since the addresses at /user/emails have individual visibility property and /user/email/visibility takes an email address as well as a visibility, it looks like visibility is a per-addess property.

However the property is nullable, and after experimenting it looks like it's only ever set for the primary address and really matches the profile-global "Keep my email addresses private" flag?

• is the inference correct
• if yes, could that be documented on the visibility property
• why does /user/email/visibility take an email address if that doesn't do anything useful and it always sets the visibility of the primary email address

Why does `/user/repos` have a `team_id` field which is documented to be invalid?

According to its documentation, team_id is not valid on user repositories. But since the request body of user and organisation repository types are specified separately, why have this field at all on the user endpoint?

Dependency Dashboard

This issue contains a list of Renovate updates and their statuses.

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to ignore the schedule.

• fix(deps): lock file maintenance

---

• Check this box to trigger a request for Renovate to run again on this repository

clear `generated/` folder before (re-)creating the files

It looks like we don't delete obsolete files from generated/. In v8.0.0, there are some files that shouldn't be there:

• ghes-3.2-anicca-diff-to-api.github.com.deref.json
• ghes-3.5-anicca-diff-to-api.github.com.deref.json

(plus related versions of the *diff-to-api.github.com* spec files

in the generated/ folder

[MAINT]: Add GHES 3.11 and 3.12, remove deprecated GHES 3.7

Describe the need

octokit/openapi-types.ts#394

SDK Version

No response

API Version

No response

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

Running `npm run build` in local does not work out of the box

What's wrong?
Running npm run build in local environment does not work out of the box. It requires $ANICCA_REPOSITORY_PATH to be set

What did you expect?
To be able to run scripts/build.js without the need of defining environment variables related to GitHub Actions. Also, a better description of anicca usage would be awesome so it is understood how to use $ANICCA_REPOSITORY_PATH.

Examples of error responses seem completely useless.

They seem to be simple copies of the schema (or a pseudo-schema) e.g.

    {
        "message": "string",
        "documentation_url": "string"
    },

Should we consider linting this project (the scripts/ folder at least)?

What’s missing?
Lint (Prettier) in this project

Why?
For consistency with the rest of the projects of the ecosystem

README: clarify that the OpenAPI specifications are not maintained manually, with the exception of the `x-octokit` extension and some workarounds

Release notifier workflow failed: Payload too big

The release notifier did not work as expected, since the payload was too big

Dispatch error: RequestError [HttpError]: client_payload is too large.

You can see the logs here: https://github.com/octokit/openapi/actions/runs/3109007129/jobs/5038811057#step:3:1755

The automated release is failing 🚨

🚨 The automated release from the main branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you can benefit from your bug fixes and new features again.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can fix this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the main branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here are some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

Invalid npm token.

The npm token configured in the NPM_TOKEN environment variable must be a valid token allowing to publish to the registry https://registry.npmjs.org/.

If you are using Two Factor Authentication for your account, set its level to "Authorization only" in your account settings. semantic-release cannot publish with the default "
Authorization and writes" level.

Please make sure to set the NPM_TOKEN environment variable in your CI with the exact value of the npm token.

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

[MAINT]: build fails during anicca step

Describe the need

When running the build command, the anicca diff fails

SDK Version

No response

API Version

N/A

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[MAINT]: `anicca` is no longer maintained

Describe the need

The anicca module is no longer maintained, it's repository is archived.

A replacement will need to be found, as it is no longer maintained, and does not support OpenAPI 3.1

SDK Version

N/A

API Version

N/A

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[BUG]: Missing types for check-run

What happened?

Hey there it looks like the input parameters are missing for the checkrun API. Maybe others?

https://docs.github.com/en/rest/checks/runs?apiVersion=2022-11-28#create-a-check-run

It's been missing for a little bit now across octokit/types and this repo. I've been trying to follow the threads but wasn't sure if it'd been fixed?

#353

I normally access it via the octokit/types package but I assume it's generated from this repo.

Versions

11.2.0

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[MAINT]: Fix build command to support GHES 3.10

Describe the need

The current build process is broken due to GHES version 3.10 release. The current override script only supports one digit in each of the version parts which is causing the build process to fail.

SDK Version

No response

API Version

No response

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

Add deprecation for `audit-log/get-audit-log` -> `enterprise-admin/get-audit-log`

See octokit/openapi-types.ts#80

Fix `summary` for removed endpoints

This endpoint does not exist ghes-3.0.json. It was added in ghes-3.1.json

should be

This endpoint does not exist in GitHub Enterprise Server 3.0. It was added in 3.1

[DOCS]: `pem`s should provide a public key example, not a private key

Describe the need

When reviewing the API spec, I noticed that the docs for https://docs.github.com/en/rest/issues/timeline?apiVersion=2022-11-28#list-timeline-events-for-an-issue note that inside the response schema pem can be returned.

It seems unlikely that this would provide the private key, and should instead return a public key, right?

For example, we can see this referenced in

openapi/scripts/overrides/issues-remove-assignees.deref.json

Line 2278 in 051b0d9

"example": "\"-----BEGIN RSA PRIVATE KEY-----\\nMIIEogIBAAKCAQEArYxrNYD/iT5CZVpRJu4rBKmmze3PVmT/gCo2ATUvDvZTPTey\\nxcGJ3vvrJXazKk06pN05TN29o98jrYz4cengG3YGsXPNEpKsIrEl8NhbnxapEnM9\\nJCMRe0P5JcPsfZlX6hmiT7136GRWiGOUba2X9+HKh8QJVLG5rM007TBER9/z9mWm\\nrJuNh+m5l320oBQY/Qq3A7wzdEfZw8qm/mIN0FCeoXH1L6B8xXWaAYBwhTEh6SSn\\nZHlO1Xu1JWDmAvBCi0RO5aRSKM8q9QEkvvHP4yweAtK3N8+aAbZ7ovaDhyGz8r6r\\nzhU1b8Uo0Z2ysf503WqzQgIajr7Fry7/kUwpgQIDAQABAoIBADwJp80Ko1xHPZDy\\nfcCKBDfIuPvkmSW6KumbsLMaQv1aGdHDwwTGv3t0ixSay8CGlxMRtRDyZPib6SvQ\\n6OH/lpfpbMdW2ErkksgtoIKBVrDilfrcAvrNZu7NxRNbhCSvN8q0s4ICecjbbVQh\\nnueSdlA6vGXbW58BHMq68uRbHkP+k+mM9U0mDJ1HMch67wlg5GbayVRt63H7R2+r\\nVxcna7B80J/lCEjIYZznawgiTvp3MSanTglqAYi+m1EcSsP14bJIB9vgaxS79kTu\\noiSo93leJbBvuGo8QEiUqTwMw4tDksmkLsoqNKQ1q9P7LZ9DGcujtPy4EZsamSJT\\ny8OJt0ECgYEA2lxOxJsQk2kI325JgKFjo92mQeUObIvPfSNWUIZQDTjniOI6Gv63\\nGLWVFrZcvQBWjMEQraJA9xjPbblV8PtfO87MiJGLWCHFxmPz2dzoedN+2Coxom8m\\nV95CLz8QUShuao6u/RYcvUaZEoYs5bHcTmy5sBK80JyEmafJPtCQVxMCgYEAy3ar\\nZr3yv4xRPEPMat4rseswmuMooSaK3SKub19WFI5IAtB/e7qR1Rj9JhOGcZz+OQrl\\nT78O2OFYlgOIkJPvRMrPpK5V9lslc7tz1FSh3BZMRGq5jSyD7ETSOQ0c8T2O/s7v\\nbeEPbVbDe4mwvM24XByH0GnWveVxaDl51ABD65sCgYB3ZAspUkOA5egVCh8kNpnd\\nSd6SnuQBE3ySRlT2WEnCwP9Ph6oPgn+oAfiPX4xbRqkL8q/k0BdHQ4h+zNwhk7+h\\nWtPYRAP1Xxnc/F+jGjb+DVaIaKGU18MWPg7f+FI6nampl3Q0KvfxwX0GdNhtio8T\\nTj1E+SnFwh56SRQuxSh2gwKBgHKjlIO5NtNSflsUYFM+hyQiPiqnHzddfhSG+/3o\\nm5nNaSmczJesUYreH5San7/YEy2UxAugvP7aSY2MxB+iGsiJ9WD2kZzTUlDZJ7RV\\nUzWsoqBR+eZfVJ2FUWWvy8TpSG6trh4dFxImNtKejCR1TREpSiTV3Zb1dmahK9GV\\nrK9NAoGAbBxRLoC01xfxCTgt5BDiBcFVh4fp5yYKwavJPLzHSpuDOrrI9jDn1oKN\\nonq5sDU1i391zfQvdrbX4Ova48BN+B7p63FocP/MK5tyyBoT8zQEk2+vWDOw7H/Z\\nu5dTCPxTIsoIwUw1I+7yIxqJzLPFgR2gVBwY1ra/8iAqCj+zeBw=\\n-----END RSA PRIVATE KEY-----\\n\""

SDK Version

No response

API Version

No response

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[MAINT]: GHES 3.13 is out

Describe the need

https://docs.github.com/en/[email protected]/admin/release-notes

The automated update fails right now:

This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason "GHES version 3.13 is not yet supported. Please check the overrides in scripts/overrides/index.js to check if they are relevant to this version, and then update SUPPORTED_GHES_VERSION.

—https://github.com/octokit/openapi/actions/runs/9179054959/job/25240335108

SDK Version

No response

API Version

No response

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

Add `"x-octokit": { "diff": { ... } }` to keep track of differences between versions

Part of octokit/octokit-next.js#15

update all the generated ghes-3.0.json (etc) OpenAPI files to include a "diff" key in "x-octokit": {}. The "diff" object is only present if there are any changes. All ghes-* versions other than the latest one should include a diff to the next GHES version, the rest should have a diff to github.com. Example:

{
  "diff": {
    "github.com": {
      "type": "added" // "added" | "removed" | "changed"
    }
  }
}

"Update" task fails due to excess memory usage

The regularly-run "update" workflow is failing because we are running out of memory. This means that this repo will not get updated as the schema evolves.

This seems to be a known issue with Prettier, which we use the formatting.

I am able to run the process on my local machine, but it fails in GitHub Actions.

I have already tried increasing Node's memory limits, but that didn't work (see #250) and the GitHub Actions runners only have 7GB of RAM to our ability to do anything is limited.

I'm not sure why this has only started happening recently.

[MAINT]: Migrate scripts to ESM

Describe the need

Dependencies used in scripts/ are doing the transition to ESM. It's time to migrate our scripts so we can enjoy the new features/security patches.

SDK Version

No response

API Version

No response

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

Check that the build script still works when changes are pushed

When you make changes to the build scripts - for example bumping dependencies - our CI flow doesn't check that the build scripts still work. This means that it's easy to break something and have no idea, unless you test the build process locally (which you probably won't for a Renovate dependency bump 😓 ).

We should run the build process when changes are pushed to the build script or dependencies and make sure that it still works, giving feedback in the PR.

Running `npm run build` in local environment fails

Even bypassing the environent variables issue (#185), I get the following error when running in local:

Click to expand!

~/dev/open_source/octokit/openapi main ❯ npm run build                                                                             17:30:20

> @octokit/[email protected] build
> ANICCA_REPOSITORY_PATH='.' node scripts/build.js

generated/api.github.com.deref.json written
generated/api.github.com.json written
generated/ghes-3.0.deref.json written
generated/ghes-3.0.json written
generated/ghes-3.1.deref.json written
generated/ghes-3.1.json written
generated/ghes-3.2.deref.json written
generated/ghes-3.2.json written
generated/github.ae.deref.json written
generated/github.ae.json written
$ cargo run --bin cli diff /Users/xxxxxxxxx/dev/open_source/octokit/openapi/generated/ghes-3.1.deref.json /Users/xxxxxxxxx/dev/open_source/octokit/openapi/generated/ghes-3.0.deref.json --format json
node:internal/errors:464
  ErrorCaptureStackTrace(err);
  ^

Error: Command failed with ENOENT: cargo run --bin cli diff /Users/xxxxxxxxx/dev/open_source/octokit/openapi/generated/ghes-3.1.deref.json /Users/xxxxxxxxx/dev/open_source/octokit/openapi/generated/ghes-3.0.deref.json --format json
spawn cargo ENOENT
  at Process.ChildProcess._handle.onexit (node:internal/child_process:282:19)
  at onErrorNT (node:internal/child_process:477:16)
  at processTicksAndRejections (node:internal/process/task_queues:83:21) {
errno: -2,
code: 'ENOENT',
syscall: 'spawn cargo',
path: 'cargo',
spawnargs: [
  'run',
  '--bin',
  'cli',
  'diff',
  '/Users/xxxxxxxxx/dev/open_source/octokit/openapi/generated/ghes-3.1.deref.json',
  '/Users/xxxxxxxxx/dev/open_source/octokit/openapi/generated/ghes-3.0.deref.json',
  '--format',
  'json'
],
originalMessage: 'spawn cargo ENOENT',
shortMessage: 'Command failed with ENOENT: cargo run --bin cli diff /Users/xxxxxxxxx/dev/open_source/octokit/openapi/generated/ghes-3.1.deref.json /Users/xxxxxxxxx/dev/open_source/octokit/openapi/generated/ghes-3.0.deref.json --format json\n' +
  'spawn cargo ENOENT',
command: 'cargo run --bin cli diff /Users/xxxxxxxxx/dev/open_source/octokit/openapi/generated/ghes-3.1.deref.json /Users/xxxxxxxxx/dev/open_source/octokit/openapi/generated/ghes-3.0.deref.json --format json',
escapedCommand: 'cargo run --bin cli diff "/Users/xxxxxxxxx/dev/open_source/octokit/openapi/generated/ghes-3.1.deref.json" "/Users/xxxxxxxxx/dev/open_source/octokit/openapi/generated/ghes-3.0.deref.json" --format json',
exitCode: undefined,
signal: undefined,
signalDescription: undefined,
stdout: '',
stderr: '',
failed: true,
timedOut: false,
isCanceled: false,
killed: false
} 

Is there something I'm missing on the way I try to run the script? Is it related to this issue (#160)?