GitHub Actions provide a powerful and flexible way to automate your software workflows directly from your GitHub repository. With UpCloud’s robust and scalable cloud infrastructure, you can create a seamless deployment pipeline that enhances your development process.
Key benefits include:
- – Automated deployments triggered by code push or pull requests
- – Increased reliability and consistency in your deployment process
- – Easy integration with your existing GitHub workflow
- – Scalable infrastructure provided by UpCloud to handle your growing needs
This tutorial will guide you through creating a GitHub Actions workflow to deploy a basic text file to an UpCloud server using SSH.
Prerequisites
- 1. An active GitHub account with the ability to create repositories.
- 2. An UpCloud account with at least one deployed Linux server.
- 3. Basic understanding of YAML syntax, GitHub Actions concepts, and SSH.
- 4. Familiarity with using terminal/command line interfaces and basic Linux commands.
- 5. Understanding of basic security practices for handling SSH keys and sensitive information.
- 6. (Optional) Familiarity with CI/CD principles and cloud computing concepts.
Set Up Your UpCloud Server and SSH Keys
1. If you haven’t already, deploy a new UpCloud server.
2. Use SSH to connect to your UpCloud server. The default Linux username is root.
ssh [email protected]
3. Within the new server, we need to create a new key pair to allow the GitHub Actions workflow to connect to the UpCloud server.
Generate a new SSH key pair on the server. You may accept the defaults for the following prompt.
ssh-keygen -t rsa -b 4096 -C "[email protected]"
| Options | |
| -t | Specifies the type of key to create. |
| -b | Specifies the number of bits in the key to create. |
| -C | Provides a new comment. |
4. Add the newly generated public key to the authorized_keys file on your server:
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
Set Up GitHub Secrets and Environment
We will now add the newly generated public key to your GitHub account.
1. Copy the content of the public key file (usually `~/.ssh/id_rsa.pub`)
cat ~/.ssh/id_rsa.pub
ssh-rsa [TRUNCATED]AAAAB3NzaC1yc2EAAAADAQABAAACAQDQYdyOZ6YJjNRgHuzsUCiPZ5gkLM2XX6ykuagraQBnX+s3mrROENHH5Yud0lBO8S2yNKa+s/kleo8VLRocnwwO4VRuhqmFJ+70olPWlLjFd3AGn12pDBnF+beU5vP2cMsyCGcw0ZykA7TL0kQilLn9ShWPqHFOaP18fZcE5Wxcy6+Ai2hhodrySiUWa2n4H93BhBEjQtejGh8ExdTnPbtGKnYOMwx6aWY9UJhJgtI0mDSvNix9cramJNPxOSm9LuX0kkrmo9XefTzjfLblkCPeMDIk4cLxT8o09CmIEvVswW1Dmhgl3bNLg7YNQ== [email protected]
2. Go to your GitHub profile > Settings > SSH and GPG keys.
3. Click the New SSH key button and paste your public key.
4. Save the public SSH key.
Now we will proceed with setting up our GitHub repository for GitHub Actions.
1. For the repository you intend to use with GitHub Actions, go to your GitHub repository settings.
2. Navigate to Settings > Environments > New environment.
Note: The Environment settings may not be available to all repository types.
3. Create a new environment. For this tutorial, the environment is named Example, but you can use any name.
4. In the Example environment, add the following secrets:
| Secrets | |
| SSH_HOST | Your UpCloud server’s IP address. |
| SSH_USERNAME | The username to log in to your UpCloud server (usually “root”). |
| SSH_KEY | The private SSH key generated on your UpCloud server (the content of `~/.ssh/id_rsa`). |
Your Environment secrets should now look like this.
Note: If you don’t have an Environment section, then Actions secrets will work instead.
Create the GitHub Actions Workflow File
1. In your GitHub repository, create a new file: .github/workflows/deploy.yml.
2. Start with the basic structure. Mind the spacing for YAML files!
name: Build & Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
environment: Example # Change this to match your environment name!
Add Deployment Steps
We will use the actions checkout repository for GitHub Actions along with Appleboy’s SSH for Github Actions to connect and deploy to our UpCloud server. For additional information on GitHub Actions refer to GitHub’s official documentation.
Add the following steps to your workflow:
name: Build & Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
environment: Example # Change this to match your environment name!
steps:
- name: Checkout code
uses: actions/checkout@v2
- name: Debug - Print Secret Availability
run: |
echo "SSH_HOST is set: ${{ secrets.SSH_HOST != '' }}"
echo "SSH_USERNAME is set: ${{ secrets.SSH_USERNAME != '' }}"
echo "SSH_KEY is set: ${{ secrets.SSH_KEY != '' }}"
- name: Deploy to UpCloud
uses: appleboy/ssh-action@master
with:
host: ${{ secrets.SSH_HOST }}
username: ${{ secrets.SSH_USERNAME }}
key: ${{ secrets.SSH_KEY }}
port: 22
script: |
echo "Connected to host"
touch helloworld.txt
echo "hello world!" > helloworld.txt
echo "Deployment successful"
Commit and Push
Commit the deploy.yml file and push it to your main branch.
This will trigger the workflow.
Monitor the Workflow
1. Go to the Actions tab in your GitHub repository.
2. You should see your workflow running. If the workflow succeeds, you will see a checkmark.
3. Click on the workflow run to see detailed logs.
4. Check the output of the Debug – Print Secret Availability step to ensure your secrets are accessible.
Verify Deployment
1. SSH into your UpCloud server.
2. Check if the helloworld.txt file has been created.
root@example-server:~# pwd
/root
root@example-server:~# ls
helloworld.txt
root@example-server:~# cat helloworld.txt
hello world!
3. You have now established a successful connection between your GitHub repository and your UpCloud server. You may now modify the workflow to suit your needs.
Troubleshooting
- – If secrets are not available, double-check they are correctly set in your repository’s environment settings.
- – Ensure the SSH key has the correct permissions on your UpCloud server.
- – If the connection fails, verify that your UpCloud server’s firewall allows incoming SSH connections.
- – Make sure the public key is correctly added to both GitHub and the authorized_keys file on your server.
If GitHub Actions fails with:
- 1. Error: missing server host; ensure you have set the correct environment in your workflow file.
- 2. Error: You have an error in your yaml syntax on line #; double-check your spacing and indentation.
Next Steps
- – Set up a web server (like Nginx) on your UpCloud server to serve the deployed files.
- – Expand the workflow to deploy more complex applications or static sites.
- – Add additional security measures, such as IP restrictions or deployment approvals.
Remember to iterate and expand on this basic setup as your project grows and deployment needs become more complex.
Discussion