Secrets and GitHub App permissions
What the GitHub App can do in your organisation, where your secrets stay and what reaches a job’s virtual machine.
What stays in GitHub
GitHub keeps your workflows, scheduling, secrets, checks and job logs. Your Actions secrets remain in GitHub’s settings. GitHub passes a job’s secrets to the runner for that job, as it does for any self-hosted runner.
Permissions for running jobs
| Permission | Used for |
|---|---|
| Repository: Metadata, read | Identifying the selected repositories. |
| Repository: Actions, read | Receiving workflow_job events and checking that a job is still queued before a runner is started for it. |
| Organization: Self-hosted runners, read and write | Registering a one-job runner in your runner group and removing its registration afterwards. |
| Webhook event: Workflow job | Learning that a job was queued, started or completed. |
GitHub App installations are limited to the repositories you select. Added permissions take effect only after the installation owner approves them.
Permissions running jobs does not need
The same App can carry further permissions for features outside CI. None of them is needed to run a job:
- Contents, read and write: used for repository sync, not by the runner. Your job’s checkout uses the token GitHub gives the job.
- Workflows, write: optional, only for exports that edit files under
.github/workflows. - Secrets, read and write: optional, only if the machine’s operator is to write Actions secrets for selected repositories.
If you use the machine only for CI, the three permissions in the table above are enough.
The runner group decides who can run
The organisation runner group lists the repositories, and optionally the workflows, that may send jobs to the machine. Battleship also checks every job’s installation, repository and labels before it starts a runner. Workflows must opt in by label; an event cannot redirect a job that asked for ubuntu-latest.
Code in an admitted job runs with the access that job has. Decide deliberately whether pull requests from outside contributors may use the group.
What reaches a job’s virtual machine
- Each job runs in a new virtual machine cloned from an image that contains no credentials.
- The virtual machine receives a one-use runner registration for a single job. The App’s private key, client secret and refresh tokens stay on the controller and never enter it.
- The machine’s own Docker socket is never mounted into a job.
- When the job ends, that virtual machine is deleted. No job disk, runner credential or job-created cache becomes part of the image later jobs start from.
Webhook deliveries are verified with HMAC-SHA256 over the raw request before anything is started.
Remove access
To stop a repository from using the machine, remove it from the runner group or from the App installation. To stop everything, uninstall the App from the organisation. Restore the previous runs-on in jobs that still name the machine’s labels; with no runner to take them they would wait in GitHub’s queue.