GitHub Actions: Complete 2026 guide with quick tutorial

What is GitHub Actions?

GitHub Actions is an automation framework built into GitHub, designed to help developers automate workflows across the software development lifecycle (SDLC). GitHub has over 100 million users, making GitHub Actions an accessible option for many development teams.

GitHub Actions uses event-driven triggers to run a series of steps—known as jobs—on a range of environments, including GitHub-hosted and self-hosted runners. Developers can define these workflows using YAML syntax, enabling version-controlled, repeatable, and maintainable CI/CD pipelines directly within their repositories.

GitHub Actions integrates with GitHub’s APIs, repositories, and issues. This integration makes it possible to automate everything from testing and building to deploying applications and managing releases. The solution provides a large marketplace of reusable actions, promoting collaboration and standardization in CI/CD pipelines.

This is part of an extensive series of guides about CI/CD.

Top 5 GitHub Actions features

GitHub Actions offers several key features designed to simplify automation for developers, supporting a range of development and operational tasks:

1. Workflow automation: Automates tasks across the software development lifecycle, including Continuous Integration, testing, and deployment. Developers can create workflows in YAML format, enabling seamless integration with the existing GitHub repository.
2. Event-driven triggers: Actions can be triggered by various GitHub events, such as commits, pull requests, or issue updates. Event-driven automation helps teams respond promptly to code changes or issues without manual intervention.
3. Reusable actions: A library of pre-built actions in the marketplace, letting developers to reuse existing workflows or build custom ones. These actions can be shared across projects, promoting modularity and efficiency.
4. Integration with GitHub ecosystem: Provides access to GitHub APIs, repositories, and other tools. This deep integration makes it easy to manage code, workflows, and issues from one central platform.
5. Custom runners: In addition to GitHub-hosted runners, which are pre-configured with popular development environments, users can deploy self-hosted runners. This flexibility allows for tailored environments, cost optimization, and hardware configurations to suit project needs.

GitHub Actions components

Workflows

A workflow is defined by a YAML file located in the repository’s .github/workflows directory. This file specifies the sequence of events and jobs to be executed, providing a blueprint for the automation process. Users can define multiple workflows per repository, each responding to different triggers or performing distinct tasks.

Each workflow can have defined triggers, known as events, which initiate the execution. These definitions allow for granular control over when and how automation occurs, enabling tailored CI/CD processes. Additionally, workflows can be configured to run concurrently, ensuring that tasks requiring immediate attention are completed in parallel.

Events

Events in GitHub Actions trigger workflows, determining when a particular workflow should start. Typical events include actions such as code commits, pull requests, or merges, which are common points in the development cycle where automation is useful. Developers can define custom events, allowing them to create highly specific triggers for unique automation requirements.

The ability to trigger workflows based on specific conditions helps maintain an efficient CI/CD pipeline. Events can also be filtered further by different contexts, such as branch, tag, or user, providing detailed control over when actions should occur.

Jobs

Jobs in GitHub Actions consist of a series of steps that execute specific tasks required by the automation process. Each job runs in an isolated environment and can have dependencies on other jobs, dictating a sequence of operations. This ability to set dependencies helps manage complex workflows efficiently, ensuring that steps occur in the correct order.

Within jobs, steps are executed using individual actions or scripts, which can be written in various programming languages such as JavaScript or Python. This flexibility allows developers to customize their jobs precisely, using the most appropriate tools for each task.

Actions

Actions are the individual tasks executed within a job in GitHub Actions. They can be small, reusable scripts or complex packages that perform various operations, from setting up a Node.js environment to deploying code to cloud services. Developers can create custom actions or use pre-existing actions from the GitHub Marketplace.

The modular nature of actions promotes reusability and sharing within the GitHub community, enabling developers to build upon each other’s work. Developers can create highly customized and efficient workflows by composing jobs with a series of actions. Additionally, actions support collaboration, as they can be shared across multiple projects or teams.

Runners

Runners in GitHub Actions are environments where jobs are executed. GitHub provides flexible options, including GitHub-hosted runners for common operating systems, which come pre-configured with software for building and deploying applications. These runners simplify the setup process, making it quick to start running jobs without additional infrastructure setup.

Alternatively, self-hosted runners offer a customizable solution for developers needing more control over the execution environment. By configuring their machines as runners, developers can accommodate specific hardware or software requirements, optimize costs, and use existing resources.

Learn more in our detailed guide to GitHub Actions Secrets

Quick tutorial: Creating your first GitHub Actions workflow

This quick start guide walks you through creating and running your first GitHub Actions workflow.

1. Create a workflow file

Start by navigating to your repository on GitHub. If the .github/workflows directory doesn’t already exist, create it at the root level of your repository. Inside this directory, add a new file named demo-github-actions-workflow.yml.

Paste the following workflow definition into the file:

name: Demo GitHub Actions Workflow
on: [push]
jobs:
 Discover-GitHub-Actions-Workflows:
   runs-on: ubuntu-latest
   steps:
     - run: echo "${{ github.event_name }} event automatically triggered this job."
     - run: echo "A ${{ runner.os }} server hosted by GitHub has this job running"
     - run: echo "Details of your repository: repo-name: ${{ github.repository }} and branch name is ${{ github.ref }} and your repository is ${{ github.repository }}."
     - name: Checking out the repository's code
       uses: actions/checkout@v3
     - run: echo "The runner has cloned your ${{ github.repository }} repository."
     - run: echo "The workflow can now test your code with the runner."
     - name: List files in the repository
       run: |
         ls ${{ github.workspace }}
     - run: echo "This job has a ${{ job.status }} status."

Commit the file by proposing a new file via the GitHub interface. Choose the option to create a new branch and start a pull request. Once committed, the workflow is automatically triggered by the push event defined in the workflow file.

2. View workflow results

To inspect the workflow run:

• Go to the repository’s main page and click on the Actions tab.
• On the left sidebar, locate and click the Demo GitHub Actions Workflow.
• In the list of workflow runs, select the one triggered by creating the new YAML file.
• Under Jobs, click Discover-GitHub-Actions-Workflows to view logs.
• Each step in the log shows the executed command and output, with GitHub-specific variables replaced by actual values.
• Click on the List files in the repository step to see a list of files in the workspace.

GitHub also provides starter workflows based on detected frameworks or languages in your repository, which you can use as a base and customize to suit your project needs.

GitHub Actions best practices

To get the most out of GitHub Actions while maintaining secure, stable, and efficient workflows, adopt the following best practices:

• Set workflow timeouts: By default, GitHub allows workflows to run for up to six hours, which can lead to long pending PRs or stuck jobs. To avoid this, explicitly set a timeout-minutes value for each job. For most use cases, 30 minutes is sufficient. This keeps the CI pipeline responsive and prevents resource bottlenecks from hung jobs.
• Use concurrency controls: When multiple commits are pushed rapidly, redundant workflows may trigger. Define a concurrency group in your YAML file to cancel in-progress jobs when new ones in the same context start. This prevents unnecessary builds and reduces queue times.

 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}

• Restrict workflow permissions: GitHub gives workflows a broad access token by default. Follow the principle of least privilege by explicitly defining only the permissions needed. For example, limit a CI workflow to read-only access if no write operations are required.

permissions:
  contents: read

• Pin action versions to SHAs: Avoid referencing actions by tags like @v3 or @latest, which can change over time. Instead, pin actions to a specific commit SHA. This ensures consistency and guards against malicious or unintended changes in third-party code. uses: actions/checkout@a12a3943b4bdde767164f792f33f40b04645d846
• Evaluate third-party actions carefully: Treat actions like external dependencies. Prefer those maintained by trusted organizations (like GitHub or Exercism) and assess their maintenance activity before using them. Where possible, reimplement critical logic under your own control.
• Use versioned runners: Pin the runner environment to a specific version such as ubuntu-22.04 rather than using ubuntu-latest. This reduces variability in builds and protects against sudden changes in the environment that might break workflows.
• Secure secrets management: Store secrets in GitHub’s encrypted secrets manager, and restrict their access to specific environments or workflows. Never hardcode secrets in workflow files.
• Cache dependencies for speed: Use the actions/cache feature to reuse build artifacts or dependencies across jobs. This minimizes setup time and accelerates workflows, especially when working with large package ecosystems.
• Maintain readable YAML files: Organize workflows clearly with consistent naming, indentation, and comments. Use composite actions for shared logic across repositories. Clean YAML makes debugging easier and helps teams maintain workflows collaboratively.

GitHub Actions pricing

GitHub Actions offers a flexible pricing model based on repository type (public or private), storage, and minutes used by GitHub-hosted runners. Public repositories enjoy free usage of GitHub-hosted runners, while private repositories receive a limited amount of free minutes and storage, depending on the account’s plan.

For private repositories, users receive free monthly allowances:

• GitHub Free: 500 MB of storage and 2,000 minutes.
• GitHub Pro: 1 GB of storage and 3,000 minutes.
• GitHub Team: 2 GB of storage and 3,000 minutes.
• GitHub Enterprise Cloud: 50 GB of storage and 50,000 minutes.

Once the included minutes or storage are exhausted, overage charges apply. Storage costs $0.008 per GB per day. Per-minute charges vary by operating system:

• Linux: $0.008 per minute.
• Windows: $0.016 per minute.
• macOS: $0.08 per minute.

Self-hosted runners do not incur usage charges, making them a cost-effective option for private repositories. However, larger runners and those running on Windows or macOS use minutes at higher multipliers, consuming more of the allotted resources.

Organizations can connect an Azure Subscription for additional payment options, particularly for scaling beyond the free tier.

The GitHub Actions pricing controversy

In late 2025, GitHub announced pricing changes that sparked concern across the developer community, particularly around the cost of using self-hosted runners. Historically, teams running their own infrastructure could execute workflows without paying for the underlying GitHub Actions platform services. The proposed change introduced a $0.002 per-minute GitHub Actions cloud platform charge for all workflows, including those running on self-hosted runners.

GitHub explained that the change was intended to better align pricing with the actual cost of operating the Actions platform. Even when workflows run on customer-managed infrastructure, GitHub still provides the control plane responsible for scheduling jobs, managing runners, handling logs, and coordinating workflow execution.

The announcement triggered strong feedback from developers and organizations that rely heavily on self-hosted infrastructure. Many users argued that charging for self-hosted workflows changed the long-standing value proposition of GitHub Actions and could significantly increase costs for large CI/CD workloads.

In response to this feedback, GitHub postponed the billing change to reevaluate its approach and gather more input from the community. The company opened public discussions to collect feedback and stated that it would use this input to guide the future GitHub Actions roadmap.

GitHub Actions limitations

While GitHub Actions offers powerful automation features, there are some limitations and challenges to consider, as reported by users on the G2 platform:

• Steep learning curve: New users often struggle with advanced features, workflow setup, and complex repository structures, making onboarding slower.
• User interface complexity: As features expand, the interface can feel cluttered, making it harder to locate settings, manage repositories, or navigate large projects.
• Performance and reliability issues: Users report occasional outages, slowdowns, and lag in areas like code reviews or large diffs, which can interrupt development workflows.
• Difficult workflow debugging: Troubleshooting GitHub Actions can be inefficient, often requiring repeated commits and pushes due to limited local testing support.
• Noisy notifications: Alerts and updates can become overwhelming, making it difficult to identify important messages or relevant activity.
• Pricing constraints for advanced use: Free tier limits and higher costs for advanced features or usage at scale can be restrictive for some teams.

In addition, our experience shows many organizations use GitHub Actions and related tools to implement full Continuous Delivery pipelines, even though they were not intended for this purpose. This creates the problem of Shadow CD:

• Shadow CD creates an illusion of automation, but it lacks crucial elements that people need to trust it.
• To manage layers of automation not supported by the platform, developers create collections of scripts, sometimes with hundreds or thousands of lines.
• The scrips are often created and maintained by a handful of engineers, often just a single person. Maintenance, security, and support become a significant challenge.
• Just like manual deployments, scripted deployments don’t provide repeatable and reliable deployments. They don’t offer the visibility required for people to trust the process.

Notable GitHub Actions alternatives

1. Octopus

2. Azure DevOps

3. Jenkins

4. GitLab CI/CD

5. CircleCI

Conclusion

GitHub Actions provides an integrated solution for automating workflows within the GitHub ecosystem. It makes it easier for developers to build, test, and deploy code continuously. With its feature set, including reusable actions, custom runners, and event-driven workflows, GitHub Actions streamlines development processes and fosters collaboration.

For those looking for alternatives, tools like Jenkins, GitLab CI/CD, and Azure DevOps offer unique capabilities that better support more complex use cases and full Continuous Delivery pipelines.

Learn more about Octopus Deploy

See additional guides on key CI/CD topics

Together with our content partners, we have authored in-depth guides on several other topics that can also be useful as you explore the world of CI/CD.

Continuous Delivery

Authored by Octopus

• [Guide] Continuous Delivery: Origins, 5 principles, and 7 key capabilities
• [Guide] Continuous Integration versus Continuous Deployment [2025 guide]
• [Ebook] The importance of Continuous Delivery
• [Product] Octopus Deploy | Continuous Delivery and deployment platform

Platform Engineering

Authored by Octopus

• [Guide] Platform Engineering: Capabilities, Practices, and Impact on DevOps

Jenkins

Authored by Octopus

• Jenkins: Pros/cons, Installation, And 8 Modern Alternatives
• [Blog] 10 Of Our Favorite Jenkins Plugins
• [Product] Octopus Deploy | Continuous Delivery and Deployment Platform

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback