GitHub training: complete developer and team workflow

GitHub is more than a place to store code. It combines distributed version control, collaborative review, planning, automation, software delivery, security and governance. This free GitHub course develops those capabilities as one coherent workflow, from your first repository to an auditable team platform.

Choose how you want to learn

Every topic provides a concept video, a hands-on walkthrough and a Documentation link to the relevant lesson below. Use a disposable public repository for exercises and never commit real credentials.

The course uses one continuing project: a small application or documentation site that can be tested and released. If you are not a programmer, use a Markdown documentation repository and replace code tests with link, spelling and formatting checks.

1. Understand Git, GitHub and the object model

Git is a distributed version-control system. Every clone normally contains the project files, branches and reachable history. GitHub hosts Git repositories and adds identity, collaboration, automation, planning, security and administration.

Git stores content as objects addressed by hashes:

• a blob stores file content;
• a tree records directory entries and points to blobs or other trees;
• a commit points to a tree, parent commit or commits, author information and a message;
• an annotated tag names an object and carries tag metadata.

A branch is a movable reference to a commit. HEAD identifies the currently checked-out branch or commit. A remote-tracking reference such as origin/main records your last known state of the remote branch; it is not the remote itself.

git status
git log --oneline --graph --decorate --all
git remote -v
git show --stat HEAD
git cat-file -t HEAD

2. Configure your account, Git and authentication

Protect the account before creating valuable repositories. Use a unique password, enable two-factor authentication, store recovery methods securely and review sessions, authorised OAuth apps, installed GitHub Apps and SSH keys periodically.

Configure the author identity written into new commits:

git config --global user.name "Your Name"
git config --global user.email "verified-or-noreply@example.com"
git config --global init.defaultBranch main
git config --global --list

HTTPS authentication uses a credential manager and token-based credentials rather than an account password. SSH authentication proves possession of a private key. Prefer modern key types supported by your environment, protect the private key and verify GitHub's host fingerprint on first connection. Personal access tokens should be fine-grained, short-lived and scoped to the minimum repositories and permissions.

Commit signing and vigilant mode help distinguish verified signatures from unverified identity claims. Signing does not prove that code is correct; it strengthens provenance.

3. Create and structure a professional repository

Repository visibility—public, private or internal where available—controls who can see the repository, not whether every operation is safe. Before publishing, inspect the entire history for credentials, customer data and proprietary assets.

Core community and engineering files include:

| File | Purpose | |---|---| | README.md | Explain value, setup, usage and support | | LICENSE | State reuse rights; absence does not mean unrestricted reuse | | .gitignore | Exclude generated/local files before they are tracked | | CONTRIBUTING.md | Define contribution and validation workflow | | CODE_OF_CONDUCT.md | Set community participation expectations | | SECURITY.md | Provide private vulnerability-reporting guidance | | CODEOWNERS | Request reviews from responsible people or teams |

Repository templates, issue forms and pull-request templates create consistent contribution data. Topics improve discovery. A default branch provides the base for new pull requests and many automation behaviours.

git init
git add README.md LICENSE .gitignore
git commit -m "chore: initialise project"
git remote add origin git@github.com:OWNER/REPOSITORY.git
git push -u origin main

4. Master commits, branches, merges and history

Make commits atomic: one coherent change with a message explaining intent. Stage selectively with git add -p; inspect git diff before staging and git diff --staged before committing.

git switch -c feat/health-endpoint
git add -p
git commit -m "feat: add service health endpoint"
git fetch origin
git rebase origin/main
git push -u origin feat/health-endpoint

Merge, rebase, cherry-pick and revert

• Merge combines histories and may create a merge commit.
• Rebase replays commits onto a new base, changing their identities. Avoid rebasing shared history without coordination.
• Cherry-pick applies a selected commit's change as a new commit.
• Revert creates a new commit that reverses an earlier change and is generally safer for published history.
• Reset moves a reference and can discard index or working-tree state depending on mode; use carefully.

Resolve conflicts by understanding the intended final program, not merely deleting markers. Run tests after resolution and inspect the resulting diff. git reflog can help recover locally reachable commits after a mistaken reference move.

5. Collaborate through pull requests and reviews

A pull request proposes merging changes from a head branch into a base branch. Keep it focused and explain the problem, solution, risk, test evidence, screenshots where relevant and rollback considerations. Draft pull requests invite early collaboration without implying readiness.

Review the behaviour, not just formatting. Start with architecture and security, then correctness, tests, maintainability, accessibility and operational impact. Comments can be general, attached to a line or submitted as an approval, comment-only review or request for changes.

GitHub supports merge commits, squash merging and rebase merging. Choose a repository policy based on traceability and history needs; do not select a strategy merely because it makes the graph look tidy. Required reviews, code-owner reviews, status checks, conversation resolution and merge queues can make the rule enforceable.

gh pr create --draft --fill
gh pr checks
gh pr diff
gh pr ready
gh pr merge --squash --delete-branch

6. Contribute through forks and open-source workflows

A fork is a repository copy under another account. Contributors commonly push to a branch in their fork and open a pull request against the upstream repository. Read CONTRIBUTING.md, issue templates, the licence and code of conduct before starting.

gh repo fork OWNER/PROJECT --clone
cd PROJECT
git remote -v
git fetch upstream
git switch main
git merge --ff-only upstream/main
git push origin main
git switch -c fix/clear-error-message

Keep the change narrow, add tests and avoid unrelated formatting. Maintainers should treat code and Actions changes from forks as untrusted. Secrets are normally withheld from fork pull-request workflows; pull_request_target has powerful security implications because it runs in the base context.

7. Plan work with Issues, Discussions, Projects and wikis

Issues represent actionable work, decisions or defects. Use templates or YAML issue forms to collect reproduction steps, expected behaviour, environment and acceptance criteria. Labels classify; assignees establish responsibility; milestones group work toward a target.

GitHub Projects provide table, board and roadmap views backed by items and custom fields. Use status, priority, iteration and estimate fields sparingly, then build views for different decisions. Automation can set fields as issues and pull requests change state.

Discussions suit open-ended questions, announcements and community knowledge that is not yet committed work. A wiki supports repository-linked documentation, although docs-as-code may be better when changes require pull-request review.

Search qualifiers such as is:issue is:open label:bug assignee:@me turn the global issue stream into a work queue. Tune watches and notification reasons instead of attempting inbox zero indiscriminately.

8. Automate quality with GitHub Actions

A workflow is YAML under .github/workflows/. Events trigger workflow runs; jobs run on runners; steps execute shell commands or actions. Jobs run in parallel unless connected through needs.

name: pull-request-quality
on:
  pull_request:
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm test
      - run: npm run build

Pin third-party actions to reviewed commit SHAs for stronger supply-chain control. Use dependency caching for reusable dependencies and artifacts for outputs from a specific run. A matrix can test multiple operating systems or runtime versions. Concurrency groups can cancel obsolete runs.

9. Engineer secure and reusable Actions workflows

Reusable workflows are called at job level with workflow_call; composite actions package repeated steps. Environments model deployment targets and can add protection rules, reviewers, branch restrictions and environment-scoped secrets.

Prefer OpenID Connect federation over long-lived cloud credentials. Set top-level permissions: {} or contents: read, then grant individual jobs only what they require. Never interpolate untrusted issue, branch or pull-request text directly into shell scripts.

Self-hosted runners offer custom hardware and network access but execute repository-controlled code near your systems. Use ephemeral isolation, narrow network reach, patching and trusted-repository policies. Do not run untrusted fork code on privileged persistent runners.

Other advanced concepts include service containers, job containers, outputs, expressions, contexts, deployment concurrency, manual approvals, required workflows and runner groups.

10. Publish releases, packages, Pages and environments

Tags identify commits; annotated tags carry metadata. A GitHub release adds notes and downloadable assets around a tag. Treat release creation as a controlled delivery event: verify the commit, tests, provenance, version, changelog and rollback path. Pre-releases communicate instability.

GitHub Packages hosts supported package ecosystems and the GitHub Container Registry. Scope package permissions deliberately, use immutable versions where possible, publish provenance and avoid overwriting trusted tags.

GitHub Pages publishes static sites from a branch or Actions workflow. Configure a custom domain with DNS ownership and HTTPS, and remember that client-side assets are public. Deployment environments can separate staging and production with approvals and scoped secrets.

git tag -s v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0
gh release create v1.0.0 --generate-notes --verify-tag

11. Secure code, secrets, dependencies and the supply chain

Security begins with access control and repository hygiene, then adds detection:

• the dependency graph identifies supported direct and transitive dependencies;
• Dependabot alerts connect vulnerable versions to advisories;
• security updates propose fixes and version updates keep dependencies current;
• dependency review shows dependency changes in pull requests;
• code scanning analyses code, including CodeQL where supported;
• secret scanning detects recognised credentials in GitHub content and history;
• push protection can block detected secrets before they enter the repository.

When a secret is committed, revoke or rotate it immediately. Removing it from the latest file or rewriting history does not make the credential safe. Configure SECURITY.md and repository security advisories for coordinated private vulnerability work.

Actions security belongs to the same supply chain: restrict the token, pin actions, protect workflow changes with CODEOWNERS, review artifact provenance and avoid unsafe trigger combinations. Feature availability varies by repository visibility and plan; verify the current GitHub security feature matrix.

12. Govern repositories, organisations and enterprises

Repository roles progress from read and triage through write, maintain and admin. Organisations group people into teams and repositories; base permissions and nested teams can create broad inherited access. Grant access through teams, review outside collaborators and separate administrative authority from ordinary contribution.

Rulesets can target branches and tags across repositories and provide evaluate, active or disabled enforcement where supported. Typical controls include pull requests, required status checks, signed commits, linear history, deployment success, creation/deletion restrictions and force-push prevention. Bypass lists must be narrow and auditable.

Organisation and enterprise governance also includes repository creation policy, visibility changes, fork policy, Actions allowlists, runner groups, security configurations, audit logs, SAML SSO, SCIM provisioning, enterprise-managed users and IP allowlists where available.

Archive inactive repositories instead of leaving unclear ownership. Transfer and deletion are consequential operations; confirm dependencies, package ownership, Pages domains, Actions secrets and redirects first.

13. Work efficiently with GitHub CLI, Desktop and Codespaces

GitHub CLI (gh) exposes repositories, issues, pull requests, releases, workflows, API calls and extensions from the terminal. Prefer explicit fields and --json output in automation.

gh auth status
gh repo view --json nameWithOwner,visibility,defaultBranchRef
gh issue list --assignee @me --state open
gh pr status
gh run list --limit 10
gh api repos/{owner}/{repo}/branches/main/protection

GitHub Desktop provides visual staging, history, branching and conflict resolution while still using Git repositories. Codespaces creates cloud development environments from dev-container configuration. Pin base images and features, use least-privilege secrets, understand billing and stop unused codespaces.

Codespaces prebuilds can reduce setup time. Dotfiles personalise the user environment, while repository dev-container configuration should define project requirements reproducibly.

14. Automate GitHub with APIs, webhooks and Apps

The REST API uses resource endpoints; GraphQL lets a client request a shaped graph of fields. Both require authentication, permission design, pagination, error handling, rate-limit awareness and version-compatible requests.

gh api --method GET repos/OWNER/REPO/issues \
  -f state=open -f per_page=20 --paginate

gh api graphql -f query='query($owner:String!,$name:String!){
  repository(owner:$owner,name:$name){
    pullRequests(first:10,states:OPEN){nodes{number title url}}
  }
}' -F owner=OWNER -F name=REPO

Webhooks deliver events to your service. Verify the signature against the exact raw body, return promptly, queue durable processing, deduplicate deliveries and tolerate retries and out-of-order events. Never trust repository-controlled payload fields as shell input.

GitHub Apps are preferable to personal tokens for many integrations because installations grant selected repository permissions and use short-lived installation tokens. OAuth Apps act primarily on behalf of users. Choose based on identity and authorisation needs, not convenience.

15. Deliver the production repository capstone

Your capstone is a repository another contributor can understand, change, verify, release and operate without relying on undocumented knowledge.

Acceptance criteria

1. README, licence, contribution, conduct and security guidance are appropriate.
2. Issue and pull-request templates capture acceptance criteria and evidence.
3. A Project connects planned work to issues and pull requests.
4. The default branch has review, status-check and deletion/force-push controls.
5. CODEOWNERS reflects real responsibility without creating an unavailable bottleneck.
6. Pull-request CI tests, builds and scans with least-privilege permissions.
7. Dependencies and secrets have preventive and detective controls.
8. A versioned release links source, notes, artifacts and deployment evidence.
9. Access roles, bypass, incident response and maintenance are documented.
10. CLI or API automation reports repository health without storing broad credentials.

Run a final scenario: a new contributor opens an issue, creates a branch or fork, submits a pull request, responds to review, passes CI and sees the change released. Then simulate a failing check, merge conflict, vulnerable dependency and leaked dummy secret. The repository is ready only when the controls produce understandable, recoverable outcomes.

Continue with primary GitHub documentation

• Get started with GitHub
• Repositories documentation
• Pull requests and collaboration
• Issues, Projects and planning
• GitHub Actions
• Security and code quality
• Organisations and teams
• GitHub CLI manual
• REST API
• GraphQL API