Connect GitHub to RIIW projects

RIIW connects GitHub development activity to project tasks through an organization GitHub App installation. A separate personal GitHub connection identifies you for attribution and future actions performed with your own GitHub permissions.

These connections have different jobs. The organization installation selects repositories and maps them to RIIW projects. Your personal connection does not independently expose private repositories to RIIW or replace the organization installation.

Before you begin

An organization owner, administrator, or custom role with Manage integrations can install and configure the GitHub App. Project members can view development activity when their project role includes View tasks. Adding a manual GitHub link requires Edit task details.

The RIIW platform super admin must configure the shared GitHub App first from Admin Panel → Integrations → GitHub App. The form provides the exact callback, setup, and webhook URLs to copy into GitHub. Secrets and the private key are encrypted at rest; deployment environment values remain read-only and take precedence. If the app detail shows GitHub App configuration required, no GitHub account has failed or expired; the platform configuration is simply not present yet.

Install GitHub for an organization

1. Open the intended organization and select Apps in its navigation section.
2. Select GitHub.
3. Select Install GitHub App.
4. In GitHub, choose the account or organization and grant access to all repositories or selected repositories.
5. Complete the follow-up GitHub authorization. RIIW uses it to verify that you can administer the returned installation.
6. Return to RIIW and confirm that the GitHub account and available repositories appear.

You can install the RIIW GitHub App for more than one GitHub organization. Repository access always follows the selection in GitHub. Adding a repository later triggers a repository synchronization through GitHub webhooks.

Map repositories to projects

Select a connected repository and a RIIW project under Repository to project mapping, then select Map repository. A repository can map to more than one project when necessary, but using one clear project is easier to understand and reduces ambiguous task references.

Unmapped repositories do not create task development links. Removing a mapping stops new automatic links; it does not delete task history that was already recorded.

Use task keys in GitHub

Every task has a stable key such as ENG-123. Include that key in any of these places:

• branch name, for example eng-123-add-export-filter;
• commit message;
• pull request title or description;
• GitHub issue title or description.

RIIW matches the key only against projects mapped to that repository. Push and pull request webhooks add the detected branch, commit, pull request, or issue to the task’s Development section. A newly linked pull request also receives a link back to the RIIW task when linkbacks are enabled.

Open a task and select Copy branch name to copy a branch-safe name based on its task key and title. Use Add link when an existing GitHub URL does not contain the task key.

Connect your personal GitHub identity

Open My apps, select GitHub, and then select Connect GitHub. The connection belongs only to your RIIW user. It lets RIIW associate GitHub identity with your profile and supports user-authorized GitHub actions as those commands become available.

Disconnecting your personal GitHub account does not remove organization installations, mappings, or previously recorded development links. Removing an organization installation does not disconnect personal identities.

Workflow automations

Repository mappings can define task status targets for pull request opened, closed, and merged events. RIIW applies only explicitly configured targets that exist in the project workflow. Keep automations small and predictable; a common starting point is moving a task to an in-progress status when a pull request opens and to a completed status when it merges.

Troubleshooting

If development activity does not appear, confirm that the repository is active in the GitHub installation, mapped to the correct RIIW project, and that the branch, commit, or pull request contains the exact task key. GitHub delivery retries are processed idempotently, so receiving the same webhook twice does not create duplicate links.

If an installation cannot be claimed, sign in to GitHub with an account that can administer that installation and repeat the setup. RIIW deliberately verifies installation access instead of trusting the installation identifier returned in the browser.