Deploying applications to a Google Cloud Platform (GCP) server can be streamlined using GitHub Actions to automate the process. This guide demonstrates how to set up a GitHub Actions workflow that uses SSH, including the appleboy/ssh-action, to deploy code to a GCP instance. The workflow supports deployments to master and staging branches with distinct deployment paths.
Prerequisites
Ensure you have:
- A GCP instance with SSH access configured.
- A GitHub repository for your project.
- SSH keys are generated and added to your GCP instance and GitHub repository secrets.
- A deploy_gcp.sh script in your repository for deployment-specific tasks.
- (Optional) An example. env file for environment configuration.
Overview
The GitHub Actions workflow will:
- Trigger on pushes to the master or staging branches.
- Check out the repository code.
- Set up SSH access to the GCP instance using secrets.
- Deploy the code to the appropriate directory (/var/www/$REPO_NAME for master, /var/www/staging/$REPO_NAME for staging).
- Handle environment setup and execute a custom deployment script.
Setting Up GitHub Secrets
To securely connect to your GCP instance, you need to store sensitive information in GitHub Secrets. Follow these steps:
- Open your GitHub project and navigate to the Settings tab.
- In the left sidebar, click on Secrets and Variables and then select Actions.
- Click New repository secret to create a new secret.
- Add the following secrets:
- PORT: Enter the port number of your GCP Virtual Machine (e.g., 22 for default SSH).
- KEY: Provide the private SSH key for your GCP Virtual Machine.
- USERNAME: Enter the username for your GCP Virtual Machine (e.g., deployer).
- GCP_IP: Add the public IP address of your GCP instance (optional, for flexibility in the workflow).
GitHub Actions Workflow
Below is the workflow configuration that uses SSH to deploy to GCP. While the appleboy/ssh-action is an option for running SSH commands, the provided YAML uses a custom SSH setup for flexibility.
Instructions
- Open your GitHub project and navigate to the Settings tab.
2. In the left sidebar, click on Secrets and Variables and then select Actions.
3. Click on New repository secret to create a new secret.
4. Add a secret named PORT and enter the port number of your Virtual Machine as the value.
5. Add another secret named KEY and provide the SSH key for your Virtual Machine as the value.
6. Finally, add a secret named USERNAME and enter the username for your Virtual Machine as the value.
Once you have added these secrets, you are ready to use the SSH action in your GitHub Actions workflow. Here’s an example job that demonstrates how to run SSH commands on your Virtual Machine:
1. Checkout Repository
- Purpose: This step uses the actions/checkout@v3 action to fetch the repository’s code onto the GitHub Actions runner (a virtual machine running ubuntu-latest).
- Details: It ensures the latest code from the branch that triggered the workflow (master or staging) is available for subsequent steps. The @v3 specifies a stable version of the checkout action.
- Why It’s Needed: Without this, the workflow wouldn’t have access to the repository’s files, such as the deploy_gcp.sh script or example.env.
2. Set REPO_NAME
- Purpose: Extracts the repository name from the GITHUB_REPOSITORY environment variable (e.g., Highpolar-Softwares/my-repo becomes my-repo) and stores it in the REPO_NAME environment variable.
- Details: The basename command strips the owner prefix, and >> $GITHUB_ENV makes REPO_NAME available to subsequent steps. This is used to dynamically construct file paths and repository URLs.
- Why It’s Needed: The repository name is used in the deployment path (/var/www/$REPO_NAME) and the GitHub URL, making the workflow reusable across different repositories.
3. Set up SSH
Purpose: Configures SSH access to the GCP instance and GitHub for secure communication.
Details:
- Creates the ~/.ssh directory and writes the private SSH key (stored in the GitHub secret GCP_SSH_PRIVATE_KEY) to ~/.ssh/id_rsa.
- Sets restrictive permissions (chmod 600) to ensure the key is secure.
- Starts an SSH agent (eval “$(ssh-agent -s)”) and adds the private key (ssh-add) for authentication.
- Uses ssh-keyscan to add the GCP instance’s (GCP_IP) and GitHub’s host keys to ~/.ssh/known_hosts, preventing host verification prompts during SSH connections.
Why It’s Needed: This enables secure SSH connections to the GCP instance for deployment and allows Git operations (e.g., cloning) from the GCP instance without manual intervention.
4. Deploy to GCP
- Purpose: Connects to the GCP instance via SSH and executes a script to deploy the application.
- Details: This step is a complex SSH command that runs a multi-line script on the remote GCP instance. The script handles repository cloning/pulling, environment setup, and deployment. Let’s break down the script within the EOF block:
a. Initialize Variables and Logging
- Purpose: Sets up variables and ensures the script exits on any error.
- Details:
- set -e stops the script if any command fails.
- REPO_NAME is inherited from the earlier step.
- REPO_URL constructs the GitHub repository URL using a personal access token for authentication.
- BRANCH is set to the branch that triggered the workflow (master or staging) using github.ref_name.
- Logs the branch for debugging.
b. Determine Deployment Path
- Purpose: Sets the deployment directory based on the branch.
- Details:
- master deploys to /var/www/$REPO_NAME (e.g., /var/www/my-repo).
- staging deploys to /var/www/staging/$REPO_NAME (e.g., /var/www/staging/my-repo).
- Other branches cause the script to exit with an error.
- Why It’s Needed: This supports separate production (master) and testing (staging) environments on the same server.
c. Set Up Directory and Permissions
- Purpose: Prepares the deployment directory with correct ownership and permissions.
- Details:
- Changes ownership of /var/www/ to GCP_USER and the nginx group, ensuring both the user and Nginx can access files.
- Grants group write permissions (g+w) to /var/www/.
- Creates the parent directory of PROJECT_PATH (e.g., /var/www/ or /var/www/staging/) if it doesn’t exist.
- Navigates to the parent directory.
- Why It’s Needed: Ensures the deployment directory is accessible and writable, preventing permission errors during cloning or file operations.
d. Clone or Update Repository
- Purpose: Prepares the deployment directory with correct ownership and permissions.
- Details:
- Changes ownership of /var/www/ to GCP_USER and the nginx group, ensuring both the user and Nginx can access files.
- Grants group write permissions (g+w) to /var/www/.
- Creates the parent directory of PROJECT_PATH (e.g., /var/www/ or /var/www/staging/) if it doesn’t exist.
- Navigates to the parent directory.
- Why It’s Needed: Ensures the deployment directory is accessible and writable, preventing permission errors during cloning or file operations.
d. Clone or Update Repository
- Purpose: Prepares the deployment directory with correct ownership and permissions.
- Details:
- Changes ownership of /var/www/ to GCP_USER and the nginx group, ensuring both the user and Nginx can access files.
- Grants group write permissions (g+w) to /var/www/.
- Creates the parent directory of PROJECT_PATH (e.g., /var/www/ or /var/www/staging/) if it doesn’t exist.
- Navigates to the parent directory.
- Why It’s Needed: Ensures the deployment directory is accessible and writable, preventing permission errors during cloning or file operations.
d. Clone or Update Repository
- Purpose: Executes a custom deployment script (deploy_gcp.sh) to finalize the deployment.
- Details:
- Checks if deploy_gcp.sh exists.
- Makes it executable (chmod +x) and runs it.
- Exits with an error if the script is missing.
- Why It’s Needed: The deploy_gcp.sh script handles project-specific tasks (e.g., installing dependencies, building the app, restarting services), making the workflow flexible for different applications.
Conclusion
Overall Functionality
This GitHub Actions workflow automates the deployment of a repository to a GCP instance, supporting distinct environments for master (production) and staging (testing) branches. It:
- Triggers on pushes to master or staging.
- Checks out the code and sets up SSH access using a private key stored in GitHub Secrets.
- Connects to the GCP instance via SSH and performs the following on the remote server:
- Clones or updates the repository in the appropriate directory (/var/www/$REPO_NAME or /var/www/staging/$REPO_NAME).
- Configures permissions for the GCP_USER and nginx group.
- Sets up a .env file from example.env if needed.
- Runs a custom deploy_gcp.sh script for project-specific deployment tasks.
- Uses GitHub Secrets (GCP_SSH_PRIVATE_KEY, GCP_USER, GCP_IP) to securely manage sensitive data.
get in touchWe are always ready to help you and answer your questions
Your next big idea starts here. Connect with us today!
Contact Us
Our Location
D-9, Ground floor, sector-3, Noida Gautam Buddha Nagar, Noida, India 201301.
4th Floor
Jay Ambe Complex, Nainital, India 263139


