Source control integrations can be configured for both Self-Hosted Runners and Ona Cloud. You can set up a GitHub integration during runner creation or in the runner settings. Self-hosted GitHub instances are supported by changing the Host during setup.

​
Configuring GitHub Access

You can skip this step if someone has already set up the runner for you and SCM integration with GitHub has already been configured. In that case, you can go directly to Authorizing GitHub Access. This step allows administrators to configure what authorization methods (OAuth, PATs) and SCM providers (GitHub, GitLab, Bitbucket, Azure DevOps) will be available for authorization.

​
Self-Hosted Runners

For self-hosted runners (like AWS), GitHub integration is configured during runner creation or in the runner settings. There are two ways to integrate with GitHub. Both can be used simultaneously:
  1. OAuth App (Recommended): Using an OAuth app allows users to sign in more quickly. You’ll need to set up an OAuth app within Ona.
  2. Personal Access Token (PAT): Each user will need to create a Personal Access Token. They will be provided with a deep link to do so on their first environment creation.

​
Using OAuth

  1. Go to Settings > Runners and select the runner for which you want to configure OAuth.
  2. Navigate to the “Configure repository access” section and click “Add a new provider”.

    Add new provider

  3. Select GitHub from the list of providers.
  4. In the modal that opens, toggle “Enable OAuth”.

    Enable GitHub OAuth

  5. Follow the instructions in GitHub’s docs to create an OAuth app.
    • The app name can be any name you like
    • For the homepage URL, you can use https://app.gitpod.io/
    • You can get the callback URL from the SCM configuration dialog
  6. After creating the OAuth app, provide the Client ID and Client Secret in the runner configuration dialog. The client secret will be encrypted with the runner’s public key, ensuring only the runner can read it.
  7. Save your changes

​
Using Personal Access Tokens (PATs)

  1. Go to Settings > Runners and select the runner for which you want to configure the PAT.
  2. Navigate to the “Configure repository access” section and click “Add a new provider”.

    Add new provider

  3. Select GitHub from the list of providers.
  4. In the modal that opens, toggle “Enable Personal Access Token”.

    Enable GitHub PAT

  5. Save your changes

​
Ona Cloud

For Ona Cloud, GitHub authentication is managed through organization settings:
  1. Organization administrators configure GitHub access in Settings -> Runners -> Ona Cloud
  2. github.com is configured by default via OAuth
  3. For self-hosted GitHub instances:
    • Administrators must add the custom host in the settings
    • Users cannot authenticate with these hosts until they are configured
  4. Users authenticate using the methods your organization enables (OAuth and/or Personal Access Tokens)

​
Authorizing GitHub Access

​
Using OAuth

  1. When creating your first environment, you will be asked to authorize the new application. A new window will open that directs you to GitHub to authorize the OAuth app.
  • The requested scopes are repo, read:user, user:email, and workflow.
  • The repo permission is required so that your environment can clone the repository.
  • The read:user permission is required so that the git author name can be set in the environment.
  • The user:email permission is required so that the git author email can be set in the environment.
  • The workflow permission is required so that GitHub Action YAML files can be edited in the environment.
  1. After you have authorized, you can close the window and go back to the environment details screen.

​
Using Personal Access Tokens (PATs)

  1. The first time a user creates an environment, they will be asked to enter a Personal Access Token.
    • Click the link provided on the screen to access the configuration dialog for creating a GitHub token.
    • The name of the token and all required scopes are pre-set.
    • By default, the token is valid for 30 days, but you can change the duration if needed.

      Set GitHub PAT

  2. After creating the token, return to the dialog and paste the token.
  3. The environment will now be created using the provided token.

​
Granting Access to Additional GitHub Organizations

After your initial OAuth authorization, you may need to grant Ona access to additional GitHub organizations to work with repositories from those organizations. This is a common scenario when you join new organizations or when organizations are added to your GitHub account after your initial setup.
This section applies to OAuth-based authentication. If you’re using Personal Access Tokens (PATs), you’ll need to ensure your token has access to the required organizations when creating the token.

​
When You Need Additional Organization Access

You’ll need to grant additional organization access when:
  • You try to create an environment from a repository in an organization that wasn’t previously authorized
  • You receive an error message indicating insufficient permissions for a specific organization
  • You join a new GitHub organization and want to use Ona with repositories from that organization

​
Granting Access via GitHub Settings

To grant Ona access to additional GitHub organizations:
  1. Navigate to GitHub OAuth Applications: GitHub OAuth Applications list
  2. Review Current Organization Access:
    • Click on the Ona Cloud application to view its details
    • You’ll see a list of organizations and their access status
    • Organizations may show as “Granted”, “Denied”, or “Request access”
    OAuth app organization permissions
  3. Grant Access to New Organizations:
    • For organizations showing “Request access”, click the “Request” button
    • For organizations you own, access will be granted immediately
    • For organizations you don’t own, an access request will be sent to the organization owners
  4. Organization Owner Approval (if required):
    • If you’re not an owner of the organization, the organization owners will receive a notification
    • They can approve or deny the request from their organization settings
    • You’ll receive an email notification once the request is processed

​
Troubleshooting Organization Access Issues

Problem: “Repository not found” or “Access denied” errors Solution:
  • Verify you have access to the repository on GitHub directly
  • Check that the organization has granted access to the Ona OAuth application
  • Ensure you’re a member of the organization with appropriate repository permissions
Problem: Organization doesn’t appear in the OAuth app settings Solution:
  • Confirm you’re a member of the organization on GitHub
  • Check if the organization has restricted OAuth app access
  • Contact your organization administrator to enable third-party application access
Problem: Access request is pending for too long Solution:
  • Contact your GitHub organization owners/administrators
  • Ask them to review pending OAuth application requests in their organization settings
  • Provide them with the Ona Cloud application details for easy identification

​
Organization Administrator Considerations

If you’re a GitHub organization administrator and users are requesting access for Ona:
  1. Review the Application:
    • Go to your organization’s Settings > Third-party access
    • Review the Ona Cloud application request
    • Verify the requested permissions align with your organization’s policies
  2. Grant or Deny Access:
    • Click “Review” next to the Ona Cloud application
    • Review the permissions and user who requested access
    • Click “Grant” or “Deny” based on your organization’s policies
  3. Set Organization Policies:
    • Consider setting up organization-wide policies for OAuth applications
    • You can require approval for all applications or pre-approve trusted applications
    • Configure these settings in your organization’s Third-party access settings