|
| 1 | +# Introduction & Your First Workflow |
| 2 | + |
| 3 | +| [← Workshop Setup][walkthrough-previous] | [Next: Running Tests →][walkthrough-next] | |
| 4 | +|:-----------------------------------|------------------------------------------:| |
| 5 | + |
| 6 | +[GitHub Actions][github-actions] is an automation platform built into GitHub that lets you build, test, and deploy your code directly from your repository. While it's most commonly used for CI/CD, it can automate just about any task in your development workflow — from labeling issues to resizing images. |
| 7 | + |
| 8 | +Before diving in, here are the key terms you'll encounter: |
| 9 | + |
| 10 | +- **Workflow**: An automated process defined in a YAML file, stored in `.github/workflows/`. |
| 11 | +- **Event**: A trigger that starts a workflow, such as a `push`, `pull_request`, or `workflow_dispatch`. |
| 12 | +- **Job**: A set of steps that run on the same runner. Jobs run in parallel by default. |
| 13 | +- **Step**: An individual task within a job — either a shell command (`run`) or a reusable action (`uses`). |
| 14 | +- **Runner**: The virtual machine that executes your jobs (e.g., `ubuntu-latest`). |
| 15 | +- **Action**: A reusable unit of code that performs a specific task, published on the [Actions Marketplace][actions-marketplace]. |
| 16 | + |
| 17 | +## Scenario |
| 18 | + |
| 19 | +The shelter has built its application — a Flask API and Astro frontend — and the team is ready to start automating their development workflow. Before diving into CI/CD, let's start with the basics: creating a simple workflow, triggering it manually, and understanding the logs. |
| 20 | + |
| 21 | +## Understanding GitHub Actions |
| 22 | + |
| 23 | +A workflow file is written in YAML and lives in the `.github/workflows/` directory. Here are the core sections you'll work with: |
| 24 | + |
| 25 | +- `name`: A human-readable name for the workflow, displayed in the **Actions** tab. |
| 26 | +- `on`: Defines the events that trigger the workflow (e.g., `push`, `pull_request`, `workflow_dispatch`). |
| 27 | +- `jobs`: Contains one or more jobs, each with a unique identifier. |
| 28 | + - `runs-on`: Specifies the runner environment (e.g., `ubuntu-latest`). |
| 29 | + - `steps`: An ordered list of tasks the job performs. |
| 30 | + - `uses`: References a reusable action (e.g., `actions/checkout@v4`). |
| 31 | + - `run`: Executes a shell command. |
| 32 | + |
| 33 | +## Create your first workflow |
| 34 | + |
| 35 | +Let's start with the classic "Hello World" — a workflow you can trigger manually from the GitHub UI. |
| 36 | + |
| 37 | +1. In your repository, create the folder `.github/workflows/` if it doesn't already exist. |
| 38 | +2. Create a new file named `.github/workflows/hello.yml`. |
| 39 | +3. Add the following content: |
| 40 | + |
| 41 | + ```yaml |
| 42 | + name: Hello World |
| 43 | + |
| 44 | + on: |
| 45 | + workflow_dispatch: |
| 46 | + |
| 47 | + jobs: |
| 48 | + greet: |
| 49 | + runs-on: ubuntu-latest |
| 50 | + |
| 51 | + steps: |
| 52 | + - name: Say hello |
| 53 | + run: echo "Hello, GitHub Actions!" |
| 54 | + |
| 55 | + - name: Show environment info |
| 56 | + run: | |
| 57 | + echo "Runner OS: $RUNNER_OS" |
| 58 | + echo "Repository: $GITHUB_REPOSITORY" |
| 59 | + echo "Triggered by: $GITHUB_ACTOR" |
| 60 | + ``` |
| 61 | +
|
| 62 | +4. Save the file. |
| 63 | +
|
| 64 | +> [!NOTE] |
| 65 | +> The `workflow_dispatch` event lets you trigger the workflow manually from the **Actions** tab. This is useful for testing workflows without needing to push code changes every time. |
| 66 | + |
| 67 | +## Push and run |
| 68 | + |
| 69 | +Now let's push the workflow and trigger it by hand. |
| 70 | + |
| 71 | +1. Stage and commit your changes: |
| 72 | + |
| 73 | + ```bash |
| 74 | + git add .github/workflows/hello.yml |
| 75 | + git commit -m "Add hello world workflow" |
| 76 | + ``` |
| 77 | + |
| 78 | +2. Push to your repository: |
| 79 | + |
| 80 | + ```bash |
| 81 | + git push |
| 82 | + ``` |
| 83 | + |
| 84 | +3. Navigate to your repository on GitHub and select the **Actions** tab. |
| 85 | +4. In the left sidebar, select the **Hello World** workflow. |
| 86 | +5. Select the **Run workflow** button, keep the default branch, and select **Run workflow** again to confirm. |
| 87 | + |
| 88 | +## Explore the logs |
| 89 | + |
| 90 | +Once the run completes, let's explore what happened. |
| 91 | + |
| 92 | +1. Select the workflow run that just completed. |
| 93 | +2. Select the **greet** job to expand it. |
| 94 | +3. Explore the logs for each step: |
| 95 | + - **Say hello** — you'll see the `echo` output. |
| 96 | + - **Show environment info** — notice the environment variables that GitHub Actions provides automatically (`RUNNER_OS`, `GITHUB_REPOSITORY`, `GITHUB_ACTOR`). |
| 97 | +4. Also look at the **Set up job** and **Complete job** steps that Actions adds automatically — these show the runner setup and cleanup. |
| 98 | + |
| 99 | +> [!TIP] |
| 100 | +> You can search within the logs using the search box at the top of the log viewer, and expand or collapse individual steps. This becomes very useful as workflows grow more complex. |
| 101 | + |
| 102 | +## Summary and next steps |
| 103 | + |
| 104 | +Congratulations! You've created and run your first GitHub Actions workflow. You've learned how to define a workflow in YAML, trigger it manually with `workflow_dispatch`, and navigate the logs in the Actions UI. |
| 105 | + |
| 106 | +Next, we'll put this knowledge to work by [building a CI workflow][walkthrough-next] that automatically tests the shelter's application. |
| 107 | + |
| 108 | +### Resources |
| 109 | + |
| 110 | +- [GitHub Actions documentation][github-actions-docs] |
| 111 | +- [Workflow syntax for GitHub Actions][workflow-syntax] |
| 112 | +- [Events that trigger workflows][workflow-triggers] |
| 113 | +- [Understanding GitHub Actions][understanding-actions] |
| 114 | + |
| 115 | +| [← Workshop Setup][walkthrough-previous] | [Next: Running Tests →][walkthrough-next] | |
| 116 | +|:-----------------------------------|------------------------------------------:| |
| 117 | + |
| 118 | +[actions-marketplace]: https://github.com/marketplace?type=actions |
| 119 | +[github-actions]: https://github.com/features/actions |
| 120 | +[github-actions-docs]: https://docs.github.com/en/actions |
| 121 | +[understanding-actions]: https://docs.github.com/en/actions/about-github-actions/understanding-github-actions |
| 122 | +[workflow-syntax]: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions |
| 123 | +[workflow-triggers]: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows |
| 124 | +[walkthrough-previous]: 0-setup.md |
| 125 | +[walkthrough-next]: 2-running-tests.md |
0 commit comments