> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/engineering-insights-classic/use-software-engineering-insights/setup-sei/configure-integrations/github-actions/index.md).

# GitHub Actions

Integrate Harness AIDI with GitHub Actions.

[GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) is a GitHub feature that enables you to automate various event-driven activities in GitHub, such as cloning a repository, generating Docker images, and testing scripts.

Over 10,000 GitHub Actions are available on the [GitHub Marketplace](https://github.com/marketplace?type=actions), and optionally, you can create your own Actions.

You can use the GitHub Action integration to integrate GitHub Actions with Harness SEI.

### Requirements <a href="#requirements" id="requirements"></a>

You can connect GitHub Actions to SEI in three ways: OAuth, a GitHub personal access token (PAT), or the GitHub App. The requirements depend on the method you choose.

**OAuth or PAT**

If you cannot use OAuth or the GitHub App, create a GitHub PAT to configure the SEI GitHub Actions integration.

1. Log in to your GitHub account and create a PAT. Go to the [GitHub documentation on personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) to create and manage one.
2. Select the following permissions for your PAT:
   * All repo scopes, including the parent repo scope. The top-level repo scope is required for Harness SEI to have the required visibility into your repos (repoadmin:org -> read:org permission).
   * If your GitHub organization uses SAML SSO, enable SSO for your PAT. Go to the [GitHub documentation on SAML SSO for personal access tokens](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) to authorize the token.

**GitHub App**

The GitHub App sends GitHub Actions events to SEI through webhooks. Use it when you want SEI to capture the inputs of manually triggered workflow runs. GitHub does not return those inputs through its REST API, so OAuth and PAT integrations cannot ingest them.

* **Permission to install GitHub Apps:** You must be able to install GitHub Apps on the GitHub organization or account that owns the repositories.
* **Manually triggered workflows:** Workflows must declare `on: workflow_dispatch`, with `inputs:` for the parameters you want SEI to capture.

{% code title=".github/workflows/deploy.yml" %}

```yaml
on:
  workflow_dispatch:
    inputs:
      environment:
        description: Target environment
        required: true
        type: choice
        options: [staging, production]
```

{% endcode %}

The GitHub App requests read access to repository Actions, Contents, and Metadata, and subscribes to the `workflow_dispatch` and `workflow_run` events. Harness hosts the webhook endpoint and verifies the signature of every delivery, so you do not configure a webhook URL or secret.

{% hint style="info" %}
If you have enabled an allowlist in your GitHub account, certain Harness IP addresses must be added to it in order to allow communication between the Harness Platform and GitHub. If the necessary IPs are not allowed, the integration may fail to authenticate or sync data properly.

To ensure your integration can work correctly, go to the list of [Harness Platform IPs](https://developer.harness.io/harness-platform/use-harness-platform/references/allowlist-harness-domains-and-ips.md) to find the addresses to allow in your firewall.
{% endhint %}

### Connect with GitHub Actions (Cloud) <a href="#connect-with-github-actions-cloud" id="connect-with-github-actions-cloud"></a>

1. Under **Data Settings**, select **Integrations**.
2. Select the **Available Integrations** tab, locate the **GitHub Actions** tile, and click **Add Integration**.
3. In the **Choose your Github Actions type** dialog, click the **Cloud** tile.
4. In the **Choose how you want to connect ?** dialog, choose the card for your authentication method.

{% tabs %}
{% tab title="Using OAuth" %}

1. On the **Using OAuth** card, click **Select**.
2. Follow the prompts to grant access to **GitHub**.
3. Enter an **Integration Name**.
4. Select repositories to associate with the integration or select **Ingest All Repos** to associate all current and future repos in your **GitHub organization**.
5. Click **Validate Connection** to run the preflight checks and validate the connection. Once successful, the integration appears under **My Integrations**.
   {% endtab %}

{% tab title="Using Personal Access Token" %}
This authentication method is suitable for various API interactions. The access token needs periodic renewal based on the timeline of the generated token.

1. On the **Using Personal Access Token (PAT)** card, click **Select**.
2. Enter an **Integration Name**.
3. Optionally, add a **Description** for the integration.
4. Enter the **Personal Access Token** that you generated earlier.
5. Click **Validate Connection** to run preflight checks and confirm the connection. Once validated, your GitHub Actions integration appears under **My Integrations**.
   {% endtab %}

{% tab title="Using GitHub App" %}
The GitHub App captures the inputs of manually triggered workflow runs through signed webhooks, and there is no PAT to rotate. Go to [Requirements](#requirements) to confirm your workflows declare `workflow_dispatch` inputs.

1. On the **Using GitHub App** card, click **Select**. The integration setup wizard opens on the **Provide GitHub Actions details** step.
2. In the **Install the GitHub App** panel, click **Install GitHub App**. GitHub opens in a new tab.
3. In GitHub, install the app on your organization, and choose all repositories or only the repositories that should send GitHub Actions data to SEI.
4. Copy the installation ID. After the installation, GitHub redirects you to a URL such as `github.com/settings/installations/154616012`, where the number is your installation ID. You can also find it later in your GitHub account or organization settings, under **Applications** > **Installed GitHub Apps**.
5. Return to Harness and click **Continue**.
6. On the **Finalize Integration** step of the wizard, enter an **Integration Name**. Optionally, add a **Description** and **Tags**.
7. In **Installation ID**, enter the installation ID you copied.
8. Click **Validate Connection** to confirm the connection. Once validated, your GitHub Actions integration appears under **My Integrations**.

![The Install the GitHub App step, with the Install GitHub App button and instructions to find the installation ID in the redirect URL](https://1124372887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEYDRcFDt1JPlcws7L5VL%2Fuploads%2Fgit-blob-dae5bf1e5869f9853bc0f1779ae4f9bf90e07e5b%2Fsei-github-actions-install-github-app.png?alt=media)

After the integration is connected, each manually triggered run sends a `workflow_dispatch` event with its inputs and a `workflow_run` event with the run ID. SEI matches the two events by repository, workflow, branch, and the user who triggered the run, then stores the inputs with that workflow run for CI/CD analytics.

{% hint style="info" %}
**Inputs missing from a workflow run**

SEI captures inputs only for runs triggered through `workflow_dispatch`, in repositories where the GitHub App is installed. If a run has no inputs in SEI, confirm the workflow declares `workflow_dispatch` inputs, the run was triggered manually, and the app installation includes that repository.
{% endhint %}
{% endtab %}
{% endtabs %}

### Connect with GitHub Actions (On-Prem) <a href="#connect-with-github-actions-on-prem" id="connect-with-github-actions-on-prem"></a>

To connect Harness SEI with an on-prem instance of GitHub Actions, you will need to use the [Ingestion Satellite](https://developer.harness.io/engineering-insights-classic/use-software-engineering-insights/setup-sei/sei-ingestion-satellite/run-the-satellite-container.md).

The steps for configuring the integration using the **Ingestion Satellite** is similar to configuring the integration on Cloud, with the exception of using satellite to communicate with the GitHub server.

1. In **Integration Name**, enter a **Name** for the integration.
2. Add a **Description** for the integration. (Optional)
3. Enter the **Personal Access Token** that you generated earlier.
4. In the **GitHub Actions URL** field, add the URL where your GitHub Actions instance is hosted.
5. Click on the **Download YAML File** button and save the `satellite.yml` file. Update it following the instructions [here](https://developer.harness.io/engineering-insights-classic/use-software-engineering-insights/setup-sei/sei-ingestion-satellite/run-the-satellite-container.md).

If you experience any issues while configuring the integration using the Ingestion Satellite, go to the [Ingestion Satellite Troubleshooting and FAQs](https://developer.harness.io/engineering-insights-classic/use-software-engineering-insights/setup-sei/sei-ingestion-satellite/satellite-troubleshooting-and-faqs.md).

Here is a sample `satellite.yml` file:

```yaml
satellite:
  tenant: <ACCOUNT_ID>
  api_key: <ACCOUNT_API_KEY>
  url: "https://app.harness.io/gratis/sei/api" 
  # Note that this URL is relative to the Environment of your Harness Account.
  
integrations:
  - id: "<INTEGRATION_ID>"
    application: github_actions
    url: "<GITHUB_INSTANCE_URL>"
    authentication: apikey
```

{% hint style="info" %}
The `Triage Rule` and `Trend` custom fields are not supported as the Stacks and Aggregation option when using the GitHub Actions integration.
{% endhint %}

<details>

<summary>Supported Reports</summary>

Following reports are supported for the GitHub Actions integration:

* CICD Job Count Report
* CICD Job Count Trend Report
* CICD Job Duration Report
* CICD Job Duration Single Stat
* CICD Job Duration Trend Report
* CICD Jobs Count Single Stat
* CICD Pipeline Jobs Count Report
* CICD Pipeline Jobs Count Trend Report
* CICD Pipeline Jobs Duration Report
* CICD Pipeline Jobs Duration Trend Report
* Deployment Frequency - Dora widget
* Change Failure Rate - Dora widget

</details>

### Re-authenticate the GitHub Actions integration <a href="#re-authenticate-the-github-actions-integration" id="re-authenticate-the-github-actions-integration"></a>

The re-authentication steps depend on how your GitHub Actions integration is configured.

#### OAuth (GitHub Cloud) <a href="#oauth-github-cloud" id="oauth-github-cloud"></a>

If you are using OAuth, re-authenticating as an [SEI Admin](https://developer.harness.io/engineering-insights-classic/use-software-engineering-insights/get-started/rbac.md#out-of-the-box-roles) refreshes the access token.

1. In GitHub, go to **Settings** → **Applications** → **Authorized OAuth Apps**.
2. Locate the **SEI app**.
3. Revoke access.
4. Return to Harness SEI.
5. Select your GitHub Actions integration.
6. Click **Re-Authenticate** and complete the OAuth flow.

#### Personal Access Token (PAT) <a href="#personal-access-token-pat" id="personal-access-token-pat"></a>

If you are using a PAT:

1. Generate a new PAT with the required scopes.
2. In Harness SEI, go to **Integrations**.
3. Select your GitHub Actions integration.
4. Click **Re-Authenticate**.
5. Enter the new token and validate the connection.

#### On-Prem (Satellite) <a href="#on-prem-satellite" id="on-prem-satellite"></a>

If your GitHub Actions data is ingested via Satellite:

1. Generate a new PAT from your GitHub instance.
2. Ensure the token includes required permissions.
3. Update the credentials in your Satellite configuration if applicable.
4. In Harness SEI, go to **Integrations**.
5. Select your GitHub Actions integration.
6. Click **Re-Authenticate**.
7. Re-authenticate the integration using the updated token.

Re-authentication ensures continued access and resolves issues caused by expired credentials or permission changes.

{% @harness-feedback/feedback %}
