FS-DOC-03Operations
Process Runbook / SOP
Software Deployment Workflow
[YourCompany.com] · IT Department · Prepared by FullSpec · [Today's Date]
This runbook describes exactly how the automated Software Deployment Workflow operates, what your team needs to do at each stage, how to handle exceptions when they arise, and who to contact if something goes wrong. The automation handles every step except the IT lead approval click in Slack, which remains a deliberate human control. Use this document as your day-to-day reference once the workflow is live in production.
01Process overview
The Software Deployment Workflow automates the chain of steps that moves a software release from a merged pull request through CI verification, IT lead approval, environment configuration, pipeline execution, and post-deploy health monitoring to a confirmed, logged outcome in Slack and Jira. Three automated agents handle eight of the nine original manual steps. The only step that requires a human decision is the IT lead clicking Approve or Reject in a structured Slack message. Every gate decision is timestamped and logged, and the team is notified automatically whether the deployment succeeds or fails.
Process name
Software Deployment Workflow
Trigger
A pull request is merged to the main branch in GitHub
Final output
Deployment result posted to Slack, Jira ticket closed with timestamp, and PagerDuty alert raised if health checks fail
Agents running
Deployment Gate Agent, Environment and Deploy Agent, Post-Deploy Monitor Agent
Tools involved
GitHub, Jira, Slack, Confluence, Datadog, PagerDuty
Weekly volume
~3 deployments/week (approximately 12/month)
Human checkpoint
IT lead clicks Approve or Reject in the Slack approval message before any code touches production
Process owner
IT Lead (Marcus Reid)
02Step-by-step: what happens and who acts
What you actually need to do: There is only one step that requires action from your team. When the Deployment Gate Agent posts an approval request in Slack, the IT lead must click Approve or Reject before the pipeline will proceed. Everything before and after that click is handled automatically by the agents.
Step
What happens
Who acts
Type
1
A pull request is merged to the main branch in GitHub. The Deployment Gate Agent detects the merge event immediately via a GitHub webhook and captures the build reference, target environment, and author details.
Automation
Automated
2
The Deployment Gate Agent queries the GitHub Actions API to confirm all CI checks have passed for the merged commit. If any check has failed, the workflow branches: the developer receives a Slack alert to fix the build, and no further steps run until the fix is re-merged.
Automation
Automated
3
Once all CI checks pass, the Deployment Gate Agent creates a Jira deployment ticket automatically, populating the version number, target environment, deployment window, and a link back to the pull request.
Automation
Automated
4
The Deployment Gate Agent posts a structured Slack message to the IT lead containing full build context and a one-click Approve or Reject button. The pipeline holds here until the IT lead responds. The IT lead reviews the build details and clicks Approve to proceed or Reject to halt the release.
IT Lead
Human
5
On approval, the Environment and Deploy Agent reads the correct environment variables from the designated Confluence config page and applies them to the target environment, removing the risk of a manual config error.
Automation
Automated
6
The Environment and Deploy Agent triggers the deployment workflow in GitHub Actions, passing the confirmed environment values and logging the pipeline start time.
Automation
Automated
7
After the pipeline completes, the Post-Deploy Monitor Agent polls Datadog health monitors for five minutes, evaluating error rates and response time against agreed thresholds. If a threshold is breached, a PagerDuty incident is raised immediately.
Automation
Automated
8
The Post-Deploy Monitor Agent posts a deployment summary to the team Slack channel and updates the Jira ticket status to reflect the outcome, including the timestamp, environment, and any health check notes. The ticket is closed if the deployment succeeded.
Automation
Automated
Process Runbook / SOPPage 1 of 4
FS-DOC-03Operations
03Handling exceptions
Situation
What the system does
What you do
CI checks fail after a pull request is merged
The Deployment Gate Agent detects the failing check, halts the workflow before any Jira ticket or approval message is created, and sends a Slack alert directly to the developer who merged the pull request, naming the failing check.
Fix the failing test or build error, then open and merge a new pull request. The workflow will restart automatically from the beginning when the new merge is detected.
The IT lead does not respond to the Slack approval request within 60 minutes
The system sends one automated reminder to the IT lead in Slack. If there is still no response after a further 30 minutes, the pipeline times out, the Jira ticket is updated to Awaiting Approval, and the deployment is held until a decision is made.
Check whether the IT lead is available. If they are unavailable, an authorised backup approver (agreed during setup) can respond to the same Slack message. Contact the IT lead directly using the contact table in Section 04.
The IT lead clicks Reject in the Slack approval message
The workflow stops immediately. The Jira ticket is updated to Rejected with a timestamp and the rejection is logged. No config is read, no pipeline is triggered, and no deployment occurs.
Review the reason for rejection with the developer. Address the concern raised by the IT lead, then merge a corrected pull request to restart the workflow from the beginning.
Confluence config page is missing or returns no data
The Environment and Deploy Agent is unable to read environment variables. It posts an alert to the team Slack channel naming the page it tried to read, and halts the deployment before any config is applied. The Jira ticket is updated to Blocked.
Verify that the Confluence config page exists at the agreed location and that the environment table is correctly formatted. If the page has moved, update the config page reference stored in the automation settings and contact FullSpec support at support@gofullspec.com if you cannot locate the setting.
Post-deploy health checks breach Datadog thresholds
The Post-Deploy Monitor Agent fires a PagerDuty incident alert immediately. It also posts a warning message in the team Slack channel and updates the Jira ticket to flag a health check breach, marking it for rollback review.
The on-call engineer responds to the PagerDuty alert. Follow your existing incident and rollback runbook to decide whether to roll back the release or mitigate in place. Update the Jira ticket with the outcome once the situation is resolved.
A connected tool is unavailable (GitHub, Datadog, PagerDuty, or Slack experiences an outage)
The automation platform retries the failed API call three times with a 90-second back-off between each attempt. If all retries fail, the workflow pauses and an alert is sent to the process owner via the backup notification channel. The Jira ticket status is set to Paused and a timestamp is recorded.
Check the status page of the affected tool. If the outage is confirmed, wait for service to restore and then manually re-trigger the workflow from the last successful step. Contact FullSpec support at support@gofullspec.com if the automation does not resume automatically once the tool is back online.
Process Runbook / SOPPage 2 of 4
FS-DOC-03Operations
04Who to contact and when
Fill in the rows below once your team is confirmed. Keep this table updated whenever responsibilities change so the right person is always reachable during a deployment issue.
Role
Name
How to reach them
IT Lead (process owner and approver)
Marcus Reid
[Rep email]
Developer (build and CI)
Priya Nair
[Rep email]
IT Ops (environment config and health checks)
Tom Osei
[Rep email]
Backup approver (if IT lead is unavailable)
[Your name]
[Rep email]
On-call engineer (PagerDuty incidents)
[Your name]
[Rep email]
FullSpec builder
FullSpec
support@gofullspec.com
FullSpec support
FullSpec
support@gofullspec.com
If the automated workflow stops unexpectedly and you cannot identify the cause from the Jira ticket status or the Slack alert message, contact FullSpec support at support@gofullspec.com before manually intervening in the pipeline. Manually triggering GitHub Actions outside the automation can create duplicate deployment records and inconsistent Jira states.
Process Runbook / SOPPage 3 of 4
FS-DOC-03Operations
05Ongoing maintenance
Whenever environment config changes
Update the structured environment variables table on the designated Confluence config page. Confirm the page location and table format match what the automation expects. If the Confluence page is reorganised or renamed, notify FullSpec so the agent's config page reference can be updated.
IT Ops
Whenever Slack approval message content or Jira ticket fields need updating
Contact FullSpec support at support@gofullspec.com to update the Slack Block Kit message template or the Jira field mappings. Do not edit these directly in the automation platform without guidance, as changes can break the approval response listener.
FullSpec (with IT Lead sign-off)
Monthly spot-check
Run a test deployment through the staging environment and confirm all eight automated steps complete correctly, the Slack approval message arrives and responds as expected, and the Jira ticket closes with the correct timestamp and status.
IT Lead
Weekly error-log review
Review the automation error log (accessible from the workflow dashboard) for any failed API calls, timed-out approvals, or retried steps. Investigate and resolve any recurring failures before they affect a production deployment.
IT Ops
When a team member changes role or leaves
Update the contact table in Section 04 of this document. If the IT lead changes, update the Slack user ID configured as the approval recipient in the Deployment Gate Agent. Contact FullSpec support to make that change safely.
IT Lead and FullSpec
Quarterly volume review
Compare actual deployment volume against the baseline of approximately 12 deployments per month. If volume has grown significantly, review whether the current Datadog polling interval, PagerDuty alert thresholds, and Jira project settings are still appropriate for the load.
IT Lead
The most common maintenance issue for this process is the Confluence config page drifting out of sync with the actual environment variables in use. When a developer updates environment variables directly in GitHub Actions secrets without updating the Confluence page, the Environment and Deploy Agent reads stale values and the deployment may fail or behave unexpectedly. Establish a rule that any environment variable change must be reflected in the Confluence config page on the same day it is made.
Process Runbook / SOPPage 4 of 4