# Call the GitHub API from a job

Use gh, actions/github-script and other GitHub API clients in jobs on your runners and runner pools, against this repository, with the job's own token.

On your runners and runner pools every job gets its own `GITHUB_TOKEN` (`${{ github.token }}`,
`${{ secrets.GITHUB_TOKEN }}`), and the job's environment points GitHub API clients at
Deutsche Cloud's Git host: `GITHUB_API_URL` is `https://<git host>/api/v3`, `GITHUB_GRAPHQL_URL` is
`https://<git host>/api/graphql`, and `GH_HOST` names the host. `gh` reads `GH_ENTERPRISE_TOKEN`
for a host that is not github.com; it is set to the job's token, unless the workflow sets its own.
So `gh pr comment`, `actions/github-script` and similar steps work unchanged.

On the one-machine-per-run hosted machines there is no per-job token; see
[Run GitHub Actions workflows](run-github-actions-workflows.md).

## Prerequisites

- The job runs on one of your runners or a runner pool.
- The workflow's `permissions:` allow what the job calls.

## Give the token its permissions

The token works for this repository only and ends with the job. It can do what the job's
`permissions:` block says, else the workflow's, else the repository's default. The default is the
repository's workflow permissions setting:

| Setting      | Grants                                                                                                |
| ------------ | ----------------------------------------------------------------------------------------------------- |
| `restricted` | `contents: read`, `packages: read` and `metadata: read`                                               |
| `permissive` | Write on every scope except `id-token`, `attestations` and `models`, which get none; `metadata: read` |

New repositories are `restricted`; repositories that existed before 2026-11-18 are `permissive`. An
import from GitHub copies the source's setting when the import token may read it. Change it with
`PATCH /git/api/repositories/{repoId}` and `{ "defaultWorkflowPermissions": "permissive" }`, which
needs `git:UpdateRepository`. The job's log shows the token's permissions under **Set up job**.

## Result

The REST API under `/api/v3` serves the repository, branches, refs, commits, compare and contents;
pull requests, issues, comments and labels; commit statuses and check runs (a check run an action
creates is kept as a commit status of its name); Actions runs, jobs, logs, workflows, dispatches and
artifacts; releases and their assets; SARIF uploads; and security advisories, answered from
Deutsche Cloud's own vulnerability database. A GraphQL endpoint serves the common queries and
mutations. Ids follow GitHub's habits; comments a job writes show as `github-actions[bot]`.

A call the token does not allow answers `403` "Resource not accessible by integration: the job's
GITHUB_TOKEN needs `issues: write` — add it under `permissions:` in the workflow or job". Writes
through the token are recorded in the audit log, allowed or refused.

As on GitHub, a push, tag, release or pull request made with the job's token starts no workflow.
A `workflow_dispatch` through the API does; that run gets the secrets of the person whose run the
job belongs to.

Not served: deployments, projects, discussions, attestations (`actions/attest-build-provenance`
accepts only github.com), and turning one workflow on or off. Re-running only the failed jobs
re-runs the whole run. An action that calls `api.github.com` directly instead of reading
`GITHUB_API_URL` talks to GitHub.

## Related

- [Run GitHub Actions workflows](run-github-actions-workflows.md)
- [Change repository settings](/docs/git/guide/change-repository-settings)
