A reliable GitHub Actions deployment starts before the first workflow run. This reusable checklist shows how to prepare repository secrets, separate build and test stages, add preview environments, protect production releases, and design rollback steps that work across common hosting setups.
Overview
GitHub Actions can automate the path from a code change to a running web application, but automation is only useful when the workflow has clear boundaries. A maintainable deployment pipeline should answer five questions:
- What must pass before code can be deployed?
- Which environment will receive the change?
- Where are credentials stored, and who can use them?
- How is a production release approved?
- What is the recovery plan if the release fails?
This guide assumes a web application is stored in a GitHub repository and deployed to a hosting provider, virtual private server, container platform, or static hosting service with a command-line interface or API. The exact deployment command varies by platform, so treat the workflow below as a pattern rather than a provider-specific script.
A basic pipeline normally contains separate jobs for validation and deployment. The validation job installs dependencies, runs tests, and builds the application. A deployment job runs only after validation succeeds. For larger teams, the deployment job can target a staging environment first and require approval before production.
If your application runs in Docker, pair this checklist with the Docker, GitHub Actions, and Nginx deployment guide. For a traditional Node.js process on a server, see the VPS, Nginx, PM2, and SSL deployment guide.
Checklist by scenario
Scenario 1: Prepare the repository
- Confirm the application can be installed, tested, and built from a clean checkout.
- Record the supported runtime version and package-manager commands.
- Ensure the lockfile is committed so automated builds use a known dependency graph.
- Define the expected output, such as a build directory, container image, package, or server artifact.
- Decide which branches or tags are allowed to deploy.
Keep the first workflow small. A useful starting sequence is checkout, runtime setup, dependency installation, tests, build, and deployment. Add caching, matrix builds, notifications, and extra checks after the basic path is observable and dependable.
Scenario 2: Configure secrets and environment variables
- Store API tokens, SSH keys, deployment passwords, and signing credentials in GitHub Actions secrets or environment-level secrets.
- Keep non-sensitive configuration in version control only when it is safe to publish.
- Use separate credentials for staging and production.
- Give each token the smallest practical set of permissions.
- Document the variable name expected by the deployment command.
Do not place secrets directly in workflow YAML, shell scripts, issue comments, or application logs. A secret can also be exposed indirectly if a command prints its full environment or if a deployment tool runs in verbose mode. Review logs after the first run and remove unnecessary diagnostic output.
Scenario 3: Add a build-and-test workflow
A typical workflow is triggered for pull requests and pushes to the main development branch. Pull requests should prove that a change is safe to merge; the deployment trigger should be narrower and intentional.
name: Validate
on:
pull_request:
push:
branches: [main]
jobs:
test-and-build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up runtime
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npm test
- run: npm run build
Versions and commands in this example are placeholders for your application. Use the runtime and action versions that your project supports, and verify them before copying the workflow into production.
Scenario 4: Deploy to staging or a preview environment
Preview deployments are valuable when the hosting platform supports temporary URLs for branches or pull requests. They let reviewers test the built application before it reaches the shared staging or production environment. If your platform does not provide previews, use a persistent staging subdomain with separate credentials and data.
- Use a non-production database or carefully isolated test data.
- Mark staging clearly in the interface and monitoring tools.
- Prevent staging pages from being indexed when appropriate; see this staging subdomain checklist.
- Test environment-specific variables, callbacks, webhooks, and email behavior.
- Define how preview environments are removed or expired.
Scenario 5: Protect production deployment
Production should not be an accidental side effect of every successful build. Restrict production deployment to a protected branch, a release tag, or a manually approved workflow. GitHub environment protection can be used to require reviewers and keep production secrets unavailable until the deployment reaches that environment.
A production job should depend on the validation job. Conceptually, the workflow should be: validate, build the release artifact, approve production, deploy, then run a smoke test. Rebuilding different source code after approval creates uncertainty, so prefer promoting the artifact that was already validated when your hosting platform supports that model.
Scenario 6: Plan rollback before the first release
- Identify the last known-good commit, tag, image, or artifact.
- Confirm how to redeploy that version without editing application code manually.
- Decide who can initiate a rollback and how the event is recorded.
- Check whether database migrations are backward-compatible.
- Write a short smoke-test list for the home page, authentication, critical API calls, and key user flows.
A rollback is not always a complete recovery. If a release changes a database schema, deletes data, or changes an external integration, reverting application files may not restore service. Treat irreversible migrations and data changes as a separate release decision.
What to double-check
Before enabling automated deployment, inspect the workflow as an operations document rather than only as code.
Triggers and branch rules
Check whether a pull request, branch push, tag, or manual dispatch can start each job. Confirm that forks cannot access sensitive secrets and that a renamed default branch will not silently stop releases.
Dependency and artifact behavior
Verify that the lockfile is honored, native dependencies can compile in the runner, and the build output contains everything needed at runtime. If the deployment uses an artifact, confirm its retention and naming rules, then test downloading it in a separate job.
Environment configuration
Compare staging and production variables deliberately. Common failures include a production API URL in a preview deployment, a missing public build variable, an incorrect port, or a callback URL that still points to localhost.
DNS, TLS, and routing
When a deployment also changes a domain, verify the A, AAAA, or CNAME record and confirm that the hosting platform recognizes the hostname. DNS changes may be cached at different layers. Use this DNS propagation diagnostic when a new endpoint is not visible everywhere. If HTTPS or a proxy was changed, review the too-many-redirects troubleshooting guide.
Observability and notifications
Make failed workflow runs visible to the people responsible for the service. Capture deployment IDs, commit SHAs, environment names, and relevant provider logs. A green workflow is not proof that the application is healthy, so pair it with an endpoint check or post-deployment smoke test.
Common mistakes
- Deploying from an unprotected branch: Require review or use a release branch and environment approval for production.
- Using one credential everywhere: Separate staging and production access so a test workflow cannot alter live infrastructure.
- Testing only after deployment: Run linting, unit tests, and the production build before the deployment job starts.
- Rebuilding during rollback: Redeploy a known artifact or commit when possible instead of relying on an untracked local build.
- Ignoring migrations: Application rollback cannot automatically undo a schema change. Plan migration compatibility and recovery separately.
- Assuming a successful upload means a healthy app: Check startup logs, status endpoints, routes, assets, and a critical user flow.
- Putting too much logic in YAML: Move complex, reusable tasks into tested scripts or Make targets, while keeping the workflow responsible for orchestration.
- Changing infrastructure and application code at once: Separate DNS, proxy, certificate, and application changes when practical so failures are easier to isolate.
When to revisit
Review this deployment checklist before a new planning cycle, before a major launch, and whenever the workflow or hosting platform changes. It is especially useful after changing runtime versions, package managers, build commands, repository permissions, DNS records, server architecture, or production credentials.
Schedule a small deployment rehearsal rather than waiting for an incident. Run the workflow against staging, confirm the artifact can be promoted, test the smoke checks, and document the exact rollback command. Recheck secrets and permissions when team responsibilities change, and remove credentials that are no longer needed.
Finally, keep the workflow close to the application and make its assumptions explicit. A dependable GitHub Actions deployment is not the longest YAML file; it is a repeatable path with observable checks, controlled access, and a practiced recovery option. Use this article as a pre-release checklist, then update it whenever the inputs to that path change.