Clarify description of `--alias` flag for `deploy` command

[rstavchansky]

Is your feature request related to a problem? Please describe.

We got some docs-related feedback about the --alias flag for the deploy command.

The alias flag was renamed to from the branch flag, and the branch flag is now deprecated. Your explanation makes sense if you think about it as if the flag is named branch because then I could say “well I’m deploying the branch which I have defined as my production branch so I expect it to go to prod”. But if the flag is named alias and the documentation says that this is useful in order to create a more predictable preview URL, then the association between that and what I chose to be the production branch is gone.

Essentially they’re still an implicit connection between “alias” and git branches.

Describe the solution you'd like

Additional content or edits to the deploy documentation, specifically the --alias description.

Additional context

Support Forums post with details about the confusion

Can you submit a pull request?

Yes (if provided more information)

[verythorough]

I can provide some context on why the --branch flag was renamed to --alias. It was done so because you can set the alias to any string, regardless of whether that string exists as a branch, and regardless of what branch you have checked out at the time that you run netlify deploy. Technically, it doesn't even have to be a Git repo you're deploying from. So branch doesn't really make sense here.

What --alias does is set the string at the beginning of the deploy subdomain (for example, https://my-alias--my-site-name.netlify.app). And of course, branch deploys do something similar, setting that same section of the URL with the name of the branch (such as https://my-branch--my-site-name.netlify.app). This is part of the reason why the person who first implemented the flag called it --branch, but this doesn't make sense for the reasons stated above.

Of course, where things get tricky is if you set an alias to the same string value as an existing deployed branch. When there are multiple deploys with the same URL pattern, our routing system displays the most recent one (or in the case of the production URL, it displays the published deploy). If you deploy to a URL pattern that matches an existing URL pattern for the site, it will be treated as the most recent deploy for that pattern and display it. (I haven't tested, but I'm pretty sure it would also "override" Deploy Previews if you used a pattern like netlify deploy --alias deploy-preview-654.)

I wonder if it would be possible to post some warnings (possibly with a confirmation step) when a user deploys with certain alias values?

• If the alias matches the name of the site's production branch, warn that the deploy will replace the most recent production branch deploy (publishing to production if deploys aren't locked)
• If the alias matches any branch names in the repo or any branches specified for deployment, warn that the deploy will replace the most recent deploy with that URL.
• If the alias follows the deploy-preview-X pattern, warn that it will replace any other deploy previews with an identical URL pattern.

[erezrokah]

I wonder if it would be possible to post some warnings (possibly with a confirmation step) when a user deploys with certain alias values?

• If the alias matches the name of the site's production branch, warn that the deploy will replace the most recent production branch deploy (publishing to production if deploys aren't locked)
• If the alias matches any branch names in the repo or any branches specified for deployment, warn that the deploy will replace the most recent deploy with that URL.
• If the alias follows the deploy-preview-X pattern, warn that it will replace any other deploy previews with an identical URL pattern.

Thanks for the explanation! I think it would be very helpful to warn/prompt the user in these cases.

[verythorough]

Cross-linking this with https://github.com/netlify/bitballoon/issues/8598, which concerns changing how CLI deploys with deploy-preview- aliases are handled in the UI and/or API.

[kflavin]

@verythorough Is it possible to use a custom domain when deploying from the cli using --alias? I am trying to build my app locally, and deploy it using the cli. Something like this:

yarn install && yarn build
netlify deploy --dir=dist/ --message="Deploy to Netlify" --alias 1-0-0

Then I'm adding a custom domain for this deployment as follows:

curl -X POST -H ... https://api.netlify.com/api/v1/dns_zones/example_com/dns_records \
  -d '{ "hostname": "1-0-0.releases.example.com", \
         "type": "NETLIFY", \
          "value": "1-0-0--example-review.netlify.app", \
          "site_id": "...", "ttl": "300" }'

We've delegated "releases.example.com" in this case to Netlify DNS, and I can see the record is created there. However, when I look at the subdomains attached to the site, I don't see the new subdomain listed (1-0-0.releases.example.com in this case).

Is this not currently possible when building outside of Netlify? If I do the build + deploy through Netlify with a git repository, then I can create the custom domain using the same curl command and 1-0-0.releases.example.com will redirect to 1-0-0--example-review.netlify.app.

This seems to be related: https://github.com/netlify/cli/issues/948

[erezrokah]

Hi @kflavin, I believe your request is exactly the same one as #948. See community post linked from that issue here.

[kaganjd]

Wanted to share a small update:

If you deploy to a URL pattern that matches an existing URL pattern for the site, it will be treated as the most recent deploy for that pattern and display it. -https://github.com/netlify/cli/issues/1984#issuecomment-797120748

We had an enterprise customer who was hoping for this behavior but found something different: he first had develop-- as a branch deploy, then disabled the branch deploy so he could use develop-- as an alias, and found:

it seems even when disabling related features, it keeps in memory the facts it’s been used as a deployed branch.

• I’ve disabled branch related features
• I’m trying to deploy to a branch alias
• I’m getting a page not found error on the alias url (develop--) despite the fact the preview url for the deploy works

so it seems like you cannot use an alias to overwrite a branch deploy, even if you don't want to use the branch deploy anymore.

[erezrokah]

Hi @kaganjd, can you share the full command the customer is using? | would like to verify we're not hitting this issue.

[kaganjd]

Hey @erezrokah, the command in his case was netlify deploy --dir=dist --alias=develop, zendesk ticket is https://netlify.zendesk.com/agent/tickets/58139 (internal only)

[erezrokah]

Hi @kaganjd, I was able to reproduce the same issue. Once you have a branch deploy that was created from our build system, netlify deploy with the same alias as that branch doesn't update the branch URL.

To clarify the reproduction:

1. Enabled all branch deploys in the Netlify UI
2. Create a branch named develop and push it
3. See that the branch deploy was created - for example https://develop--netlify-build-reproductions.netlify.app/
4. Change some content
5. Run netlify deploy --alias=develop
6. Access https://develop--netlify-build-reproductions.netlify.app/ again and see that is shows the old content

However, accessing the unique deploy URL works https://60ca2f288c2fb01ae5d84233--netlify-build-reproductions.netlify.app

[overlordofmu]

I have this (internal only) feature request filed as well for the API to offer support for full branch deploys with CLI manual deploys:

https://github.com/netlify/bitballoon/issues/6619

[rstavchansky]

Re: suggestions from @verythorough:

I wonder if it would be possible to post some warnings (possibly with a confirmation step) when a user deploys with certain alias values?

• If the alias matches the name of the site's production branch, warn that the deploy will replace the most recent production branch deploy (publishing to production if deploys aren't locked)
• If the alias matches any branch names in the repo or any branches specified for deployment, warn that the deploy will replace the most recent deploy with that URL.
• If the alias follows the deploy-preview-X pattern, warn that it will replace any other deploy previews with an identical URL pattern.

We got more feedback in the Support Forums that it would be useful to see these types of warnings in the CLI: https://answers.netlify.com/t/headers-not-read-for-alias-deploy-from-netlify-cli/40264

[chrismetzmudbath]

Hi @kaganjd, I was able to reproduce the same issue. Once you have a branch deploy that was created from our build system, netlify deploy with the same alias as that branch doesn't update the branch URL.

To clarify the reproduction:

1. Enabled all branch deploys in the Netlify UI
2. Create a branch named develop and push it
3. See that the branch deploy was created - for example https://develop--netlify-build-reproductions.netlify.app/
4. Change some content
5. Run netlify deploy --alias=develop
6. Access https://develop--netlify-build-reproductions.netlify.app/ again and see that is shows the old content

However, accessing the unique deploy URL works https://60ca2f288c2fb01ae5d84233--netlify-build-reproductions.netlify.app

I came across the exact same issue a couple of days ago. Is there any known work around for this?

[erezrokah]

Hi @chrismetzmudbath, the only workaround is using a different branch name for branch deploys and aliases. We do have an issue filed for our backend team to make branch deploys and aliases more alike, but we don't have an estimate yet.

[tobiasdiez]

I seem to have the same problem as above, with the slight twist that I've only used deploy --alias without any branch deploys (never even linked a git repo in the netlify ui). However, after the initial deploy further deploys with the same alias are not updated.

(Caveat: for some reason deploys with --alias sometimes show up as a branch deploy in the netlify ui, e.g. https://app.netlify.com/sites/sagemath-tobias/deploys/6200662d92eba278c3b1fc6d; not sure if that's related or a bug.)

[inadeqtfuturs]

Looking to see if this request is getting any traction.

We're very successfully using the cli to handle preview deploys for PRs, however we have a handful of static branches (develop, preprod, etc.) that we'd also move into our CI/CD pipeline. Being able to perform branch deploys would be a real boon.

[mordonez]

Any updates in this feature? Branch deploys from netlify cli is very useful

[dikaso]

Same here. We use Jenkins to manage deploys and currently we cannot accomplish manual deploys to dev/staging branch.