A complete beginner's guide to setting up your first GitHub Actions workflow

What are GitHub Actions?

GitHub Actions is GitHub's built-in automation platform that lets you create workflows to automatically build, test, and deploy your code. Think of it as having a virtual assistant that can perform tasks whenever specific events happen in your repository.

Real-world analogy: It's like setting up automatic rules in your email - "When someone sends a message with 'urgent' in the subject, forward it to my phone." GitHub Actions works similarly: "When someone pushes code to main branch, automatically run tests and deploy if they pass."

🏗️ The Foundation: Repository Structure

The Special .github Folder

Every GitHub Actions setup starts with a special hidden folder in your repository:

your-repository/
├── src/
├── package.json
├── README.md
└── .github/              ← This is the magic folder
    └── workflows/        ← All automation lives here
        ├── ci.yml        ← Your workflow files
        ├── deploy.yml
        └── tests.yml

Why .github?

• The dot (.) makes it hidden on most systems
• GitHub automatically scans this folder for automation instructions
• It's a convention that keeps automation separate from your actual code

The workflows Directory

Inside .github/workflows/, you place YAML files that define your automation:

.github/workflows/
├── main.yml           ← Main CI/CD pipeline
├── pull-request.yml   ← PR validation
├── nightly.yml        ← Scheduled tasks
└── release.yml        ← Release automation

Key points:

• Each .yml or .yaml file is a separate workflow
• You can have multiple workflows in one repository
• File names can be anything descriptive

📝 YAML Basics for GitHub Actions