Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more

Use Git branches and pull requests to organize collaboration, then use GitHub Actions to run checks at the moments that help your team most. A practical starting point is a short-lived branch for each change, automated checks on pushes and pull requests, and a pull request to review and integrate the work. The right merge, rebase, trigger, and permission choices depend on your repository’s conventions and security needs.

How Git branches and GitHub Actions fit together

Git branches let people work on changes independently. GitHub Actions automates tasks around repository events: a workflow can build, test, or lint code when someone pushes a commit or opens or updates a pull request.

A useful baseline for many teams is to create a short-lived topic branch, make commits that represent useful units of work, open a pull request for review, and integrate the change after review and required checks pass. This is a practical starting point, not a rule for every project. Some teams also use long-running integration or release branches. The Git project documents more specialized workflows as well, but those are examples for particular project needs rather than a beginner requirement.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

A workflow is a YAML file stored in .github/workflows. GitHub’s GitHub Actions quickstart describes this location and the basic workflow structure: a name, event triggers, and jobs. Each job selects a runner and contains steps, such as checking out the repository and running a project’s existing test command.

Should you merge or rebase a Git branch?

Merge and rebase both bring branch work into a new context, but they represent history differently. Merge combines branch histories and records their integration relationship. Rebase replays commits onto a different base, producing new commit identities and a more linear history. Neither is the universal choice; follow the repository’s review and release conventions.

Consideration Merge Rebase
History Preserves the relationship between the branch and the integration point. Replays commits onto a new base, changing their identities and history.
Linear history preference Can retain explicit branch integration history. Can produce a more linear history.
Already-published shared commits Does not require rewriting the published commits. Rewriting shared history can disrupt collaborators; coordinate before doing so.
Team conventions Fits teams that value explicit integration history or use merge-based review conventions. Fits teams that prefer linear history and have agreed on how to handle rebased work.

Git also distinguishes branch-level integration from cherry-picking: a merge integrates branch histories, while cherry-pick applies selected commits. See the Git project’s gitworkflows documentation and Pro Git’s rebasing chapter for the consequences and workflow examples.

How to add a first GitHub Actions workflow

Start with the project’s actual setup and test commands; there is no single dependency-installation or test step that works for every language and repository. Create a workflow under .github/workflows, choose the events that should run it, then add a job with a runner and the steps needed to check the code.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
name: Checks

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v6
      - name: Run project checks
        run: <replace with your project's test or lint command>

This is an adaptable shape, not a universal copy-and-run recipe. Replace the example branch, runner, and final command to match your project. The quickstart’s current example lists actions/checkout@v6; action versions can change, so verify the action’s maintained instructions and your repository’s policy before adopting or updating a version. Pin and update actions in line with your supply-chain policy. Consult GitHub’s workflow syntax reference for current YAML syntax.

When should a workflow run on push or pull request?

A push trigger provides feedback after commits are pushed to a branch or a tag is pushed. GitHub documents that, for a push run, GITHUB_SHA identifies the tip commit pushed to the ref. A pull_request trigger runs in the pull request context, so the code and ref available to a job depend on the event and checkout configuration. Do not assume that every trigger tests the same commit or ref; verify what your workflow checks.

Trigger choice Useful for Trade-off to consider
push Fast feedback after commits reach a branch. May run repeatedly as work is pushed; ensure checks are relevant to the ref.
pull_request Giving reviewers check results before integration. Consider the contribution’s trust context and configure checkout and credentials carefully.
Both Branch feedback as well as review-time checks. Some work may run more than once; avoid unnecessary duplication while preserving required feedback.

Use GitHub’s events that trigger workflows reference to confirm event behavior and current filter syntax.

Narrow runs with branch, tag, or path filters

Branch and tag filters limit which refs trigger a workflow; path filters limit runs based on changed files. When a workflow specifies both branch and path filters, both conditions must match. This can reduce irrelevant work, but it also changes which checks are reported.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

A workflow skipped by branch, path, or commit-message filtering can leave an associated required check pending. If a branch protection rule or ruleset requires that check, the pull request may be blocked even though no job ran. Before narrowing a required workflow, confirm how the repository reports skipped checks and whether the required-check policy still behaves as intended.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

How to give workflow jobs only the permissions they need

Set GITHUB_TOKEN permissions explicitly and keep them minimal. A build or test job that only reads repository contents generally should not receive broad write access. When you specify a permissions map, permissions you omit are set to none, so add only the permissions the workflow or job actually needs. Scope permissions at job level when different jobs have different responsibilities; use workflow-level permissions when one policy safely covers them all.

An action may be able to access the token through the GitHub context even if you did not pass it to that action as an input. Review the actions used in a workflow and avoid treating an omitted input as proof that an action cannot access credentials. GitHub’s workflow syntax reference explains permission behavior, and its automatic token authentication documentation covers the token’s use.

How to handle secrets and untrusted pull requests

Store sensitive values as GitHub secrets and expose each one only to the step that requires it. Keep test workflows separate from trusted deployment flows so a contribution that has not earned deployment access cannot inherit production credentials. Avoid printing secrets or inserting untrusted pull-request text directly into shell scripts.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

GitHub’s log masking is not guaranteed to cover every transformed version of a secret. Treat masking as defense in depth, not permission to print credentials or pass them into unnecessary commands. For workflows that handle outside contributions or need elevated privileges, check GitHub’s current secure use reference and secrets documentation before selecting a privileged trigger or exposing credentials.

Branch protection and rulesets can require checks before a change is integrated, but the exact policy is repository-specific. Keep production deployment permissions and environment approvals out of a basic test workflow unless the workflow actually deploys; add those controls separately when needed.

A practical setup sequence

  1. Agree on branch conventions. Decide how topic branches are named, how changes are reviewed, and whether integration preserves branch history or favors linear history.
  2. Add a workflow in .github/workflows. Choose a YAML filename and define the jobs that run the project’s real checks.
  3. Select event triggers. Use push events for branch feedback and pull-request events for review-time results when both serve the team’s process.
  4. Set filters only when their behavior is clear. If using both branch and path filters, ensure both can match intended changes and check the effect on required status checks.
  5. Scope credentials. Give the workflow or job the smallest necessary token permissions; expose secrets only to the steps that need them.
  6. Connect checks to integration policy. Configure required checks through the repository’s protection rules or rulesets, then verify that ordinary changes can complete the review path.

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.