Recommended Free Tools
The fastest way to learn GitHub Actions is to write one small workflow in a real repository, run it, and read the logs before adding anything else. The account behind this title is personal: a first attempt that didn’t work, and a second, AI-assisted attempt that did. Those sessions can’t be reconstructed independently, so this article doesn’t rely on them as proof. Instead it covers the parts you can check yourself: how a workflow is built, how to get a first run working, how to read a failure, and where AI assistance fits.
What GitHub Actions does, in one model
GitHub describes Actions as a CI/CD platform for automating build, test, and deployment work. Its workflow documentation gives a useful chain of parts: a workflow starts from an event, a manual trigger, or a schedule; it contains jobs; each job runs on a runner; and each job contains steps, where each step runs a script or a reusable action. The table below maps those parts to the YAML keys you will actually type. Source: GitHub Docs, “Workflows”.
As an Amazon Associate I earn from qualifying purchases.
| Part | Where it lives | What it does | YAML key |
|---|---|---|---|
| Workflow | A .yml or .yaml file in .github/workflows/ |
Defines the whole automation | Top level of the file |
| Trigger | Top of the file | Decides when the workflow starts, such as on a push, a pull request, a manual run, or a schedule | on: |
| Job | Under jobs: |
A unit of work with its own runner | jobs: with a job ID you choose |
| Runner | Inside a job | The machine the job executes on | runs-on: |
| Step | Under steps: |
One action, run in order within its job | steps: list items |
| Script step | Inside a step | Runs shell commands you write | run: |
| Action step | Inside a step | Runs a reusable action, often from another repository | uses: |
What you need before you start
- A GitHub repository you are allowed to push to. A personal test repository is enough.
- Actions enabled for that repository. Check under the repository’s Settings > Actions > General. Labels can change, so look for the Actions policy if the path differs.
- Basic familiarity with repositories, commits, and pull requests. GitHub’s Quickstart for GitHub Actions assumes this background and is the official free starting point.
Build a first workflow
Follow these steps in a test repository. Each one ends with something you can see, so you know whether the step worked before moving on.
- Open the repository on github.com and select Add file > Create new file.
- In the file name box, type
.github/workflows/first-workflow.yml. Typing the slashes creates the folders automatically. - Paste the example below into the editor.
- Commit the file to your default branch, or to a new branch and open a pull request. Either way, the push will trigger the workflow.
- Select the Actions tab. A run named after your commit message should appear, first yellow while it runs, then green or red.
- Click the run, then the job named
hello, and expand each step to read its output.
name: First workflow
on: push
jobs:
hello:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Show what ran
run: |
echo "Repository: $GITHUB_REPOSITORY"
echo "Commit: $GITHUB_SHA"
ls -la
The @v4 pin on the checkout action was current when this was written. Check the action’s README for the latest major version before you copy the line into a production workflow.
#1 Best Overall
Read the file one line group at a time
on: decides when it runs
on: push starts the workflow whenever anyone pushes to the repository. This is the broadest trigger. Other common values include pull_request and workflow_dispatch, which adds a manual Run workflow button. A trigger can also be narrowed, for example to a single branch, once the basic run works.
runs-on: chooses the machine
runs-on: ubuntu-latest asks GitHub to run the job on a hosted Linux runner. The job starts from a fresh environment, which is why the first step uses actions/checkout: without it, the runner has none of your repository’s files.
steps: with uses: and run:
A uses: step pulls in a prepared action, identified by owner, name, and version. A run: step executes shell commands exactly as you would type them into a terminal. The name: line is only a label that appears in the logs. Steps run in order, and if one fails, the job stops.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →When the first run fails
Most first-run failures come from a small set of causes. Check them in this order.
- The workflow doesn’t appear in the Actions tab. The file must sit directly in
.github/workflows/, and its extension must be.ymlor.yaml. A YAML indentation error can also prevent the file from being read; use two spaces per level and avoid tabs. - The run never starts after a push. The trigger may be narrower than you think, for example restricted to a branch you did not push to, or Actions may be disabled for the repository.
- A step shows a red X. Open that step’s log and find the first error line, which usually names the cause. A
run:command that exits with a non-zero code fails its step, so a typo in a command is the most common case. - A value is empty or missing. Check the spelling of the variable or secret name against the workflow.
Keep credentials out of the YAML
Never paste a token, password, or API key directly into a workflow file. Anyone with read access to the repository can see the file, and the value stays in the commit history even after you delete it. Store the value in the repository’s Settings > Secrets and variables > Actions page, then reference it through the secrets context, for example ${{ secrets.EXAMPLE_TOKEN }}, where EXAMPLE_TOKEN is the name you chose. GitHub’s workflow syntax reference documents the secrets context.
Where AI helps, and where it doesn’t
GitHub publishes a tutorial, Develop agentic workflows in GitHub Actions, that describes using a coding agent to write and refine workflow instructions, compile the workflow, and then review the generated files. That is a documented way to build workflows. It does not show that AI improves learning outcomes for everyone, and the account behind this title is one person’s experience.
Prompts that teach rather than just produce
- Paste your own working file and ask for a line-by-line explanation of each key, such as
on,runs-on, andsteps. - Ask for a workflow for one specific goal, such as running a test command on every pull request, rather than a general “CI setup.”
- Paste the first error line from a failed log and ask what it means, then check the answer against the step’s output.
Checks before you trust generated output
- Run it. A workflow that looks right but has never executed is not verified.
- Compare every key against GitHub’s workflow syntax reference, and confirm each action’s version in its README.
- Look for a
permissions:block and keep it as narrow as the job needs. - Remove any real credential from the prompt and use the secrets page instead.
Resources to use, in order
| Resource | Use it for | Notes |
|---|---|---|
| Quickstart for GitHub Actions | Your first working workflow | Official and free; assumes repository and pull request basics |
| Workflows | The mental model of events, jobs, runners, and steps | Read after your first run so the terms have a concrete example |
| Workflow syntax for GitHub Actions | Looking up any key you see in a file | Official reference, found on GitHub Docs; use it as the source of truth over any generated answer |
| Develop agentic workflows in GitHub Actions | AI-assisted authoring and review | Use after you can read a workflow yourself |
After your first run succeeds, the natural next step is adding a second job with needs: so one job waits for another, then narrowing the trigger to the branches you care about. Each change should be followed by a run and a look at the logs, the same habit that made the first workflow work.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
