Documentation missing about the github-app.yml file

[rajbos]

Feature summary

Add documentation

What problem are you trying to solve?

I am trying to configure the run configuration for my repository but it is unclear how to do so. The UI shows the config is linked, but clicking the button sends me to the settings.

Run button

Settings

Proposed solution

Add docs and share the format and location for the file to be in.
Improve the UI to help the user configure this

Workflow impact

A lot of manual opening and steps when I want to debug the app, even though I have a commandline that can do it in one go

Installation context

Single Repo

Additional context

No response

[rajbos]

I asked the app to analyze this, it found the GitHub Copilot App application on disk and got me this analysis:

Based on extensive investigation of the app's code, I can now give you an honest assessment.

The github-app.yml file is not currently supported by the Copilot CLI app. After searching through the entire app.js (the Node.js backend) and SDK type definitions, there's zero reference to github-app.yml, auto_issue_session, or any script trigger mechanism. The file was created speculatively in a previous session, but the feature doesn't appear to be implemented yet.

Here's what I found:

session.create in the app is an RPC method name (part of the internal ACP protocol), not a script trigger
The app reads .github/copilot-instructions.md, .github/copilot/settings.json, .github/instructions/*.md — but not github-app.yml
The "remote_control" field maps to the CLI's /remote command, unrelated to this file
The "run" button you're clicking likely triggers the scheduled workflows system (the one behind save_workflow/run_workflow in-app tools)
The actual ways to achieve what the file describes:

Intent	Actual feature
Run setup scripts on session start	Extension hook: onSessionStart in .github/extensions/*.mjs
Scheduled/manual runnable prompts	App workflows (save_workflow with interval: manual)
Auto-run on cloud agent launch	copilot-setup-steps.yml GitHub Actions workflow
The github-app.yml format may be a planned but unreleased feature. I'd recommend filing a bug/feedback via /feedback in the CLI, or checking with the Copilot team to confirm whether this file will be supported and what the correct format will be.

So I will need some help here 😄