GitHub Actions: Automating Your Project

⚙️ GitHub Actions are tools that run automatically when certain things happen in your repository. They can test your code, build your docs, publish your package, and more.

In template-project, GitHub Actions live in the .github/workflows/ folder.

---

🤖 What Is a GitHub Action?

A GitHub Action is a set of instructions that GitHub runs in response to events like:

• Opening a pull request

• Pushing new code

• Creating a release tag

Each Action is defined in a .yml file inside .github/workflows/.

---

🧪 tests.yml: Run Your Tests Automatically

When it runs:

• Every time you open or update a pull request

What it does:

• Sets up Python

• Installs your dependencies

• Runs pytest to check your code

Why it matters:

• Makes sure new code doesn’t break old code

• Helps catch bugs early

---

🧱 docs.yml: Test Your Documentation Build

When it runs:

• On every pull request to main

What it does:

• Builds your documentation using Sphinx

• Ensures you haven’t broken the docs accidentally

Why it matters:

• Keeps your docs up to date with your code

• Warns you if a bad docstring or config breaks the build

---

🚀 docs_deploy.yml: Publish to GitHub Pages

When it runs:

• After a pull request is merged into main

What it does:

• Rebuilds the documentation

• Publishes the result to the gh-pages branch

Why it matters:

• You get a public documentation site (e.g., https://yourusername.github.io/your-repo)

---

📦 pypi.yml: Publish a Package to PyPI

When it runs:

• When you push a GitHub release tag (e.g., v0.1.0)

What it does:

• Builds your Python package

• Uploads it to PyPI using secure GitHub credentials

Why it matters:

• Makes your code pip install-able by others

---

🛠️ How to Customize These Workflows

Look in .github/workflows/*.yml files. You’ll see sections like:

• on: — what triggers the workflow

• jobs: — what steps to run

Each step can run shell commands or call existing actions (e.g., actions/setup-python).

If you want to:

• Add coverage reports → modify tests.yml

• Deploy to a different site → update docs_deploy.yml

• Use conda instead of pip → swap the environment setup steps

---

✅ Summary

GitHub Actions in this template help you:

• Test every pull request

• Keep documentation working

• Publish code to the web or to PyPI automatically

💡 You don’t have to do anything to use them — they just work when you push code to GitHub!