Set Up GitHub

What this setup enables

Curoxi separates company-level GitHub configuration from project-level repository mapping. That keeps the shared OAuth app and webhook secret in one place while letting each project connect to the correct repositories.

After setup, project admins can connect GitHub for a specific project, fetch repositories from GitHub, map one or more repos, and let pull request activity update task delivery status.

• GitHub OAuth connection from project settings
• Repository mapping for project delivery work
• Pull request workflows linked to tasks
• Better task-to-code traceability by customer project

Before you start

You need both the company-level GitHub settings and the correct project context. Without both, project users will not be able to finish the repository connection flow.

This setup has two parts. First, a company admin configures the OAuth app credentials and shared webhook secret in Curoxi. Second, a project admin connects GitHub and maps repositories inside the correct project.

• Sign in as a company admin to save the company GitHub settings
• Use a project admin role for the project-level GitHub mapping
• Have admin access to the target GitHub repositories if you need to create repository webhooks
• Know your app callback URL, for example https://app.curoxi.com/github/oauth/callback in production
• Know your backend webhook receiver URL, for example https://your-backend-domain/webhooks/github
• Use the same webhook secret in both GitHub and Curoxi

Important note about OAuth token vs personal access token

Curoxi does not ask you to create a personal access token manually for this flow. The GitHub connection uses a GitHub OAuth app. You create the OAuth app in GitHub, save the Client ID and Client Secret in Curoxi, and then Curoxi obtains the access token when a project admin clicks Connect GitHub and completes the GitHub consent screen.

So for this integration, the GitHub-side credentials you create are the OAuth app details and the webhook configuration. You do not need to paste a personal GitHub token into Curoxi for the current product flow.

Step 1: Create the GitHub OAuth app

Create the OAuth app in GitHub first, because Curoxi needs the Client ID, Client Secret, and Redirect URI from that app.

• The callback URL must match exactly what you save in Curoxi.
• If your test and production environments use different domains, create separate OAuth apps so each environment has the correct callback URL.
• Curoxi currently requests the repo scope during GitHub authorization, so authorize with an account that can see the repositories you need.

1. In GitHub, open your profile menu and go to Settings.
2. Open Developer settings.
3. Open OAuth apps.
4. Click New OAuth App.
5. Set Application name to something your team can recognize, such as Curoxi Production or Curoxi Test.
6. Set Homepage URL to your public app URL, such as https://curoxi.com.
7. Set Authorization callback URL to the exact callback URL used by your Curoxi app, such as https://app.curoxi.com/github/oauth/callback.
8. Register the application.
9. Copy the Client ID from GitHub.
10. Generate a new Client Secret and copy it immediately.

GitHub Docs: Creating an OAuth app

GitHub Docs: Authorizing OAuth apps

Step 2: Save the GitHub app settings in Curoxi

After the OAuth app exists in GitHub, move to Curoxi and save those values at the company level. This is the shared setup used by company projects.

• Leave the secret fields blank only when you want to keep the already-saved secrets.
• The redirect URI saved in Curoxi must match the GitHub OAuth app exactly.
• Use a long random webhook secret. Do not reuse an easy-to-guess string.

1. In Curoxi, sign in as a company admin.
2. Open Settings.
3. Open Company GitHub.
4. Paste the GitHub Client ID from the OAuth app.
5. Paste the GitHub Client Secret from the OAuth app.
6. Paste the same GitHub Redirect URI that you configured in the OAuth app.
7. Generate a strong random webhook secret and paste it into GitHub Webhook Secret.
8. Save Company GitHub.

Step 3: Create the repository webhook in GitHub

Curoxi listens for GitHub pull request webhook deliveries on the backend. That is how pull request activity can update the linked task workflow in the project.

• GitHub will send a ping delivery after you create the webhook. That is normal.
• Curoxi currently processes pull_request webhook events in this flow, so you do not need to subscribe to every event.
• If you manage more than one repository for the project, add the webhook to each mapped repository.

1. In GitHub, open the target repository.
2. Open Settings.
3. Open Webhooks.
4. Click Add webhook.
5. Set Payload URL to your Curoxi backend webhook receiver, for example https://your-backend-domain/webhooks/github.
6. Set Content type to application/json.
7. Paste the same shared secret that you saved in Curoxi under GitHub Webhook Secret.
8. Choose Let me select individual events.
9. Select pull requests.
10. Keep the webhook Active and click Add webhook.

GitHub Docs: Creating webhooks

Step 4: Connect GitHub for the right project

After the company-level setup is complete, switch to the project where the repositories belong. GitHub connection and repository mapping happen in the selected project context.

• Map frontend and backend repositories separately if the project uses more than one repository.
• Do not connect the wrong customer project to a shared repository unless that is an intentional delivery model.

1. Log in and make sure the correct project is selected for your session.
2. Open Settings.
3. Open Project GitHub.
4. Click Connect GitHub.
5. Complete the GitHub authorization screen in the browser window that opens.
6. Return to Curoxi and click Fetch Repositories.
7. Select the repository from GitHub.
8. Set the branch prefix and base branch.
9. Mark the repository as default if needed.
10. Save the repository mapping.

Prerequisites for task-linked pull request updates

The webhook can only update tasks cleanly when Curoxi can match the pull request back to a task.

• The repository must already be mapped to the correct project in Curoxi.
• The webhook must be active on the repository.
• The pull request should carry the task reference in a way Curoxi can resolve.
• The task must exist in the target project and customer workspace.

Best way to get the strongest outcome

If your goal is reliable task-to-code tracking, keep the GitHub flow simple and consistent across projects.

• Use one clear OAuth app per environment so callback URLs stay clean.
• Keep the default branch prefix as feature whenever possible. The current webhook branch parsing works best with branch names like feature/ZRQ-123-task-title.
• If your branch naming differs, make sure the pull request body still includes the task marker such as ZRQ-123 so Curoxi can resolve the task.
• Map repositories only after the correct customer project is selected.
• Test with one small pull request before rolling the setup across every project.

What benefit this delivers

1. Cleaner project-level delivery tracking
2. Better visibility from task to branch to pull request
3. Less manual follow-up when pull requests open, update, or merge
4. More reliable release coordination across customer workspaces

Common mistakes to avoid

• Using the frontend domain as the webhook payload URL instead of the backend webhook URL
• Saving one redirect URI in GitHub and a different one in Curoxi
• Creating the webhook but forgetting to save the same secret in Curoxi
• Connecting GitHub in the wrong project session
• Expecting webhook-driven task updates before the repository mapping is complete

Explore Curoxi

Browse the core pages that explain how Curoxi works, how pricing is structured, and how to start a workspace.