GitHub Services

Third-party services that integrate with GitHub can help you do anything from enabling continuous integration to closing stale issues and pull requests. Services on GitHub can take multiple forms:

• GitHub applications: applications that are developed by third parties and listed on the GitHub Marketplace
• OAuth applications: applications that are authorized by a user, that then act on their behalf
• Token-based integrations: integrations, like browser or editor extensions, that use a user's personal access token to access the GitHub's API and user's data

You may use third-party services with Google repositories under certain conditions.

Third-party GitHub and OAuth applications

IMPORTANT: Hosted third-party services that require commit access to Google repositories cannot be used without a vendor security assessment (go/vsa).

Granting general read and write access grants full access to private and public repositories. This is an example of a permission dialogue that requests an overly-broad set of permissions:

TIP: You can search for a previous VSA assessment, though you may still need to initiate a new one, as assessments are per vendor per use case/engagement. See go/vsa-policy for more information.

Note that some services can operate in several different modes depending on how it is configured. These are fine to use provided that they only have read access to our repositories. Some services like CircleCI will sometimes use deploy keys to access your repository; these are only okay if they are read-only deploy keys.

If the service doesn't require commit access (public_repo or repo scope), then it's generally fine to use. Granting read/write access for repo hooks (write:repo_hook scope) and commit status (repo:status scope) is fine.

Third-party integrations

Code that was written by external parties but is managed by Googlers is also generally fine to use. Examples of external code managed by Googlers include a Jenkins instance running on GCP that is controlled completely by Googlers, or an extension that integrates GitHub functionality with a Googler's desktop application.

Google-authored applications and integrations

Code that is completely written by Googlers is generally fine to use, regardless of access level, however standard security precautions should always be taken (go/external-software-policy). For example, a tool your team wrote to migrate issues or leave comments on pull requests is fine. Granting Google Container Registry access to a GitHub repository is also fine.

GitHub Actions

go/github-actions

GitHub Actions allows the creation of automated workflows that will perform arbitrary actions in response to events that occur in a repository.

GitHub Actions may be used on Google repositories with the following conditions:

• When using a third-party action (one not hosted in a Google-managed org), a fixed version of the action MUST be used by specifying a specific commit, rather than a branch like "master", or a tagged release, which can be overwritten by any maintainer of the action. Docker images should always be run at a fixed version rather than "latest".

• If an action is being granted additional GitHub access (e.g. being passed the GITHUB_TOKEN variable), all main development branches (typically, "master") must use branch protection with "Require pull request reviews before merging" enabled and/or "Restrict who can push to matching branches" limited to repository admins. (See go/github-docs/security for additional security best practices.)

• Be aware that GitHub Actions that run on private repositories will have access to the content, and can potentially transmit that content to a third-party. Make sure that any actions you use on private repositories are not leaking anything.

GitHub Actions best practices

Set a job timeout

The default setting for job timeout (jobs.<job_id>.timeout-minutes) in GitHub Actions is six hours. This can result in workflows in other repos being queued and/or quota getting used unnecessarily.

jobs:
  example-job:
    runs-on: ubuntu-latest
    timeout-minutes: 30

Cancel workflows

Use concurrency to prevent previous workflows from running. This can occur in PRs where the author raises multiple commits in quick succession.

concurrency:
  group: $\{\{ github.head_ref \}\}
  cancel-in-progress: true`

GitHub Apps

GitHub apps are fine to use but write access to repos should only be granted to GitHub apps that are managed by Google OR external services that have an approved VSA. For information about using third-party GitHub apps, see Third-party GitHub and OAuth applications.

For organization owners

As an owner of an organization, you may receive requests from members of your org to install GitHub or OAuth apps. When reviewing these installation requests, pay close attention to the permissions they are requesting.

If the app complies with the above guidance, you may approve the request.