README.md

ssh-compute

Compute SSH Github Action aims to provide an easy way to connect to GCP instances via ssh and execute user’s commands.

You should enable IAP TCP forwarding to establish an encrypted tunnel over which you can forward SSH connections to the VM.

Note, this action does not work when connecting to Windows VMs. Please, check this guide to know more how to connect to a Windows instance.

This is not an officially supported Google product, and it is not covered by a Google Cloud support contract. To report bugs or request features in a Google Cloud product, please contact Google Cloud support.

Prerequisites

This action requires:

• Enable the Cloud Identity-Aware Proxy API

• Create a firewall rule to enable connections from IAP.

• Grant the required IAM permissions to enable IAP TCP forwarding.

• Generate SSH keys pair and set a private key as an input param. See Create SSH keys tutorial to generate keys using ssh-keygen tool or use gcloud compute ssh command.

• Set Google Cloud credentials that are authorized ssh connection to the VM. See the Authorization section below for more information.

Usage

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
    - uses: 'actions/checkout@v4'

    - id: 'auth'
      uses: 'google-github-actions/auth@v2'
      with:
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        service_account: 'my-service-account@my-project.iam.gserviceaccount.com'

    - id: 'compute-ssh'
      uses: 'google-github-actions/ssh-compute@v1'
      with:
        instance_name: 'example-instance'
        zone: 'us-central1-a'
        ssh_private_key: '${{ secrets.GCP_SSH_PRIVATE_KEY }}'
        command: 'echo Hello world'

    # Example of using the output
    - id: 'test'
      run: |-
        echo '${{ steps.compute-ssh.outputs.stdout }}'
        echo '${{ steps.compute-ssh.outputs.stderr }}'

Inputs

Name	Requirement	Default	Description
instance_name	required		Name of the virtual machine instance to SSH into.
zone	required		Zone of the instance to connect to.
user	optional		Specifies the username with which to SSH. If omitted, the user login name is used. If using OS Login, USER will be replaced by the OS Login user.
ssh_private_key	required		SSH private key with which to SSH.
ssh_keys_dir	optional	Random directory in the temp folder	Path for a directory to store ssh keys.
container	optional		The name or ID of a container inside of the virtual machine instance to connect to. This only applies to virtual machines that are using a Google Container-Optimized virtual machine image.
ssh_args	optional		Additional flags to be passed to ssh tool. Example: '-vvv -L 80:%INSTANCE%:80'.
command	optional		A command to run on the virtual machine. Action runs the command on the target instance and then exits. You must specify at least command or script, specifying both command and script is invalid.
script	optional		A script file to run on the virtual machine. Action runs the script on the target instance and then exits. You must specify at least command or script, specifying both command and script is invalid.
project_id	optional		The GCP project ID. Overrides project ID set by credentials.
flags	optional		Space separated list of other compute ssh flags, examples can be found: https://cloud.google.com/sdk/gcloud/reference/compute/ssh/#FLAGS. Ex --ssh-key-expiration=2017-08-29T18:52:51.142Z.
gcloud_version	optional		Version of the Cloud SDK to install. If unspecified or set to "latest", the latest available gcloud SDK version for the target platform will be installed. Example: "290.0.1".

Outputs

• stdout: Stdout from ssh command.
• stderr: Stderr from ssh command.

Authorization

Via google-github-actions/auth

Use google-github-actions/auth to authenticate the action. You can use [Workload Identity Federation][wif] or traditional [Service Account Key JSON][sa] authentication. This Action supports both the recommended [Workload Identity Federation][wif] based authentication and the traditional [Service Account Key JSON][sa] based auth.

See usage for more details.

Authenticating via Workload Identity Federation

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
    - uses: 'actions/checkout@v4'

    - id: 'auth'
      uses: 'google-github-actions/auth@v2'
      with:
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        service_account: 'my-service-account@my-project.iam.gserviceaccount.com'

    - id: 'compute-ssh'
      uses: 'google-github-actions/ssh-compute@v1'
      with:
        instance_name: 'example-instance'
        zone: 'us-central1-a'
        ssh_private_key: '${{ secrets.GCP_SSH_PRIVATE_KEY }}'
        command: 'echo Hello world'

Authenticating via Service Account Key JSON

jobs:
  job_id:
    steps:
    - uses: 'actions/checkout@v4'

    - id: 'auth'
      uses: 'google-github-actions/auth@v2'
      with:
        credentials_json: '${{ secrets.gcp_credentials }}'

    - id: 'compute-ssh'
      uses: 'google-github-actions/ssh-compute@v1'
      with:
        instance_name: 'example-instance'
        zone: 'us-central1-a'
        ssh_private_key: '${{ secrets.GCP_SSH_PRIVATE_KEY }}'
        command: 'echo Hello world'

Via Application Default Credentials

If you are hosting your own runners, and those runners are on Google Cloud, you can leverage the Application Default Credentials of the instance. This will authenticate requests as the service account attached to the instance. This only works using a custom runner hosted on GCP.

jobs:
  job_id:
    steps:
    - uses: 'actions/checkout@v4'

    - id: 'compute-ssh'
      uses: 'google-github-actions/ssh-compute@v1'
      with:
        instance_name: 'example-instance'
        zone: 'us-central1-a'
        ssh_private_key: '${{ secrets.GCP_SSH_PRIVATE_KEY }}'
        command: 'echo Hello world'