Your First GitHub Action: Hello World

We're going to create a GitHub Actions workflow that you can trigger manually from the GitHub website. When triggered, it will run on a GitHub-hosted runner, display a friendly "Hello World" message, show some system information, and list the files in your repository. This simple workflow will teach you the fundamental structure of GitHub Actions: workflow files, jobs, steps, and manual triggers.

The best part? Once you understand this basic pattern, you can build anything—from running tests to deploying applications. Think of this as your "Hello World" for automation, the first step toward building powerful CI/CD pipelines.

To follow along, you need a GitHub repository. It can be any repository—public or private, new or existing. If you don't have one, create a new repository on GitHub (it's free). The repository can be empty; we're not working with actual code files for this example.

That's it! You don't need any special permissions beyond being able to create files in your repository. GitHub Actions is enabled by default for all repositories, so no additional setup is required.

GitHub Actions workflows are defined in YAML files stored in the .github/workflows/ directory of your repository. If these directories don't exist yet, you'll create them as you go.

In your repository, create a new file at .github/workflows/hello-world.yml. You can do this directly on GitHub by clicking "Add file" > "Create new file". Paste the following YAML content into the file.

Click "Commit changes" to save the file to your main branch. Congratulations—you've just created your first GitHub Actions workflow!

Let's break down each part of our workflow file to understand what it does. The name field gives our workflow a display name. When you look at the Actions tab, you'll see this name.

The on: workflow_dispatch section defines the trigger. workflow_dispatch is a special event that allows manual triggering. This adds a "Run workflow" button to the Actions tab. It's perfect for workflows you want to run on demand rather than automatically.

Under jobs, we defined a single job called hello-world-job. This job runs on ubuntu-latest, which is GitHub's hosted Ubuntu runner. Within the job, we have three steps. Each step runs a command using the runner's shell. The first step prints "Hello, World!" The second shows the current date and time. The third shows system information and lists the files in the repository.

The | symbol in the third step allows us to write multi-line shell commands. This is useful when you need to run several commands in sequence within a single step.

Now for the exciting part—let's run your workflow! Navigate to the "Actions" tab in your repository. You'll see "Hello World Workflow" listed on the left side. Click on it.

On the workflow page, you'll see a "Run workflow" button. Click it, then select the branch you want to run on (usually main), and click "Run workflow" again. GitHub will immediately start executing your workflow.

After a moment, you'll see a new run appear in the list. Click on it to view the details. You'll see your job, and you can click on each step to expand and view the output. You should see your "Hello, World!" message, the current date, and the system information you asked for.

After your workflow finishes, you can explore the detailed logs. Click on the "Say Hello" step to see the output. You should see something like:

The "Show Date" step will display the current date and time on the GitHub runner. The "System Info" step will show information about the Ubuntu runner, including the kernel version, current directory, and a list of files in your repository (which should include your .github/workflows directory).

Each step shows the exact commands that were executed and their output. If any step fails, the workflow stops and shows you exactly where the error occurred. This makes debugging straightforward.

Now that you have a working workflow, try customizing it! Here are a few simple modifications you can make:

Change the message: Modify the echo command in the "Say Hello" step to print something else. Commit the change, then run the workflow again to see your new message.

Add another step: Add a fourth step that runs something like echo "This is my custom step!" or ls -la to explore the file system.

Use a different runner: Change runs-on: ubuntu-latest to runs-on: windows-latest or runs-on: macos-latest to see how the workflow behaves on different operating systems.

Add inputs: You can add inputs to your manual workflow so you can pass values when triggering it. Add this to your workflow_dispatch section:

Now that you know how to create a simple workflow, you can build more practical automations. Here are some common use cases to explore next:

Automated Testing: Replace the echo commands with npm test, pytest, or your language's test runner. Run tests automatically on every pull request.

Deployment: Add steps to deploy your application to AWS, Azure, or a VPS. Use secrets to store credentials securely.

Code Linting: Run linters like ESLint, Prettier, or Rubocop to enforce code quality standards automatically.

Dependency Updates: Schedule a workflow to check for outdated dependencies and create pull requests automatically.

Security Scanning: Integrate tools like CodeQL or Snyk to scan your code for vulnerabilities on every push.

Each of these starts with the same basic structure you just learned. The difference is the commands you run and the actions you use.