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.
This action requires:
-
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-keygentool 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.
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 }}'| 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". |
stdout: Stdout from ssh command.stderr: Stderr from ssh command.
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.
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'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'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'