Why you need this guide and not another tutorial that repeats itself

Short version. You want automation that runs predictable shell scripts inside GitHub Actions so your CI does the boring work and not your future self. This guide gives the exact steps to create a shell script, make it executable, wire it into a workflow, and troubleshoot permission and path problems that will inevitably show up.

Make the script the way humans and runners expect

Put a file under scripts or in the repo root and start it with a proper interpreter line. Use bash if you are using bash features. Keep it small and testable.

#!/bin/bash
set -e
set -o pipefail

echo "Hello from the script"
# run build or test commands here

Notes

• set -e and set -o pipefail help fail fast so your job does not politely ignore errors
• Use relative paths that match where actions checks out the repo to avoid path surprises

Make it executable without drama

Runners are not mind readers. They need the execute bit. Locally run

chmod +x scripts/run_tests.sh

If you want the permission change to persist in the repo you can do

git add --chmod=+x scripts/run_tests.sh
git commit -m "make script executable"

Hook the script into a workflow and let automation do its job

Create a workflow file under .github/workflows that runs on a runner that matches your shell needs. If you need bash features pick a Linux runner such as ubuntu-latest. The workflow steps you need are simple

• checkout the repo using actions/checkout@v3 so the runner can see your files
• ensure the script is executable on the runner with chmod if you did not commit the execute bit
• run the script with a relative path like ./scripts/run_tests.sh

Example step list that you can adapt

# in your workflow job steps
use actions/checkout@v3
run chmod +x scripts/run_tests.sh
run ./scripts/run_tests.sh

Why that works

The runner executes the command using the default shell for the platform. On ubuntu-latest the default shell supports bash like behavior in most cases. If your script relies on bash specific builtins then ensure the shebang is correct and use a Linux runner.

Common failure modes and how to stare them down

• Permission denied. Either forget to commit the execute bit or skip chmod on the runner. Add a chmod step or commit the change with git add --chmod=+x
• Wrong runner. Windows and macOS have different default shells. If you need bash use a Linux runner
• Path not found. The repository is checked out into the workspace. Use relative paths and verify working directory if a step changes it
• Silent failures. Use set -e and set -o pipefail and exit codes so the job fails loudly and gives you a log to rage at

Debugging like a pro without crying

Logs are your friend. The Actions tab shows step by step output and failing line numbers. Add echo statements or a debug step that prints the workspace, ls output, and env so you are not surprised.

run echo "pwd is $(pwd)" && ls -la scripts

Quick checklist

• Create script with shebang and strict mode
• Make it executable locally or chmod in the workflow
• Use actions/checkout@v3 so the runner has the files
• Run the script with a relative path matching the checkout location
• Pick the correct runner for your shell features

If you follow these steps your script will run inside GitHub Actions and do the boring, repeatable work you paid for. If it breaks consult the logs and then add more echoes until you feel better.