Skip to content

GitHub Integration Guide

This guide provides step-by-step instructions on how to connect your GitHub repository with the AppAmbit Dashboard to enable automated CI/CD workflows.

Prerequisites

Before you begin, ensure you have an existing GitHub repository with a configured workflow file at .github/workflows/ that generates the required build artifacts. The only requirement is that the artifact uses the correct file extension for the selected platform. Artifact Naming and Loading.

Step 1: Create a Personal Access Token

The AppAmbit Dashboard needs a Personal Access Token to communicate securely with your GitHub repository.

  1. Go to your GitHub account, click your profile picture (top-right), and select Settings. Settings (light) Settings (dark)

  2. In the left menu, click Developer settings. Developer Settings (light) Developer Settings (dark)

  3. Select Personal access tokens > Tokens (classic) and click Generate new token (classic). Generate token (light) Generate token (dark)

  4. Configure the token with the following settings:

    • Note: Give your token a descriptive name (e.g., "AppAmbit Dashboard Integration").
    • Expiration: Set an appropriate expiration date.
    • Scopes: Grant the following permissions:
      • repo: Full control of private repositories
      • workflow: Update GitHub Action workflows
      • read:packages: Download packages from GitHub Package Registry Token permissions(light) Token permissions (dark)

  5. Click Generate token. Generate token button (light) Generate token button (dark)

Save Your Token!

GitHub will only show you the token once. Copy it immediately and store it in a secure place. You will need this for Step 3. If you lose it, you must create a new one. Copy token(light) Copy token (dark)

Step 2: Configure the Webhook

The webhook notifies the dashboard whenever a workflow completes.

  1. Navigate to your repository and click the Settings tab. Repository settings (light) Repository settings (dark)

  2. In the left sidebar, select Webhooks. Webhooks menu (light) Webhooks menu (dark)

  3. Click Add webhook. Add webhook (light) Add webhook (dark)

  4. Fill in the configuration form:

    • Payload URL: Your dashboard's webhook endpoint. 
      https://appambit.com/github/webhook/YOUR_APP_KEY_HERE
    • Content type: application/json
    • Secret: Paste the Webhook Secret. For instructions on how to generate it, see the Securing Your Webhooks section in our overview guide.
    • SSL verification: Enable SSL verification
    • Triggers: Select Workflow runs. This ensures the webhook fires when workflows complete. Webhook configuration (light) Webhook configuration (dark)

  5. Click Add webhook to save the configuration. Webhook configuration (light) Webhook configuration (dark)

Tip

For a quick start, use GitHub's official Actions templates for your technology stack. These templates provide a solid foundation and can be customized to fit your deployment process.

Step 3: Configure AppAmbit Dashboard

The final step is to provide your repository details and the Personal Access Token to the dashboard.

  1. Navigate to your App's Edit view in the AppAmbit Dashboard.
  2. Fill in the following fields:
    • Repo name: Enter your GitHub repository name in the format owner/repository-name.
    • Delivery token: Paste the GitHub Personal Access Token you created in Step 1. AppAmbit release information (light) AppAmbit release information (dark)
  3. Click Save changes.

Configuration Complete!

Your GitHub repository is now fully integrated. From now on, successful workflow runs will automatically appear in your Releases Section.

Troubleshooting

  • Ensure the webhook URL and secret are correct.
  • Verify workflow artifacts are generated as expected.
  • Check permissions for the Personal Access Token.
  • Review GitHub Actions (Webhooks) logs for errors.

Next Steps

Learn about Bitbucket CI/CD integration