GitHub Integration - Script Runner and Terraform

Collect evidence from GitHub using Script Runner or Terraform data blocks

Written By Micah

With the GitHub integration, you can collect evidence of your git settings and configurations directly from GitHub. This integration supports two collection methods — Script Runner and Terraform — so you can choose the approach that best fits what you're trying to collect. Both methods use the same authentication setup and support automated collection.

Types of evidence you might collect

There are a lot of different types of evidence you can collect from GitHub, including:

  • User access lists for your code repositories

  • Protected branch settings

  • Release status

  • Artifacts from your CI/CD pipelines

<a href="https://help.strikegraph.com/en/articles/15024407-script-runner-for-integrations" target="_blank">Script Runner makes it easy to collect common evidence types using pre-built scripts, and is just as powerful when used with custom scripts for more advanced needs. Terraform data blocks offer an alternative collection method using HCL, limited to the data sources supported by the GitHub Terraform provider.

Important note: You do not need to use Terraform in your tech stack in order to use this integration.

Setting up the integration

The GitHub integration requires a Personal Access Token (PAT) whose resource owner is the GitHub organization you want access to (not your personal account). This is the most common setup mistake and the root cause of most integration failures.

Personal Access Token Setup

Option 1: Fine-grained PAT (recommended)

Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens → Generate new token.

  • Resource owner: Set this to the organization (e.g., Strike-Graph), not your personal account. The dropdown defaults to your user — you have to change it.

  • Repository access: "All repositories" or "Only select repositories" with each target repo explicitly added. Repos created after the token is issued won't be included automatically.

  • Repository permissions minimums (read-only on each):

    • Metadata — required by default

    • Administration — required for github_branch_protection_rules; branch protection data lives under admin permissions, not contents

    • Contents — required for repo content data sources

    • Any additional read-only permissions required for the data you plan to collect

If your organization has fine-grained PAT policies enabled, the token will sit in a pending approval state until an org admin approves it. It won't work until that approval goes through.

Option 2: Classic PAT

Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Tokens (classic).

  • Scope: repo (full)

  • After creating the token, find it in the token list, click "Configure SSO", and authorize it for your organization. Without this step, the token will work against personal repos but fail on org repos protected by SAML — even with the correct scope.

Classic PATs span all organizations the user belongs to, so one token can cover multiple orgs.

Once you have your token, navigate to Integration Manager > GitHub > Create new and paste the token into the appropriate field. Give the integration a name, and confirm the organization that is configured with the token.

You can create as many GitHub connections as you need, so that you can manage the scope integrations as necessary. Please note that everyone with access to your GRC organization will be able to use any configured GitHub connections during evidence collection.

Collecting evidence

Once your integration is configured, navigate to the evidence item you want to collect for and click Attach Directly or Automated Collection. Select your GitHub - Scripts & Terraform integration from the list of available integrations. If you have configured multiple GitHub integrations, make sure you select the one with the right permissions for the evidence that you plan to collect.

The evidence collection form has two tabs: Scripts and Terraform. Choose the method that works best for your needs.

Using Script Runner

The Scripts tab lets you collect evidence using Strike Graph's library of pre-built compliance collection scripts. No code required — just search, preview, and run.

  1. Select the Scripts tab.

  2. Use the search box to find a relevant script. The search is pre-populated with your evidence item's name as a starting point, but you can adjust as needed.

  3. Browse the results. Each script card displays the script name, category, a short description, and the GitHub services it targets.

  4. Optionally, click Preview on any script card to review its full details and source code before running it.

  5. Click Run to execute the collection.

Strike Graph will run the script and attach the results to your evidence item. A loading indicator will appear while the script runs — this may take a moment to complete. Once finished, the modal will close and the collected data will appear as an attachment.

Writing custom scripts (Advanced)

If the pre-built scripts don't cover your needs, you can write your own Python script using the Advanced button at the top of the Scripts tab. Custom scripts must be read-only — write operations are blocked before execution. Your script should return the data you want collected as evidence.

The custom script editor includes validation that checks for forbidden patterns (write calls, unsafe code execution) and provides feedback before the script runs.

Using Terraform Data Blocks

The Terraform tab lets you write your own HCL data blocks to collect from specific GitHub data sources. This approach gives you the most flexibility and is well suited for evidence types that aren't covered by the available scripts.

Terraform integrations use "data blocks" to define what data to collect. More information about data blocks and local values can be found on the Terraform overview page. A full list of supported data sources is available at the bottom of this page and on the Terraform GitHub provider page.

Step 1: Define the data block. Data blocks are extensible, but follow a typical pattern:

  • data_source: this defines which GitHub setting we should read from. Terraform for GitHub supports data collection from any resource with a supported data source from Terraform's GitHub provider (see below for a list).

  • temp_name: this is a temporary name you define and is used to refer to this data block during execution. It only has labeling significance within the scope of this configuration. The temp name is used in the output's filename, so it's recommended that you name it with something recognizable. Names can be repeated across configurations, are limited to alphanumeric characters, and do not allow spaces.

  • query constraints / arguments – Many data sources require specific argument(s) to be included (like the name of the resource you're pulling data from), or provide methods for constraining the data based on specific queries so that you can tailor the output. These are written as key/value pairs and can include multiple arguments as accepted by the data source. Refer to the specific data source requirements in the Terraform GitHub provider documentation.

Step 2: Define the local values used for the execution. This also follows a typical pattern that is derived from the data block: data.data_source.temp_name (sometimes followed by a key if a filter argument is desirable).

Run the data collection

After you have defined the data block and local values, click the "Attach" button to execute the data collection. This may take a few minutes as we set up the data pipeline to collect the attachment.

Once the collection is finished, the attachment modal will close and you can see the collected data has been added to the evidence. You can confirm what was collected by clicking on the attachment to view the data.

Automated Collection

It is highly recommended that you configure your evidence collection with automated collection. Both Script Runner and Terraform support automated collection. With Automated Collection, Strike Graph can recollect evidence attachments from GitHub a few days before expiration so that your evidence remains in an effective 'audit ready' state.

To configure your evidence with Automated Collection, follow the steps above after clicking on the "Automated Collection" button found on the evidence item detail pages. Additional information about Automated Collection is available here.

Removing your GitHub integration

You can remove the integration at any time. Please note that removing an integration does not delete any files that were attached using that integration. Removing an integration will also disrupt automated collection.

To remove:

  1. Go to the Integrations Manager and click on the GitHub integration card to access the integration configurations.

  2. Click the "Deactivate" button next to your configuration.

Note: You may have access to remove integrations for other users on your team.

If you are fully removing access between Strike Graph and your GitHub system, you may also wish to delete the access token that you set up during configuration. Before deleting, verify that you are not using it for other purposes.

Troubleshooting

For additional Terraform troubleshooting tips, click here.

Terraform integrations will return an error if we were unable to execute the collection request. The errors returned will be different depending on which step of the collection failed.

Errors when setting up an integration

If you receive an error while setting up an integration, check if there is a specific error message at the top of the form. Possible errors include providing a project id that’s not associated with the credential configuration, or providing a malformed credential configuration (which would most likely be due to a copy+paste error).

General formatting errors

If the error message returned during evidence collection is pretty generic (like "Something went wrong") it may be a formatting issue. Check that your temp_name is formatted correctly (no spaces, only alphanumeric characters) and that there are not any other unexpected characters or formatting issues in the data block or local values.

Check permissions

If it is a permissions error, ensure that you have given your service account the necessary read-only permissions to access the resource.

Confirm the data_source requirements

Check that the resource you defined in the data_source is available from the GitHub Terraform provider, and ensure that you have included any required query constraints / arguments.

Confirm the local values

Confirm that the local values are formatted correctly. Typically, the local value should start with "data" (as described above) and include the data_source and temp_name. Check that the data_source and temp_name values are the same between the data block and local values.

The list of supported GitHub data sources

The following list is a snapshot of supported data sources from the GitHub Terraform provider. For up-to-date support and specific data source requirements, visit the Terraform documentation.