START HERE
What you will learn
- Distinguish the server’s host key from your deployment key.
- Interpret common connection failures without weakening the checks.
- Explain how credential scope and account permissions affect a release.
Before you start: You need the idea of a remote server and a deployment account. Do not paste real private keys into examples or shared notes.
Two keys with different purposes
The server’s host key identifies the server. Your SSH client can compare it with an expected key stored in known_hosts, a record of recognised hosts. Your deployment key identifies the client account: the server accepts the corresponding public key if that account is configured to allow it.
The private half of the deployment key must remain private. The public half can be installed for the intended account. Neither fact removes the need to verify the server. Proving who you are to the wrong server would not be a safe deployment connection.
An encrypted connection still needs appropriate permissions
A connection can be encrypted and authenticated while the account has far too much authority. A routine release identity should be able to perform the release operations it needs, without automatically receiving the permissions used for general host administration.
In automation, the secret must also be available in the environment that the job actually uses. A value stored only for staging does not become a production credential. Check the name, scope and complete value rather than printing secrets while diagnosing a failure.
Step-by-step process
Confirm the intended host and account
Establish the destination and deployment username through your trusted administration process. An incorrect username can make a valid key appear to be broken.
Verify the expected host fingerprint independently
A fingerprint is a short representation of a key. Compare it using an administration channel you already trust before recording the expected host identity. Merely collecting a key from an unverified network connection does not establish its authenticity.
Use a dedicated deployment identity
Keep its private key out of source code, frontend variables and logs. Make the server account’s permissions match the release task. Record how the key can be revoked or replaced.
Require identity checks in unattended jobs
Use strict host checking and noninteractive authentication, with an explicit identity where appropriate. Set a connection timeout so a failed route does not wait indefinitely.
Diagnose the stage that failed
“Missing secret” means a required value was unavailable. “Host key verification failed” concerns server identity. “Permission denied (publickey)” concerns client authentication or account configuration. These failures require different investigations.
FOLLOW ONE EXAMPLE
Worked scenario
The key works in staging but production cannot connect
A release job reports that its host value is missing. The deployment key itself has not yet been tested because the connection cannot be constructed.
- Check whether the job references the production environment while the value was saved only under staging. Fix the scope or missing value without exposing the key.
- If the next failure is host verification, compare the expected fingerprint through the trusted administration channel and inspect the host entry. Do not turn off checking to proceed.
- If the host is verified but authentication fails, inspect the username and matching authorised public key. Avoid replacing every credential at once, which would make the cause harder to identify.
What this shows: You resolve the specific identity or configuration problem while preserving the protections that made the failure visible.
The process at a glance
Read Mermaid diagram source
flowchart TD
A[Deployment job has configuration] --> B{Expected server identity?}
B -->|No| C[Stop and verify host details]
B -->|Yes| D{Client key allowed for this account?}
D -->|No| E[Check account and authorised public key]
D -->|Yes| F[Perform permitted release operations]What you should have at the end
- A connection that checks both server identity and client authentication.
- A deployment account with task-appropriate permissions.
- A troubleshooting record that contains causes and decisions, not secret values.
Common mistakes and how to avoid them
Confusing a public key with a private key
The server’s authorised public key and the client’s private credential are different files with different purposes.
Disabling host checks after an error
Investigate a changed or missing host identity through a trusted channel.
Using an administrator key for every release
A more restricted identity limits the consequences of an automation mistake.
APPLY THE IDEA
Try it yourself
Your task: Create a credential inventory using labels only: destination, account owner, host-key verification method, secret location and revocation owner.
What to produce: A one-page inventory without private keys, passwords or sensitive host details.
Check your understanding: Can you identify the right owner and check for a missing-secret, host-identity or public-key-authentication failure?
Key terms in plain English
- Host key
- The key identifying the server to the SSH client.
- known_hosts
- The client’s record of expected server identities.
- Public key
- The shareable half of a key pair used to recognise an allowed identity.
- Private key
- The secret half used by the client to prove that identity.