An integration says it is connected. The demo works. Then the client asks it to read a second project, and it fails.
The tempting fix is to grant more access until the error disappears. Before doing that, ask a smaller question: connected where, allowed to do what, and against which resource?
On October 23, GitHub made enterprise installations for GitHub Apps generally available, with expanded support for administrative and governance automation. It is a useful update, but not a promise that one installation unlocks every project below it.
The practical lesson for freelancers is broader than GitHub: a connection is not an acceptance test. You need a simple map of the access the work actually requires.
Three questions hidden inside one connected badge
An installation answers where an app has been added. Permissions describe operations it may perform. Resource scope identifies the actual projects or data involved. Those are related decisions, not interchangeable ones.
GitHub's enterprise installation guide makes a particularly clear distinction: an enterprise installation manages enterprise-level operations. It does not grant organization or repository access; those resources require separate organization installations. Enterprise installations also do not currently receive webhooks for enterprise-level activities.
That means an administrator can complete a legitimate installation while a repository-based feature still needs a different setup. A success screen at one level does not prove access at another.
If you are learning to frame these tasks for an AI coding tool, my $3 AI App Builder Starter Prompts provide a guided starting point. For this task, give the assistant an access map before asking it to fix the integration.
You do not need an enterprise plan to practice the reasoning. Use a disposable project and the tools you already have. The enterprise feature is the news hook, not a reason to buy anything.
Turn a client request into an access map
Imagine a fictional client who wants a weekly release summary from one private repository. The tool should read merged work and prepare a draft. It should not modify code, publish a release or inspect the client's unrelated repositories.
Before implementation, I would write five plain-language lines:
Requested outcome: prepare a draft weekly summary from the selected project.
Installation location: the client's organization account, using its normal approval process.
Target resource: the explicitly selected test repository first, then the approved production repository after review.
Allowed operations: only the reads needed for the summary. Check each chosen API endpoint's actual requirements rather than guessing permission names.
Forbidden operations: modifying repository contents, changing settings, publishing the draft and reading unrelated private repositories.
This is a proposed work record, not a GitHub configuration format. The client's administrator still needs to review the real installation screen and approve the actual access.
The map also exposes an ordinary scope question: where will the draft live? If it is saved in another service, that service has its own access and data-retention decisions. Do not silently turn a read-only GitHub task into permission to publish somewhere else.
Ask AI to explain the access, not broaden it
A vague instruction such as "fix the permissions" gives a coding assistant too much room to reinterpret the job. I would use a more bounded request:
Inspect the integration code and identify each API operation used to produce the summary. For each operation, link the official documentation and state the required permission and installation scope. Compare those requirements with our approved access map. Do not request broader access or change account settings. Report mismatches and propose the smallest change for review.
GitHub's permission-selection guide recommends minimum required permissions and explains that endpoint documentation specifies the needed access. It also notes that changing an app's requested permissions does not automatically update every installation: account owners must approve the new permissions, or their installation retains the old set.
That last detail matters during client delivery. A developer may update the app configuration while the client is still running with previously approved access. Record both the requested configuration and what the client has actually approved. Neither a code change nor a saved settings page proves the client's workflow now works.
Test the boundary, not just the happy path
For the fictional summary tool, a good demo includes a successful read from the selected test repository. A useful acceptance check also asks whether the tool stays inside its limits.
Use only synthetic data and accounts or repositories you are authorized to test. Do not probe another person's private resources.
Allowed case: the tool reads the approved sample project and produces a draft containing the expected sample changes. Compare its output with a small known input so a plausible-looking summary cannot hide missing work.
Excluded case: a second private test repository, deliberately outside the approved selection, remains inaccessible to the same integration. The tool should explain the missing access rather than return an empty success or ask for every repository automatically.
Write case: confirm that the credentials used by this read-only workflow cannot perform a harmless write in a disposable test project. Never test a forbidden operation against production just to see whether it succeeds.
Interrupted-access case: have the authorized owner suspend or remove the disposable test installation through normal controls, then run the test again. The app should show that action is required, preserve the draft already produced and stop treating the connection as healthy. Restore only the access deliberately approved for the test.
These are suggested acceptance checks, not claims that any particular product runs them for you. Keep the observed result, time and test environment with the delivery record. An unrun test stays unverified.
Make the narrow version easy to hand over
There is a tradeoff. Restricting access can add setup work when the client adds a project. Broad access can make that expansion feel easier, but it also increases what the integration could affect.
Do not bury that choice in an implementation shortcut. Explain it in the client's language: adding another project requires a fresh selection and approval; it is not a broken feature or an automatic entitlement.
At handover, give the client the access map, the observed test results and the normal place to review or revoke the installation. Record who can approve a future expansion. Do not include passwords, tokens or private customer data in the handover document.
The useful result is not a badge that says connected. It is a small, understandable agreement between the job, the resources and the operations the app is allowed to perform. When those three match, a failed request becomes a specific question instead of an invitation to grant everything.
A guided next step
The $3 Starter Prompts help frame your next task. The $9 AI App Builder From Zero e-book gives you an organized path from idea to publication. The $10 learning bundle includes both complete resources.
Bootcamp Bundle (Review Radar) is coming soon; checkout is closed. See the preview and manually request waitlist updates by email.
You can also find me here:
Medium: https://medium.com/@marcusykim
DEV.to: https://dev.to/marcusykim
Website: https://marcusykim.com/
X: https://x.com/marcusykim
LinkedIn: https://www.linkedin.com/in/marcusykim/
Upwork: https://www.upwork.com/freelancers/marcusykim
Top comments (0)