Automate builds, tasks and deploys with GitHub Actions
Run code on GitHub's servers every time you push, on a schedule, or with one click. Free for most small projects.
How GitHub Actions works
Every workflow follows the same chain: an event starts a job, and the job runs its steps.
Workflow
A YAML file inside .github/workflows that describes what to automate.
Event
The trigger: a push, a pull request, a schedule or a manual button.
Job
A group of steps that runs on one fresh machine called a runner.
Step
One command (run) or one ready-made action (uses) inside a job.
Your first workflow
Four steps, about five minutes.
Create the workflow file
In your repo press Add file, then Create new file. Type the path below as the file name. The folders are created as you type the slashes.
.github/workflows/hello.ymlPaste this code
name: Hello
on:
push:
branches: [main]
workflow_dispatch:
jobs:
hello:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: echo "Hello from GitHub Actions"It runs on every push to main and also has a manual Run workflow button. YAML uses spaces for indentation, never tabs.
Commit the file
Press Commit changes on the main branch. The push itself starts the workflow.
Watch it run
Open the Actions tab, click the latest run, then the hello job. A green tick means success, a red cross means failure, and the logs show every step.
Triggers: when it runs
The on: section decides when a workflow starts. You can combine several.
| Trigger | Starts when | Example |
|---|---|---|
push | Code is pushed to a branch | branches: [main] |
pull_request | A pull request opens or updates | Run tests before merging |
schedule | A cron time arrives (always UTC) | cron: "30 1 * * *" is 07:00 IST every day |
workflow_dispatch | You press Run workflow | Manual deploy button |
release | A release is published | Build and attach files |
issues | An issue is opened or labelled | Auto-reply or auto-label |
repository_dispatch | Another app calls the GitHub API | Start a build from a bot or webhook |
Secrets and permissions
Keep API keys out of your code and give workflows only the access they need.
Add a secret
- Open the repo Settings, then Secrets and variables, then Actions.
- Press New repository secret, enter a name such as API_KEY and paste the value.
- Use it in a workflow as
${{ secrets.API_KEY }}. Logs mask it, but never print it on purpose.
Set permissions
Every run gets a temporary GITHUB_TOKEN. By default it may be read-only. Add a permissions: block for what you need, such as contents: write to commit files or pages: write to deploy Pages.
What you can do with it
Anything that is a repeatable task on code or data can become a workflow.
| Use | Usual trigger | Examples |
|---|---|---|
| Deploy your site | Push to main | GitHub Pages, Cloudflare or any host with a deploy action |
| Run tests and lint | Pull request | npm test, pytest, ESLint before merging |
| Scheduled scripts and bots | Schedule | Daily news or content generator, price checker, backups |
| Commit generated files | Schedule or push | Sitemap, RSS feed, README stats, data JSON |
| Build and release | Release or tag | Zip, APK, Docker image, npm or PyPI package |
| Send notifications | Any event | Telegram, Discord or email when a job finishes |
| Manage issues and PRs | Issues or PRs | Auto-label, welcome new contributors, close stale issues |
| Check quality | Pull request | Broken link checker, image compression, spell check |
| Keep dependencies fresh | Schedule | Dependabot version updates and security alerts |
Copy-paste examples
Replace file names, secret names and versions with your own. Check each action's page for its latest version.
Deploy a static site to GitHub Pages
First set Settings, then Pages, then Source, to GitHub Actions.
name: Deploy Pages
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v4
- uses: actions/upload-pages-artifact@v3
with:
path: .
- id: deployment
uses: actions/deploy-pages@v4Run a script every day and commit the result
name: Daily task
on:
schedule:
- cron: "30 1 * * *"
workflow_dispatch:
permissions:
contents: write
jobs:
run:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: node script.js
env:
API_KEY: ${{ secrets.API_KEY }}
- name: Commit changes
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add -A
git diff --cached --quiet || git commit -m "daily update"
git pushThe cron time is 01:30 UTC, which is 07:00 IST. Add API_KEY as a repo secret first.
Run tests on every pull request
name: Tests
on:
pull_request:
push:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm testSend a Telegram message when a job ends
Add this as the last step of any job. Create the secrets TG_TOKEN (from BotFather) and TG_CHAT (your chat id).
- name: Notify Telegram
if: always()
env:
TG_TOKEN: ${{ secrets.TG_TOKEN }}
TG_CHAT: ${{ secrets.TG_CHAT }}
run: |
curl -s "https://api.telegram.org/bot$TG_TOKEN/sendMessage" \
-d chat_id="$TG_CHAT" \
-d text="Workflow finished: ${{ job.status }}"Fix common errors
Open the failed run, expand the red step and read the last lines first.
| Problem | Fix |
|---|---|
| Workflow does not appear | The file must be in .github/workflows/, end in .yml or .yaml, and be on the default branch. |
| Invalid workflow file | Check indentation. Use spaces, not tabs, and keep list dashes aligned. |
| Permission denied when pushing | Add permissions: contents: write to the workflow. |
| Secret is empty | Check the name matches exactly. Forked pull requests do not receive secrets. |
| Schedule never runs | It runs only from the default branch, in UTC, and may be paused after 60 inactive days in public repos. |
| Command not found | Install the tool first, for example with setup-node or setup-python. |
Common questions
Is GitHub Actions free?
Yes for standard runners in public repositories. Private repositories get a monthly allowance that depends on your plan, and usage beyond it can be billed unless you set a spending limit.
How long can a job run?
A single job on a GitHub-hosted runner can run for up to 6 hours before it is stopped.
Can it replace a server?
Not for always-on apps. It is built for tasks that start, finish and stop, such as builds, deploys and scheduled scripts.
Where are the logs kept?
In the Actions tab. Uploaded artifacts and logs are kept for 90 days by default, and you can change that in the repository settings.