Repository navigation
Proposal: Enhanced GitHub Action Experience #185
Copy link
Copy link
Closed
Description
Following up on #149
Based on the research findings, this proposal outlines the implementation approach for GitHub App authentication to achieve branded comments.
Problem
Code PushUp users receive generic github-actions[bot] comments that don't reflect our professional identity. This limits the brand's visibility and credibility in the developer ecosystem.
Solution
GitHub App installation authentication with an optional marketplace listing
Why GitHub App installation authentication?
- Replaces generic
github-actions[bot]withcode-pushup-staging[bot](orcode-pushup[bot]) for clear brand attribution - Provides more precise permission control
- Lays the foundation for future advanced integrations and features
- Is an industry standard; many successful tools consistently require GitHub Apps installation
- Requires zero breaking changes
User experience flow
- Without app: User gets standard
github-actions[bot]comments (current behavior) - With app: User gets branded
code-pushup-staging[bot]comments - Automatic detection: No user configuration needed after app installation
Implementation details
Users must install the Code PushUp GitHub App on their repository or organization to receive branded comments. The GitHub Action cannot authenticate with an app that's only installed on the Code PushUp organization.
Technical requirements
- GitHub App ID and private key stored as repository secrets
- Permissions:
pull-requests: write(for posting comments) - The user must grant app access to target repositories during installation
Authentication process
- User installs the Code PushUp GitHub App on their repository/organization
- Action detects an app installation on the current repository during workflow execution
- Action uses the
@octokit/auth-applibrary to authenticate as the GitHub App and generate installation tokens - Action uses an installation token for API calls instead of the default
github.token - Comments appear as an app identity instead of a generic bot
- Graceful fallback to the standard token when the app is not installed
Implementation scope
- An authentication system that can detect when the Code PushUp GitHub App is installed on a user's repository
- Token generation logic that creates GitHub App installation tokens for API calls
- Fallback mechanism that uses a standard GitHub token when the app is not installed
- Professional GitHub App page with a meaningful description (the current app has no user-facing documentation)
- Documentation updates increasing app visibility (currently, no repositories mention the app)
Discussion points
- App identity: Should we use
code-pushup-stagingor create a more generalcode-pushupapp? - Permission compatibility: Does the current app have sufficient permissions?
- Marketplace priority: Should we create a GitHub Marketplace listing to help users discover the app (requirements for listing an app)?
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels
Activity
matejchalk commentedon Jul 16, 2025
Thanks for the write-up, the proposal sounds good to me 👍 Fallback to default
github.tokenalso makes it a non-breaking change, which is welcome.I'd create a separate
code-pushupapp for production. We can use thecode-pushup-stagingapp for testing this feature in our own repos, but as the name suggests, it's not intended for users outside our organization.I believe not. It's currently only used to give portal access to GitHub API, so the permissions are restricted for this purpose. Specifically, it only has Read-only Metadata (mandatory) and Read-only Contents (selected) permissions.
So I believe we'd need to add a Read and write Pull requests permission, is that right?
Not sure about this. I think we can list it as a free app, but even so it seems like there are some hoops to jump through and I'm not sure it gives us much advantage to be discoverable through the GitHub Marketplace. What do you think, @vmasek?
vmasek commentedon Jul 16, 2025
I would not prioritize creating market place app for now, but having separate app for prod and using our logo for the icon would definitely be a nice touch
hanna-skryl commentedon Jul 16, 2025
Makes perfect sense to set up a production app. I can create a ticket for someone with owner/admin privileges to do this.
I think I was too quick to add
pull-requests: writepermission in the proposal technical requirements. Looking at the code, the action uses GitHub's Issues API endpoints to manage PR comments. So, the app will likely need Issues: Read and write permissions. But this needs to be tested.Agreed. A marketplace listing can always be added later if we find users have trouble discovering the app.
I'm thinking we'll need two separate tickets:
code-pushup-stagingapp with proper permissionscode-pushupappOne question, though: how do you think we should approach testing this feature on Code PushUp repositories before creating a public release?
matejchalk commentedon Jul 16, 2025
This is suprisingly easy when it comes to GitHub Actions, we can reference any Git branch, commit or tag in our workflows. For example, let's say you had a work-in-progress implementation pushed to a
github-app-authbranch. Then you can create a dummy PR incode-pushup/cliwith the following change and it'll execute your code:matejchalk commentedon Jul 16, 2025
Looks like adding permissions will prompt existing GitHub users to accept them 🤔
So maybe it would best to test it with a new GitHub App until it's ready. I can create it, just ping me when you need it. I'm guessing you'll want to implement it, @hanna-skryl?
hanna-skryl commentedon Jul 16, 2025
@matejchalk Sure, I'd like to try and implement it. There is no rush on the app setup. If you can do it this week, that's great, but it can wait until later.
matejchalk commentedon Jul 24, 2025
I've just created the new GitHub App Code PushUp - we'll use it for production later, but for now you can use it to for testing (saves creating an extra app). I've given the new app Contents: Read, Metadata: Read and Issues: Read and write permissions. I'll share the private key with you on Slack, @hanna-skryl. Let me know if you need anything else 🙂
matejchalk commentedon Oct 1, 2025
Closed via: